README

PHP 语音菜单设置库

阅读其他语言的描述

要求

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

设置

将关联 zadarma/multi-ivr 添加到项目的 composer.json 文件中

composer require zadarma/multi-ivr

特性

通过使用过滤器和规则实现了灵活的语音菜单配置。支持四种类型的过滤器：

呼叫者号码；
被叫号码；
按计划过滤；
用户操作。

规则由过滤器和动作组成。当规则过滤条件匹配时，将执行动作。有两种类型的动作 - 转接到菜单（播放音频文件并等待用户操作）和呼叫转接到电话号码或场景（拨打多个号码或黑名单）。

下面我们将更详细地介绍这些特性。

使用

要接收呼叫通知，您需要创建一个对所有访问开放的链接，该链接将接收来自 Zadarma 系统的信息 POST 请求。此链接必须输入到个人账户下的“PBX 呼叫通知”标题中。

以下 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。每个标签都有其允许的属性，下面将描述。

属性由空格分隔，因此属性值中不能使用空格。

开始标签

必需。它设置了对 PBX 的 incoming call 的开始规则。

它有以下属性

action - 动作类型。

2 个可能的值
- redirect - 转接到场景或 PBX 扩展号码；
- goto - 通过其名称转接到语音菜单。
action-target - 动作目的。

如果动作属性值为
- redirect
  
  必须输入扩展号码或场景 ID。
  
  场景是在个人账户中创建的。场景 ID 设置为 0-1 格式，其中 0 - 语音菜单号码，1 - 场景号码。
  
  场景还可以具有黑名单值 - 在这种情况下，电话将被忙音拒绝。
- goto
  
  必须输入语音菜单名称。
callerid - 通过呼叫者号码过滤，用逗号分隔。
calleddid - 通过被叫号码过滤，用逗号分隔。
default - 默认动作。必须有一个动作带有默认标志。
schedule - 调度名称过滤，可用于设置工作和午餐时间。

使用多个过滤器开始示例

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，通话将转移到黑名单场景（忙音拒绝通话）
如果第一条规则未应用，则检查以下规则；
如果没有应用任何规则，则执行默认操作 - 通话转移到号码100。

菜单标签

设置语音菜单元素，元素之间的转移规则，以及转移到场景或总机分机的规则。

与“开始”标签具有相同的属性，以及

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

计划名称为工作，设置为周一至周五时间为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有两个时间区间从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来电，通话将转移到黑名单场景（挂断）；
- 否则如果满足下班时间计划条件，通话将转移到下班时间菜单
- 否则如果满足晚餐时间计划条件，通话将转移到晚餐菜单；
- 否则如果是电话号码112或223来电，通话将转移到main.1菜单；
- 否则通话将转移到主菜单。
主菜单
- 播放文件43d8a740ec032766，输入超时 - 5，如果呼叫者没有按按钮，文件播放重复次数 - 2，可以输入的最大符号数 - 2。
- 如果按下1，电话将转接到主菜单1；
- 否则如果按下2，电话将转接到主菜单2；
- 否则如果按下3，电话将转接到场景0-1；
- 否则如果按下4，电话将转接到总机分机号101；
- 否则如果按下10，电话将转接到总机分机号110；
- 否则电话将转接到总机分机号100。
主菜单1
- 播放文件a279dd3a1da19e57；
- 如果按下1，电话将转接到场景0-2；
- 否则如果按下2，电话将转接到总机分机号102；
- 否则如果按下*，电话将转接到主菜单；
- 否则重复菜单1。
主菜单2
- 播放文件a6842305f1996e34；
- 如果按下1，电话将转接到场景0-3；
- 否则如果按下2，电话将转接到总机分机号103；
- 否则如果按下*，电话将转接到主菜单；
- 否则重复菜单2。
晚餐菜单
- 播放文件facdfc7ca2029552；
- 电话将转接到场景0-4。
加班时间菜单
- 播放文件b1b2d11f59d8d208；
- 电话将转接到黑名单场景（挂断）。
晚餐时间表
- 条件：星期一至星期五从13:00:00至13:59:59；
加班时间表
- 条件：星期一至星期五从00:00:00至08:59:59，从18:00:00至23:59:59，星期六、星期日。

zadarma / multi-ivr

维护者

详细信息