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 makes 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 connect applet parameters against which your endpoint’s response will be validated.

Current Version: 1.0


Query Parameters:

Parameter Name

Description

CallSid

Unique identifier of the call

CallFrom

In case of outgoing call, it’ll be set to the number from which the call is made. In case of incoming call, it’ll be set to the number from which the call is received

CallTo

In case of outgoing call, it’ll be set to the number being dialed out. In case of incoming call, it’ll be set to the number where the call landed.

Direction

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

Created

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

DialCallDuration

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 previous applet and if there’s no second leg in the call flow.

StartTime

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

EndTime

1970-01-01 05:30:00 // Unix time (also known as POSIX time or epoch time)

Note that this would be a constant value and you may instead trigger our Call details API few minutes after the call has been completed, to get the accurate information

CallType


Scenario

Value

IVR only, no connect applet

call-attempt

Call conversation happened

completed

Client hung up during connect applet

client-hangup

Connect applet, no agent picked up

incomplete

Went to voicemail applet

voicemail

DialWhomNumber

Shows the number of the agent who was dialed to last

flow_id

Flow id associated with the call

From

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

To

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

CurrentTime

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                Description

DialCallStatus

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

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

digits

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

CustomField

If the call was initiated via API, the value that was passed in CustomField in the API call will be set here.

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


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": {
"numbers":["+919812345678"]
},
"outgoing_phone_number":"+918047115777",
"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;
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, dial attempt to happen based on the initial response. No subsequent hits to the URL.

`true` will indicate if connect parameters including number to dial should be fetched again (hit the configured URL again) if 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.

Request:
GET /<customer-url>

Apart from standard request params, it’ll include <connect> params from previous dial attempt.

Response:
<Same as above>

destination

Mandatory

Indicates the destination(s) to dial out.

numbers

Array of numbers to be dialed out in E.164 format.

Dial will happen in order they appear in the array.


Sample:

“destination”: { 

  “numbers”: [“+622131921111”, “+622131921112”]

}


outgoing_phone_number

Optional;
default = Incoming ExoPhone

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

Validations:

  • 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 where Incoming ExoPhone is in Bangalore.


NOTE: If ExoPhone is not present in your acor ExoPhone is unable to dial out i.e. if 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; 
default = false

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:

  • single

  • dual

max_ringing_duration

Optional;

default = 30

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

max_conversation_duration

Optional;

default = 900 (15 minutes)

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

music_on_hold

Optional;

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

}

parallel_ringingOptional;

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

}

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 to hello@exotel.in before using this parameter.

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.

*Above set of parameters can also be controlled through the dashboard if one opts to configure the Connect applet using the flow builder instead of Application URL.

Cases where Fallback URL will be triggered are:

  • Primary URL does not return HTTP 200 OK

  • Primary URL doesn’t return within 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 next applet

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 conversation doesn’t occur. If no applet is present in "we didn't dial anyone", it will fallback 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 Primary and Fallback URL endpoint times out or returns non-2xx response code. 

    • If both Primary and Fallback URL endpoint doesn’t return a valid payload.

    • If number to dial returned is in invalid format.

    • If empty number (destination) is returned in the response


Authored-By: Sarthak Singhal, Product Manager, Exotel