{"_id":"59147c45f865370f000b4037","__v":0,"githubsync":"","version":{"_id":"558d9c33beb7c719007f631c","project":"558d9c32beb7c719007f6319","__v":19,"createdAt":"2015-06-26T18:38:43.154Z","releaseDate":"2015-06-26T18:38:43.153Z","categories":["558d9c33beb7c719007f631d","558db0bc7afc102f008ed863","558db0d07afc102f008ed864","558db3c84cd25f0d00b7ecb2","558dbace7afc102f008ed894","558dbd104cd25f0d00b7ecca","558dbd4c4cd25f0d00b7eccb","559d3e858639bd21008e90a6","55bb8ca5a8400c2d00873e70","58fdfb438fbd2819000db9eb","590829c7ade4172d006a87b8","59082a11beedcf0f00235d87","5908bd2cba2afd23007d6d12","5908d1f64f544425002b6aae","591e5e9e2c1b1f0f000fa4e5","5a283434aba91f002834ea86","5a69fe5cde745d002c936c66","5a81e6ef761cf300127317f8","5a81e7d63b1e120012bed5a1"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"project":"558d9c32beb7c719007f6319","user":"58cadf93d223510f005d27db","parentDoc":null,"category":{"_id":"591e5e9e2c1b1f0f000fa4e5","__v":0,"project":"558d9c32beb7c719007f6319","version":"558d9c33beb7c719007f631c","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-05-19T02:55:26.437Z","from_sync":false,"order":6,"slug":"webhooks","title":"Webhooks"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-05-11T14:59:17.018Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"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.\n\nThe 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.\n\nAs 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.\n\nThe following sections will help set up a WebHook for first time use.\n* [Enable the IVR WebHook](doc:webhook-overview#section-enable-the-ivr-webhook)\n* [Determine the WebHook settings](doc:webhook-overview#section-determine-the-webhook-settings)\n* [Available IVR generated parameters](doc:webhook-overview#section-available-ivr-generated-parameters)\n* [Responding to DialogTech's WebHook](doc:webhook-overview#section-responding-to-dialogtechs-webhook)\n* Advanced WebHook features\n  * [Using user parameters](doc:webhook-overview#section-using-user-parameters)\n  * [Using pass-through data](doc:webhook-overview#section-using-pass-through-data)\n  * [Transcription Postback](doc:webhook-overview#section-transcription-postback)\n[block:api-header]\n{\n  \"title\": \"Enable the IVR WebHook\"\n}\n[/block]\nFor 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.\n\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/f6d1662-Screen_Shot_2017-05-11_at_12.31.01_PM.png\",\n        \"Screen Shot 2017-05-11 at 12.31.01 PM.png\",\n        269,\n        118,\n        \"#e1cdc2\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Determine the WebHook Settings\"\n}\n[/block]\nOnce 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.\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/1161570-Screen_Shot_2017-05-11_at_12.38.40_PM.png\",\n        \"Screen Shot 2017-05-11 at 12.38.40 PM.png\",\n        456,\n        350,\n        \"#d8dbd8\"\n      ]\n    }\n  ]\n}\n[/block]\n**Advanced Webhook Actions**\nDetermines how the response from the web server will be handled.\n\n`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.\n\n`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](doc:webhook-overview#section-responding-to-dialogtechs-webhook))*\n\n**Method**\nDetermines the HTTP Method that is used when sending data to the web server\n\n`GET` - DialogTech's IVR response data is included within the URL itself; That information can be read by anyone who can see the URL.\n\n`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.\n\n**Target URL**\nThe 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)\n\n**Call Generated Parameters**\nCall Generated Parameters are the responses to the individual questions within an IVR. The key used for each parameter is defined within the IVR. \n\nFor example, there may be a question within an IVR named `Service Score` with the text\n\n*On a scale of 1 to 5, 5 being the best, how would you rate the service you received?*\n\nThe 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.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/7434ef7-Screen_Shot_2017-05-11_at_1.10.08_PM.png\",\n        \"Screen Shot 2017-05-11 at 1.10.08 PM.png\",\n        475,\n        297,\n        \"#d9dad6\"\n      ]\n    }\n  ]\n}\n[/block]\nUsing 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`\n\n\n[block:api-header]\n{\n  \"title\": \"Available IVR Generated Parameters\"\n}\n[/block]\nIn addition to the *Call Generated Parameters*, the IVR WebHook also includes data points about the call itself on every WebHook.\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter Name\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"ivr_number_called\",\n    \"0-1\": \"The number the caller dialed (assuming an inbound call) to reach this IVR. Also known as \\\"DNIS.\\\"\",\n    \"1-0\": \"ivr_caller_id\",\n    \"1-1\": \"Caller ID, if known, of the IVR respondent.\",\n    \"2-0\": \"ivr_id\",\n    \"2-1\": \"The building block ID of the IVR\",\n    \"3-0\": \"ivr_response_id\",\n    \"3-1\": \"The Unique respondent ID assigned by DialogTech for the respondent to an IVR.\",\n    \"4-0\": \"ivr_timestamp\",\n    \"4-1\": \"Time stamp of start of user interaction with IVR.\",\n    \"5-0\": \"ivr_pass_through\",\n    \"5-1\": \"Data you passed to the IVR which is passed back to the web server. *(see: [Using pass-through data](doc:webhook-overview#section-using-passthrough-data))*\",\n    \"6-0\": \"ivr_session_id\",\n    \"6-1\": \"Unique DialogTech assigned identifier for the call\",\n    \"7-0\": \"ivr_completed\",\n    \"8-0\": \"ivr_call_result\",\n    \"9-0\": \"ivr_monitored_time\",\n    \"10-0\": \"ivr_opted_out\",\n    \"7-1\": \"True/False flag identifying if the IVR was completed in its entirety. False typically indicates a caller disconnected before completing the IVR.\",\n    \"8-1\": \"Outbound call results for an outbound IVR.\",\n    \"9-1\": \"Duration of any `Monitored (recorded)` call transfer from an IVR.\",\n    \"10-1\": \"Opt Out Selection\",\n    \"11-0\": \"ivr_phone_label\",\n    \"11-1\": \"The phone label assigned to the `ivr_number_called`\"\n  },\n  \"cols\": 2,\n  \"rows\": 12\n}\n[/block]\n**Include SourceTrak Data**\nWhen Include SourceTrak Data is selected, additional IVR Generated Parameters are sent with the WebHook.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter Name\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"st_rank\",\n    \"1-0\": \"st_search_term\",\n    \"2-0\": \"st_referrer\",\n    \"3-0\": \"st_baseuri\",\n    \"4-0\": \"st_activity_keyword\",\n    \"5-0\": \"st_displayed_timestamp\",\n    \"6-0\": \"st_ip_address\",\n    \"7-0\": \"st_document_title\",\n    \"8-0\": \"st_browser\",\n    \"9-0\": \"st_os\",\n    \"10-0\": \"st_ibp_custom\",\n    \"11-0\": \"st_ibp_unique_id\",\n    \"12-0\": \"st_pid\",\n    \"13-0\": \"st_domain_set_id\",\n    \"14-0\": \"st_gclid\",\n    \"15-0\": \"st_google_ua_client_id\",\n    \"16-0\": \"st_pool_name\",\n    \"17-0\": \"st_location_name\",\n    \"18-0\": \"st_sourceguard\",\n    \"19-0\": \"st_campaign\",\n    \"20-0\": \"st_platform\",\n    \"21-0\": \"st_url_tag\",\n    \"21-1\": \"The SourceTrak tracked URL Parameter that lead to the phone call\",\n    \"20-1\": \"Ad Platform captured by SourceTrak session or default value set in SourceTrak configuration.\",\n    \"19-1\": \"Ad Campaign captured by SourceTrak session or default value set in SourceTrak configuration.\",\n    \"18-1\": \"Indicates if call was to a SourceGuard number.\",\n    \"17-1\": \"When displaying multiple numbers using SourceTrak Multi-Location on a page, indicates which SourceTrak Location received the call.\",\n    \"16-1\": \"SourceTrak pool name for the number called.\",\n    \"15-1\": \"Google Universal Analytics assigned Client ID captured during the SourceTrak session.\",\n    \"14-1\": \"Google Click ID captured from a Google Adwords visit.\",\n    \"13-1\": \"ID of the SourceTrak Domain Set for the number called.\",\n    \"12-1\": \"Unique identifier for a SourceTrak session.\",\n    \"11-1\": \"Optional custom data passed into SourceTrak.\",\n    \"10-1\": \"Optional custom data passed into SourceTrak.\",\n    \"9-1\": \"Operating system used during SourceTrak session.\",\n    \"8-1\": \"Web Browser used during SourceTrak session.\",\n    \"7-1\": \"Title of the initial page view during SourceTrak session.\",\n    \"6-1\": \"The IP address of the visitor during SourceTrak session.\",\n    \"5-1\": \"The date and time (listed in Eastern time) that the SourceTrak phone number was first displayed on your website for the visitor.\",\n    \"4-1\": \"The SourceTrak pool activity that triggered the number display.\",\n    \"3-1\": \"The landing page of your website where the SourceTrak phone number was initially displayed.\",\n    \"2-1\": \"The referring domain that resulted in the display of a phone number on your website.\",\n    \"1-1\": \"The literal search string (keywords) that resulted in the display of a phone number on your website.\",\n    \"0-1\": \"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.\"\n  },\n  \"cols\": 2,\n  \"rows\": 22\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Responding to DialogTech's WebHook\"\n}\n[/block]\nWhen Method of a WebHook is set to `Retrieve next action` the IVR expects to receive an XML-formatted response.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<action>\\n\\t<app>ivr</app>\\n\\t<parameters>\\n\\t\\t<id>12345</id>\\n\\t\\t<user_parameters>\\n\\t\\t\\t<param1>alpha</param1>\\n\\t\\t\\t<param2>bravo</param2>\\n\\t\\t</user_parameters>\\n\\t\\t<p_t>my pass through data</p_t>\\n\\t</parameters>\\n</action>\",\n      \"language\": \"xml\",\n      \"name\": \"Example Response\"\n    }\n  ]\n}\n[/block]\nAn \"action\" element is required, at minimum, or the IVR will fail to complete and the **Backup Routing** set in the portal will be triggered.\n\nThe \"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.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"App\",\n    \"h-1\": \"Parameter\",\n    \"h-2\": \"Description\",\n    \"h-3\": \"Required\",\n    \"0-0\": \"ivr\",\n    \"0-1\": \"id\",\n    \"0-2\": \"If `id` is provided the call will transfer to the IVR with the appropriate `id`\",\n    \"0-3\": \"Yes\",\n    \"2-0\": \"ivr\",\n    \"2-1\": \"user_parameters\",\n    \"2-2\": \"*(see: [Using user parameters](doc:webhook-overview#section-using-user-parameters))*\",\n    \"2-3\": \"No\",\n    \"3-0\": \"findme\",\n    \"3-1\": \"id\",\n    \"3-2\": \"If `id` is provided the call will transfer to the FindMe with the appropriate `id`\",\n    \"3-3\": \"Yes (1)\",\n    \"4-0\": \"findme\",\n    \"4-1\": \"phone_list\",\n    \"4-3\": \"Yes*\",\n    \"4-2\": \"A pipe delimited list of phone numbers to try in the order specified on a Dynamic FindMe *(i.e. `<phone_list>2223334444|5556667777<phone_list>`)*\",\n    \"5-0\": \"findme\",\n    \"5-1\": \"simultaneous\",\n    \"5-2\": \"Determines the number of simultaneous calls to make to the various numbers in the FindMe list.\",\n    \"5-3\": \"No\",\n    \"6-0\": \"findme\",\n    \"6-1\": \"record\",\n    \"7-0\": \"findme\",\n    \"7-1\": \"screen_method\",\n    \"8-0\": \"findme\",\n    \"8-1\": \"whisper_phrase\",\n    \"9-0\": \"findme\",\n    \"9-1\": \"whisper_audio\",\n    \"10-0\": \"findme\",\n    \"10-1\": \"auto_accept\",\n    \"6-2\": \"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.\",\n    \"6-3\": \"No\",\n    \"7-2\": \"**0** - Record the caller's name (default)\\n**1** - Whisper the `whisper_phrase` value using text-to-speech\\n**2** - Whisper the audio file provided via `whisper_audio` *(note: The audio file must be an existing audio file within the account)*\",\n    \"8-2\": \"Phrase spoken to person who answers phone\\n\\nTo be used with `screen_method` *(default is no phrase)*\",\n    \"9-2\": \"The name of an audio file in your Whisper Phrase Audio files folder\\n\\nTo be used with `screen_method`\",\n    \"10-2\": \"Determines how the recipient of the call will be prompted (or not) to accept the call\\n\\n**0** - Agent will be prompted to accept the call *(note: can be used with `dtmf_only` to require a keypress to accept the call)*\\n**1** - The first number that answers, receives the call without any option to accept/deny the call\\n**2** - The last number attempted will be sent the call. Call screening will be disabled if transferred in this way.\\n**3** - The last number attempted will be sent the call. Call screening will remain enabled if transferred in this way.\",\n    \"10-3\": \"No\",\n    \"7-3\": \"No\",\n    \"8-3\": \"No\",\n    \"9-3\": \"No\",\n    \"14-0\": \"vr\",\n    \"14-1\": \"id\",\n    \"15-0\": \"voicemail\",\n    \"15-1\": \"id\",\n    \"16-0\": \"hangup\",\n    \"17-0\": \"transfer\",\n    \"17-1\": \"destination\",\n    \"16-2\": \"Hangs up the call\",\n    \"14-3\": \"Yes\",\n    \"15-3\": \"Yes\",\n    \"17-3\": \"Yes\",\n    \"14-2\": \"If `id` is provided the call will transfer to the virtual receptionist with the appropriate `id`\",\n    \"15-2\": \"If `id` is provided the call will transfer to the voicemail with the appropriate `id`\",\n    \"17-2\": \"Transfers the call to the `destination` provided\",\n    \"16-3\": \"*n/a*\",\n    \"16-1\": \"*n/a*\",\n    \"11-0\": \"findme\",\n    \"11-1\": \"nextaction\",\n    \"11-3\": \"No\",\n    \"12-0\": \"findme\",\n    \"12-1\": \"nextactionitem\",\n    \"12-3\": \"No (2)\",\n    \"11-2\": \"Determines what happens if no numbers in the FindMe answer *(see table below)*\",\n    \"12-2\": \"Determines what happens if no numbers in the FindMe answer *(see table below)*\",\n    \"13-0\": \"findme\",\n    \"13-1\": \"timeout\",\n    \"13-2\": \"Determines the **No Answer Timeout** for the FindMe list recipients\\n\\n*Can be between 20 and 60 seconds. Default is 30 seconds*\",\n    \"13-3\": \"No\",\n    \"1-0\": \"ivr\",\n    \"1-1\": \"question_id\",\n    \"1-2\": \"If `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)*\",\n    \"1-3\": \"No\"\n  },\n  \"cols\": 4,\n  \"rows\": 18\n}\n[/block]\n(1) For the App `findme`, either `id` or `phone_list` must be provided. If `id` is provided, `phone_list` will be ignored.\n(2) For the App `findme` if `nextaction` is provided, the `nextactionitem` may be required or not depending on the `nextaction` selected\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Action Description\",\n    \"h-1\": \"nextaction Value\",\n    \"h-2\": \"nextactionitem Value\",\n    \"0-0\": \"If unable to connect, telluser no one is available and disconnect (default).\",\n    \"0-1\": \"1\",\n    \"0-2\": \"*(not required)*\",\n    \"1-1\": \"2\",\n    \"2-1\": \"3\",\n    \"3-1\": \"4\",\n    \"4-1\": \"5\",\n    \"5-1\": \"6\",\n    \"6-1\": \"7\",\n    \"1-0\": \"If unable to connect, transfer to Voice Mail.\",\n    \"1-2\": \"Voicemail Building Block ID\",\n    \"2-0\": \"Automatically accept the call on the last number tried.\",\n    \"2-2\": \"*(not required)*\",\n    \"3-0\": \"If unable to connect, route to a Virtual Receptionist.\",\n    \"3-2\": \"Virtual Receptionist Building Block ID\",\n    \"4-0\": \"If unable to connect, route to a FindMe.\",\n    \"5-0\": \"If unable to connect, route to an IVR.\",\n    \"4-2\": \"FindMe Building Block ID\",\n    \"5-2\": \"IVR Building Block ID\",\n    \"6-0\": \"Automatically accept call on last number tried without screening.\",\n    \"6-2\": \"*(not required)*\"\n  },\n  \"cols\": 3,\n  \"rows\": 7\n}\n[/block]\nBelow is an example response for using a Dynamic FindMe that calls a single number, has a whisper message and records the call.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<action>\\n\\t<app>findme</app>\\n\\t<parameters>\\n\\t\\t<phone_list>2223334444</phone_list>\\n\\t\\t<screen_method>1</screen_method>\\n\\t\\t<whisper_phrase>Call from Radio Ad</whisper_phrase>\\n\\t\\t<record>1</record>\\n\\t</parameters>\\n</action>\",\n      \"language\": \"xml\",\n      \"name\": \"Webhook - Dynamic FM Example 1\"\n    }\n  ]\n}\n[/block]\nBelow is an example response for using a Dynamic Find Me that calls two numbers simultaneously, has a whisper audio message and records the call.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<action>\\n\\t<app>findme</app>\\n\\t<parameters>\\n\\t\\t<phone_list>2223334444|5556667777</phone_list>\\n\\t\\t<simultaneous>2</simultaneous>\\n\\t\\t<screen_method>2</screen_method>\\n\\t\\t<whisper_audio>customwhisper.wav</whisper_audio>\\n\\t\\t<record>1</record>\\n\\t</parameters>\\n</action>\",\n      \"language\": \"xml\",\n      \"name\": \"Webhook - Dynamic FM Example 2\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Using User Parameters\"\n}\n[/block]\nIf 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.\n\nUsing a WebHook with user parameters *param1* with value *alpha* and *param2* with the value *bravo* is shown below.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<action>\\n\\t<app>ivr</app>\\n\\t<parameters>\\n\\t\\t<id>12345</id>\\n\\t\\t<user_parameters>\\n\\t\\t\\t<param1>alpha</param1>\\n\\t\\t\\t<param2>bravo</param2>\\n\\t\\t</user_parameters>\\n\\t</parameters>\\n</action>\",\n      \"language\": \"xml\",\n      \"name\": \"Example Response\"\n    }\n  ]\n}\n[/block]\nThese user parameters can be substituted into the questions of IVR 12345 by using `:::at:::param1` and `@param2` within the questions.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/107a29a-Screen_Shot_2017-05-11_at_2.50.00_PM.png\",\n        \"Screen Shot 2017-05-11 at 2.50.00 PM.png\",\n        732,\n        291,\n        \"#f1f0ee\"\n      ]\n    }\n  ]\n}\n[/block]\nWhen the IVR above is used from the webhook example, @param1 and @param2 will be substituted with the `alpha` and `bravo` values for the caller.\n\nThe 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.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/031559f-Screen_Shot_2017-05-11_at_2.52.43_PM.png\",\n        \"Screen Shot 2017-05-11 at 2.52.43 PM.png\",\n        736,\n        289,\n        \"#f1f1ee\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Using Pass-Through Data\"\n}\n[/block]\nPass-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.\n\nSome 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.\n\nTo 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<action>\\n\\t<app>ivr</app>\\n\\t<parameters>\\n\\t\\t<id>12345</id>\\n\\t\\t<user_parameters>\\n\\t\\t\\t<param1>alpha</param1>\\n\\t\\t\\t<param2>bravo</param2>\\n\\t\\t</user_parameters>\\n\\t\\t<p_t>user_id|90786||step|verify_user</p_t>\\n\\t</parameters>\\n</action>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nIn this example there are two pass-through parameters\n* *user_id* with a value of *90786*\n* *step* with a value of *verify_user*\n\nAs 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](doc:webhook-overview#section-available-ivr-generated-parameters).\n\nIt's possible to pass this data back-and-forth from the web server to DialogTech as many times as needed.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Common Use of Pass-Through Data\",\n  \"body\": \"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.\\n\\nThis 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.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Transcription Postback\"\n}\n[/block]\nDialogTech's IVR allows for the configuration of a separate web hook to receive completed transcriptions from recorded IVR questions.\n\nTo configure the Transcription Post Back URL, a `Transcription URL` must be provided within the *Advanced Settings* section of the WebHook configuration.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0a070ef-Screen_Shot_2017-05-11_at_3.17.23_PM.png\",\n        \"Screen Shot 2017-05-11 at 3.17.23 PM.png\",\n        466,\n        288,\n        \"#343d6a\"\n      ]\n    }\n  ]\n}\n[/block]\nThere 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.\n\nThe 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.\n\nIncluded GET Request parameters:\n\n`survo_id` - Building Block ID of the IVR\n`unique_id` - The Unique respondent ID assigned by DialogTech for the respondent to an IVR.\n`question` - Question number that was transcribed\n`duration` - Length of the recording that was transcribed\n`date` - Date of the transcription\n`text` - Text of the transcription","excerpt":"WebHooks are used to integrate call-flows directly with an external web-service","slug":"webhook-overview","type":"basic","title":"IVR WebHooks"}

IVR WebHooks

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.

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.

Parameter Name
Description

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 Monitored (recorded) call transfer from an IVR.

ivr_opted_out

Opt Out Selection

ivr_phone_label

The 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 Name
Description

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.

App
Parameter
Description
Required

ivr

id

If id is provided the call will transfer to the IVR with the appropriate id

Yes

ivr

question_id

If 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

ivr

user_parameters

No

findme

id

If id is provided the call will transfer to the FindMe with the appropriate id

Yes (1)

findme

phone_list

A 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*

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

findme

whisper_phrase

Phrase spoken to person who answers phone

To be used with screen_method (default is no phrase)

No

findme

whisper_audio

The name of an audio file in your Whisper Phrase Audio files folder

To be used with screen_method

No

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

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

No

vr

id

If id is provided the call will transfer to the virtual receptionist with the appropriate id

Yes

voicemail

id

If id is provided the call will transfer to the voicemail with the appropriate id

Yes

hangup

n/a

Hangs up the call

n/a

transfer

destination

Transfers the call to the destination provided

Yes

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

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