FlexML Requests

Overview

When a call is initiated, CarrierX makes an HTTP request to your application URL and expects FlexML instructions in response. These instructions are XML-based commands that determine what happens next in the call (e.g., play a message, gather digits, or dial another number).

• For inbound calls, CarrierX uses the url and method defined in the DID object configuration. If not set on the DID, values from the Account object are used.
• For outbound calls, the url and method values can be defined in the Call object. If not defined in the Call object, the same sequence is used: DID > Account.

Request Data

Each request contains identifying information about the call (such as CallSid, From, To, and Direction) and contextual metadata like ApiVersion and RequestUrl.

The request to your application can be either a POST or a GET. If it's a POST the request data is in a JSON body and if it's a GET the request data is in query parameters.

Attribute	Data Type	Description
AccountSid	string	The account secure ID. Reserved for future use. This field is currently always blank.
ApiVersion	string	The API version used to make the request.
CallerName	string	The CNAM of the calling party, if available.
CallSid	string	The call secure ID. This value remains the same throughout the call.
CallStatus	string	Indicates the current state or final outcome of the call. Possible values: busy - The destination was busy. cancel - The caller canceled before the call was answered. completed - The call was answered successfully. failed - The call could not be completed (e.g., invalid number, all channels busy). noanswer - The call rang too long without an answer.
Direction	string	Denotes whether the call was inbound or outbound.
ForwardedFrom	string	Contains the phone number in the Diversion header, if available (used for conditional call forwarding). Note that not all carriers support passing this information in the header.
From	string	The calling party phone number, formatted in E.164.
OriginalFrom	string	The unformatted number received directly from the carrier. Generally, From is used in development.
OriginalTo	string	The dialed number in its raw form as received from the carrier. Generally, To is used in development.
RequestUrl	string	The URL of the FlexML that was running to trigger the current request.
To	string	The dialed phone number in E.164 format.

Below is an example JSON object posted to the provided URL:

{
    "AccountSid":"",
    "ApiVersion":"2.0",
    "CallerName":"",
    "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
    "CallStatus":"completed",
    "Direction":"inbound",
    "From":"15162065338",
    "OriginalFrom":"+15162065338",
    "OriginalTo":"15162065337",
    "RequestUrl":"https://sampleurl.com/example",
    "To":"15162065337"
}

note

In addition to the initial request fields, CarrierX can send callback requests during and after a call. Additional data may be included with such requests depending on the type of event and the verbs used in the FlexML response.

Status Callbacks

Data about completed calls can be received by setting status_callback_url and status_callback_method in the Call object, the DID object, or FlexML verbs such as Dial and Record.

CarrierX can send additional HTTP requests to your application during or after a call to provide call state information (e.g., completed, busy, failed). These are status callbacks.

You can configure status callbacks using the status_callback_url and status_callback_method fields on multiple levels with the following precedence:

1. Call object — applies to outbound calls only.
2. DID object.
3. Account object — used as a last fallback if not specified elsewhere.

For example, if the values are set on both, the Call and the DID objects, the Call object setting takes precedence.

These values can also be overridden using the Override verb.

In addition to the standard callback fields the following fields are included in status callback requests:

Attribute	Data Type	Description
CallDuration	integer	Total call duration in seconds.
PlaybackUrl	string	URL of the audio file played.
PlayOffset	integer	Position of the playback from the beginning of the file when the call ends (either played or skipped to using DTMF controls).
RequestMethod	string	Type of request made to the RequestUrl, either POST or GET.
RequestUrl	string	Initial URL to which the request was made, as set in the Call object or DID object.

Verb-Specific Callbacks

Some FlexML verbs add extra attributes to callback requests. Below is a list of verbs and the additional fields they provide. For detailed descriptions, refer to each verb's documentation.

• Dial → AnswerTime, CallDuration, DialAnswerTime, DialCallDuration, DialEndTime, DialStartTime, EndTime, StartTime

  note

  Dial fields always reflect the most recent Dial verb. Some may be null during in-progress callbacks.

• Gather → Digits

  note

  DTMF input collected. Empty if none collected.

• Play → Digits, PlaybackUrl, PlayOffset

  note

  Digits shows key pressed if stopOnKey triggered playback stop.

• Record → RecordingDuration, RecordingSid, RecordingStatus, RecordingUrl, TranscriptionSid, TranscriptionStatus, TranscriptionText, TranscriptionUrl

  note

  Only included if recording/transcription enabled.

• Store → Storage_* (custom fields defined in the store object)

  note

  Data stored is automatically included in all subsequent callbacks.

important

If an action URL is set for a verb, action callbacks occur as soon as the verb completes. If no action URL is set, FlexML continues with the next instruction.

info

For each verb-specific call back the following rule applies (except for Store): In addition to the standard callback fields the following fields are included in the callback request when the verb completes:

• If an action URL is specified, these fields are sent immediately in the action request.
• If no action URL is specified, FlexML continues with the next instruction, but the verb-related fields are still included in all subsequent callbacks (including the final status callback).

Dial Callback Fields

Attribute	Data Type	Description
AnswerTime	string	Timestamp when the call was fully connected and both parties could start talking.
CallDuration	integer	Duration in seconds from when the call was answered until it ended. Will be null if the call is still ongoing when the action URL is requested.
DialAnswerTime	string	Timestamp when the most recent Dial verb was fully connected.
DialCallDuration	integer	Duration in seconds of the talk time for the most recent Dial verb.
DialEndTime	string	Timestamp when the most recent Dial verb execution ended.
DialStartTime	string	Timestamp when the most recent Dial verb execution started.
EndTime	string	Timestamp (with millisecond precision) when the overall call ended. If the action callback is triggered before the call ends, this value will be null.
StartTime	string	Timestamp (ms) indicating when the FlexML flow initially started executing the Dial verb.

If multiple Dial verbs are executed in the same call flow, the Dial* fields always reflect the most recent Dial verb.

If the callback occurs while the call is still active (e.g., an in-progress action callback), EndTime, CallDuration, and their Dial-specific equivalents may be null.

Gather Callback Fields

Attribute	Data Type	Description
Digits	string	DTMF digits collected during the Gather session. Empty if no digits were collected before timeout or finishOnKey.

Play Callback Fields

Attribute	Data Type	Description
Digits	string	Key (stopOnKey) pressed to stop playback. Empty if playback ended normally.
PlaybackUrl	string	URL of the played audio file.
PlayOffset	integer	Playback position (in seconds) from the beginning of the file when the call ended (either fully played or skipped via DTMF controls).

Record Callback Fields

Attribute	Data Type	Description
RecordingDuration	integer	Duration in seconds of the recorded audio.
RecordingSid	string	Unique identifier of the recording.
RecordingStatus	string	Status of the recording (completed, failed, etc.).
RecordingUrl	string	URL to access the recording file.
TranscriptionSid	string	Unique identifier of the transcription (if transcription was enabled).
TranscriptionStatus	string	Status of the transcription request.
TranscriptionText	string	Text result of the transcription (if available).
TranscriptionUrl	string	URL to fetch the transcription result.

Store

The Store verb does not trigger its own callback request. Instead, the data stored is automatically included as additional fields in all subsequent callback requests (for example, when a Redirect verb is executed or during the final status callback). The stored data is returned in the following format:

Attribute	Data Type	Description
Storage_{name}	string	The value stored under the name key of the Store verb. Each stored item is returned as a Storage_* field with the key substituted.