OMAPI编程指南

OMAPI编程者使用指南OMAPI编程者实用指南概述OMAPI是迅时通信OM系列IPPBX（以下简称“OM”）为第三方应用系统（以下简称“应用系统”）提供的控制接口。通过该接口，OM将呼叫相关的事件、状态、统计信息以及录音包传送给应用系统；同时，应用系统可以向OM发出呼叫控制的请求、设置相关参数。本文将介绍OMAPI的通讯机制以及双方信息交互的有关命令，并给出大量实例。OM与应用系统交互的机制OM应用系统座席座席座席HTTP POST(来电号码、分机状态、通话记录)HTTP POST(呼叫控制、分机配置、状态查询)最简单的例子（一个简单的对外呼叫系统）这个对外呼叫系统由语音交换机和调度系统两部分构成。其中，语音交换机（由OM构成）负责建立从分机向外线的呼叫；调度系统（由应用系统构成）负责制定外呼的策略和计划，例如决定何时、由哪个分机、向那里发起呼叫，并将这个决定告诉语音交换机。OM系统本身带有连接电话网的接口和连接分机话机的接口。另外，OM通过本身的以太网接口，通过IP网络，如局域网、VPN或Internet与应用系统连接。OM内置Web服务器，并支持http协议。应用系统可以通过http访问OM，即下达呼叫请求。有关OM的设置，请参见OM的用户手册或OM管理界面上的提示。下面是应用系统（调度系统）向OM发出的外呼请求。要求OM通过分机200向外部的手起呼叫。OM在收到该请求后，将立即发起呼叫，如果对方接机，OM将接通分机200，并向应用系统发回200 OK。OMAPI消息在上述例子中用到了OMAPI的呼叫命令（Transfer）中的建立呼叫（Connect）子命令。OMAPI中规定了事件、控制命令、呼叫命令、详细话单等四种类型的消息。消息类型消息名称方向描述事件报告EventOM发给应用系统OM向应用系统报告IVR收到的DTMF、分机状态、来电状态。控制命令Control应用系统发给OM应用系统用来设置OM的相关参数，控制分机的通话状态。呼叫命令Transfer应用系统发给OM应用系统告诉OM将来电连接到语音菜单、队列、分机、外线等；还可以告诉OM向外发起呼叫。通话记录CdrOM发给应用系统通话结束后OM向应用系统发该通话的详细话单。录音OM发给录音系统OM提供配套录音软件，可产生mp3格式的录音文件供应用系统查询消息的XML格式如前所说，在OMAPI中所有消息（命令、报告）都是以XML的格式通过http的Request发给对方。上述四种消息的格式分别为：内容内容内容内容这里，ABCD是子命令的名称，XYZ是通话记录的序号。下面对这些消息做详细说明。事件报告在OMAPI中，OM通过事件报告将OM设备上的来电状态、来电主叫方发送的DTMF信号、分机的状态等通知应用系统。通过在OM上设置，用户可以选择报告或不报告某些事件。事件描述DTMF向应用系统报告检测到的DTMF号Idle向应用系统报告分机空闲Ring向应用系统报告来电在振铃中Answered向应用系统报告来电被应答Busy向应用系统报告分机忙线Bye向应用系统报告来电方挂机Transient向应用系统报告OM将来电从一个实体转到另一实体。例如：OM将在group中等待的电话分配给某分机。举例（告诉应用系统通话结束）在前面的外呼系统设计中，OM可以将外呼结束这一事件通报应用系统。OM将通过http的Request将以下消息发给应用系统：控制命令控制命令用来设置OM的相关参数，或用来控制分机的通话状态。控制命令属性通过命令属性来规定不同类型的子命令。属性描述Assign设置OM上的相关实体参数Suspend将分机置于屏蔽状态，处于此状态的分机不能接任何来电，但可以发起呼叫Resume接触分机的屏蔽状态Clear清除与实体相关的所有通话。此命令与Query命令用法类似参数设置命令（Assign）应用系统通过控制命令中的“Assign”对OM中的各种实体进行设置。下面是对分机进行设置的一个例子。20063320/1/2/3on/off22222,44444,55555561202888612028886120288861202888应用系统可以通过“Assign”对任何实体进行设置。这些实体包括：实体类型描述MenuOM提供的语音菜单。语音菜单是组成多级互动式语音导航系统（IVR）的基本要素，其主要用途是向来电主叫方播放语音提示。通常主叫方将菜单的提示内容在话机上键入DTMF。Menu的参数请参见？ExtOM内部的分机。分机的参数请参见？GroupOM 内部由若干个分机组成的组。Group 具有排队、自动话务分配和等待背景音乐等功能。每个Group 由若干分机组成。允许将同一分机分配给多个 Group。分机暂挂命令（Suspend）分机继续命令（Resume）清除命令（Clear）查询命令（Query）呼叫命令（Transfer）呼叫命令用于建立分机到外线的外呼，将呼入电话连接到语音菜单、分机组、分机、或外线。子命令（属性）呼叫命令描述Connect设置OM上的相关参数。Queue将当前通话暂时挂起。常用消息使用举例1. 设置分机20063320/1/2/3on/off22222,44444,55555561202888612028886120288861202888说明：Assign参数配置lineid分机线路编号id分机号码staffid工号group分机归属组emailEmailCall_Restriction呼叫权限：0内线1市话2国内长途3国际长途Disturb免打扰（on/off）Black_List黑名单列表All_Fwd_Number无条件转移号码Busy_Fwd_Number遇忙转移号码No_Answer_Fwd_Number无应答转移号码Offline_Fwd_NumberIP分机离线转移号码2. 分机挂起说明：3. 解除挂起4. 创建语音菜单welcome.dat5#说明：上例表示创建一个id为1的语音菜单，对应的语音文件为welcome.dat，用户在此语音菜单上的按键位数为5，或用户按键完毕可以用表示结束。Assign参数配置Menu语音菜单Id语音菜单编号infolength用户按键位数Exit退出方式1. 将来电接入菜单说明：将从4008123123打入的来电用入id为1的语音菜单（在上例中创建）。应答：表示转接成功Connect接通visitor表示来电用户IdOM为每个来电用户分配的唯一编号，用于标识用户from来电号码to用户接入号码Menu语音菜单Id语音菜单编号2. 将来电接入分机说明：将从4008123123打入的来电用入分机200。3. 将来电接入队列说明：例表示将从4008123123打入的来电用入分机200的队列。4. 将来电接入分机组队列说明：将从4008123123打入的来电用入分机组2。5. 将来电转接到外部电话622+file1.pcm+file2.pcm说明：将从4008123123打入的来电转接到外部手同时播放工号为622等语音提示。6. 分机外呼说明：分机200呼叫外部手机用7. 回拨说明：将外部手机用外部手机用通。8. 分机状态查询说明：查询分机200的状态及配置信息。返回结果1：“active”表示分机与61202703处于通话中。 active talk 返回结果2：“ready”表示分机处于空闲状态。2readyOM向CRM汇报的事件呼叫状态类1. 用户接入说明：上例表示用4008123123呼入。DTMF用户选择visitor表示来电用户IdOM为每个来电用户分配的唯一编号，用于标识用户from来电号码to用户接入号码2. 用户按键汇报58662说明：上例表示用语音菜单1上的按键为58662。DTMF用户选择visitor表示来电用户IdOM为每个来电用户分配的唯一编号，用于标识用户from来电号码to用户接入号码Info用户按键Menu语音菜单Id语音菜单编号分机状态类1. 空闲说明：上例表示分机200处于空闲状态。IDLE空闲Ext分机Id分机号码2. 忙线说明：上例表示分机200处于忙线状态。BUSY空闲Ext分机Id分机号码3. 振铃说明：上例表示用入分机200，分机200处于振铃状态。Ring分机振铃visitor表示来电用户IdOM为每个来电用户分配的唯一编号，用于标识用户from来电号码to用户接入号码Ext分机Id分机号码4. 通话中说明：上例表示用入分机200，分机200处于振铃状态。Answered通话中visitor表示来电用户IdOM为每个来电用户分配的唯一编号，用于标识用户from来电号码to用户接入号码Ext分机Id分机号码5. 通话结束说明：上例表示用分机200通话结束。通话记录32782INXO13000004022200200906191737392009061917395371400812312320020090619-173739_32782.mp3说明：上例表示用分机200通话结束后产生的通话记录。Cdr通话记录callid呼叫标识visitor表示来电用户IdOM为每个来电用户分配的唯一编号，用于标识用户Type通话类型：IN呼入OU呼出FI转移入FW转移出LO内部CB回拨Route通话路由：IPSIP中继XO模拟中继IC内部OP呼叫总机CPN主叫号码CDPN被叫号码TimeStart通话开始时间，格式：yyyymmddhhmmssTimeEnd通话结束时间，格式：yyyymmddhhmmssDuration通话时长，单位：秒TrunkNumber通话中继号码Recording录音文件名，规则如下：分机_外部号码_通话开始时间_呼叫标识.mp3附录:OM API配置说明一、 在OM上开启API1、 登陆OM admin管理软件，配置API服务器地址及接收url，如下图： 在API服务器处填写应用系统服务器的ip地址及端口：此参数用于应用系统接收OM发送的各种事件。 在API URL处填写CRM服务器的接收URL：应用系统如有指定的页面用于接收OM发送的消息，可在此处指定