This applet allows you to take numeric information from the user when they are pressing something on their keypads. The information gathered can be used for mobile number input, order id verification etc. along with the Pass-thru applet to process such information in real time and proceed with appropriate set of actions with the user on call.


You can choose to configure the gather 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.


In case 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 gather 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 gather applet.

Header: 

Exotel-Version

This value will indicate the version of gather 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.

CallStatus

Status of the call depending on what stage it is at.

Possible values: 'queued', 'ringing', 'in-progress', 'completed', 'busy', 'failed', 'no-answer', 'canceled'

Direction

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

Created

Timestamp when the call is created

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

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'

Legs

An array which will denote detailed information about each leg attempt if the previous applet was “connect”.

Sample:
Legs[0][CauseCode]=NORMAL_CLEARING
Legs[0][Cause]=16

Legs[0][Type]=single

Legs[0][OnCallDuration]=21
Legs[0][Number]=07200498123


Meaning:

  • Legs[i]: i denotes the index of the attempt in the connect applet. If there are multiple numbers attempted, array’s length will be equal to total attempts.

  • CauseCode: Cause code of the call as returned by the operators

  • Code: Numeric representation of the cause code

  • Type: single or parallel

  • OnCallDuration: Time spent by the leg on call. This value could be 0 if there was no conversation with the attempted leg.

  • Number: Phone number of the attempted leg


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.


Response


This is the response Exotel will expect to the GET request from your Gather Application URL. The response will decide what parameters will be set while executing gather during the call flow.


Response Header:

Content-Type

application/json


Sample:

{
"gather_prompt": {
    "text": "Hello Kovalan, please provide your order id",
  },
"max_input_digits": 5,
"finish_on_key": "#",
"input_timeout": 6,
"repeat_menu": 2,
"repeat_gather_prompt": {
    "text": "It seems that you have not provided any input, please try again."
  }
}


Explanation:

Parameter

Type

Behaviour

Description

gather_prompt

string

Mandatory

URL of the audio file or text which will be played out

Possible Values:

{

 "audio_url": "http://your-endpoint.com/test-audio.mp3"

}

OR

{

"text": "Please enter your mobile number"

}

max_input_digits

integer

Optional;

default = 255

Maximum number of digits which are expected by the user to be entered, after which the gather should end successfully.

finish_on_key

string

Optional;

default = #

Input key after which the gather should end successfully.

Allowed: ‘’ (empty string), 0-9, *, #

Empty would mean there is no finish key.


If null or not set, it’ll take the default value #.

input_timeout

integer

Optional;

default = 5 seconds

Time period in seconds between each key press within which the user has to enter another input key (first input included)

repeat_menu

integer

Optional;

default = 0

Number of times menu has to be repeated if there is no input provided by the user

repeat_gather_prompt

string

Optional;

default = gather_prompt

URL or text to be played out if menu is repeated i.e. in case repeat_menu > 0

Possible values:

{

 "audio_url": "http://your-endpoint.com/test-audio.mp3"

}

OR

{

"text": "Please enter your mobile number"

}

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

NOTE: 

  • When mandatory params are missing, URL is unresponsive (non-2xx) or type validation fails from both Primary and Fallback URL (if set), it will go to URL failure case.


  • If optional parameters are not passed in response, it will be set to default.
  • If both finish_on_key and max_input_digits are passed, whichever criteria is met first will occur i.e. if finish_on_key is pressed or max_input_digits is reached as per user's input


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


To try this out, head over to 'App Bazaar' page on Exotel's dashboard and create a new flow.


*In case your gather applet is still on the older version or if you face any issues with Gather applet, kindly reach out to hello@exotel.in

Authored-By: Sarthak Singhal, Product Manager, Exotel