IVR Web Hook

Introduction

An IVR Web Hook allows you to transfer data from a phone call to your web server. You can pass along the answers to any non-recorded IVR questions as well as information such as the Caller ID, time stamp, the number dialed and more.

The data is sent to your server using the standard HTTP POST or GET methods, just as if someone had filled out a form on your website and submitted it. You can send back an XML response 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.

The best part is you can continue to use the programming language of your choice to construct all of the business logic on your server. We simply send you the data as an HTTP POST or GET request and you respond with a small chunk of XML.

This guide will walk you through the process of setting up a Web Hook for an IVR, how to configure it to send the data to your web server, and what types of responses you can send back.

Setting up the IVR Web Hook

For each IVR that you set up you can select where to send the results. This is the action that will happen as soon as the IVR has ended. This document will focus on the ‘My web server’ (Web Hook) option. Click the checkbox and we’ll configure the settings next.

The ‘Webhook Settings” tab is on the top right of the IVR screen.

See the expanded "Webhook Settings" Tab below:

Advanced Webhook Actions

The first menu, Advanced Webhook Actions, is where you select what you want to happen after we send the IVR data to your web server. Each option is explained below:

• Retrieve message and read to user - In response to its HTTP(S) request, the IVR expects to receive HTML or text, which it will then read to the user using text-to-speech.
• Retrieve next action - In response to its HTTP(S) 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.

The first option is fairly straight forward. The IVR will pass the data to your server and your response will be read to the user. The real power lies in the second option to Retrieve next action. We will cover those actions in a moment, but first let's continue configuring the Web Hook.

Method

The Method can be either GET or POST. Select the method that works best for you.

• GET includes the information in the URL itself; this is by far the most common method of writing a URL. GET puts all information into the URL, actually as part of the URL itself, and that information can be read by anyone who can see the URL.
• The other method to send information via HTTP is through POST, in which the information is transmitted separately from the URL. Using POST is a bit more difficult as it requires some HTML coding or some programming. On the other hand, by using POST you can send information securely, because the information isn't part of the URL.

Target URL

The Target URL is the full URL for your server. In the example above it is "http://www.example.com". You can include a specific page and/or static parameters in the URL.

"Call Generated Parameters": The Dynamic Parameters

This is the heart of the IVR. Dynamic parameters include the answers that users give to your questions.

To use the Call-Generated parameters start by clicking "add parameter". Your server will receive the parameter, so make it something that's sensible for you -- and then select the value for the parameter from the drop-down list.

The IVR webhook also includes important information about the call itself, such as when it happened and the caller ID of the caller. These values will be automatically included in the webhook request and are listed in the table below.

Include SourceTrak Data

Response to the IVR Web Hook from Your Server

As we stated just above, the "Advanced Web Hook Action" can have one of two values. You can set the IVR web hook request to expect a next action or you can set it to expect text to read.

If you set it to "Retrieve next action," the IVR expects to receive an XML-formatted response.

The response will be formatted as follows:

An "action" element is required, at minimum, or the IVR will fail to complete.

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. This next table gives the possible values of the "app" parameter; the names of any elements in the "parameters" element that are associated with that value of "app," and what it all means.

If you would like to use dynamic wav files in your IVR prompts based on a Web Hook response, see this guide for configuring Custom Audio Prompts within IVR.

"app" value	Parameters: name(s)	What it means
SurVo	id (Required)	IVR will transition call to a different IVR with given "id." See below for other data you can send. 'SurVo' must be used as the value, but you may include an IVR id.
findme	id (for pre-configured Find Me in your account)	If "id" is given, IVR will transition to a Find Me with given "id." If 'phone_list' is provided a Dynamic Find me will be used. The configuration items below will determine the configuration of the Dynamic Find me.
findme	phone_list (if you want to use a Dynamic Find me)	A "|" delimited list of phone numbers to try in the order specified on your Dynamic Find Me
findme	simultaneous	# of Simultaneous Calls.
findme	nextaction (optional)	Findme configuration option. See table below.
findme	nextactionitem (depends on nextaction)	Findme configuration option. See table below.
findme	record (optional)	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.
findme	screen_method (optional)	Call Screening Method. 0 = Record Caller's Name, 1 = Whisper Text, 2 = Whisper Audio, 3 = No Screening.
findme	whisper_phrase (optional, with screen_method 1)	Text whisper read to the Find Me recipient.
findme	whisper_audio (optional, with screen_method 2)	Audio file whisper played to the Find Me recipient. WAV file must be uploaded to 'Whisper Phrase Audio' directory under Audio File Mainenance in your account.
findme	auto_accept (optional)	0 = Disabled, 1 = First answered call, 2 = Last number tried with screening, 3 = Last number tried without screening.
vr	id	IVR will transition call to a Virtual Receptionist with given "id."
voicemail	id	IVR will transition call to a Voicemail Box with given "id."
hangup		Hangs up the call.
transfer	destination	Transfers call to phone number.

