Skip to content

Latest commit

 

History

History
286 lines (218 loc) · 17.7 KB

README_RU.md

File metadata and controls

286 lines (218 loc) · 17.7 KB
Raw

Интерактивное голосовое меню

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. По нажатию на кнопку 1 направлять звонки в отдел продаж.
  2. По нажатию на кнопку 2 направлять звонки в отдел закупок.
  3. По нажатию на кнопку 3 направлять звонки в отдел обслуживания.
  4. Если остались на линии, то звонок направляется на секретаря.

Опишем правила голосового меню:

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.

Атрибуты разделяются пробелами, поэтому недопустимо использовать пробелы в значениях атрибутов.

Тег start

Обязательный. Задает правила начала входящего звонка в АТС.

Он имеет следующий атрибуты:

  1. action - тип действия.

    Возможны 2 значения:

    • redirect - перевод на сценарий или внутренний номер телефона АТС;
    • goto - переход на голосовое меню по его имени.

  2. action-target - цель действия.

    Если атрибут action имеет значение:

    • redirect

      Необходимо указать внутренний номер телефона, либо id сценария.

      Сценарии создаются в личном кабинете. Id сценария задается в формате 0-1, где 0 - номер голосового меню, 1 - номер сценария.

      Сценарий также может иметь значение blacklist - в этом случае звонок будет отклонен с сигналом занято.

    • goto

      Необходимо указать название голосового меню.

  3. callerid - фильтр по номерам звонящих, указываются через запятую.

  4. calleddid - фильтр по номерам, на которые звонят, указываются через запятую.

  5. default - признак действия по умолчанию. Одно из действий должно обязательно иметь признак default.

  6. 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.

Тег menu

Задает элементы голосового меню, правила перехода между ними, правила перевода на сценарии или внутренние номера телефонов АТС.

Он имеет те же атрибуты, как start, а также:

  1. name - имя элемента голосового меню, обязательный атрибут.

  2. playfile - id воспроизводимого файла, обязательный атрибут.

    Указывается один раз для голосового меню в отдельной строке от фильтров, отвечает за воспроизводимый файл голосового меню. id загруженного или начитанного файла можно узнать в личном кабинете.

  3. timeout - время ожидания ввода в секундах.

    Указывается в одной строке с атрибутом playfile, значение по умолчанию - 3.

  4. attempts - количество повторов воспроизводимого файла, если абонент ничего не нажал.

    Указывается в одной строке с атрибутом playfile, значение по умолчанию - 1

  5. maxsymbols - максимальное количество символов, ввода которых дожидаться.

    Указывается в одной строке с атрибутом playfile, значение по умолчанию - 1.

  6. button - фильтр нажатия одной или нескольких кнопок.

Тег schedule

  1. name - имя расписания.
  2. 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
  1. start
    • если звонит номер 111 или 222, то выполняется перевод звонка на сценарий blacklist(положить трубку);
    • иначе если выполняется условие schedule c именем off-the-clock, то выполняется переход в меню off-the-clock
    • иначе если выполняется условие schedule с именем dinner, то выполняется переход в меню dinner;
    • иначе если звонит номер 112 или 223, то выполняется переход в меню main.1;
    • иначе выполняется переход в меню main.
  2. main menu
    • Воспроизводим файл 43d8a740ec032766, время ожидания ввода - 5, количество повторов воспроизводимого файла, если абонент ничего не нажал - 2, максимальное количество символов, ввода которых дожидаться - 2.
    • если нажали 1, то выполняется переход в меню main.1;
    • иначе если нажали 2, то выполняется переход в меню main.2;
    • иначе если нажали 3, то выполняется перевод звонка на сценарий 0-1;
    • иначе если нажали 4, то выполняется перевод звонка на внутренний номер АТС 101;
    • иначе если нажали 10, то выполняется перевод звонка на внутренний номер АТС 110;
    • иначе выполняется перевод звонка на внутренний номер АТС 100.
  3. main.1 menu
    • Воспроизводим файл a279dd3a1da19e57;
    • если нажали 1, то выполняется перевод звонка на сценарий 0-2;
    • иначе если нажали 2, то выполняется перевод звонка на внутренний номер АТС 102;
    • иначе если нажали *, то выполняется переход в меню main;
    • иначе повторяем menu.1.
  4. main.2 menu
    • Воспроизводим файл a6842305f1996e34;
    • если нажали 1, то выполняется перевод звонка на сценарий 0-3;
    • иначе если нажали 2, то выполняется перевод звонка на внутренний номер АТС 103;
    • иначе если нажали *, то выполняется переход в меню main;
    • иначе повторяем menu.2.
  5. dinner menu
    • Воспроизводим файл facdfc7ca2029552;
    • выполняется перевод звонка на сценарий 0-4.
  6. off-the-clock menu
    • Воспроизводим файл b1b2d11f59d8d208;
    • выполняется перевод звонка на сценарий blacklist(положить трубку).
  7. dinner schedule
    • Условие: понедельник - пятница с 13:00:00 до 13:59:59;
  8. off-the-clock schedule
    • Условие: понедельник - пятница с 00:00:00 до 08:59:59,18:00:00 до 23:59:59, суббота, воскресенье.