Freeswitch Event Socket IVR外呼方案

一、项目应用解决方案

1、内呼方案流程：

客户拨号 <——> 运营商/网关 <——> FreeSWITCH(MRCP +ASR/TTS/NLP) <——>Lua(嵌入FS)

Ps: 根据特定号码，FS路由配置好的拨号计划(dialplan)，进而调用lua APP，Lua脚本的运行，实现业务逻辑控制，每一通电话都可以调用该lua脚本；

2、外呼方案流程：

Web(http) <——> Python(ESL) <——> FreeSWITCH(MRCP +ASR/TTS/NLP) <——> 运营商/网关 <——> 目标客户

Ps: Python脚本通过http协议对接Web，实现批量的自动拨号与电话通道的管理与控制；当客户接通电话后，调用Lua脚本实现外呼的业务逻辑；

二、Event Socket

与Lua嵌入式脚本不同，通过Event Socket方式，可以在远程机器的外部独立程序控制FreeSWITCH。大多数语言都支持Socket，所以几乎可以和任何语言开发的程序通信，便于跟任何系统进行集成。

Event Socket的连接分两种模式： InBound/OutBound

1、内连模式InBound

InBound模式：FS作为服务端，监听所配置的端口，FS启动时自动加载，当外部客户端程序主动向FS发起socket连接来实现通信。

该模式由于是可以主动连接并可长期稳定保持，且此通道有且只有一个，心跳、外呼和注册等动作必须通过此种连接完成。

2、外连模式OutBound

OutBound模式：FS作为客户端，需要在dialplan的配置文件中设置，当有电话进来时，FS路由dialplan, 触发一个app(socket)动作，向外部服务端程序建立一个socket连接来实现通信。

该模式一般用于外线电话呼入的时候会触发socket连接事件，支持同一时间呼入数量不唯一，每个来电建立一个socket连接，所以此连接的数目也是动态变化的。

3、FS mod_event_socket模块配置

a.进入安装FS的根目录：

cd /usr/local/freeswitch(默认)

b.编辑FS模块加载配置文件：vim ./conf/autoload_configs/modules.conf.xml

c.编辑event_socket配置文件：vim ./conf/autoload_configs/event_socket.conf.xml

d. 重启freeswitch，使相应配置生效。

三、Event Socket Library

FreeSWITCH用C语言将Event Socket协议写了一些库函数，并用SWIG封装成各种高级语言的接口，目前支持的语言有Perl、PHP、Python、Ruby、Java、C#等，这些高级语言的库函数开发接口即为ESL(Event Socket Library)，通过这些开发接口来使用FS内部提供的APP和API,可以很方便地与FreeSWITCH交互，进而控制FS的所有通道和各种媒体功能。

本文介绍Python 利用 Event Socket Library 与FreeSWITCH通信，并控制其进行相应操作；

1、Python ESL的两种安装方式

a.FS源码的Pymod编译、安装：

cd /usr/src/freeswitch/libs/esl

make pymod

make pymod-install

(默认安装路径：/usr/lib/pythonX.X/site-packages/)

b.在线pip安装：pip install python-ESL

(默认安装路径：/usr/lib64/pythonX.X/site-packages/)

2、Python ESL使用

ESLconnection对象

ESLconnection对象维护与freeswitch之间的连接，以发送命令并进行事件处理。成员函数列表如下：