Values of "nextaction" and "nextactionitem" parameters for Dynamic Find Me
Custom Action	nextaction Value	nextactionitem Value (if required)
If unable to connect, telluser no one is available and disconnect (default).	1	(not required)
If unable to connect, transfer to Voice Mail.	2	Voice Mail 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 ID
If unable to connect, route to a Find Me.	5	Find Me ID
If unable to connect, route to an IVR.	6	IVR ID
Automatically accept call on last number tried without introduction.	7	(not required)

Below is an example response for using a Dynamic Find Me that calls a single number, has a whisper message and records the call.

The response will be formatted as follows:

Here is an example response for using a Dynamic Find Me that calls two numbers simultaneously, has a whisper audio message and records the call.

The response will be formatted as follows:

User Parameters

If the next action is an IVR, you can use the parameters element to send the next IVR any user parameters. In the example of "action" we saw above, the IVR with ID 75 will receive user parameters of param1 with value1 and param2 with value2. These user parameters can be substituted into the text of outgoing announcements just as explained above. The "p_t" element of the parameters element will contain any pass-through data, as previously discussed.

In the XML response you send back to an IVR you can include user parameters to be used in another IVR. These parameters can contain information to be read back to a user or a phone number to transfer the caller to. Here is an example using a users first and last name with a number to transfer to:

To use these parameters in an IVR question you simply put the '@' symbol in front of the parameter name, such as @firstName. The example below shows an IVR question filled out with the parameters used in the XML response above.

The first and last name "Bill Johnson" will be inserted into the text that is read back to the caller using text-to-speech.

If you would like to use dynamic wav files in your IVR prompts based on a Web Hook response, see this guide for configuring Custom Audio Prompts within IVR.

Pass-through Data

"Pass-through" parameters provide a useful way for you to keep track of data about the history of a particular call, the same way you might use hidden form parameters or cookies in a web-based application.

What are "pass-through" parameters? Some IVRs interact with a caller and afterwards send the results back to your servers. If you send pass-through parameters to the IVR when you make your web request, the IVR will send the pass-through parameters back to your servers along with the results. The parameters "pass through" the IVR.

To use the pass-through parameters you include them in your XML response from a Web Hook in the p_t parameter. From the example above:

In this example we are passing back two parameters: "user_id" with a value of "12345" and "step" with a value of "call_user". Notice there is a single bar delimiter between the key|value pairs and two bars || between each set of key|values.

As mentioned above, the Passthrough data parameter will be included in every Web Hook request as 'ivr_pass_through'.

When this second IVR completes it will send the pass-through data back to your server.

An example of how this might be useful is for maintaining a users account number for the life of a call. Say you have an IVR that asks a user for their account number and PIN. At the end of the IVR you do a NetGet to your server for validation. Assuming the account number and PIN were valid you could send an XML response to direct the user to another IVR and include their account number in the passthrough data. The next IVR might offer the user some options like checking their balance or making a payment. When the user selects an option the Web Hook from this IVR will pass back their response along with the passthrough data, in this case their account number. Since you have the users account number you will not need to ask for that data again.

You can continue to "pass" this data back and forth from IVR to your server and back to another IVR as many times as necessary on a call and use it at any time you need.

Transcription Post Back

IVR allows for the configuration of a separate web hook to receive completed transcriptions from recorded IVR questions.

Configuration of the Transcription Post Back simply requires a URL for the receiving web service that will handle the transcription text data. To configure the URL, click on "Advanced Settings" under the IVR Web Hook 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 your transcription settings. Human or Human-assisted transcription will take longer than Standard transcriptions.