Version 1.0 of the CCM Programmable Connect (Private Beta) should not be integrated henceforth as we will be deprecating it soon. Please use version 1.1 of CCM Programmable Connect (Beta)
Short video:
CCM programmable connect is our call centre version of connecting customers with agents by returning the agent id or phone number dynamically via a webhook. Using CCM programmable connect will ensure your agents are marked busy while they are on a call such that no other call (incoming or outgoing) is routed to them until they are free. Such agents (users) need to be created on Exotel via the dashboard or using APIs, or else the dial to non-agents would fail. If you are looking for a generic programmable connect without agent state management, refer here.
If this feature is enabled for your account you would see the option as shown above.
You can choose to configure the Connect applet parameters using the flow builder itself or control it dynamically through a URL. However, you'll need to configure the transitions (next applet) while building the flow irrespective.
If you choose to configure the parameters dynamically using your application URL, you can set a ‘Primary URL’ for handling the requests. You can also set a ‘Fallback URL’ (optional) which will be contacted in case something goes wrong with your ‘Primary URL’.
Request
If an application URL is set for Connect applet, Exotel will make a GET request to the URL with the call details as URL-encoded HTTP query parameters.
The following are the parameters of the GET request. Note that only some of this list may be passed to your application - depending on what stage of the flow you have placed the Connect applet.
Header:
exotel-version | This value will indicate the version of connecting applet parameters against which your endpoint’s response will be validated. Current Version: 1.0 |
Query Parameters:
*These parameters will be passed if certain conditions are met as described below:
Response
This is the response Exotel will expect to the GET request from your Connect Application URL. The response will decide what parameters will be set while executing Connect during the call flow.
Response Header:
Content-Type | application/JSON |
Sample
{
"fetch_after_attempt":false,
"destination_type": "user",
"destination": [{"device_contact_uri": "+91995312XXXX"}],
"dial_passthru_event_url": "https://your-server.com",
"outgoing_phone_number":"+918047115XXX",
"record": true,
"recording_channels":"dual",
"max_ringing_duration":45,
"max_conversation_duration":3600,
"music_on_hold": {
"type":"operator_tone"
},
"start_call_playback": {
"type":"text",
"value":"This text would be spoken out to the callee"
}
}
Explanation:
Parameter | Mandatory/Optional | Description |
fetch_after_attempt | Optional; | This parameter will indicate if, after each unsuccessful dial attempt within connect, the parameters should be fetched again including destination numbers. |
destination_type | Mandatory | Possible values
|
destination | Mandatory | An array of objects (JSON blocks). Possible values:
If, destination_type = external_number,
NOTE 1: Currently dial to only one user or external_number is allowed at a time. To dial multiple users/external_number, use fetch_after_attempt to provide different users/external_number for same connect attempt. NOTE 2: The dial will happen in the order they appear in the array. |
outgoing_phone_number | Optional; | ExoPhone is to be used for dialing out in E.164 format.
NOTE: If ExoPhone is not present in your account ExoPhone is unable to dial out i.e. if the above validation fails, then the call would be dial-ed out using the same ExoPhone as the first leg (where the incoming call landed). |
record | Optional; | true/false; Record the call or not |
recording_channels | Optional; default = single | To record the caller and callee in separate channels in the recording file. Possible values:
|
max_ringing_duration | Optional; | Value in seconds to limit the ringing duration. This can be increased up to 60 seconds. |
max_conversation_duration | Optional; | Value in seconds to limit the conversation duration. This can be increased up to 75 minutes (4500 s). |
music_on_hold | Optional; | Possible Values:
Sample Values: { “type”: “default_tone” } { “type”: “operator_tone” } { "type": "custom_tone", "value": "<audio_url>" } |
parallel_ringing | Optional; | Use this option to dial the numbers in parallel (simultaneously). This will dial all the numbers returned under the destination parameter. "parallel_ringing": { "activate": true, "max_parallel_attempts": 5 } |
dial_passthru_event_url | Optional; | The URL passed here will be requested for dial start and dial end events. For more details on request, refer to this. You can also subscribe to an answered event on this URL (currently available to be enabled for select accounts via [email protected]) |
start_call_playback | Optional; | Play a recording to the number that is being called “type”: “audio_url”, “value”: “http://...mp3” } OR { “type”: “text”, “value”: “hello, this is a sample text” } Configuration for audio files supported in this playback are: Sample Rate = 8 kHz Bit depth = 16 bit Bit rate = 128 kbps Channel = mono File Format = wav |
Cases, where the Fallback URL will be triggered, are:
The primary URL does not return HTTP 200 OK
The primary URL doesn’t return within the timeout period (5 seconds)
Primary URL returns invalid response:
Content-Type should be application/JSON
Mandatory parameters are present
audio_url / text should be HTTP/HTTPS and returns 200 HTTP code
Transition to the next applet
The below transitions are to be set in the call flow builder to decide what to execute next.
Scenarios:
After the call conversation ends: The applet set here will be triggered if a conversation occurs.
If nobody answers: The applet set here will be triggered if we dial the number and a conversation doesn’t occur. If no applet is present in "we didn't dial anyone", it will fall back to this.
We didn’t dial anyone: The applet set here will be triggered if we don’t dial. Cases when this can occur:
If both the Primary and Fallback URL endpoint times out or returns a non-2xx response code.
If both the Primary and Fallback URL endpoint doesn’t return a valid payload.
If the number to dial returned is in invalid format.
If an empty number (destination) is returned in the response
- Invalid user UUID or phone number of a user which doesn't exist
- The user device is unverified
- The user device is OFF (available = false) on Exotel
- The user is busy on another call (Incoming or Outgoing)
If you have any questions or concerns, please connect with us using the chat widget on your Exotel Dashboard or Whatsapp us on 08088919888.