socketDescriptor()
该函数返回连接的UNIX文件句柄
connected()
判断是否已连接，连接返回1，否则返回0
getInfo()
当freeswitch使用outbound模式连接时，它将首先发一个CHANNEL_DATA事件，getInfo会返回该事件；
在inbound模式中返回None
send(command)
向freeswitch发送一个command，但不会等待返回结果，需要显式调用recvEvent或recvEventTimed以接收返回的事件。
sendRecv(command)
向freeswitch发送一个command，并等待返回结果（一个ESLevent对象）。
api(command[,arguments])
向freeswitch发送api命令，阻塞执行
bgapi(command[, arguments][,custom_job_uuid])
向freeswitch发送bgapi命令，后台执行，非阻塞执行
sendEvent(event)
向freeswitch发送一个事件
sendMSG(event,uuid)
参考sendmsg命令
recvEvent()
从freeswitch接收事件，阻塞模式
recvEventTimed(milliseconds)
与recvEvent类似，但不会无限等待，而是在参数指定的毫秒数会返回。
recvEventTimed(0)会立即返回。
filter (header,value)
事件过滤，类似filter命令。
events (event_type,value)
事件订阅，类似event命令。
execute (app[,arg][,uuid])
执行dialplan的app，并阻塞等待返回. 返回结果为一个ESLevent对象，通过getHeader(“Reply-Text”)可以获取返回值，”+OK”表示成功，”-ERR”表示失败。
executeAsync (app[,arg][,uuid])
与execute()相同，但非阻塞执行。
setAsyncExecute(value)
强制将socket设置为异步模式，value为1是异步，0是同步。
setEventLock(value)
使用该选项后，后续所有的execute()调用都将带有”event-lock:true”头域。
disconnect()
主动中断与freeswitch的连接。

ESLevent对象

当接收一个事件时，用户将获得一个ESLevent对象，这个对象包含各种帮助函数变量来帮助解析和处理收到的事件。

ESLevent对象成员函数列表如下：
serialize([format])
将event数据转换成”name:value”型数据，format参数可以为：
"xml"
"json"
"plain" (default)
示例如下：
eventData.serialize('json') 获取json格式数据
setPriority([number])
设置事件的级别
getHeader(headerName)
获取header对应的value，示例如下：
eventData .getHeader('Event-Name') #获取事件名称
getBody()
获取事件的正文
getType()
获取event object的事件类型
addBody(value)
向事件中加入正文，可以调用多次
addHeader(key,value)
向事件中加入一个头域(ESL_STACK_BOTTOM)
pushHeader(key,value)
向事件中加入一个头域(ESL_STACK_PUSH)
unshiftHeader(key,value)
向事件中加入一个头域(ESL_STACK_UNSHIFT)
delHeader(key)
从Event中删除头域
firstHeader()
将指针指向Event的第一个头域，并返回它的key值。它必须在nextHeader之前调用
nextHeader()
移动指针指向下一个header，在函数调用前必须先调用firstHeader()

应用示例：

Python InBound模式示例代码：


import ESL
import timehostIp,port,user = "127.0.0.1","8021","ClueCon"con = ESL.ESLconnection(hostIp,port,user)con.events("CHANNEL_CREATE")eventData = con.api("originate {ignore_early_media=true}user/1005 &park")
print eventData.getHeader("Job-UUID")while True:eventData = con.recvEvent()print eventData.getHeader("Event-Name")con.disconnect()

originate返回的事件信息：


//tcp header
Content-Length: 625
Content-Type: text/event-plain//event header
Job-UUID: 7f4db78a-17d7-11dd-b7a0-db4edd065621
Job-Command: originate
Job-Command-Arg: sofia/default/1005%20'%26park'
Event-Name: BACKGROUND_JOB
Core-UUID: 42bdf272-16e6-11dd-b7a0-db4edd065621
FreeSWITCH-Hostname: ser
FreeSWITCH-IPv4: 192.168.1.104
FreeSWITCH-IPv6: 127.0.0.1
Event-Date-Local: 2008-05-02%2007%3A37%3A03
Event-Date-GMT: Thu,%2020%20Jun%202008%2023%3A37%3A03%20GMT
Event-Date-timestamp: 1209685023894968
Event-Calling-File: mod_event_socket.c
Event-Calling-Function: api_exec
Event-Calling-Line-Number: 609
Content-Length: 41//event body
+OK 7f4de4bc-17d7-11dd-b7a0-db4edd065621