Skip to main content

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​

  1. When making a call via the API, pass a StatusCallback URL parameter
  2. When the call reaches a terminal state, Exotel sends a POST request to that URL
  3. Your server receives call details including status, duration, and recording URL
caution

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:

ParameterTypeDescription
CallSidStringUnique alpha-numeric call identifier
DateUpdatedDateTimeLast status update timestamp (format: YYYY-MM-DD HH:mm:ss)
StatusStringTerminal call status: completed, failed, busy, or no-answer
RecordingUrlStringCall 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:

ParameterTypeDescription
EventTypeStringThe event type (e.g., terminal, answered)
DateCreatedDateTimeWhen the call was initiated
ToStringRecipient phone number
FromStringCalling phone number
PhoneNumberSidStringExoPhone identifier
StartTimeDateTimeWhen the call started
EndTimeDateTimeWhen the call ended
ConversationDurationIntegerSeconds both parties were connected
DirectionStringinbound, outbound-dial, or outbound-api
CustomFieldStringCustom data passed during the original API request
LegsArrayPer-leg attempt details with OnCallDuration and Status

Leg Information​

{
"Legs": [
{
"OnCallDuration": 41,
"Status": "completed",
"AnsweredBy": "NA"
},
{
"OnCallDuration": 32,
"Status": "completed",
"AnsweredBy": "HUMAN"
}
]
}

AnsweredBy Values​

ValueDescription
HumanAnswered by a person
MachineAnswered by voicemail/IVR
NotSureCould not determine
NANot applicable (first leg)

Leg Status Values​

Individual call legs can have the following statuses:

StatusDescription
completedLeg completed successfully
busyCalled party was busy
failedLeg failed
no-answerCalled party did not answer
canceledLeg was canceled
nullLeg 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​

FieldTypeDescription
CallSidStringCall SID
AccountSidStringAccount SID
AnsweredByStringHUMAN, MACHINE, or NOTSURE
AmdCauseStringCause 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.
MachineDetectionDurationStringAMD detection duration in integer seconds as a string (e.g. 4). 0 when AMD completes within the same second. Empty string when not provided.
CallStatusStringCall 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=hangup after 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 From and To parameters in the original call request
  • StatusCallbackEvents does not apply when using VoiceUrl — use the Passthru applet instead
  • Your webhook endpoint should respond with HTTP 200 to acknowledge receipt