Mandatory

to

Mandatory

JSON block containing the phone number of the customer (leg2) to be connected to agent.

• customer_contact_uri - Phone Number in E.164 format which will be dialed if Leg1 (agent) picks up.

Example -
"to": {
    "customer_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 agent (leg1) and customer (leg2).

Example -

"virtual_number": "+911454XXXX"

recording

Optional

Boolean; Record the conversation of your call. The RecordingUrl will be sent to the StatusCallback 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.

recording_channels

Optional

String; Number of audio channels to be present in the final recording. This parameter works if Record is set to 'true'. Can be:

• single (default) - 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.

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 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, user might hear normal ringing tone for 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 file 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

attempt_time_out

Optional

custom_field

Optional

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

status_callback

Optional

Array; StatusCallback events to be received against the call. Answered/Terminal or both events can be subscribed.

• Supported Events
  • answered - This will be triggered for each leg (agent and customer) if and when they answer the call.
  • terminal - This will be triggered once the call is over.
• Refer to event payloads in next section. 

Request example-

[
   {
      "event": "answered",
      "url": "<webhook-url>"
   },
   {
      "event": "terminal",
      "url": "<webhook-url>"
    }
]

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).
• data - This block will contain the information corresponding to the response array element and will contain the fields for a user record as explained below. 

string; an alpha-numeric unique identifier of the call

• inbound - Incoming call to a virtual number (Exophone)
• outbound - Outbound calls (Initiated by the agent via Dashboard or API)

The virtual number (ExoPhone) where the call landed (Incoming) or was used to initiate the call (Outgoing)

• active: call is not yet over OR post call processing data is yet to be processed
• terminal: call is over and data is processed against it

• completed - Call is completed and agent/customer had a conversation.
• agent_unanswered - Agent leg was unanswered due to various reasons such as switched off, not reachable, no-answer, busy, connection failed etc.
• customer_unanswered - Customer leg was unanswered due to various reasons such as switched off, not reachable, no-answer, busy, connection failed etc.
• agent_canceled - Agent canceled the call while customer was dialed. This could happen during ringing, blank calls or during an operator message such as switched off, no-answer, busy etc.
• customer_no_dial - There was no dial initiated to customer (rare scenario)
• agent_no_dial - There was no dial initiated to agent (rare scenario)

assigned_agent_details will be the details of the agent who is the primary agent assigned for the call. In case of-

• Outbound Connecting 2 numbers: Assigned agent is corresponding to user_contact_uri as provided in 'from'  for outbound call connecting 2 numbers (Leg1)
• Inbound / Outbound flow calls: Assigned agent is corresponding to the last agent that was attempted in the call flow (including transfer) who may or may not have answered (Leg2)

Fields

• "user_id": unique UUID of the agent
• "name": Name of the agent
• "contact_uri": Phone Number or SIP device URI of the agent’s device
• "group_id":  group id of which agent was part of as per the call attempt else set to null (in case of outgoing or direct transfer to agent)
• "group_name": Name corresponding to the group id
• "call_status": Indicates the call status of the agent leg
  • in-progress - The call was answered and is currently in progress
  • completed - The call was answered and has ended normally
  • failed - The call could not be completed as dialled, most likely because the phone number was non-existent
  • busy - The caller received a busy signal
  • no-answer - The call ended without being answered

This is the number the caller called from (for inbound calls), or the number the call was placed to (for outbound calls), and is equal to

• leg2 (outbound call connecting 2 numbers)
• leg1 (inbound calls / outbound call connecting to flow)

Fields-

• "contact_name": Customer Name as stored in Address Book otherwise set as null
• "contact_uri": Customer Phone Number
• "call_status": Indicates the call status of the customer leg
  • in-progress - The call was answered and is currently in progress
  • completed - The call was answered and has ended normally
  • failed - The call could not be completed as dialled, most likely because the phone number was non-existent
  • busy - The caller received a busy signal
  • no-answer - The call ended without being answered
  • null - customer leg was not dialled or N/A

DateTime as per ISO 8601 date format at which the user initiated the call via API.
Eg- 2021-07-28T02:59:34+05:30

Total time a customer was on call. If there were more than one conversation, it would be the sum of all conversations.

Eg- Agent 1 spoke to Customer for 5 minutes and transferred to Agent 2 and spoke to customer for 10 minutes, total_talk_time for the call would be 15 minutes.

Flow ID which was used at the start of the call. Null if flow was not used.

DTMF digits pressed during the call separated by “-” for different applets. Similar to how it is represented in Call Reports.

Array; It will contain all recordings associated with the call. Each array will contain

• url - This will represent the playable URL for the corresponding recording