StatusCallback
StatusCallback is an asynchronous webhook mechanism that notifies your application when a call completes. Exotel sends an HTTP POST to your specified URL with call details.
How It Works
- When making a call via the API, pass a
StatusCallbackURL parameter - When the call reaches a terminal state, Exotel sends a POST request to that URL
- Your server receives call details including status, duration, and recording URL
StatusCallback delivery may be delayed or fail due to network issues, server problems, or webhook downtime. Implement fallback logic using the Call Details API to ensure you capture all call data.
Default Parameters
These parameters are always included in the webhook POST:
| Parameter | Type | Description |
|---|---|---|
CallSid | String | Unique alpha-numeric call identifier |
DateUpdated | DateTime | Last status update timestamp (format: YYYY-MM-DD HH:mm:ss) |
Status | String | Terminal call status: completed, failed, busy, or no-answer |
RecordingUrl | String | Call recording URL (if recording was enabled) |
Event-Specific Parameters
When you subscribe to specific events via StatusCallbackEvents (supports terminal and answered), these additional parameters are included:
| Parameter | Type | Description |
|---|---|---|
EventType | String | The event type (e.g., terminal, answered) |
DateCreated | DateTime | When the call was initiated |
To | String | Recipient phone number |
From | String | Calling phone number |
PhoneNumberSid | String | ExoPhone identifier |
StartTime | DateTime | When the call started |
EndTime | DateTime | When the call ended |
ConversationDuration | Integer | Seconds both parties were connected |
Direction | String | inbound, outbound-dial, or outbound-api |
CustomField | String | Custom data passed during the original API request |
Legs | Array | Per-leg attempt details with OnCallDuration and Status |
Leg Information
{
"Legs": [
{
"OnCallDuration": 41,
"Status": "completed",
"AnsweredBy": "NA"
},
{
"OnCallDuration": 32,
"Status": "completed",
"AnsweredBy": "HUMAN"
}
]
}
AnsweredBy Values
| Value | Description |
|---|---|
Human | Answered by a person |
Machine | Answered by voicemail/IVR |
NotSure | Could not determine |
NA | Not applicable (first leg) |
Leg Status Values
Individual call legs can have the following statuses:
| Status | Description |
|---|---|
completed | Leg completed successfully |
busy | Called party was busy |
failed | Leg failed |
no-answer | Called party did not answer |
canceled | Leg was canceled |
null | Leg was not attempted |
Example Webhook Payload
{
"CallSid": "80bfbec2d78bbbf10fb851f4fa165211",
"DateUpdated": "2024-01-15 14:30:45",
"Status": "completed",
"RecordingUrl": "https://s3-ap-southeast-1.amazonaws.com/...",
"EventType": "terminal",
"DateCreated": "2024-01-15 14:25:10",
"To": "09123456789",
"From": "09876543210",
"PhoneNumberSid": "0XXXXXX4890",
"StartTime": "2024-01-15 14:25:12",
"EndTime": "2024-01-15 14:30:45",
"ConversationDuration": 320,
"Direction": "outbound-api",
"CustomField": "order_12345",
"Legs": [
{
"OnCallDuration": 335,
"Status": "completed"
},
{
"OnCallDuration": 320,
"Status": "completed"
}
]
}
Answering Machine Detection Callback
When a call is created with MachineDetection=Enable, the AMD result is delivered to the AsyncAmdStatusCallback URL you provide — not to StatusCallback. This is a separate webhook that fires when AMD completes, regardless of whether the call is still active.
Payload Fields
| Field | Type | Description |
|---|---|---|
CallSid | String | Call SID |
AccountSid | String | Account SID |
AnsweredBy | String | HUMAN, MACHINE, or NOTSURE |
AmdCause | String | Cause string from the AMD engine (e.g. HUMAN, INITIALSILENCE-2500-2500). Numbers inside AmdCause are detector thresholds in milliseconds, not the detection duration. Empty string when not provided. |
MachineDetectionDuration | String | AMD detection duration in integer seconds as a string (e.g. 4). 0 when AMD completes within the same second. Empty string when not provided. |
CallStatus | String | Call state at the time AMD completed (e.g. in-progress, completed). This handler does not change the call state. |
Content-Type defaults to multipart/form-data. To receive JSON, pass StatusCallbackContentType=application/json when creating the call.
Example payload
CallSid=amdtest0911T15514314660dTCD011
AccountSid=ex105
AnsweredBy=HUMAN
AmdCause=HUMAN
MachineDetectionDuration=123
CallStatus=in-progress
When cause and duration are absent (Hermix sent AnsweredBy only):
{
"CallSid": "amdtest0911T15514314660dTCD021",
"AccountSid": "ex105",
"AnsweredBy": "MACHINE",
"AmdCause": "",
"MachineDetectionDuration": "",
"CallStatus": "completed"
}
Behaviour notes
- Fires even if the call has already ended when AMD completes
- AMD runs on the first (
From) leg only; dial-leg AMD events are ignored - Callback failure does not affect the call
- The platform does not auto-hangup on machine detection — your server must call
PUT .../Legs/{leg_sid} Action=hangupafter receiving the callback
See Connect Two Numbers for the AMD request parameters (MachineDetection, AsyncAmd, AsyncAmdStatusCallback).
Usage Notes
- Additional StatusCallback fields (event-specific parameters) require both
FromandToparameters in the original call request StatusCallbackEventsdoes not apply when usingVoiceUrl— use the Passthru applet instead- Your webhook endpoint should respond with HTTP
200to acknowledge receipt