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("#################################");
})
IN THIS ARTICLE

Related Articles

Setting Up Call Lines

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

4 min read
Read Article