Short video:
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 an 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.
1. Configure using flow builder
- Play a prompt to the caller to enter the input
- Specify Key Input behaviour
2. Configure parameters dynamically by providing a URL
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 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 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 an outgoing call, it’ll be set to the number from which the call is made. In case of an incoming call, it’ll be set to the number from which the call is received | ||||||||||||
CallTo | In case of an outgoing call, it’ll be set to the number being dialled out. In case of an incoming call, it’ll be set to the number where the call landed. | ||||||||||||
Call status | The status of the call depends on what stage it is at. | ||||||||||||
Direction | The 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 the 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) | ||||||||||||
CallType |
| ||||||||||||
DialWhomNumber | Shows the number of the agent who was dialled to last | ||||||||||||
flow_id | Flow id associated with the call | ||||||||||||
From | In 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. | ||||||||||||
To | In 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. | ||||||||||||
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 the previous applet was “connected”. |
Legs | An array that will denote detailed information about each leg attempt if the previous applet was “connect”. Legs[0][Type]=single Legs[0][OnCallDuration]=21
|
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. |
| RecordingUrl | 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. |
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 "audio_url": "http://your-endpoint.com/test-audio.mp3" } OR{ "text": "Please enter your mobile number" } |
max_input_digits | integer | Optional; | A 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; | Input key after which the gather should end successfully.
|
input_timeout | integer | Optional; | 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; | Number of times menu has to be repeated if there is no input provided by the user |
repeat_gather_prompt | string | Optional; | URL or text to be played out if the menu is repeated i.e. in case repeat_menu > 0 { "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 the 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 are met first will occur i.e. if finish_on_key is pressed or max_input_digits is reached as per the 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 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
If you have any questions or concerns, please connect with us using the chat widget on your Exotel Dashboard or Whatsapp us on 08088919888