Short video:

CCM programmable connect is our call centre version of connecting customers with users by returning the phone number of the user dynamically via a webhook. Using CCM programmable connect will ensure your users are marked busy while they are on another call such that no other call (incoming or outgoing) is routed to them until they are free. Such users need not be mandatorily created on Exotel via the dashboard or using APIs.

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’. 


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.



This value will indicate the version of connecting applet parameters against which your endpoint’s response will be validated.

Current Version: 1.1

Query Parameters:

Parameter Name



Unique identifier of the call


The direction of the call. Possible values: ‘incoming’ or ‘outbound-dial’


Timestamp when the call is created (format: yyyy-mm-dd hh:mm:ss)


Value in seconds from the time call is triggered to the second leg of the call till it is over (including conversation time). This value can be set to zero depending on the previous applet and if there’s no second leg in the call flow.


Timestamp when the call is started (format: yyyy-mm-dd hh:mm:ss)


Shows the number of the agent who was dialed at last


In the case of an incoming call, it is the number of the caller. In the case of an outgoing call, it is the number of the first leg of the call.


 In the case of an incoming call, it is the ExoPhone into which the call came. In the case of an outgoing call, it is the number to which the call was made.


Current server time (format: yyyy-mm-dd hh:mm:ss)

*These parameters will be passed if certain conditions are met as described below:

Parameter Name                



This will denote what happened with the second leg of the call if the previous applet was “connect”.

Possible values: 'completed', 'busy', 'no-answer', 'failed', 'canceled'


‘digits’ will be passed if there was a 'Gather' or ‘IVR’ applet before this applet and will be equal to the input digits that were entered. NOTE: This parameter comes with a double quote (") before and after the number. You'll have to trim() this parameter for double quotes (") to get the actual digits.


This will be populated if the previous applet was "voicemail". It will contain the URL of the voicemail recording. There could be a delay before the recording can be accessed depending on the length of the recording file.


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:




    "fetch_after_attempt": false,
    "destination": [
            "contact_uri": "+9198765xxxxx"
            "contact_uri": "sip:gauravjfb55d386"
            "contact_uri": "+9197864xxxxx"
    "state_management": true,
    "outgoing_phone_number": "90876xxxxx",
    "sticky_agent": false,
    "recording": {
        "record": true,
        "channels": "single"
    "max_ringing_duration": 30,
    "max_conversation_duration": 900,
    "music_on_hold": {
        "type": "default_tone"
    "parallel_ringing": {
        "activate": true,
        "max_parallel_attempts": 5
    "call_event_passthru_url": "",
    "start_call_playback": {
        "type": "text",
        "value": "hello, this is a sample text"






default = false

This parameter will indicate if, after each unsuccessful dial attempt within connect, the parameters should be fetched again including destination numbers.

  • `false` will indicate a dial attempt to happen based on the initial response. No subsequent hits to the URL.

  • `true` will indicate if connect parameters including a number to dial should be fetched again (hit the configured URL again) if the dial attempt is unsuccessful.

NOTE: If 2 subsequent fetch results contain exactly the same set of destination numbers, Exotel will not make any subsequent attempts even if fetch_after_attempt is set to true.

GET /<customer-url>
Apart from standard request params, it’ll include <connect> params from previous dial attempts.
<Same as above>



Array of JSON block

  • contact_uri - Phone number of the user in EE.164 format, or the SIP URIs if VOIP calling is enabled. DND checks would apply as applicable by the platform. The dial will happen in the order they appear in the array.

If any SIP URI is provided, state_management parameter value will be ignored and state management will be done by default.

If any contact_uri is already added to the Exotel dashboard as a user number, state_management parameter value will be ignored and state management will be done by default.


"destination": [


            "contact_uri": "+9198765xxxxx"



            "contact_uri": "sip:gauravjfb55d386"



            "contact_uri": "+9197864xxxxx"



*The dial will happen in the order they appear in the array.



default = false

Allows the state management to be done on the ‘destination’ numbers. Can be:

  • false (default) - Numbers will not be checked for busy status before allowing calls on those numbers

  • true - Numbers will be checked for busy status before allowing calls on those numbers


default = Incoming ExoPhone

ExoPhone is to be used for dialing out in E.164 format.


  • The ExoPhone added should be present in your account.

  • Restrictions will depend on telecom regulations i.e. another call can only be dial-ed out from the same telecom circle/region. For example, outgoing ExoPhone cannot be set to Delhi whereas Incoming ExoPhone is in Bangalore.

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).



default = false

true/false, enable sticky agent mapping if set to true



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

  • record: Record the conversation of your call. 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 (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



    "recording": {

        "record": true,

        "channels": "single"





default = 30

Value in seconds to limit the ringing duration. This can be increased up to 60 seconds.



default = 900 (15 minutes)

Value in seconds to limit the conversation duration. This can be increased up to 75 minutes (4500 s).



default = default_tone

Possible Values:

  • default_tone: Exotel default music on hold as present here.

  • operator_tone: Audio returned by the operator on the dialing channel as is.

  • custom_tone: Audio URL as provided in the response.

Sample Values:


“type”: “default_tone”



“type”: “operator_tone”



"type": "custom_tone",

"value": "<audio_url>"



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": 10


max_parallel_attempts value can be between 1-10. Default: 5

*Please note this feature is chargeable and consult with your Account Manager or email before using this parameter.


The URL passed here will be used to send the details for dial, ringing, answered and terminal events.

Sample response that will be sent to the call_event_passthru_url:


    "event_details": {

        "event_type": "terminal"


    "call_details": {

        "call_sid": "6518aba3264320d7bf8583fa6d8516bg",


        "from": "08516043026",

        "to": "9968654311",

        "virtual_number": "01135124160",

        "created_time": "2022-11-16T00:19:02+05:30",

        "current_time": "2022-11-16T00:19:12+05:30",

        "status": "free"



Note: 'ringing' and 'answered' events can be enabled for select accounts only. If you wish to subscribe to these two events, please raise a request via


Play a recording to the number that is being called


“type”: “audio_url”,

“value”: “http://...mp3”




“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

Note: If the file name returned in the case of `audio_url` is the same, it will be cached by our servers. Kindly, provide dynamic file names if the audio to be played is different each time.

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.


  • 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 phone number of a user which doesn't exist
    • The user device is unverified, if the user is added in Exotel
    • The user device is OFF (available = false) in Exotel, if the user is added in Exotel
    • The number is busy on another call (Incoming or Outgoing) going through Exotel where state_management was requested

If you have any questions or concerns, please connect with us using the chat widget on your Exotel Dashboard or Whatsapp us on 08088919888.