API & DOCS

My Account            

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

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.

269269

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.

456456

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.

475475

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.

Parameter NameDescription
ivr_number_calledThe number the caller dialed (assuming an inbound call) to reach this IVR. Also known as "DNIS."
ivr_caller_idCaller ID, if known, of the IVR respondent.
ivr_idThe building block ID of the IVR
ivr_response_idThe Unique respondent ID assigned by DialogTech for the respondent to an IVR.
ivr_timestampTime stamp of start of user interaction with IVR.
ivr_pass_throughData you passed to the IVR which is passed back to the web server. (see: Using pass-through data)
ivr_session_idUnique DialogTech assigned identifier for the call
ivr_completedTrue/False flag identifying if the IVR was completed in its entirety. False typically indicates a caller disconnected before completing the IVR.
ivr_call_resultOutbound call results for an outbound IVR.
ivr_monitored_timeDuration of any Monitored (recorded) call transfer from an IVR.
ivr_opted_outOpt Out Selection
ivr_phone_labelThe phone label assigned to the ivr_number_called

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

Parameter NameDescription
st_rankA 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_termThe literal search string (keywords) that resulted in the display of a phone number on your website.
st_referrerThe referring domain that resulted in the display of a phone number on your website.
st_baseuriThe landing page of your website where the SourceTrak phone number was initially displayed.
st_activity_keywordThe SourceTrak pool activity that triggered the number display.
st_displayed_timestampThe date and time (listed in Eastern time) that the SourceTrak phone number was first displayed on your website for the visitor.
st_ip_addressThe IP address of the visitor during SourceTrak session.
st_document_titleTitle of the initial page view during SourceTrak session.
st_browserWeb Browser used during SourceTrak session.
st_osOperating system used during SourceTrak session.
st_ibp_customOptional custom data passed into SourceTrak.
st_ibp_unique_idOptional custom data passed into SourceTrak.
st_pidUnique identifier for a SourceTrak session.
st_domain_set_idID of the SourceTrak Domain Set for the number called.
st_gclidGoogle Click ID captured from a Google Adwords visit.
st_google_ua_client_idGoogle Universal Analytics assigned Client ID captured during the SourceTrak session.
st_pool_nameSourceTrak pool name for the number called.
st_location_nameWhen displaying multiple numbers using SourceTrak Multi-Location on a page, indicates which SourceTrak Location received the call.
st_sourceguardIndicates if call was to a SourceGuard number.
st_campaignAd Campaign captured by SourceTrak session or default value set in SourceTrak configuration.
st_platformAd Platform captured by SourceTrak session or default value set in SourceTrak configuration.
st_url_tagThe 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.

AppParameterDescriptionRequired
ivridIf id is provided the call will transfer to the IVR with the appropriate idYes
ivrquestion_idIf question_id is provided, and is is associated with the provided id of the IVR the call will transfer to the IVR with the appropriate id in addition to starting the IVR at the question associated with the question_id. (Note: question_id can be found in the IVR Setup screen, after a webhook has been saved)No
ivruser_parameters(see: Using user parameters)No
findmeidIf id is provided the call will transfer to the FindMe with the appropriate idYes (1)
findmephone_listA pipe delimited list of phone numbers to try in the order specified on a Dynamic FindMe (i.e. <phone_list>2223334444|5556667777<phone_list>)Yes*
findmesimultaneousDetermines the number of simultaneous calls to make to the various numbers in the FindMe list.No
findmerecordUse 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
findmescreen_method0 - Record the caller's name (default)
1 - Whisper the whisper_phrase value using text-to-speech
2 - Whisper the audio file provided via whisper_audio (note: The audio file must be an existing audio file within the account)
No
findmewhisper_phrasePhrase spoken to person who answers phone

To be used with screen_method (default is no phrase)
No
findmewhisper_audioThe name of an audio file in your Whisper Phrase Audio files folder

To be used with screen_method
No
findmeauto_acceptDetermines 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 dtmf_only to require a keypress to accept the call)
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.
No
findmenextactionDetermines what happens if no numbers in the FindMe answer (see table below)No
findmenextactionitemDetermines what happens if no numbers in the FindMe answer (see table below)No (2)
findmetimeoutDetermines the No Answer Timeout for the FindMe list recipients

Can be between 20 and 60 seconds. Default is 30 seconds
No
vridIf id is provided the call will transfer to the virtual receptionist with the appropriate idYes
voicemailidIf id is provided the call will transfer to the voicemail with the appropriate idYes
hangupn/aHangs up the calln/a
transferdestinationTransfers the call to the destination providedYes

(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

Action Descriptionnextaction Valuenextactionitem Value
If unable to connect, telluser no one is available and disconnect (default).1(not required)
If unable to connect, transfer to Voice Mail.2Voicemail Building Block ID
Automatically accept the call on the last number tried.3(not required)
If unable to connect, route to a Virtual Receptionist.4Virtual Receptionist Building Block ID
If unable to connect, route to a FindMe.5FindMe Building Block ID
If unable to connect, route to an IVR.6IVR 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

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.

732732

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.

736736

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.

466466

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