Setting Up IVR Webhooks

Use an external service to authenticate callers in your IVR flow by setting up a Webhook. 
Important:
This article requires basic knowledge of HTTP servers and Webhooks.

What are IVR Webhooks

In some cases we might want to ask our users to enter an identification number so we can know how to route them further on in the IVR flow. IVR Webhooks allow you to use an external service to provide authentication for such cases.

How Does It Work?

These are the steps that occur when the user reaches a Webhook IVR step:
  1. The caller is requested to enter a number followed by # (with a message configured by you).
  2. The caller enters the number followed by the # key.
  3. A POST HTTP/S request is sent to the external Webhook url defined in IVR settings.
  4. External web-hook returns an HTTP/S response.
  5. According to the response the caller is either directed to another IVR described by the response, or the call is terminated (more on that in the following sections).

Example payload sent to your Webhook:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{ 
  callId: 'f304229f-dc2c-4c84-bc65-90c92a980dd7',
  from: {
      countryCode: "111", number: "444444444"
  },
  user: {
      id: "123abc45-67d8-912e-3fg4-56789h0123456",
      email: "user@domain.com",
      emailStatus: 0,
      creationDate: 1540910161000,
      lastUpdateDate: 1540910161000,
      userType: 2,
      firstName: "User",
      phoneNumbers: [ {countryCode: "111", number: "544444444"} ],
      banned: false,
      uri: "/user/123abc45-67d8-912e-3fg4-56789h0123456",
      fullName: "User User",
      hasEmail: false,
      hasName: false,
      fullPhoneNumbers: [ "111-444444444" ]
  },
  input: "1234"
}

Hook's Response

The response can either be EMPTY or a valid IVR GUID string.

Empty response

An empty response means you are not interested in redirecting the user to another IVR. Therefore
upon receiving an empty response from your Webhook, the call is disconnected.

IVR GUID response

You can return an IVR's GUID as the result from your hook, in which case the ongoing call is redirected to that IVR.

Finding an IVR's GUID

Finding the IVR's ID is easy, all you need to do is navigate to the desired IVR
and copy the <IVR-GUID> part from the browser's URL:
<your-wix-answers-domain>/settings/callcenter/ivrs/<IVR-GUID>

Example Use-Case

A common use-case might be as follows:
  1. A user (caller) calls your Call Center.
  2. The caller is routed to a main menu IVR.
  3. The caller chooses an option that requires authentication.
  4. The caller is routed to the Number Input IVR.
  5. The caller enters his ID number followed by #.
  6. A request is sent to your webhook with the user's details and input.
    1. Your webhook looks up the user in some DB or Server.
    2. If user is found - the webhook checks that the input matches the expected ID.
    3. If the ID matches, the webhook returns a response containing the GUID of some success IVR, otherwise it might return the GUID of some failure IVR.
7. The user is routed to the IVR returned by the webhook.

How you can achieve this in Wix Answers

In order to achieve the above example, we will need to create 4 IVR flows:
  • Main menu IVR - will act as the entry point for the IVR flow, listing the different options.
  • External webhook IVR - will get input from the user and authenticate against the external service.
  • Success IVR - will be redirected to the external service upon successful authentication.
  • Failure IVR - will be redirected to the external service upon unsuccessful authentication.
Having these set up, all that is left to do is create a simple web server that will handle the requests sent to: https://www.external-service.com
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
let users = [
    {id: '602efa31-01d8-482d-8ff2-26910b026703', pass: '1234'},
    {id: '602efa31-01d8-482d-8ff2-26910b026703', pass: '4321'},
]

app.post('/', function (req, res) {
    console.log(req.body)
    let caller = req.body.user;
    let input = req.body.input;

    let dbUser = users.find((user) => user.id === caller.id);
    if (dbUser) {
        // Found user, authenticating password
        if (dbUser.pass === input) {
            // User entered correct password, routing to success IVR
            res.send("5a9e9d0d-6d65-4494-ad7e-0ee7bc7aa064");
        } else {
            // User entered wrong password, routing to failure IVR
            res.send("5a9e9d0d-6d65-4494-ad7e-0ee7bc7aa064");
        }
    } else {
        // Could not find user, disconnecting call
        res.send();
    }
})

app.listen(80, function () {
   console.log("IVR authentication server example");
   console.log("#################################");
})

Related Articles

Setting Up Your IVR Flows

Make a great first impression with callers by customizing their first point of contact with your company - your Interactive Voice Response (IVR) flow. With IVR flows, you determine the paths callers can take to be routed to appropriate queues, phone numbers, or voicemails. Add text to speech or recorded audio messages to your flows to personalize the directions your callers hear.To create a new IVR flow:Hover over Settings  and click Call Center.Click the IVR Flows tab.  Click + Create New IVR Flow.Enter a name for the new IVR flow and click Create. Select the IVR flow you just created under My IVR Flows.Click + Add Welcome Message.Select a message type:Text to speech:Click the drop-down and select a language.Type the message that will be played to your callers.Click Save. Recorded sound file (.WAV, .MP3, .WMP):Click Upload an audio file.Select a file from your computer and click open.Click Save. (Optional): Click + Add Another Message to add more than 1 message. Note: Click the Reorder icon  and drag a message up or down to reorder your messages. Tip:Inform callers about the IVR flow's next actions in your welcome message. For example, if Digit Input is the next action, explain which numbers callers should press to be routed appropriately. Click Add Action.Select the action that occurs next:Route CallTransfer the call to a specific queue, IVR flow, or phone number:Click the Route Call To drop-down and select a routing option:Queue: Click the next drop-down and select the queue calls will be routed to.IVR Flow: Click the next drop-down and select an IVR flow calls will be routed to.Phone Number: Enter a phone number calls will be routed to. Click Done. Hang UpHang up the call. This can be helpful in flows with several Digit Input options. Note: When you add Digit Input actions, if a caller doesn't respond after hearing the flow repeated 2 times, the call hangs up automatically. Digit InputAllow the caller to press a number on their dial pad to select an option:Click the When Caller Presses drop-down and select a number.(Optional) Click + Add Message to add a message that plays after the caller presses the number. See step 7 above for instruction on adding a message. Click the Then drop-down and select the routing option that occurs next.Click Done. Click Add User Input to add more Digit Inputs. Number InputThe caller enters a series of numbers and presses # to be authenticated by your 3rd party application:Enter your Webhook's URL. Learn more about setting up IVR Webhooks.(Optional) Click + Add Message to add a message that plays after the caller presses #. Click Save.Route to VoicemailThe caller can leave a voice message, which creates a new ticket with their message:(Optional) Click to apply any of the following actions to the ticket:Assign ticket to: Click the drop-down and select an agent or group to assign.Set ticket priority to: Click the drop-down and select a priority level to apply.Add labels to ticket: Click the drop-down and select the label(s) to apply. Automatically transcribe voicemail messages: Create text from the recorded voicemail for agents to read on the ticket.  Note: Transcription costs $0.06 per minute, withdrawn from your call credit balance.Click Done.Send Caller Info to CRMThe call details are sent to an external service in order to query the caller's information. This is useful when you need to send customer info to a URL without them inputting anything. Enter the endpoint URL in the field. (Optional) Click + Add Message to add a message that plays after the caller info is sent to the external service. Click Add. 11. Click Save. 

4 min read