Skip to main content
POST
/
inbound_call
Handle inbound call
curl --request POST \
  --url https://api.call24x7.ai/inbound_call \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'CallSid=<string>' \
  --data 'From=<string>' \
  --data 'To=<string>' \
  --data 'ForwardedFrom=<string>' \
  --data 'agent_id=<string>' \
  --data 'external_call_id=<string>'
"<string>"

​
Overview

Process an incoming call from Twilio. This endpoint is typically called by Twilio webhooks when a call is received on a configured phone number. The endpoint returns TwiML XML to instruct Twilio how to handle the call.

​
Query Parameters

​
query
string
ID of the AI agent to handle the inbound call. Can also be provided in the request body or determined from the ForwardedFrom phone number.

​
Request Body

This endpoint accepts application/x-www-form-urlencoded data from Twilio webhooks.
​
body
string
required
Twilio call SID (automatically provided by Twilio)
​
body
string
required
Caller’s phone number (automatically provided by Twilio)
​
body
string
required
Called phone number (automatically provided by Twilio)
​
body
string
Forwarded from phone number if the call was forwarded (automatically provided by Twilio)
​
body
string
ID of the AI agent to handle the call. Can be provided in query string, request body, or determined from ForwardedFrom phone number.
​
body
string
Optional external call ID for tracking purposes.

​
Example Request

curl -X POST "https://api.call24x7.ai/inbound_call?agent_id=agent-123" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "CallSid=CA1234567890abcdef&From=%2B1234567890&To=%2B0987654321"

​
Response

On success, this endpoint returns TwiML XML that instructs Twilio to stream the call audio to the Call24x7.AI WebSocket server.

​
Success Response (TwiML XML)

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <Stream url="wss://ws.call24x7.ai/{call_id}" />
  </Connect>
</Response>

​
Error Response (JSON)

​
success
boolean
Always false for errors
​
message
string
Human-readable error message
​
error_code
string
Error code. Possible values: MISSING_PARAMS, AGENT_NOT_FOUND, INSUFFICIENT_BALANCE, INTERNAL_ERROR

​
Example Error Response

{
  "success": false,
  "message": "Missing agent_id in query string, request body, or unable to find agent from ForwardedFrom phone number",
  "error_code": "MISSING_PARAMS"
}

​
Agent ID Resolution

The agent_id can be provided in three ways (checked in order):
  1. Query parameter: ?agent_id=agent-123
  2. Request body: agent_id=agent-123 in the form data
  3. ForwardedFrom lookup: If ForwardedFrom is provided, the system attempts to find the user by phone number and use their active inbound agent

​
Twilio Configuration

To use this endpoint, configure your Twilio phone number’s webhook URL to point to: 
https://api.call24x7.ai/inbound_call?agent_id=YOUR_AGENT_ID
Or configure it without the agent_id and provide it in the request body or use the ForwardedFrom lookup feature.

​
Notes

  • This endpoint is designed to be called by Twilio webhooks, not directly by your application
  • The endpoint returns TwiML XML on success, not JSON
  • Ensure your account has sufficient balance before receiving calls
  • Calls are billed at $0.15 per minute with precise second-by-second billing

Authorizations

​
Authorization
string
header
required

API key authentication. Include your API key in the Authorization header as: Bearer YOUR_API_KEY

Query Parameters

​
agent_id
string

ID of the AI agent to handle the inbound call

Body

application/x-www-form-urlencoded

Twilio webhook parameters

Twilio webhook parameters for inbound calls

​
CallSid
string

Twilio call SID

​
From
string

Caller's phone number

​
To
string

Called phone number

​
ForwardedFrom
string

Forwarded from phone number (if call was forwarded)

​
agent_id
string

ID of the AI agent to handle the call

​
external_call_id
string

Optional external call ID for tracking

Response

TwiML response for Twilio

TwiML XML response