16.03.2021
Zadarma API MULTI IVR

Voice menu is one of the most vital tools for incoming calls. IVR can introduce clients to useful information and direct them to certain employees and departments. Today one level of voice menu might not be enough, let’s learn how to create a multilevel IVR with Zadarma API.

What do you need a multilevel voice menu for?

IVR (voice menu) processes DTMF signals — pressing phone keys. So with several menu levels you can direct clients to and offer them more options: to enter data, listen to information, return to the previous step etc.

Multilevel menu will assist your business if it has:

  • Many departments. For example, you work with both businesses and individuals, and on the first step you need to separate the two groups and direct them to the appropriate departments.

  • Several stores or offices. All these offices can be “placed” in one virtual PBX. With the first menu level, you can choose a city and with the second one a certain office.

  • Several languages. Larger companies often work with clients from all over the world, so it will be logical to separate clients based on languages on the first level of IVR. For English press 1, para español pulsa 2. Though we recommend doing that in advance by caller’s number or the number that is being called.

How to create a multilevel menu?

A simple IVR can be created on the corresponding Zadarma virtual PBX page. Not even one menu, but several, for example, for incoming calls to different numbers. Upload (or voice with a machine) greetings message and set call processing scenarios.

Multilevel PBX menu can be managed with a preset PHP library. Here are the required conditions for it to work:

  1. PBX is created and active
  2. On My PBX – Incoming calls and IVT page audio files are uploaded and incoming calls scenarios are set
  3. On My PBX – Extension numbers page all required extension numbers are created, they have OS or equipment set for incoming calls or call forwarding enabled
  4. Virtual number is connected to receive incoming calls from clients
  5. On Settings – Integrations and API page Key and Secret are generated for API

Detailed features and rules for menu creation are described on Github. Here we will demonstrate an example and show the code for menu creation.

Multilevel voice menu is created via Webhooks. You need to have experience with PHP and Git, as well as your own server or a third-party server to place the code with a constant URL that webhooks will be sent to. Here are other important requirements for server configurations:


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

Voice menu creation example

To receive call notifications you need to create a link open for access that will receive POST-requests with information from Zadarma. This link has to be entered in the personal account under "PBX call notifications".

Download a library on Github, and place the following php code to 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 and $secret are authorization keys for API interface, they have to be received in the personal account. $ivrMenuConfig is a text file with voice menu configurations that will be discussed below.

For convenient voice menu settings for each client, all of its IVR configurations are in a separate file. To adapt the menu to yourself you don’t need to change code, just its settings.

Here’s our example. We are creating a two-level voice menu:

First level: You have reached Babylon company. If you have a business account, press 1. If you are an individual client, press 2.

Key 1. To contact finance department, press 1. To contact legal sales department, press 2. If you have a different question, please wait for the answer.

Key 2. If you are a new client, press 1. If you already have an account, press 2 or wait for the answer.

Multilevel voice menu example:


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 – action type. There are 2 possible action values:

  • redirect – redirecting to a scenario or PBX extension number;
  • goto – redirecting to voice menu by its name.

In our example:

  • extension number 102 – finance department employee for business accounts
  • extension number 100 – first line of support operator
  • menu scenario 1-5 – sales department
  • extension number 105 – manager for new
  • menu scenario 6-7 – individual accounts departments
  • playfile=a6842305f1996e34 – voice greetings audio file, to receive file ID go to voice menu settings ("Choose or voice another file" button)

You can additionally add working hours and schedule. You can find an example for that on Github.