Skip to main content

​
Endpoint

POST /api/call
Initiates an outbound call to a specified phone number with a custom AI prompt. This endpoint allows external tools (like ClawdBot or other integrations) to trigger calls programmatically.

​
Request Body

​
to
string
required
The phone number to call in E.164 format (e.g., +1234567890).
​
prompt
string
Custom system instruction for the AI agent. If not provided, uses the default prompt from config.yaml or a fallback prompt.Default: "You are a helpful AI assistant making a phone call."
​
webhook_url
string
Base URL for webhook callbacks (e.g., https://your-ngrok-url.ngrok.io). If not provided, uses the AGENTICAI_WEBHOOK_URL or NGROK_URL environment variable.The server will append /twilio/voice and /twilio/status to this base URL for Twilio webhooks.
​
metadata
object
Optional metadata object to store with the call session. Can include any custom fields for tracking or context.Default: {}

​
Response

​
success
boolean
required
Indicates whether the call was successfully initiated.
​
call_id
string
Unique identifier for the call. Use this ID with other API endpoints to manage the call.
​
to
string
The phone number that was called (echoed from request).
​
webhook_url
string
The webhook base URL used for this call.
​
error
string
Error message if success is false.

​
Examples

​
Basic Call

curl -X POST http://localhost:8080/api/call \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890",
    "webhook_url": "https://your-ngrok-url.ngrok.io"
  }'
Success Response: 
{
  "success": true,
  "call_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "to": "+1234567890",
  "webhook_url": "https://your-ngrok-url.ngrok.io"
}

​
Call with Custom Prompt

curl -X POST http://localhost:8080/api/call \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890",
    "prompt": "You are a friendly customer service agent for Acme Corp. Help the customer with their order inquiry and be polite.",
    "webhook_url": "https://your-ngrok-url.ngrok.io"
  }'
Success Response: 
{
  "success": true,
  "call_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "to": "+1234567890",
  "webhook_url": "https://your-ngrok-url.ngrok.io"
}

​
Call with Metadata

curl -X POST http://localhost:8080/api/call \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890",
    "prompt": "You are calling to confirm an appointment.",
    "webhook_url": "https://your-ngrok-url.ngrok.io",
    "metadata": {
      "customer_id": "12345",
      "appointment_id": "apt-789",
      "source": "crm_system"
    }
  }'
Success Response: 
{
  "success": true,
  "call_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "to": "+1234567890",
  "webhook_url": "https://your-ngrok-url.ngrok.io"
}

​
Error Responses

​
Missing Phone Number

{
  "success": false,
  "error": "Missing 'to' phone number"
}

​
Missing Webhook URL

{
  "success": false,
  "error": "Missing 'webhook_url'. Set AGENTICAI_WEBHOOK_URL environment variable or pass in request."
}

​
Twilio Error

{
  "success": false,
  "error": "Unable to create record: The 'To' number +1234567890 is not a valid phone number."
}

​
Implementation Details

The endpoint performs the following steps:
  1. Validates the to phone number is provided
  2. Resolves the webhook_url from request body or environment variables
  3. Uses the custom prompt or falls back to the default from config
  4. Generates a unique call_id (UUID v4)
  5. Creates a CallSession to track the call state
  6. Initiates the call via Twilio REST API
  7. Stores the session in the CallManager
  8. Returns the call details to the caller
The call is initiated asynchronously. The endpoint returns immediately after Twilio accepts the call request. Use the List Calls endpoint to monitor the call status.

​
Source Code Reference

Implementation: src/agenticai/server/app.py:176-234

​
Next Steps

List Active Calls

Monitor the call you just initiated

End a Call

Programmatically end the call

Build docs developers (and LLMs) love

Get started for freeTalk to us