API 接口概览
S系列 IPPBX 提供 二次开发接口(API)。第三方服务器与 PBX 通过 API 对接,你可以在第三方服务器上查询和编辑 PBX 的设置、实现多种呼叫功能。PBX 还会主动发送系统报告和通话报告到第三方服务器。
使用S系列 IPPBX API 之前,你需要先启用 PBX 的 API 功能、了解S系列 IPPBX API 的通信方式、API 请求结构、响应消息和 API 报告。
启用 API 功能
配置API之前,先启用PBX的API接口功能。
为 REST API 资源启用 CORS
跨源资源共享 (CORS) 是一项浏览器安全特征,浏览器限制脚本内发起跨源 HTTP 请求。如果你无法访问 API 并收到错误响应提示 CORS 跨域错误,那么你需要启用 CORS。本文介绍如何为简单请求启用 CORS。
删除被拉黑的 API IP
如果某个 IP 在短时间内,多次尝试登陆 API 接口失败,PBX 会将该 IP 拉入禁止名单,并将该 IP 类型标记为“API-IP”。如果该 IP 为受信任的 IP,你可以将这个 IP 从禁止名单列表中删除。
通信方式
S系列 IPPBX 和第三方应用服务器的通信是相互的, 双方互为服务端和客户端。
请求结构
本文介绍S系列 IPPBX 的 API 请求结构,包括通信协议、请求方式和请求地址说明。
响应消息
S系列 IPPBX 返回的响应消息为 JSON 格式。
API 报告推送
第三方服务器通过 API 接口与S系列 IPPBX 对接后,PBX 会主动发送 API 报告给第三方服务器。
API Demo
Yeastar提供 API demo 软件,你可以通过 API demo 软件测试 API 接口。
登录
S系列 IPPBX API 采用用户名和密码的方式验证,只有用户名和密码验证通过的应用服务器,API 才会处理其发送的请求。
API 心跳包
当连接 PBX 的第三方应用的 IP 地址、监听端口或者 URL 有变更的时候,可通过 API 的心跳包接口对 IP、Port 和 URL 进行更新。
系统启动报告
当 PBX 系统启动后,PBX 会向应用服务器推送该报告。
配置变更报告
当 PBX 的配置发生变化时,PBX 会向应用服务器发送配置变更报告,以便于应用服务器及时更新和同步 PBX 的相关配置。
分机状态变更报告
当分机状态发生变更时,PBX 主动向应用服务器推送变更信息。
‘响铃&回铃’报告
当 PBX 的分机拨打电话或收到来电时,PBX 会向第三方服务器发送回铃报告(ALERT)和响铃报告(RING)。
‘通话应答’报告
当分机接听内部来电或外部来电时,PBX 会向应用服务器发送“通话应答”报告。
‘通话被应答’报告
当分机呼出的通话被应答时,PBX 会向应用服务器发送“通话被应答”报告。
‘通话结束’报告
当一路通话释放,即通话挂断时,PBX 会向第三方应用服务器发送两个 BYE 报告。在第一个 BYE报告中,先记录主动挂断电话的用户号码,后记录被挂断电话的用户号码。
‘呼叫转移’报告
当 PBX 分机用户转移通话时,PBX 向应用服务器发送 “呼叫转移” 报告。
‘呼叫失败’报告
当发起的呼叫失败时,PBX 会向应用服务器发送“呼叫失败”报告。
‘按键信息’报告
通话过程中,当用户根据提示输入相关的按键(如通过 IVR 输入按键),PBX 向应用服务器推送“按键信息”报告。
‘通话记录’报告
当通话结束后,PBX 向应用服务器实时发送通话详细记录(CDR)。
‘来电呼叫请求’报告
在开启中继的 “来电接听控制” 的情况下,当来电通过该中继呼入时,PBX 会向应用服务器推送 INVITE 事件。
‘来电呼入’报告
在开启中继的 “呼入目的地控制” 情况下,当来电通过该中继呼入时,在 PBX 应答该来电后,会向应用服务器推送 INCOMING 事件。
‘播放语音结束’报告
PBX 给分机号码或外线号码播放提示音结束后,会发送报告。
‘满意度调查结果’事件
进行满意度调查时,当收到用户的按键信息后,PBX 主动向应用服务器发送满意度调查的结果。
酒店客房管理应用方案
通过 API 对接 S系列 IPPBX 和酒店管理系统,实现酒店客房分机管理、叫醒服务、通话统计、迷你吧消费统计、房间清洁状态变更和退房的自动化管理。
指挥调度系统应用方案
通过 API 对接 S系列 IPPBX 和调度系统,借助终端话机实现单向、双向和组播的指挥调度。
呼叫中心系统应用方案
通过 API 对接 S系列 IPPBX 和呼叫中心,实现自动话务分配、坐席管理、日常通话和满意度调查。
IVR 语音互动服务应用方案
通过 API 对接 S系列 IPPBX 和业务系统,提供语音互动服务。
IVR 预警系统应用方案
通过 API 对接 S系列 IPPBX 和预警系统,提供语音预警播报。