Parameter

Mandatory/

Optional

Value/Description

from

Mandatory

JSON block indicating the number to be dialed first (leg1). This should be your user/agent number. Currently it has two attributes:

• contact_uri - Phone Number preferably in E.164 format or the SIP URI if VOIP calling is enabled. 
• state_management- Allows the state management to be done on the ‘from’ number. Can be:
  • false (default) - Number will not be checked for busy status before allowing calls on that number
  • true - Number will be checked for busy status before allowing calls on that number

If the contact_uri is already added to the Exotel dashboard as a user number, state_management will be ‘true’ by default.

Example- 

{
  "from": {
    "contact_uri": "+9199XXXXXXX",
    "state_management": "true"
  }
}

If not set in E.164 format, our system will try to match it with a country and make a call. If landline number, prefix it with STD code; Ex: 080XXXX2400

to

Mandatory

JSON block containing the phone number of the customer (leg2) to be connected after the ‘from’ number is connected.

• contact_uri- Phone number in E.164 format which will be dialed if the leg 1 of the call is picked up

Example -

{
  "to": {
    "contact_uri": "+9199XXXXXXX"
  }
}

virtual_number

Mandatory

ExoPhone (Virtual Number) present in your account in E.164 format or local format for Indian virtual numbers. This will be the number that will be used to make the call to both ‘from’ and ‘to’ numbers.

recording

Optional

JSON block containing the recording related attributes. Currently these are record, channels and the ormat.

• record: Record the conversation of your call. The recording url will be sent to the status_callback URL if this is set to 'true' and the call conversation happens. Can be:
• true - Call conversation will be recorded
• false (default) - Call conversation will not be recorded
• channels: Number of audio channels to be present in the final recording
  • single- Record both legs of the call in a single channel of the recording file
  • dual - Record the caller and the callee into separate channels of the recording file
• format: Quality of the audio recording.
  • mp3- Standard bitrate recording
  • mp3-hq- Higher bitrate (32 kbps/channel) recording. Mp3-hq option is an on-demand feature.

Please reach out to hello@exotel.com to get it enabled for your account before using this option.

Example-

{
  "recording": {
    "record": "true",
    "channels": "single",
    "format": "mp3-hq"
  }
}

wait_audio_url

Optional

String; Play this audio to the caller. When the first leg (from) has to wait for the other leg (to) to pick up the call, the audio file specified in this parameter will be played.

Please refer to this article to understand the format specifications of the audio file to be played (wav is only supported).

Guidelines on usage:

• The audio file size is recommended to be less than 2MB. Please note, Exotel will cache the wav file. During the first few call attempts of setting this parameter, the user might hear normal ringing tone for the first 5 seconds (for a ~2MB file). This is only temporary for initial few calls and once the audio file is cached, audio will be played out smoothly
• In case you decide to change the audio file later, the WaitUrl should be different (as Exotel will cache audio files based on URL). You can do so by hosting the audio file with a different name
• When using this parameter, it is recommended to set the TimeOut parameter as well

Example: "http://{your_hosted_endpoint}/{audio file name}.wav"

max_time_limit

Optional

Integer; The time limit (in seconds) that you want this call to last. The call will be cut after this time

Default: 4 hours

attempt_time_out

Optional

Integer; The time (in seconds) to ring the called parties (both first and second call leg)

Default: 30 seconds.

custom_field

Optional

String; Any application specific value like order id that will be passed back as a parameter in status_callback

status_callback

Optional

Array: An HTTP request will be made to the specified URLs based on the subscribed events and methods. Currently the supported attributes are: 

• event: Call events for which we will send details to the URL as set in the url attribute. 'event' becomes mandatory if you have specified a url for the status_callback. terminal/answered or both events could be subscribed to:
  • terminal - This will be triggered once the call is over
  • answered - This will be triggered for each of the legs (From and To) if and when they answer the call
• url: An HTTP request will be made to this URL depending on what event is subscribed to using the ‘event’ attribute.

method: Default: POST

Allowed: GET and POST

content_type: The HTTP header ‘Content-Type’ using which the status_callback webhook will be triggered to your URL. Can be:

• multipart/form-data
• application/json  (default)

Example:

{
  "status_callback": [
    {
      "event": "answered",
      "url": "",
      "method": "POST",
      "content_type": "application/json"
    },
    {
      "event": "terminal",
      "url": "",
      "method": "GET",
      "content_type": "application/json"
    }
  ]
}

playback

Optional

Array: Contains the playback related attributes. Currently, the supported attributes are:

• event: When should the party (Callee or Both) listen to the playback. Can be:
  • start: At the start of the call
• to: The party that should listen to the playback. Audio to be listened by the user or both customer and user based on the event. Can be:
  • callee (default) - Playback audio will be played to callee only
  • both - Playback audio will be played to both caller and callee
• value: URL for the audio to be played just before the call gets connected

Example:

{
  "playback": [
    {
      "event": "start",
      "to": "both",
      "value": ""
    }
}

streaming

Optional

JSON block containing the streaming related attributes. Currently, these are:

• url: url that supports webSocket where audio will be streamed
• begin: Describes the beginning of audio streaming- from the point when first user connection is established or once both the users’ connections are established. Can be:
  • from_leg_connect
  • to_leg_connect

Example:

{
  "streaming": {
    "url": "",
    "begin": "from_leg_connect"
  }
}

This indicates the unique id of the request. Useful for debugging and tracing purposes.

This indicates the HTTP method for the request such as GET/POST/PUT etc.

This indicates the HTTP code for the request such as 200, 400, 500 etc.

Response block contains the user device record matching the request URI. The block contains

• code - This indicates the http code for the particular record in the response array like 200, 400 etc.
• error_data - This block will be null if there is no error else contain error information for the response with following fields
  • code - This would be the error code useful for Exotel's team to debug and can be highlighted in case of unexpected errors.
  • description - This describes the details of the error.
  • message - This is the error message corresponding to the error code useful for Exotel's team to debug and can be highlighted in case of unexpected errors.
• status - This field would indicate status of the response (success/failure).
• call_details - This block will contain the information corresponding to the response array element and will contain the fields for a user record as explained below.