WebHooks are used to integrate call-flows directly with an external web-service
An IVR WebHook allows the transfer of data from a phone call to a web server. It can pass along the answers to any non-recorded IVR questions as well as information such as the caller ID, timestamp, the number dialed and more.
The data is sent to the web server using the standard HTTP POST or GET methods. The server can respond with XML that can change the flow of the phone call in progress. The response can contain dynamic information such as people's names or addresses to be read back to the caller, or it can redirect the call to another application such as a Virtual Receptionist or Find Me.
As the response from the web server is a simple XML response, there are no requirements as to which programming language is used on the server enabling the freedom of choice for the developer.
The following sections will help set up a WebHook for first time use.
- Enable the IVR WebHook
- Determine the WebHook settings
- Available IVR generated parameters
- Responding to DialogTech's WebHook
- Advanced WebHook features
Enable the IVR WebHook
For each IVR that is set up, the results are able to be sent to a specified 3rd party system using DialogTech's WebHook. The WebHook is triggered as soon as the IVR has ended. To enable this WebHook, the first step is selecting My web server (Webhook Settings) within the DialogTech IVR. This option is located under the Send Results To section.
Determine the WebHook Settings
Once a WebHook is enabled to send results to my web server, additional fields will be shown on the screen which allow the WebHook settings to be specified.
Advanced Webhook Actions
Determines how the response from the web server will be handled.
Retrieve message and read to user - In response to the HTTP request, the IVR expects to receive HTML or text, which it will then read to the user using text-to-speech and read to the user.
Retrieve next action - In response to the HTTP request, the IVR expects to receive data in XML format. The data will include the ID of the next application to execute and input parameters for that application. (see: Responding to DialogTech's WebHook)
Determines the HTTP Method that is used when sending data to the web server
GET - DialogTech's IVR response data is included within the URL itself; That information can be read by anyone who can see the URL.
POST - DialogTech's IVR response data is transmitted separately from the URL. Instead, the response data will be included in the body of the HTTP Request. This information can not be read by anyone who can see the URL.
The Target URL is the full URL for the web server. Static Parameters and pages can be included. (i.e. https://www.example.com/listener.php?auth=abc123)
Call Generated Parameters
Call Generated Parameters are the responses to the individual questions within an IVR. The key used for each parameter is defined within the IVR.
For example, there may be a question within an IVR named
Service Score with the text
On a scale of 1 to 5, 5 being the best, how would you rate the service you received?
The WebHook will then have a call generated parameter available as there is a question with a response. The parameter name assigned to this response can be anything, such as
qos, and in the dropdown, we'd select
1. Service Score as the value assigned to the
qos parameter that was just created.
Using the above https://www.example.com, the above question example -- assuming the caller pressed 5, and the GET method; The request to the web server will be a GET to
Available IVR Generated Parameters
In addition to the Call Generated Parameters, the IVR WebHook also includes data points about the call itself on every WebHook.
|ivr_number_called||The number the caller dialed (assuming an inbound call) to reach this IVR. Also known as "DNIS."|
|ivr_caller_id||Caller ID, if known, of the IVR respondent.|
|ivr_id||The building block ID of the IVR|
|ivr_response_id||The Unique respondent ID assigned by DialogTech for the respondent to an IVR.|
|ivr_timestamp||Time stamp of start of user interaction with IVR.|
|ivr_pass_through||Data you passed to the IVR which is passed back to the web server. (see: Using pass-through data)|
|ivr_session_id||Unique DialogTech assigned identifier for the call|
|ivr_completed||True/False flag identifying if the IVR was completed in its entirety. False typically indicates a caller disconnected before completing the IVR.|
|ivr_call_result||Outbound call results for an outbound IVR.|
|ivr_monitored_time||Duration of any |
|ivr_opted_out||Opt Out Selection|
|ivr_phone_label||The phone label assigned to the |
Include SourceTrak Data
When Include SourceTrak Data is selected, additional IVR Generated Parameters are sent with the WebHook.
|st_rank||A general confidence indicator between 1 and 5 of how a phone call is matched to a source. A lower rank indicates a higher confidence.|
|st_search_term||The literal search string (keywords) that resulted in the display of a phone number on your website.|
|st_referrer||The referring domain that resulted in the display of a phone number on your website.|
|st_baseuri||The landing page of your website where the SourceTrak phone number was initially displayed.|
|st_activity_keyword||The SourceTrak pool activity that triggered the number display.|
|st_displayed_timestamp||The date and time (listed in Eastern time) that the SourceTrak phone number was first displayed on your website for the visitor.|
|st_ip_address||The IP address of the visitor during SourceTrak session.|
|st_document_title||Title of the initial page view during SourceTrak session.|
|st_browser||Web Browser used during SourceTrak session.|
|st_os||Operating system used during SourceTrak session.|
|st_ibp_custom||Optional custom data passed into SourceTrak.|
|st_ibp_unique_id||Optional custom data passed into SourceTrak.|
|st_pid||Unique identifier for a SourceTrak session.|
|st_domain_set_id||ID of the SourceTrak Domain Set for the number called.|
|st_gclid||Google Click ID captured from a Google Adwords visit.|
|st_google_ua_client_id||Google Universal Analytics assigned Client ID captured during the SourceTrak session.|
|st_pool_name||SourceTrak pool name for the number called.|
|st_location_name||When displaying multiple numbers using SourceTrak Multi-Location on a page, indicates which SourceTrak Location received the call.|
|st_sourceguard||Indicates if call was to a SourceGuard number.|
|st_campaign||Ad Campaign captured by SourceTrak session or default value set in SourceTrak configuration.|
|st_platform||Ad Platform captured by SourceTrak session or default value set in SourceTrak configuration.|
|st_url_tag||The SourceTrak tracked URL Parameter that lead to the phone call|
Responding to DialogTech's WebHook
When Method of a WebHook is set to
Retrieve next action the IVR expects to receive an XML-formatted response.
<action> <app>ivr</app> <parameters> <id>12345</id> <user_parameters> <param1>alpha</param1> <param2>bravo</param2> </user_parameters> <p_t>my pass through data</p_t> </parameters> </action>
An "action" element is required, at minimum, or the IVR will fail to complete and the Backup Routing set in the portal will be triggered.
The "app" element informs the IVR what to do next. Depending on the value of the "app" element, the "parameters" element may contain one or more additional elements to fully define what happens next.
|ivr||user_parameters||(see: Using user parameters)||No|
|findme||id||If ||Yes (1)|
|findme||phone_list||A pipe delimited list of phone numbers to try in the order specified on a Dynamic FindMe (i.e. ||Yes*|
|findme||simultaneous||Determines the number of simultaneous calls to make to the various numbers in the FindMe list.||No|
|findme||record||Use 1 to enable recording on the dynamic Find Me call (call recording warning will be played to both parties). Use 0 to disable recording.||No|
|findme||screen_method||0 - Record the caller's name (default)|
1 - Whisper the
2 - Whisper the audio file provided via
|findme||whisper_phrase||Phrase spoken to person who answers phone|
To be used with
|findme||whisper_audio||The name of an audio file in your Whisper Phrase Audio files folder|
To be used with
|findme||auto_accept||Determines how the recipient of the call will be prompted (or not) to accept the call|
0 - Agent will be prompted to accept the call (note: can be used with
1 - The first number that answers, receives the call without any option to accept/deny the call
2 - The last number attempted will be sent the call. Call screening will be disabled if transferred in this way.
3 - The last number attempted will be sent the call. Call screening will remain enabled if transferred in this way.
|findme||nextaction||Determines what happens if no numbers in the FindMe answer (see table below)||No|
|findme||nextactionitem||Determines what happens if no numbers in the FindMe answer (see table below)||No (2)|
|findme||timeout||Determines the No Answer Timeout for the FindMe list recipients|
Can be between 20 and 60 seconds. Default is 30 seconds
|hangup||n/a||Hangs up the call||n/a|
|transfer||destination||Transfers the call to the ||Yes|
(1) For the App
phone_list must be provided. If
id is provided,
phone_list will be ignored.
(2) For the App
nextaction is provided, the
nextactionitem may be required or not depending on the
|Action Description||nextaction Value||nextactionitem Value|
|If unable to connect, telluser no one is available and disconnect (default).||1||(not required)|
|If unable to connect, transfer to Voice Mail.||2||Voicemail Building Block ID|
|Automatically accept the call on the last number tried.||3||(not required)|
|If unable to connect, route to a Virtual Receptionist.||4||Virtual Receptionist Building Block ID|
|If unable to connect, route to a FindMe.||5||FindMe Building Block ID|
|If unable to connect, route to an IVR.||6||IVR Building Block ID|
|Automatically accept call on last number tried without screening.||7||(not required)|
Below is an example response for using a Dynamic FindMe that calls a single number, has a whisper message and records the call.
<action> <app>findme</app> <parameters> <phone_list>2223334444</phone_list> <screen_method>1</screen_method> <whisper_phrase>Call from Radio Ad</whisper_phrase> <record>1</record> </parameters> </action>
Below is an example response for using a Dynamic Find Me that calls two numbers simultaneously, has a whisper audio message and records the call.
<action> <app>findme</app> <parameters> <phone_list>2223334444|5556667777</phone_list> <simultaneous>2</simultaneous> <screen_method>2</screen_method> <whisper_audio>customwhisper.wav</whisper_audio> <record>1</record> </parameters> </action>
Using User Parameters
nextaction for a call is an IVR, there are user parameters available which allow the
nextaction IVR to utilize customized messaging for the questions.
Using a WebHook with user parameters param1 with value alpha and param2 with the value bravo is shown below.
<action> <app>ivr</app> <parameters> <id>12345</id> <user_parameters> <param1>alpha</param1> <param2>bravo</param2> </user_parameters> </parameters> </action>
These user parameters can be substituted into the questions of IVR 12345 by using
@param2 within the questions.
When the IVR above is used from the webhook example, @param1 and @param2 will be substituted with the
bravo values for the caller.
The IVR is not restricted to using
param2 and in-fact can support almost any naming convention desired such as
lastname which can then be used similar as shown below.
Using Pass-Through Data
Pass-Through parameters provide a useful way to keep track of data about the history of a particular call. This is similar to how hidden form parameters or cookies are used in a web-based application.
Some IVRs interact with a caller and afterwards send the results back to a web-server. If pass-through parameters are included in the WebHook response, the IVR will send the pass-through parameters back to the web server along with the results from the IVR. The parameters simply "pass through" the IVR and are not shown to the caller in any way.
To use the pass-through parameters you include them in your XML response from a Web Hook in the p_t parameter. The format is a single bar delimiter
| between the
key|value pairs and two pipe delimiters
|| between each
<action> <app>ivr</app> <parameters> <id>12345</id> <user_parameters> <param1>alpha</param1> <param2>bravo</param2> </user_parameters> <p_t>user_id|90786||step|verify_user</p_t> </parameters> </action>
In this example there are two pass-through parameters
- user_id with a value of 90786
- step with a value of verify_user
As mentioned above, the pass through data parameter will be included in every Web Hook request as
ivr_pass_through as described in Available IVR Generated Parameters.
It's possible to pass this data back-and-forth from the web server to DialogTech as many times as needed.
Common Use of Pass-Through Data
The most common use of Pass-Through data is to track failed login or validation attempts. An example would be to put a maximum on the amount of times a user can attempt to enter a PIN on a call to validate with the integrated web-service (Your web-server). Many users enforce a maximum of 3 attempts. When the 3rd attempt fails, the WebHook response is changed to no longer send the caller to the Login IVR and instead transfer the call to a support team or other call-flow.
This stops a caller from attempting to enter a PIN over and over which helps prevent phishing for credentials and also helps prevent a call looping repeatedly within the Login IVR, subsequently using copious amounts of minutes within the DialogTech account.
DialogTech's IVR allows for the configuration of a separate web hook to receive completed transcriptions from recorded IVR questions.
To configure the Transcription Post Back URL, a
Transcription URL must be provided within the Advanced Settings section of the WebHook configuration.
There will be a separate Post Back GET request to the configured URL for each question response that is transcribed. The requests will not always come back in the order that the questions are asked, but instead as each transcription is complete.
The Post Back will not happen unless a transcription is completed, and timing will vary depending on the IVR transcription settings. Human or Human-assisted transcription will take longer than Standard transcriptions.
Included GET Request parameters:
survo_id - Building Block ID of the IVR
unique_id - The Unique respondent ID assigned by DialogTech for the respondent to an IVR.
question - Question number that was transcribed
duration - Length of the recording that was transcribed
date - Date of the transcription
text - Text of the transcription