PHP библиотека для настройки голосового меню Zadarma
Прочтите описание на других языках:
- PHP >= 7.2.0
- cURL
- TLS v1.2
- php-mbstring
Добавьте зависимость zadarma/multi-ivr
в файл composer.json вашего проекта:
composer require zadarma/multi-ivr
Реализована возможность гибкого конфигурирования голосового меню при помощи фильтров и правил. Поддерживается четыре вида фильтров:
- по номеру звонящего;
- по номеру, на который звонят;
- фильтр по расписанию;
- действие пользователя.
Правило состоит из фильтров и действия. Действие выполнится в случае совпадения условий фильтров правила. Действия бывают двух типов - переход в меню (воспроизводится звуковой файл и ожидается действие пользователя) и перевод вызова на номер телефона или сценарий (обзвон нескольких номеров или blacklist).
Рассмотрим возможности более подробно ниже по тексту.
Для приема уведомлений о звонках необходимо создать открытую для всеобщего доступа ссылку, которая будет принимать POST-запросы с информацией из системы Zadarma. Эту ссылку необходимо указать в личном кабинете под заголовком "Уведомления о звонках в АТС".
По ссылке необходимо разместить следующий php код:
<?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
- ключи для авторизации в интерфейсе API, их необходимо получить в личном кабинете.
$ivrMenuConfig
- текстовый конфиг голосового меню, о нем подробнее расскажем ниже.
Задача:
При помощи голосового меню разделить клиентов на 3 группы:
- По нажатию на кнопку 1 направлять звонки в отдел продаж.
- По нажатию на кнопку 2 направлять звонки в отдел закупок.
- По нажатию на кнопку 3 направлять звонки в отдел обслуживания.
- Если остались на линии, то звонок направляется на секретаря.
Опишем правила голосового меню:
start default action=goto action-target=main
menu name=main playfile=file1
menu name=main button=1 action=redirect action-target=100
menu name=main button=2 action=redirect action-target=101
menu name=main button=3 action=redirect action-target=102
menu name=main default action=redirect action-target=103
Конфиг имеет 3 допустимых тега - start, menu, schedule. Каждый тег имеет свои разрешенные атрибуты, они описаны ниже.
Имя и значение атрибута разделяется знаком равно attribute=attributeValue
.
Атрибуты разделяются пробелами, поэтому недопустимо использовать пробелы в значениях атрибутов.
Обязательный. Задает правила начала входящего звонка в АТС.
Он имеет следующий атрибуты:
-
action - тип действия.
Возможны 2 значения:
- redirect - перевод на сценарий или внутренний номер телефона АТС;
- goto - переход на голосовое меню по его имени.
-
action-target - цель действия.
Если атрибут action имеет значение:
-
redirect
Необходимо указать внутренний номер телефона, либо id сценария.
Сценарии создаются в личном кабинете. Id сценария задается в формате 0-1, где 0 - номер голосового меню, 1 - номер сценария.
Сценарий также может иметь значение blacklist - в этом случае звонок будет отклонен с сигналом занято.
-
goto
Необходимо указать название голосового меню.
-
-
callerid - фильтр по номерам звонящих, указываются через запятую.
-
calleddid - фильтр по номерам, на которые звонят, указываются через запятую.
-
default - признак действия по умолчанию. Одно из действий должно обязательно иметь признак default.
-
schedule - фильтр с именем расписания, по нему можно указать рабочее или обеденное время.
Пример start с несколькими фильтрами:
start default action=redirect action-target=100
start callerid=111 calleddid=112 action=redirect action-target=blacklist
start callerid=111 action=redirect action-target=101
start calleddid=112 action=redirect action-target=102
- первое правило - если номер 111 позвонил на номер 112, то выполняется перевод звонка на сценарий blacklist (положить трубку с сигналом занято)
- если первое правило не выполнилось, то проверяется следующее по порядку;
- если ни одно правило не выполнилось, то выполняется действие по умолчанию - перевод звонка на номер 100.
Задает элементы голосового меню, правила перехода между ними, правила перевода на сценарии или внутренние номера телефонов АТС.
Он имеет те же атрибуты, как start, а также:
-
name - имя элемента голосового меню, обязательный атрибут.
-
playfile - id воспроизводимого файла, обязательный атрибут.
Указывается один раз для голосового меню в отдельной строке от фильтров, отвечает за воспроизводимый файл голосового меню. id загруженного или начитанного файла можно узнать в личном кабинете.
-
timeout - время ожидания ввода в секундах.
Указывается в одной строке с атрибутом playfile, значение по умолчанию - 3.
-
attempts - количество повторов воспроизводимого файла, если абонент ничего не нажал.
Указывается в одной строке с атрибутом playfile, значение по умолчанию - 1
-
maxsymbols - максимальное количество символов, ввода которых дожидаться.
Указывается в одной строке с атрибутом playfile, значение по умолчанию - 1.
-
button - фильтр нажатия одной или нескольких кнопок.
- name - имя расписания.
- data - описание расписания.
Пример расписания:
schedule name=work data=mo,tu,we,th,fr:0800-1300;1400-1700,sa:0900-1500
Расписание имеет имя work, указано, что по понедельникам - пятницам рабочее время с 08:00 до 12:59:59 и с 14:00 до 16:59:59, в субботу с 09:00 до 14:59:59.
Допустимые наименования дней недели: su, mo, tu, we, th, fr, sa.
Время возможно указать для каждого дня недели в виде одного или нескольких интервалов, разделенных точкой с запятой. Интервал состоит из двух значений, разделенных дефисом - времени начала и времени окончания. Время начала и окончания должно состоять из четырех цифр. Первые две цифры отвечают за часы, вторые за минуты.
Также возможно задать время сразу для нескольких дней недели, указав дни недели через запятую, а время через двоеточие, вот так mo,tu,we,th,fr:0800-1300;1400-1700
.
Если время не указано, то берется целый день от 00:00:00 до 23:59:59.
Например, mo,tu,we,th,fr:0800-1300;1400-1700,sa,su
mo,tu,we,th,fr имеют 2 интервала времени с 8:00 до 12:59:59 и с 14:00:00 до 16:59:59, а sa,su имеют один интервал времени с 00:00:00 до 23:59:59.
Пример расписания:
schedule name=relax data=mo,tu,we,th,fr:1300-1400,sa,su
Расписание имеет имя relax, указано, что по понедельникам - пятницам время отдыха с 13:00:00 до 13:59:59, в субботу и воскресенье выходные.
К правилам относятся строки конфига, имеющие в своих атрибутах фильтры.
К фильтрам, как описывалось выше, относятся атрибуты: callerid, calleddid, button, schedule. Правила описывают условия выполнения определенных действий в зависимости от номера звонящего, номера, на который звонят, действия пользователя и текущего времени.
Приоритет правил определяется по порядку следования строк.
Пример правил:
...
menu name=main button=1 callerid=111 calleddid=112 schedule=dinner action=redirect action-target=101
menu name=main button=1 callerid=111 action=redirect action-target=102
menu name=main button=1 action=redirect action-target=103
menu name=main default action=redirect action-target=104
...
schedule name=dinner data=mo,tu,we,th,fr:1300-1400
- первое правило - если номер 111 в обеденное время позвонил на номер 112 и нажал кнопку 1, то выполняется перевод звонка на номер 101;
- если первое правило не выполнилось, то проверяется следующее по порядку;
- если ни одно правило не выполнилось, то выполняется действие по умолчанию - перевод звонка на номер 104.
start callerid=111,222 action=redirect action-target=blacklist
start schedule=off-the-clock action=goto action-target=off-the-clock
start schedule=dinner action=goto action-target=dinner
start callerid=112,223 action=goto action-target=main.1
start default action=goto action-target=main
menu name=main playfile=43d8a740ec032766 timeout=5 attempts=2 maxsymbols=2
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 button=3 action=redirect action-target=0-1
menu name=main button=4 action=redirect action-target=101
menu name=main button=10 action=redirect action-target=110
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=0-2
menu name=main.1 button=2 action=redirect action-target=102
menu name=main.1 button=* action=goto action-target=main
menu name=main.1 default action=goto action-target=main.1
menu name=main.2 playfile=a6842305f1996e34
menu name=main.2 button=1 action=redirect action-target=0-3
menu name=main.2 button=2 action=redirect action-target=103
menu name=main.2 button=* action=goto action-target=main
menu name=main.2 default action=goto action-target=main.2
menu name=dinner playfile=facdfc7ca2029552
menu name=dinner default action=redirect action-target=0-4
menu name=off-the-clock playfile=b1b2d11f59d8d208
menu name=off-the-clock default action=redirect action-target=blacklist
schedule name=dinner data=mo,tu,we,th,fr:1300-1400
schedule name=off-the-clock data=mo,tu,we,th,fr:0000-0900;1800-2400,sa,su
- start
- если звонит номер 111 или 222, то выполняется перевод звонка на сценарий blacklist(положить трубку);
- иначе если выполняется условие schedule c именем off-the-clock, то выполняется переход в меню off-the-clock
- иначе если выполняется условие schedule с именем dinner, то выполняется переход в меню dinner;
- иначе если звонит номер 112 или 223, то выполняется переход в меню main.1;
- иначе выполняется переход в меню main.
- main menu
- Воспроизводим файл 43d8a740ec032766, время ожидания ввода - 5, количество повторов воспроизводимого файла, если абонент ничего не нажал - 2, максимальное количество символов, ввода которых дожидаться - 2.
- если нажали 1, то выполняется переход в меню main.1;
- иначе если нажали 2, то выполняется переход в меню main.2;
- иначе если нажали 3, то выполняется перевод звонка на сценарий 0-1;
- иначе если нажали 4, то выполняется перевод звонка на внутренний номер АТС 101;
- иначе если нажали 10, то выполняется перевод звонка на внутренний номер АТС 110;
- иначе выполняется перевод звонка на внутренний номер АТС 100.
- main.1 menu
- Воспроизводим файл a279dd3a1da19e57;
- если нажали 1, то выполняется перевод звонка на сценарий 0-2;
- иначе если нажали 2, то выполняется перевод звонка на внутренний номер АТС 102;
- иначе если нажали *, то выполняется переход в меню main;
- иначе повторяем menu.1.
- main.2 menu
- Воспроизводим файл a6842305f1996e34;
- если нажали 1, то выполняется перевод звонка на сценарий 0-3;
- иначе если нажали 2, то выполняется перевод звонка на внутренний номер АТС 103;
- иначе если нажали *, то выполняется переход в меню main;
- иначе повторяем menu.2.
- dinner menu
- Воспроизводим файл facdfc7ca2029552;
- выполняется перевод звонка на сценарий 0-4.
- off-the-clock menu
- Воспроизводим файл b1b2d11f59d8d208;
- выполняется перевод звонка на сценарий blacklist(положить трубку).
- dinner schedule
- Условие: понедельник - пятница с 13:00:00 до 13:59:59;
- off-the-clock schedule
- Условие: понедельник - пятница с 00:00:00 до 08:59:59,18:00:00 до 23:59:59, суббота, воскресенье.