Get started

Prerequisites

• Advanced Nodes activated.
• An API point to reach your customer database e.g. http://yourcompany.azurewebsites.net/api/reportAbsence.
• Access token to the API (if needed by your system).

Create new IVR or use existing

• If this is your first IVR, please refer to the support page for info on how to set up an IVR with standard nodes: How to set up your PBX services.
  
  
• The image to the right is an example of a complete IVR setup to cater for this use case. Use this as a reference to create your own IVR flow in the admin portal.
  
  
• The following steps will go through the setup of the Advanced nodes marked with green in the IVR flow.
  
  

Enter identifying number

Add Save Keypad Input node

Choose an empty box in your IVR and click Advanced > Save keypad input to add the node. 

Two nodes need to be added, one for each previous IVR option. The IVR options in this example would be “Report sick leave” and “Report care of sick child”. 

This node will let the caller enter either their employee number or their social security number to verify their identity in the upcoming HTTP request.

Variable name

Name of the variable where the digits will be saved, in this case we will call it identifier.

Sound that is played

Add a phrase prompting the caller to enter their identifier. It could be something along the lines of: 

"Enter either your personal number, 12 digits, or your employee number, 10 digits, and end with pound(#)". 

Since you record this sound yourselves you can customise it however you like! 

Minimum and maximum digits

Specifying how many digits a valid number must have allows for feedback to the user about an incomplete number already at this stage. The HTTP request will not be executed if the number is invalid.

Report absence to external system

Add HTTP Request node

Choose an empty box in your IVR and click Advanced > HTTP-request to add the node.

Two HTTP nodes will be added, one for the IVR choice “sick leave” and one for “care of sick child”. The node will send a request to an external system, such as Microsoft Azure, containing the identifier which was entered previously. The external system might be set up to retrieve the supervisor’s information based on the identifier, and send them an SMS and an email. The system will also answer with a code which lets us know if the request was successful or not.

URL

Enter the URL address to the HTTP request. To include the identifier write {identifier}.

Keep in mind that the request is sent from Telavox network which means that the system needs to allow requests made from the network 80.83.208.0/20. 

What is a HTTP request?
HTTP works as a request-response protocol between a client and a system. What information you can receive from the system, and how to reach it, is specified in its API.

This example requires an API point which can accept a request containing an identifying number and send back a response of whether the absence report was successful or not. The system that the request is sent to could be your own, or the API of a supplier that you use, such as Microsoft Azure.

Variable name

Choose what you would like to call the response from the HTTP request. The more accurate the description the easier it will be to understand in the next node, when we will use it.

The variable that is saved here can be accessed later in other Advanced nodes or in a Call Widget. A Call Widget can display information about a call to the agent answering it.

What will my response be?
What the response will be can differ, depending on the design of your API. In this example the response is either 0 or 1 where 0 means that the request was a success, and 1 means that no employee with that number was found. 

JSON-Path

Choose this based on what format the response from the API will be in.

If the response from your system is already exactly what you want to save in the variable, such as “0” or “1” in this case, then no need to write a JSON-Path. 

But if the response is an object of information, where you need to extract the specific part needed for the variable, then enter the path to that part here.

Example of a JSON object:
{

    “customer”: {

        “name”: “John Doe”,

        “phoneNumber”: “+46706170786”,

      }

}

To save the phoneNumber part in the variable, enter customer.phoneNumber as JSON-Path.

HTTP Method

Specify which method the API endpoint uses, either GET or POST.

In this example we use POST since that is the standard method for a request that sends information to make an update in the system.

When do I use GET?
GET is used when information is gathered only to be displayed, and no alters are made in the other system.

Request Content-type

This option will present itself when choosing POST. This is the format in which the following variables will be sent in the HTTP request. Check your API specification to find out what it should be.

Post variables

This option will also present itself when choosing POST. Here the identifier (social security number or employee number) will be added to the request, followed by the reason for the absence. This could e.g. be a number code, corresponding to either sick leave or care of sick child, depending on which of the HTTP nodes it’s added to.

HTTP Headers

Here you get the option to input headers into the request if they are required by your system. This could be for authentication purposes for example. Another way to authenticate without using headers is to make sure the firewall of your service allows requests made from 80.83.208.0/20.

Once you have entered a Name and a Value, click the button to add this header to the request. You can add several headers.

Are there any limitations of what I can send in a header?
It’s not possible to send nested objects/JSON, only one plain text Name and Value per header.

We do not support OAuth which is an authentication method used in e.g. Microsoft Dynamics. It requires a token being sent back and forward which is not possible in Advanced Nodes.

Choose which pre-recorded message to play

Add Condition node

Choose an empty box in your IVR and click Advanced > Condition to add the node.

In this node we will check if the response from the HTTP request means that the absence request was successful or not. One Condition node needs to be added for each HTTP node. The condition node will be followed by a Hang up node, which will play a pre-recorded message. 

The different messages could be: 

0: “Thank you, your sick leave has successfully been reported to your manager. Please call back tomorrow if you need to report another day. Take care and get well soon! ”

1: “Sorry, no employee with that social security number could be found in the system. Please try again or call the administrator if you are still having trouble.”

f: “Due to a technical error the absence report could not be handled automatically and has been cancelled. Please call your manager instead to let them know that you are sick.”

Variable name

Enter the name of the variable that this node should check, in this example responseCode.

Conditions

There are several different types of conditions. Click on Read more to learn about them and choose the option that fits your needs.

In this example the response from the API is either “0” if the absence report was a success, or “1” if it failed because no employee with that identification number was found. The request can also fail for other reasons, which will then be catched in the f-node. Here we choose EqualTo and set the values to 0 and 1.

EqualTo or Contains?
Choose EqualTo when the variable must match the value exactly. Contains is used when the value must be found in the variable as a part of it. E.g. +46123123123 contains +46.

What do I do if I need to add 100 different EqualTo conditions?

Each condition needs to be added manually, but instead of adding that many conditions there are some options to consider. 

• If you find yourself needing to add 100 different conditions, you might want to create an API endpoint in your system and use the HTTP node instead. The endpoint would then receive the number and can return a corresponding response from your database, for example the number of the correct queue to send the call to.
• If you have a number series that should all have the same outcome, e.g. number 1-5 should all lead to the external support queue, you can use GreaterThanOrEqual and LessThanOrEqual instead of EqualTo. Use two conditions-nodes instead of one. In the first one you choose GreaterThanOrEqual: 1. All numbers that match this condition will continue to the next condition-node where the condition will be LessThanOrEqualTo: 5. If a number passes this condition as well you know that they are within the range 1-5 and can send them to the external queue.