IVR of any complexity - multi-level voice menu via API

The voice menu is one of the most important tools for receiving incoming calls. IVR not only provides customers with useful information, but also directs calls to the right employees or departments. Despite the fact that the Zadarma PBX offers a multi-level menu, you may need your own menu created using the API. API methods will allow you to implement non-standard and flexible solutions for routing your calls. We’ll show you how to create a multi-level IVR yourself using the Zadarma API.

Why do you need a multi-level voice menu?

IVR (voice menu) processes DTMF signals - phone key presses. Accordingly, thanks to several menu levels, you can not only "direct" the client, but also offer them more options - entering data, listening to information, going back a step.

A multi-level menu will help you solve the problem if your business has:

• Many departments. For example, you work with corporate and individual clients, and at the first step you just need to separate these clients from each other and then send them to the necessary departments.

• Several branches or stores. Moreover, it is easy to "fit" all branches within the framework of one cloud PBX. The first menu will help you choose a city, the second - a specific office.

• Several languages. If you are a large company and work with clients from different countries, it is logical to separate clients by language at the first stage of a multi-level IVR. For English press 1, para Español pulsa 2. Although we recommend separating "language" customers by caller’s number or the number the customers are calling.

How to create a multi-level menu?

You can create a simple IVR in the corresponding section of the Zadarma cloud PBX. Not just one menu, but several menus at once, for example, for incoming calls to different numbers. You upload (or read with the help of a robot) the greeting record and configure the call processing scenario.

The multi-level PBX menu can be managed using a ready-made PHP library. Here are the mandatory conditions for work:

1. PBX must be created and active
2. In the section "My PBX - Incoming calls and IVR" audio files of voice greetings must be uploaded, and incoming call scenarios must be created
3. In the "My PBX - Extensions" section, the required number of PBX extensions must be added, with software or equipment configured to receive calls or call forwarding enabled
4. A virtual number for incoming calls must be connected to which customer calls will be received
5. In the Settings - Integrations and API section, the Key and Secret must be generated for API operations

Detailed menu possibilities and creation rules are described in Github. Here we will show a small example and present the code to create the menu.

A multi-level voice menu is created using Webhooks. For this, you should already have experience working with PHP and Git, as well as your own server or a third-party service for hosting the code, with a permanent URL to which webhooks will be sent. Here are some other important server configuration requirements:

PHP >= 7.2.0
cURL
TLS v1.2
php-mbstring

Example of creating a voice menu

To receive call notifications, you need to create a public link that will accept POST requests with information from the Zadarma system. This link must be specified in the personal account under the heading "Notifications about calls to PBX".

Download the library at Github, and place the following php code at the link:

<?php

use MultiIvr\MultiIvr;

if (isset($_GET['zd_echo'])) {
    exit($_GET['zd_echo']);
}

require_once 'vendor/autoload.php';
$key = 'Your api key';
$secret = 'Your api secret';
$ivrMenuConfig = 'your config';
MultiIvr::default()->handle($key, $secret, $ivrMenuConfig);

$key та $secret - are the keys for authorization in the API interface, they must be obtained in the personal account. $ivrMenuConfig - is the text file with the configuration of the voice menu, which will be discussed below.

For the convenience of customizing the voice menu for each client, the entire IVR configuration is located in a separate file. To customize the menu for yourself, you don't need to change the code, just modify its settings.

Now, our example. We are creating a two-level voice menu:

First level: You have reached the company “Babylon”. If you work as a legal entity, press 1. If you are an individual, press 2.

Button 1. To contact the accounting department, press 1, if you want to reach the corporate department, press 2. If you have another question, wait for the operator's response.

Button 2. If you are a new customer, press 1. If you are an existing customer, press 2 or wait for the operator's response.

Example of a multi-level voice menu:

start default action=goto action-target=main
menu name=main playfile=43d8a740ec032766
menu name=main button=1 action=goto action-target=main.1
menu name=main button=2 action=goto action-target=main.2
menu name=main default action=redirect action-target=100

menu name=main.1 playfile=a279dd3a1da19e57
menu name=main.1 button=1 action=redirect action-target=102
menu name=main.1 button=2 action=redirect action-target=1-5
menu name=main.1 default action=redirect action-target=100

menu name=main.2 playfile=a6842305f1996e34
menu name=main.2 button=1 action=redirect action-target=105
menu name=main.2 button=2 action=redirect action-target=6-7
menu name=main.2 default action=redirect action-target=100

"Action" - is an action type. There are 2 possible values for action:

• redirect - redirects to scenario or PBX extension;
• goto - goes to the voice menu by its name.

In our example:

• extension 102 - an accounting employee working with corporate clients
• extension 100 - first-line support operator
• menu scenarios 1-5 - corporate department
• extension 105 - new client manager
• menu scenarios 6-7 - individual client department
• playfile=a6842305f1996e34 - audio file of the voice greeting uploaded in the personal account, to get the file ID, go to the voice menu settings ("Choose or read another file" button)

Additionally, you can set the schedule and working hours. You will find an example for this at Github.