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
  • Using user parameters
  • Using pass-through data
  • Transcription Postback

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)

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

Target 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 https://www.example.com/listener.php?auth=abc123&qos=5

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.

Include SourceTrak Data
When Include SourceTrak Data is selected, additional IVR Generated Parameters are sent with the WebHook.

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.

(1) For the App findme, either id or phone_list must be provided. If id is provided, phone_list will be ignored.
(2) For the App findme if nextaction is provided, the nextactionitem may be required or not depending on the nextaction selected

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

If the 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 @param1 and @param2 within the questions.

When the IVR above is used from the webhook example, @param1 and @param2 will be substituted with the alpha and bravo values for the caller.

The IVR is not restricted to using param1 and param2 and in-fact can support almost any naming convention desired such as firstname and 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 key|value pair.

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

Transcription Postback

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