XSwitch

XSwitch用户手册

XSwitch.cn

2022年5月11日

法律声明

若接收烟台小樱桃网络科技有限公司（以下称为“小樱桃”）的此份文档，即表示您已同意以下条款。若不同意以下条款，请立即停止使用本文档。

本文档版权所有烟台小樱桃网络科技有限公司。保留任何未在本文档中明示授予的权利。文档中涉及小樱桃的专有信息。未经小樱桃事先书面许可，任何单位和个人不得复制、传递、分发、使用和泄漏该文档以及该文档包含的任何图片、表格、数据及其他信息。本网页版文档仅在xswitch.cn上发布。

本产品符合有关环境保护和人身安全方面的设计要求，产品的存放、使用和弃置应遵照产品手册、相关合同或相关国法律、法规的要求进行。

本文档按“现状”和“仅此状态”提供。本文档中的信息随着小樱桃的产品和技术的进步将不断更新，小樱桃不再通知此类信息的更新。

烟台小樱桃网络科技有限公司

地址：烟台市高新区蓝海路1号
邮编：264000
电话：0535-6753997

1 总体介绍

XSwitch是一个电信级的IP电话软交换系统和综合实时音视频多媒体通信平台。

XSwitch支持电话、传真、视频会议、呼叫中心等。支持主流的通信协议如SIP、H323、WebRTC、RTMP等，支持单机部署、云原生集群部署，支持无限扩容及动态伸缩。目标是为用户提供一站式语音、视频、会议解决方案，可以作为IP-PBX、视频会议服务器、传真服务器、多协议网关、呼叫中心服务器等使用。XSwitch提供REST、Websocket二次开发接口。XSwitch基于开源技术构建，如FreeSWITCH、PostgreSQL、Nginx等。

XSwitch是模块化，积木式按需叠加和无限伸缩扩容的通信产品，更可以通过定制支持集群部署，实现更强大的功能。XSwitch的位置、组件和逻辑关系如下图所示：

其中，SIP话机通过SIP协议接入XSwitch，管理员可以通过Web浏览器进行系统管理和维护，也可以通过WebRTC打电话，静态Web页面都由Web服务器提供，动态API请求会由Web服务器转发到XSwitch端进行处理。

1.1 产品介绍

  • XSwitch是一个电信级的综合音视频通信平台及软交换系统。
  • XSwitch是一个电话、呼叫中心和音视频会议平台，安全、稳定、高效、功能强大，能满足企业多样性地通信业务需求。
  • XSwitch是一套电话软交换系统，可用于IP-PBX、呼叫中心、视频会议服务、融合通信等。
  • XSwitch有直观易用的图形化操作界面，支持用户管理、网关配置、视频会议、路由设计、IVR设计、呼叫队列、智能语音交互等。
  • XSwitch支持全方位的互联互通，支持与PSTN、SIP、H323、E1/T1、WebRTC、RTSP、RTMP、GB28181等系统和协议对接，支持与Agora（声网）、腾讯会议、微信小程序等对接。
  • XSwitch是一个融合通信平台，支持语音、视频、即时通信、传真等。
  • XSwitch平台提供开放的接口和API，可对接各种AI平台、CRM业务系统等。
  • XSwitch是一个通信能力开放平台。
  • XSWitch是一个企业通信中台。
  • XSwitch云是一个SSaaS（Soft-Switch as a Service，软交换即服务）平台。
  • XSwitch云是一个UCaaS（Universal Communication as a Service，统一通信即服务）平台。
  • XSwitch系统是一个高度可定制的实时音视频通信平台，通过模块化设计、积木式叠加、开放的API接口，满足客户独一无二的功能需求。

XSwitch的网址是 https://xswitch.cn 。

1.2 运行环境

XSwitch运行于GNU/Linux环境，支持通用的64位服务器，支持虚拟机及Docker容器化、K8S云原生部署，以及Raspberry Pi等ARM系统。支持阿里云、腾讯云、微软云、华为云、青云、Amazon云等云端环境，支持私有化部署。支持国产Linux平台如统信UOS、麒麟等，支持国产CPU如ARM、MIPS、麒麟等，支持鲲鹏和泰山系列服务器。

1.3 基本功能和特性

  • 系统内部呼叫：分机呼叫
  • 异地呼叫：分支机构间呼叫
  • 语音和视频会议：多方语音电话会议、高清视频会议MCU
  • 小型呼叫中心：IVR及座席排队
  • 点击拨号
  • 录音、录像、直播
  • 连接传统电话和手机
  • 连接PSTN或IMS线路
  • 支持SIP
  • 支持UDP/TCP/TLS连接
  • 支持WebRTC，在浏览器中打电话
  • 传统设备对接
  • 移动端App
  • Android/iOS SIP客户端
  • 开放的API
  • 可对接各种CRM及第三方呼叫中心系统
  • 可二次开发、一切尽在掌控
  • 支持第三方功能模块
  • 多维度统计图表
  • 在线SIP跟踪
  • 在线日志跟踪
  • 支持双机高可用（HA）部署
  • 支持双平面和多平面部署
  • 中、英文Web管理界面
  • 支持PCMA/PCMU/OPUS/G722/H264/H265/VP8/VP9编码
  • 健康的生态环境

1.4 高级功能和特性

  • 连接到IMS网络
  • 4GVoLTE、5GNR视频呼叫
  • 连接到Agora网络
  • 连接到腾讯TRTC网络
  • 连接到微信小程序
  • BFCP双流支持
  • H323
  • 推流到RTMP
  • RTSP/RTMP拉流
  • GB28281摄像头接入
  • xTalk视频会议

具体功能根据软、硬件版本和型号可能有所不同。不同型号的产品与本文的描述也可能有所出入。

1.5 系统参数

根据硬件不同，所支持的用户量也不同。以8核8G内存的服务器为例。

  • 单机可支持1～10000路SIP注册
  • 1～5000路（Channel）并发呼叫
  • 1～800路视频呼叫
  • 1～400路视频会议融屏
  • 最大可支持36万BHCA（Busy Hour Call Attempt）

1.6 安装

  • 如果是购买硬件，系统在出厂时已安装完毕，可直接开始使用。
  • 如果是购买软件，一般以Docker镜象形式安装部署，您拿到本手册的时候系统应该已经安装好了。
  • 如果是从软件安装，可以参考《XSwitch安装配置手册》。

1.7 基本架构

  • XSwitch在生产环境部署时，一般搭配PostgreSQL数据库和Nginx Web服务器部署。
  • XSwitch内置XUI，不依赖任何其它外置系统和开发语言。
  • XSwitch支持积木式添加更多功能模块。

1.8 部署方式

XSwitch支持以下几种部署方式：

  • 小型嵌入式系统
    • 使用OpenWRT系统，使用SQLite数据库。
  • 小型Linux系统
    • 基于Debian 10/11部署，或基于Docker容器部署，使用PostgreSQL数据库。
  • 大型系统
    • 基于Debian 10/11部署，或基于Docker容器部署，使用PostgreSQL数据库，使用Kamailio与OpenResty做SIP和Web代理。
  • 定制化部署
    • XSwitch可以定制化部署在其它Linux系统或Windows平台上，支持K8S云原生部署。定制化部署超出了本文档的范围。

1.9 名词术语

  • VoIP：Voice over IP，即基于IP的语音传输。随着时代发展，VoIP现在也支持视频，也可以认为是Video over IP。
  • SIP Server：SIP服务器。
  • PBX：Private Branch eXchange，小交换机，通常都是SIP Server。
  • SBC：Session Border Controller，会话边界控制器。一般用于不同VoIP网络的分界点，它可以转换信令和媒体流，并保护运营商- 或企业VoIP网络。
  • B2BUA：Back to Back User Agent，背靠背用户代理。通过XSwitch通话的双方都是独立的通道，通过XSwitch背靠背的连接。
  • 网关：类似SBC，连接不同的VoIP网络，通常具有比SBC更强的路由功能和更多的路由策略。
  • 网元：网络中的一个设备或具有相对独立功能的组件，如PBX就是一个网元。
  • 中继：SIP Server间一个点对点的连接，中继分为出、入和双向三种。
  • 中继组：一组中继。中继组中包含出中继的负载分担策略。轮循、按百分比选择等。
  • 黑白名单：黑名单内的IP和号码不能打通，白名单内的IP和号码能通。
  • 路由码：8位字母或数字（可以包含-_等连字符，不能有其它字符和空格），可以在主叫号码，被叫号码，或SIP头域中携带。用于区分同一中继来话不同的主叫类型，进而可以选择不同的出局路由。
  • 呼叫源：呼叫从哪里来，用于选路由。
  • 目的地：呼叫到哪里去，可以是中继或中继组。
  • 号码变换：在路由的过程中可以变换主、被叫号码，也可以在中继组或中继上做变换。
  • 路由表：描述呼叫从哪里来到哪里去的表。
  • 路由：名词：路由表中的一条路由（一行）；动词：选路，根据当前通话的参数从路由表中选择一条路由。
  • 标志符：是一个字符串，除“-_.”外不允许有特殊符号，如不能有空格，中文以及有特殊含义的符号如“&$@\”等。
  • 分机：系统内的一个电话号码，必须属于一个用户。
  • 外线号码：从运营商处取得的电话号码，通常对应一条电话线或虚拟的电话线路。
  • 用户：能登录Web界面的管理员，或拥有分机的用户。
  • 多租户：在同一个系统中支持多个不同的组织、分支机构、公司等，不同租户中可以有相同的电话号码。XSwitch底层完全支持多租户，但Web界面没有严格的区分。
  • 域：域是SIP中的概念，也可以将租户分开，系统使用前需要先选定一个域。域可以是一个域名（FQDN，Fully Qualified Domain Name），也可以是一个IP地址。

1.10 约定

本手册内容和排版遵循以下约定：

  • 章节号或重要的内容会以粗体或黑体表示，有的地方可能有“重要”或“提示”字样。
  • 系统中会用到一些标志符，它们通常以等宽字体表示，如：context-1。
  • 菜单或按钮顺序以下列形式给出：【一级菜单】⇨【二级菜单】⇨【按钮】。
  • 有些内容会有（TLDR）标志，即（Too Long Don't Read），这些内容在快速阅读时可以先忽略。

系统中用到的字符串值（通常是名称字段的约束）遵循以下约定：

  • 表达式：大小写字母、数字及“-_.”，不能有其它字符，如“$/\;@%'"[]{}()”等
  • 任意字符串：任意合法的UTF-8字符串，不包含控制字符（ASCII码为0~31的字符）

系统中使用的按钮和动作使用以下约定：

  • 新建/New：弹出新建对话框，可以新建一条记录，成功后显示在列表页第一行
  • 添加/Add：有时候，有的页面上，资源是存在的，但是需要添加到某个列表时，比“新建”语义更明确一些
  • 删除/Delete：删除一行或多行
  • 导入/Import：弹出导入框
  • 导出/Export：导出Excel或CSV文件
  • 刷新/Refresh：在不刷新整个页面的情况下刷新数据
  • 保存/Save：保存当前修改
  • 重载/Reload：将当前数据应用到运行时的程序中
  • 上传/Upload：上传文件
  • 下载/Download：下载相关资源
  • 快速删除模式/Fast Delete Mode：可快速删除多条数据，而不需要确认

系统中的对象，有以下一些通用的字段和属性：

  • ID/ID：唯一标志
  • 名称/Name：最大20个汉字1
  • 描述/Description：最大250个汉字
  • 创建时间/Created At
  • 更新时间/Updated At
  • 删除时间/Deleted At
  • 启用/Enabled
  • 状态/Status

2 快速上手

任何管理员拿到一个新系统都想快速做一个体验，而不是先阅读冗长的手册。本章将带你快速打通第一个电话。

系统默认的管理员admin密码是admin，登录Web界面后可以看到一些统计信息和图表。

系统默认自带1000~1019共20个分机，密码都是1234。你可以使用任何一个分机注册到系统打电话。

可以用SIP话机或软电话注册到系统（注册端口可通过【高级配置】⇨【SIP】⇨default查看SIP端口，默认7060），常用的注册选项是：

  • 服务器：XSwitch服务器的IP地址，或域名
  • 用户名：如1000
  • 密码：如1234

有时候，你使用的域和IP地址不同，或者“域”只是个标志字符串不是一个合法的域名（FQDN），或者你在内网上注册根本无法解析这个域名2，这时候你就需要填入：

  • 域：域的名字
  • 代理服务器：XSwitch服务器的IP地址

通过这种方法，你的SIP终端就会将SIP注册及呼叫消息发到你指定的IP地址上，但SIP消息中的域是你指定的域名。

还有时候，你的SIP终端要求输入“鉴权用户名”，XSwitch默认的设置是它必须跟你的用户名相同。当然你熟悉了本系统，可以参考本手册后面的章节修改这个默认设置。

注册成功后，可以尝试拨打回声测试号码9196，一切正常的话它应该自动应答，你就能听到自己的声音。

注册两个不同的分机可以互打。

多个分机可以同时呼入3000会议室开会。如果你的终端支持视频（并且购买了XSwitch的视频许可），也可以进行视频会议。

如果拨打系统外的电话，如手机，则需要添加一个网关。具体网关的添加方法见后面的章节。

3 基本概念

本章描述XSwitch系统中的基本概念和设计原则。

3.1 用户及组织架构

  • 用户指一个人，属性有用户名、密码、电子邮件、手机号等，可以登录Web系统。
  • 用户名只可以是字母与数字的组合，区分大小写，除“-_.”外不能有特殊符号。
  • 组织架构对应公司的组织架构。
  • 组织架构可以级连。
  • 组织架构与用户是一对多关系，比如一个部门有个多个用户，但一个用户只属于一个部门。
  • 用户组是一组用户。
  • 用户组与用户是多对多关系，即一个用户可以属于多个组。
  • 用户与分机是一对多关系，即一个用户可以有多个分机。
  • 用户可以在呼叫中心中作为座席使用，可以把工号当做用户名和登录名。
  • 只有用户可以登录Web系统，根据设置，可以使用用户名、电子邮件、分机号、手机号等登录系统。
  • 在API调用时，为避免每次都使用密码调用，可以使用Token，或者开发Key调用。
  • 系统默认有两个特殊用户：
    • ID为0的system用户，没有任何权限，不能登录系统，不能被删除。当对应不到真人的时候可以使用它，如不属于任何人的分机号，可以关联到该用户。
    • ID为1的admin用户，该用户是最高级的管理员，在简单的场景中可以使用，在复杂的权限管理下，每个管理员都应该使用自己的账号登录。

实际上，为了使系统保持简单，我们淡化了用户的使用。在最小最简的应用中，您可以只有一个admin用户，但它下面可以挂很多分机。

3.2 分机

  • 一个用户可以有0个或多个分机。创建一个用户可以选择同时创建一个同名分机。
  • 在简单场景下，可以只有一个admin用户，其它分机都挂在该用户下（当然也可以挂在system用户下）。
  • 也可以用户与分机一一对应。
  • 分机可以使用密码或Token鉴权，如果在Websocket/WebRTC端使用，可以使用用户登录，再获取分机的Token（详见API手册）。
  • 如果是SIP客户端软件，在可以获取Token的情况下，可以/建议使用Token鉴权，如果是硬件话机则仍使用用户名/密码登录。
  • 用户管理分机，分机用于打电话。
  • 分机必须属于一个用户，在小规模应用场景下，为每个分机都建立一个对应的用户可能有点复杂，这时候，可以让分机属于system用户。

3.3 权限

权限指Web界面和API的使用权限。权限采用业界流行的RBAC（Role Based Access Control，基于角色的访问控制）设计。可以给一个用户分配多个不同的角色，不同的角色可以分配不同的权限。用户总是从自己所属的角色上获取权限。权限用于控制某些菜单对用户是否可见，某些API对用户是否可以访问等。

3.4 呼叫方向和呼叫流程

呼叫方向有入局（Inbound、Incoming）和出局（Outbound、Outgoing）呼叫两种。所有方向都是相对于XSwitch本身而言的。即呼叫的方向是相对的，看参照物是谁。比如我打了你一拳，我就是出拳，而对于你就是入拳了。

一个通常的误解是用户描述电话故障的时候通常说电话打不出去，这时候，他（她）其实是站在自己（电话机）的角度说的，对于XSwitch而言，可能是入局故障（从话机到XSwitch），也可能是出局故障（从XSwitch到落地网关或运营商）。所以在排查电话故障时，一定注意参照物，把呼叫流程搞清楚再下手。

XSwitch是一个B2BUA（背靠背用户代理），一个典型的呼叫流程如下：

3.5 路由

路由是本系统中最最重要的概念。路由即电话从哪里来到哪里去。呼叫源用于描述电话从哪里来，目的地描述电话到哪里去。在路由上可以做“号码变换”，设置计费规则，是否自动录音，设置不同时间段目的地等。

本系统路由均根据被叫号码判断。在默认配置中，来自“本地分机”（即注册分机）的呼叫，一般呼叫源为default，来自中继网关的外部呼叫，一般为public，在实际部署时可能有所不同。

呼叫源是针对来话而言的，系统允许在最先收到来话的地方设置关联的呼叫源，如本地注册用户来话、中继来话、网关来话等。

DID和DOD中的号码映射规则优先级要高于路由，除此之外，所有送到系统的呼叫都要通过路由决定去向，详见路由。

3.6 呼叫权限

呼叫权限指分机的呼叫权限，可以在分机上指定。如果分机的呼叫权限大于或等于路由上设置的呼叫权限，电话就能通，反之不通。

3.7 会话和通道

会话（Session）和通道（Channel）在XSwitch中是一对一的。XSwitch是一个背靠背的用户代理（B2BUA）。分机A通过XSwitch打给分机B，在XSwitch内会产生两个通道，也就是两个会话。同理，分机A通过XSwitch拨打一个手机号，也会产生两个通道。分机或外线打电话到IVR或会议，只会产生一个通道。每一个通道都有一个唯一的UUID（Universally Unique Identifier，通用唯一识别码，全球唯一，包含36个字符，如“00000000-0000-0000-0000-000000000000”）。

XSwitch的许可证是按通道授权的，分机打IVR或会议只占用一个通道授权，但通过网关打外线电话则占用两个授权。

3.8 通话

通话指一路电话、一个电话、或一通电话，指通信的两个实体间逻辑的概念。如分机A打给B，称为一路通话，它包含两个通道。三方通话其实也是一个通话，但是会有三个通道，每个通道代表参与通话的一方。

3.9 WebRTC

XSwitch支持基于SIP信令（SIP Over Websocket）及Verto信令的WebRTC通话，但是，WebRTC通话通常需要相应的https及相关证书。如何部署WebRTC通话不在本文档范围内。

如果已经部署了WebRTC功能，则可以在最新版的Chrome、Firefox、Microsoft Edge等主流浏览器中使用WebRTC通话。

WebRTC通话支持PCMA、PCMU、OPUS、H264、H265、VP8等音视频编码。

可以通过以下方法设置证书。

3.9.1 GoDaddy获取到的证书

客户需要提供自己的私钥（申请证书时上传的私钥）以及下载的证书

openssl x509 -in gd_bundle-g2-g1.crt -out chain.pem -outform PEM
cat 客户提供的证书.pem chain.pem > fullchain.pem
cat fullchain.pem 客户的私钥.pem > wss.pem
cat 客户提供的证书.pem 客户的私钥.pem > agent.pem

将生成的wss.pem上传到/usr/local/freeswitch/cert/下即可

3.9.2 nginx配置

如果存在Nginx镜像，修改Nginx配置文件，开启如下参数：

ssl_certificate /data/xswitch.cn/fullchain.pem;
ssl_certificate_key /data/xswitch.cn/客户私钥.pem;
ssl_trusted_certificate /data/xswitch.cn/chain.pem;

3.9.3 其他途径获取的证书

提供私钥以及证书即可。

按照上述方式上传到/usr/local/freeswitch/cert/以及修改Nginx配置。

4 Web界面使用说明

系统Web界面分为横向的快捷菜单、左侧功能菜单、全局功能区和工作区。菜单显示内容均可定制，左侧菜单也可以收起成条状，以便显示更大的工作区。

XSwitch工作台界面

全局功能区有用户设置及退出等功能。最右上角的小绿点（通常是绿色）代表Websocket的连接状态。绿色代表连接正常，黄色代表正在连接，红色代表连接失败。连接失败时系统可能也能正常工作，但是一些实时的消息推送将不能正常送达到前端，比如一些统计图表和系统状态等将不能实时变化，但通话不受影响。

4.1 多语言支持

Web界面支持多种语言，点击右上角的国旗图标，可以进行中英文切换。如果系统中安装超过三种语言包，则语言选择会以下拉菜单显示。

4.2 浏览器

系统界面使用跨浏览器框架Ant Design提供跨浏览器支持，支持主流浏览器较新的版本。

WebRTC功能支持音、视频通话，目前测试支持最新的桌面版Chrome、FireFox、Opera、Edge、Safari等浏览器、Android版Chrome和FireFox、iOS版Safari。

WebRTC技术比较新，更新也比较快，所以请保持浏览器版本最新。

如果在使用过程中发现功能不正常，请使用最新版本的Chrome或基于Chrome内核的Microsoft Edge浏览器，因为这是我们研发和测试过程中使用最多的浏览器。

4.3 界面使用约定

系统界面简单直观。大部分页面在设计时都遵循以下约定，下面以分机页面为例加以说明。

4.3.1 列表页

如分机列表，列表页列出所有分机，有翻页功能。

在该页面上通常有一个【新建】按钮可以新建一个分机。

4.3.2 详情页

点击一个分机号码，可以进入详情页，显示详细信息。

在该页面上有一个【编辑】按钮，点击后进入编辑状态，编辑完毕后可以保存。

可点击进入详情页的区域通常有其它颜色（如绿色）显示，其他参数黑色显示。

4.3.3 即时编辑

有些页面，如SIP Profile管理页面，有即时编辑（In Place Edit）功能。即时编辑适用于一个对象有很多属性，但你只想修改其中某一项内容的情况。

点击某一可编辑的区域时，则出现编辑框，修改内容后按【回车键】，都可以退出编辑状态并自动保存。如果想放弃编辑，则可以按键盘上的【ESC】键或用鼠标单击编辑框以外的任何区域。

如果不知道哪些区域可以编辑，则可以按下旁边的【编辑】按钮，则可编辑的区域会显示成输入文本框或选择框。

有的按钮也有即时编辑功能，一般用于“是”、“否”的场景。点击后会直接改变状态，并自动保存。

5 功能使用说明

5.1 登录

“用户”可以使用“用户名”和“密码”登录系统。登录后一直有效，关闭浏览器并不能使登录失效，只有在XSwitch重启后失效。为安全起见，建议在使用完成后主动退出系统。当然，在对登录安全性要求较高的场合，可以通过配合Redis缓存服务做超时自动退出。默认的XSwitch不带Redis缓存功能。

5.2 工作台

工作台首页主要显示一些系统相关的统计信息。

  • 更新时间：界面数据时间
  • 运行时间：XSwitch自启动以来的运行时间
  • 当前会话数：当前通话数量。注意XSwitch是一个B2BUA，呼入和呼出会分别占用一个通道，也就是会话
  • 系统状态：就绪：可以接打电话；暂停：系统暂停所有呼叫
  • 预设SPS：系统支持的最大SPS，即Sessions Per Second，指一秒内最大能承受的试呼次数
  • SPS：当前的SPS
  • 最大SPS：开机以来SPS峰值
  • 5分钟SPS：最近5分钟内SPS峰值
  • 最大并发会话数：系统开机以来并发会话数峰值
  • 5分钟最大会话数：最近5分钟内并发会话数峰值
  • 磁盘：根据年月日查询磁盘使用率
  • 内存：根据年月日查询磁盘使用率
  • 通道：根据年月日查询通道数/SPS

5.3 呼叫管理

呼叫相关的功能及设置。

5.3.1 分机

分机用于打电话。一个分机必须属于一个用户，可以为每个分机建一个对应的用户，也可以所有分机属于同一个用户。

5.3.1.1 基本属性

分机有以下一些基本属性：

  • ID：分机唯一标志，系统自动生成
  • 名称：该分机的名称，支持中文和空格
  • 号码：分机号，是一个“标志符字符串”，即只能是数字和字母的组合，区分大小写，除“-._”外不支持其它字符，如不能有空格或中文等
  • 密码：分机的密码，在注册和呼叫时会用到
  • 呼叫源：如果该分机发起呼叫，XSwitch就会认为它来自该呼叫源，进而通过呼叫源查找路由
  • 所属用户：选择一个已有的用户
  • 主叫名称：若为空，则以名称字段作为主叫名称，若设置为PASS，则透传SIP INVITE中的主叫名称
  • 主叫号码：若为空，则使用号码字段作为主叫号码，若设为PASS，则透传SIP INVITE中的主叫号码
号码透传设置
  • 域：该号码所属的域。若后台设置有force_domain，则该值是不可编辑的；反之，为多租户模式，可以编辑。
  • 类型：见分机类型。

关于号码透传：

  • 默认是可以透传主叫号码的，不管SIP还是Verto，都可以透传；
  • 如果不允许透传，在用户设置里把主叫号码和主叫名称设成指定的值；
  • 如果强制透传，把主叫号码和名称设成PASS。

5.3.1.2 分机类型

  • SIP：SIP分机，包括SIP over WebRTC
  • WebRTC：Verto协议的WebRTC分机
  • SIP+WebRTC：同一分机既支持SIP分机登录，也支持WebRTC分机登录，做被叫时会同振
  • 海康摄像头：支持GB28181协议的海康摄像头注册
  • 网关：将分机作为网关使用，比如可以使用FXO口的网关使用该账号注册到XSwitch上，多用于FSO口的网关在NAT后面的情况

5.3.1.3 高级属性–主叫业务

点击分机详情页面的【显示高级属性】按钮可以设置如下主叫属性：

5.3.1.3.1 呼出限制
  • 可以呼出
  • 禁止呼出
5.3.1.3.2 呼叫权限
  • 紧急呼叫：只能拨打110、119等特殊号码
  • 本局呼叫：仅在XSwitch内部呼叫
  • 本地呼叫：仅呼叫本地网（无区号）的号码
  • 国内呼叫：仅呼叫国内号码
  • 国际呼叫：可以呼叫国际号码

权限是递增的，高级的权限自动具有低级的呼叫权限，即开通了国际呼叫的分机可以呼叫所有号码。

5.3.1.3.3 代答

开启可以代答其他通话的权限。

  • 无权限：不可以代答任意通话
  • 分组代答：当同组中有振铃分机时，拨打*63可以代答该分机
  • 代答组名：选择组名，仅可以代答此组里的通话
  • 全局代答：拨打*75可以代答正在振铃的分机
5.3.1.3.4 强插

如果开启强插权限，如果某分机正在通话，拨打*62+分机号可以强行插入当前通话形成三方通话。

5.3.1.3.5 强拆

如果开启强拆权限，如果某分机正在通话，拨打*63+分机号可以强行插入当前通话并强制原来与该分机通话的一方挂机。

5.3.1.3.6 监听

如果开启监听权限，拨打*78+分机号可以监听指定号码的通话。

5.3.1.4 高级属性–被叫业务

点击分机详情页面的显示高级属性按钮可以设置以下属性：

5.3.1.4.1 呼入限制
  • 可以呼叫此号码
  • 禁止呼叫此号码
5.3.1.4.2 语音邮箱
  • 启用/禁用
  • 语言邮箱密码：仅支持纯数字和*，以便从话机上读取语音邮件时能正确输入。

这是一个被叫业务。分机开启了语音信箱后，如果做被叫时无法接通，则可以将来话转到语音邮箱提求主叫进行留言。

5.3.1.4.3 自动录音
  • 启用/禁用
5.3.1.4.4 呼叫转移
  • 呼叫转移号码：转移到的目的号码
  • 呼叫转移类型：有以下几种
    • 同振
    • 顺振
    • 无条件前转

配合呼叫转移号码以及超时时长使用，以分机1001为例，无条件转移，如果呼叫1001，那么则直接转接到呼叫转移号码对应的号码。如果设置了同振，则两个号码同时振铃。如果设置了顺振，则1001未响铃或拒接等情况下，通话转移到呼叫转移号码对应的号码。默认超时时长为60秒，如果设置了超时时长为15，则表示1001分机15秒后没有应答则直接转接到其他号码。

5.3.1.4.5 超时时长

呼叫该分机的超时时长。

5.3.1.4.6 彩铃
  • 启用/禁用
  • 铃音：铃音或音乐文件。当该分机做被叫时该彩铃会播放给主叫方
5.3.1.4.7 代答
  • 不允许被代答
  • 允许同组代答：当该分机振铃时，允许其他同组的分机通过拨打*63代答该通话
  • 代答组名：输入一个组名
  • 允许全局代答：允许其他拥有全局代答权限的分机通过拨打*75代答正在振铃的该分机
5.3.1.4.8 强插

允许其他分机拨打*62+分机号可以强行插入该分机的当前通话。

5.3.1.4.9 强拆

允许其他分机拨打*63+分机号可以强行插入当前通话并强制该分机通话挂机。

5.3.1.4.10 监听

允许其他分机拨打拨打*78+分机号监听该号码的通话。

5.3.1.4.11 分机编码

呼叫该分机时的编码。这可以在A与B没有共同编码时强制使用相应的编码。分机编码设置优先级高于路由界面中的媒体编码，即当分机设置了编码PCMA，路由界面设置了媒体编码PCMU，则选择PCMA去呼叫此分机。

5.3.1.4.12 自动录音

开启后则自动录音，此自动录音和路由上的自动录音区别在于路由时针对所有。分机的录音是只针对此分机（前提路由不开启录音）。

5.3.1.5 新建分机

新建分机有三种方法：

  • 在分机列表页面点击【新建】⇨【单个创建】或【批量创建】，批量创建
  • 在分机列表页面点机【导入】，导入一批分机（可根据导出的表格作为模版）
  • 在用户详情界面可以新建属于该用户的分机

5.3.1.6 用户名显示

经过鉴权的用户，在使用时最好使用${username}（鉴权用户名）。因为caller_id_number是可以由客户端指定的，不一定是你期望的。具体原因如下：

  • SIP注册界面中的“Display name”和“User ID”，会成为${caller_id_name}和${caller_id_number}，而这两个值可由set重置。Authorization Name才是真正的鉴权用户名，并成为${username}。

名称优先原则：

  • 如果在路由中set caller_id_name，则优先选被set后的值，如果没有被set,则${caller_id_name}会优先选系统用户里的主叫名称，如果没有设置主叫名称，则会取系统用户中的名称；
  • 如果在路由中set caller_id_number，则优先选被set后的值，如果没有被set,则${caller_id_number}会优先选择系统用户中的号码，
  • 如果想要获取主叫号码中的值，请使用${effective_caller_id_number};

SIP话机中的显示名称是无法通过通道变量获取的。

5.3.1.7 分机CIDR字段用法

分机CIDR字段用于使用IP鉴权。

通常情况下，分机注册和呼叫都使用用户名/密码鉴权方式。在知道对方IP地址（对方需为固定IP）的情况下，可以使用IP鉴权，而无需给对方分配密码。

CIDR的全称是无类域间路由（Classless Inter-Domain Routing），它是的格式是“IP地址/掩码位数”，可以指定一个IP地址或IP段，如：

  • 192.168.1.1/32：32位掩码（255.255.255.0），代表一个IP
  • 192.168.1.1/24：24位掩码（255.255.255.255），代表一个IP段，即192.168.1.0~192.168.1.255

当设置了CIDR以后，所有从这个IP地址段的来话都认为来自这个用户（为区分不同用户的来话，通常会设置主叫号码透传）。

CIDR在系统内部默认使用ACL实现，因此每次修改后要手要点击【重载】按钮重载ACL设置。

5.3.2 路由

路由表描述呼叫从哪里来到哪里去。当有呼叫到达XSwitch时，XSwitch会根据呼叫的来源确定一个“呼叫源”，并根据呼叫源和被叫号码查找路由表。如果能找到相应的路由，则会根据路由描述送往相应的目的地，如进入IVR、进入一个会议、呼叫另外一个号码等。

路由表查找策略有以下几个重要参数：

  • 呼叫源：呼叫从哪里来
  • 被叫号码前缀：用于匹配被叫号码的前几位数字或字母
  • 最大号长：该路由允许的最大号长
  • 目的地：如果路由匹配将呼叫送往何处

路由其他参数功能说明：

  • 黑/白名单：如果路由中选择了此参数，比如指定某个黑名单，那么所有通过此路由的呼叫，系统会先判断是否在黑名单中，如果是则不予通过。
  • 费率：默认系统费率为空，如果需要使用计费界面，那么根据呼叫线路选择对应的费率即可。
  • 呼叫类型：默认呼叫类型为最大权限类型（国际呼叫）。此权限类型和分机权限类型相对应。类型权限包含关系为：国际呼叫 > 国内呼叫 > 本地呼叫 > 本局呼叫 > 紧急呼叫。例如：路由呼叫类型为“国内呼叫”，那么类型为国内呼叫或国际呼叫的分机才有权限通过此路由外呼。
  • 代理媒体：默认为是。如果该参数为否，则媒体绕过，即不处理媒体。
  • 媒体编码：如果设置了媒体编码，当呼叫本地用户或通过网关呼叫被叫时，则指定此参数的编码进行呼叫协商
  • 时间段设置：默认为空，所有时间均可用。如果想工作时间和其他时间走不同的路由，那么点击展开，选择时间模版或直接创建工作时间，然后根据时间，选择相应的路由目的地类型即可。

5.3.2.1 路由默认功能码

功能码仅针对本地分机而言，为系统自带功能路由。

*3到*6为本地通话过程中，话机可通过按功能码实现相应功能；*62到*85为分机对其他通话进行的操作。

5.3.2.1.1 通话中功能码
  • *3：盲转；1001和1002通话，如果需要转到1003，1002只需按*31003即可
  • *4：协商转；1001和1002通话，如果需要转到1003，但需要先了解1003是否方便，那么1002只需按*41003，此时1002和1003通话，如果方便，则1002挂机，1001和1003通话，反之，1001和1002继续通话
  • *5：三方通话；1001和1002通话，如果需要1003加入，1002只需按*51003即可形成三方通话
  • *6：呼叫停泊；1001和1002通话，1002临时有事，那么只需按*6将来电暂存在系统中，其他用户拨打*76取回即可
5.3.2.1.2 分机操作功能码
  • *62：强插。如1001正在和1002通话，1003可通过拨打*62+1002，强行插入通话，形成三方通话。
  • *63：强拆。如1001正在和1002通话，1003可通过拨打*63+1002，强行挂断1001，从而和1002通话
  • *75：代答最近号码。如分机1001正在振铃，1002也在振铃，此时，1003可通过拨打*75代答最后振铃的分机（1002）
  • *76：指定代答。如分机1001正在振铃，1002也在振铃，此时，1003可通过拨打*76+1001代答指定分机（1001）
  • *77：取回指定停泊号码。针对通话通过*6已经停泊的，可以通过其他分机拨打*77+1001重新取回通话
  • *78：监听指定号码。如1001正在和1002通话，分机1003可通过拨打*78+1001，来实时监听该分机通话。
  • *79：组播。针对拨号*79可对所有配置组播地址话机进行喊话
  • *85：查询语音信箱文件。如1002呼叫1001，1001未接听，1002进行留言。当1001想要听取留言时，可直接拨打*85即可听取留言
  • *86：立即会议接入码。拨打*86即可获取临时会议号码并进入此临时会议。

5.3.2.2 路由优先级

XSwitch使用呼叫字冠号码最长匹配优先（longest-prefix）路由选择算法，被叫号码的前几位称为呼叫字冠（XSwitch中也称为被叫号码前缀），假设系统中只有如下一条路由：

1              通过移动网关出局

则所以人拨打所有1开头的号码，都会走这个路由。后来，你又加了一个联通网关，让某些号码通过联通网关出局，但你不确定这个网关是否好用，因此，你想用你自己的手机号测一下，因此你加了一条路由，路由表如下：

1              通过移动网关出局
1860535xxxx    通过联通网关出局

这样，当你拨打1860535xxxx时，它就会从联通网关出局，因为它匹配的号码更长、更精确，而其它以1开头的号码仍然从移动网关出局。等你测试没问题以后，你可以修改路由表，把0535xxxx去掉，让所有186开头的号码都从联通网关出局。如：

1              通过移动网关出局
186            通过联通网关出局

所以，号码最长匹配优先这个规则就是基于上述理论设计，下面是更详细的解释。

路由查找算法可以这样理解（实际的路由查找过程比描述的高效得多，这里的说明仅方便大家理解）：

  • 根据呼叫源，找到所有路由表项（行）
  • 从匹配的行中，找到所有“被叫号码前缀”与实际的被叫号码匹配的路由表项
  • 如果有多条匹配路由，则根据“最大号长”字段重新排序，最大号长越短越优先（因为它更严格、更精确、更匹配）
  • 如果还有多条匹配路由，则根据“被叫号码前缀”排序，匹配越长的越优先，这称为“号码最长匹配优先”算法

如路由表中有以下路由：

139
1390535

则呼叫13905350000会走第二条路由（从开头共有8位匹配，而第一条路由只有3位匹配），呼叫13912345678走第一条路由（3位匹配，第二条不匹配）。

注意，如果路由上设置了最大号长，则路由受号长约束。还是以上述号码为例，如果第一条路由的最大号长为11，第二条最大号长为8，则呼叫13905350000时，由于被叫号码的号长为11位，超出了第二条路由的限制（最大仅支持8位），因此即使它能匹配8位，但也只能走第一条路由。

即使被叫号长没有超出高大号长最大值，也是“最大号长”短者优先（因为这个匹配更精确），如路由表中有以下路由：

  • 起始号码：155 最大号长：12
  • 起始号码：155 最大号长：11

则呼叫15568181234走第二条路由。

路由被叫号码前缀可以为空字符串，依然采用长度最短匹配优先算法，如路由表中有以下路由：

  • 起始号码：[空] 最大号长：12
  • 起始号码：155 最大号长：13

则呼叫15568181234走第一条路由。同理，如果第二条路由长度变为11，则呼叫15568181234走第二条路由。

路由查找顺序跟路由规则有关，跟在路由表中的顺序关系不大。如果根据路由规则找到多条匹配路由，则以数据库返回的顺序为准取第一条。注意，数据库返回的顺序是不可预知的（如果有两条一模一样的路由，一般数据库会返回更新时间比较早的那一条，但最好不要依赖这种不确定的逻辑）。

路由的目的地有多种不同的条件，根据不同的条件生成相关的呼叫字符串。

这样设计主要是为了解决以下问题，假设路由表中有以下项：

被叫号码前缀 最大号长 目的地
1 4 本地分机
1 3 网关，短号码如110等
1 11 网关，呼手机
0 12 网关，长途
[空] 8 网关，市话

上表中是一个简单的办公室IP-PBX路由表。

  • 拨打数字1开头的4位号码是本地分机
  • 1开头的3位号码是特殊号码，送网关，如110、119等
  • 其它号码可以送到同一个或不同的网关
  • 最后一条是本地网（市话）呼叫，由于市话可以是除1以外任何数字开头的，所以前缀为空可以匹配任何号码，当然也可以以2～9开头做上8条路由，那样更明确，但也更复杂。

如果你买了一个新网关，想做个路由测试，但不想在确认新网关正常前影响其它通话，你就可以做一条更严格的路由，如用你的手机号前7位1555555作为被叫号码前缀，指向你的新网关。

5.3.2.3 号码变换规则

号码变换支持主叫和被叫号码变换，有以下几种类型：

  • -nnn+nnn：其中nnn为号码，-表示从号码开头删除nnn，+表示在号码开头加上nnn
  • rnnn和Rnnn：分别表示在号码开头和结尾替换掉相应位数，其中n可以是多个。如果位长小于n的个数，则号码会变为nnn。
  • mxnnn：从第x位起，替换掉nnn相应的位数，其中n可以是多个。如果位长小于n的个数，则号码会变为nnn，如果x大于9，还可以使用16进制数a-f，如f代表第15位，本算法不支持大于15位的变换。
  • ixnnn：在第x位前插入nnn，x取值0-9,a-f。
  • Ixnnn：在第x位后插入nnn，x取值0-9,a-f。
  • dxn：从第x位开始删掉n位，x和n取值0-9,a-f。
  • nnn：将全部号码替换为nnn。
  • /pattern/replace/：正则表达式替换，将匹配pattern的替换为replace。正则表达式使用PCRE格式。
号码变换实例
原号码 变换规则 变换后号码
01234 -0+9 91234
01234 -0 1234
01234 +9 901234
01234 999 999
01234 r999 99934
01234 R999 01999
01 r999 999
01 R999 999
01234 m3** 01**4
01234 i399 0199234
01234 I399 0129934
01234 d23 04
01234 /^(.*)[0-9][0-9]$/$1/ 012
123456 /^(\d{2})\d{2}(.*)$/$1**$2/ 12**56

高级变换规则

  • s/table/field1/field2/：将表table中的field1替换为field2。

示例：

设numbers表内容如下（该表在数据库中必须存在）：

高级变换示例
a b
1000 13912345678
1001 13987654321
原号码 变换规则 变换后号码
1000 s/numbers/a/b/ 13912345678
1001 s/numbers/a/b/ 13987654321
01000 -0\|s/numbers/a/b/ 13912345678

特别注意：在新建路由时，只能指定基本信息如名称、起始号码、描述、呼叫源、目的类型等，主叫、被叫号码变换等高级信息可以在路由创建完成后再修改。

5.3.2.4 新建路由、修改、删除

创建新用户账号有两种方法：

  • 点击【新建】，输入红色必填项
  • 点击用户界面右上方【导入】（适用于创建大批量用户），可通过导出获取路由模版
  • 点击名称进入路由详情页面 ⇨【编辑】⇨ 修改路由信息，保存即可。
  • 点击路由页面右侧【删除】，即可删除路由信息。
  • 点击路由页面右侧【启动】，即可启动或关闭此路由。

5.3.2.5 添加、修改路由Application

  • 点击路由名称进入路由详细页面 ⇨ 点击Applications右侧【添加】，即可添加Application ⇨ 点击【修改】，可修改选定的Application。如下图所示：
修改路由Application

5.3.2.6 目的地类型

路由的目的的决定通话的去向。有以下类型：

5.3.2.6.1 分机

路由到与被叫号码相同的分机号。如果分机不存在，则返回空号（SIP 404）。

5.3.2.6.2 同振分机组

路由到临时分机组，即目的类型选择【同振分机组】后，手动选择需要同振的分机。

当呼叫此路由的被叫号码时，被选中的分机会同步振铃，直到某个分机应答。

5.3.2.6.3 顺振分机组

路由到临时分机组，即目的类型选择【顺振分机组】后，手动选择需要顺振的分机。

当呼叫此路由的被叫号码时，被选中的分机中第一个会优先振铃，如果超时未接听则第二个分机振铃，直到主叫挂机或被应答。

5.3.2.6.4 指定会议室

路由到一个已存在的会议室，即在会议室界面已经创建好的会议室。会议室号码和被叫号码可以不相同。

5.3.2.6.5 同号会议室

路由到和被叫号码相同的会议室，如果被叫是3000，则路由到已创建好的号码为3000会议室。

5.3.2.6.6 立即会议接入码

不需要提前创建会议室，可随时开会，即动态创建一个临时会议室，会议号码会随机生成。

5.3.2.6.7 IVR

路由到一个IVR（语音导航功能）

5.3.2.6.8 指定队列

路由到指定的队列。比如拨打0535xxx，进到测试队列中。

5.3.2.6.9 同号码队列

需要事先建立与被叫号码相同的队列，适用于有很多队列需要适配的场景。

5.3.2.6.10 网关

路由到一个网关。需要在网关界面，提前创建对接网关信息。

5.3.2.6.11 分机网关

FXO口的网关作为一个分机注册到系统中，可以使用该网关出局。用于FXO网关位于NAT后面的情况。

简单来说，适用于网关在内网，系统在公网情况。

5.3.2.6.12 中继

SIP Server间一个点对点的连接，中继分为出、入和双向三种

5.3.2.6.13 中继组

中继组中包含中继的负载分担策略。轮循、按百分比选择等。

主要用于高并发高负载的情况，即使用kamailio时。

5.3.2.6.14 IP地址

路由到一个IP地址。格式如下（以10.0.0.1为例）：

  • 10.0.0.1：直接送往IP地址，默认端口5060，SIP消息为：sip:被叫号码@10.0.0.1
  • 10.0.0.1:5060：送往指定的IP和端口，默认使用UDP协议
  • 10.0.0.1:5060;transport=tcp：送往指定IP和端口，使用TCP协议
  • this.domain;fs_path=sip:proxy.this.domain;transport=tcp：送往域名，指定真实IP和端口，使用TCP协议
5.3.2.6.15 语音调度

语音调度，主要针对本系统分机而言。即系统分机间呼叫调度。

在使用此功能前，需要在分机界面，查看主被叫分机是否有相应的权限。如：

员工A的话机响铃，此时员工B想要代答。B拨打代答码后发现无法代答，通过查看权限，发现员工A没有代答权限或B开启了不允许被代答功能。

同样，其他强插/强拆/监听等均针对主被叫做了权限限制。

5.3.2.6.16 强插

系统默认功能码*62实现强插功能。

当需要强插某路通话时，用户拨打*62+分机号即可强行插入指定通话，形成三方通话。

5.3.2.6.17 强拆

系统默认功能码*63实现强拆功能。

当需要强拆某路通话时，拨打*63+分机号可以强行插入当前通话并强制原来与该分机通话的一方挂机。

5.3.2.6.18 监听

系统默认功能码*78实现监听功能。

开启了此参数，拨打*78+分机号可以监听指定号码的通话。

5.3.2.6.19 代答

系统默认功能码*63实现强插功能。

  • 代答最近分机：拨打*75可以代答正在振铃的分机
  • 代答指定分机：拨打*76+分机号可以代答指定的分机号
5.3.2.6.20 脚本

可以选择一个已编程的路由脚本，特殊应用，用于一些特定的场景。

5.3.2.6.21 积木

路由到一个积木。在积木界面，通过积木模块组合实现需求。也可以理解为图形化脚本功能实现。

5.3.2.6.22 分配器

分配器是一个算法，可对指定对象等进行加权轮询分配。通常用于网关分配。

5.3.2.6.23 系统

系统路由是一种高级路由。系统路由支持底层XSwitch（FreeSWITCH）提供的标准Application，如下列内容执行应答并回声：

answer
echo

下面的内容应答并播放文件：

answer
playback http://ip:port/welcome.wav

该路由一般仅供高级管理员使用，用于一些比较复杂的边缘场景，如在二次开发或调试时快速创建一些路由逻辑等。对于标准配置方法无法支持的路由逻辑，也可以在这里设置。

注意：错误的使用系统路由可能导致电话不通或不可预知的后果，使用前请资询XSwitch工程师。

5.3.2.6.24 组播

组播是使用TCP/IP协议的组播功能（发送一个IP包，同网段上有很多其它主机都能收到），从一台话机上对很多话机“广播喊话”，提高通话效率。使用时拿起电话拨打指定号码，即可对一群人（话机）喊话。该功能需要加载mod_esf模块。

目的类型选择“组播”，组播地址如果不填写，则默认组播地址为224.168.168.168:34567。如需填写其他地址及端口，则在文本框内直接填写并保存即可。

实现此功能需要话机按照如下配置：

在支持组播功能界面的话机上，按照如下所示，填写组播地址。如下图和所示

方位话机配置
潮流GXV3275配置

此时拿起话机拨打指定号码即可对所有设置过组播地址的话机进行喊话了。

特别注意：使用组播功能需要在同网段下，即话机和系统需要在同一个交换机下，一般不支持NAT环境（如需支持需要配置各路由器的组播路由，但需要注意网络安全，具体的配置方法超出本手册范围）。

Linux服务器系统上通常需要配置组播路由，如下：

ip route add 224.0.0.0/4 dev eth0 src 192.168.x.x

5.3.2.7 Application

采用XSwitch（FreeSWITCH）提供的标准Application，主要用于临时设置一些通道变量或其他参数。

名称为App名称，如常用的set，值为具体的参数值，如effective_caller_id_name=XSwitch。

5.3.2.7.1 智能回呼

智能回呼：在一定时间内打出去的电话，如果客户回过来时就直接分配到最近的分机号上去。

指定时间通过【高级配置】⇨【系统管理】⇨【全局变量】中参数callback_time_limit控制（单位为秒）。如果没有设置此参数，则系统默认为3600秒时间内的通话可以回呼。如下图所示：

时间设置

为了实现部分用户想要的智能回呼功能，我们在路由中通过设置Application实现。如下：

  • 外呼路由里，在Application添加弹出框中，输入名称xcallback，值track保存，那么所有经过这条路由打出去的通话都会被追踪。

  • 来话路由里，在Application添加弹出框中，输入名称xcallback，值check保存，那么所有经过这条路由的来话都会先判断一定时间内是否有分机呼叫过，如果有则直接路由到对应的分机响铃。如下图所示：

智能回呼

如果想要实现通过相同的网关出局的通话，只能通过相同的网关线路呼入时才去分配到最近的号码，那么如下：

  • 外呼路由里，在Application添加弹出框中，输入名称xcallback，值track-zl保存，那么所有经过这条路由打出去的通话都会被追踪并记录该线路名。

  • 来话路由里，在Application添加弹出框中，输入名称xcallback，值check-zl保存，那么所有经过这条路由的来话都会先判断一定时间内是否有经过此线路的分机呼叫过，如果有则直接路由到对应的分机响铃。

5.3.2.8 路由查询

查询功能，是根据被叫号码来确定路由是否建立正确。比如想拨打156xxxxxxx这个号码，但是不知道是否已经建了路由或不知道拨打此号码会走哪条路由。

如果不输入呼叫源则默认查询所有呼叫源。

路由查询

如果结果列表有多条路由，则会走与呼叫源的匹配的第一条路由。如果没有结果，表示没有路由，拨打该号码将返回空号。

点击【重置】后，可重新显示所有路由。

点击【？】可显示查询使用说明。

5.3.2.9 路由列表导出

点击用户界面右上方【导出】，导出后格式为.csv。

5.3.3 呼叫源

呼叫源，即电话呼叫的来源。通常在用户、分机、路由中关联应用。如果你需要给用户设置新的呼叫源，则需要在此界面先新建“呼叫源”，方可在用户、分机、路由中选择关联此呼叫源。

如果你需要实现DID功能，则需要在相应的呼叫源右侧点击【启用DID】。开启DID功能后，当有通话过来时，系统会自动判断此号码是否为DID号码，如果是则直接呼叫对应的号码。通常default和public为默认系统呼叫源，默认不开启DID，如下图所示：

DID号码

5.3.4 黑白名单

黑白名单主要配合路由使用。白名单与黑名单相对应。通过黑白名单规则对通话进行控制。路由中黑名单启用后，被列入到黑名单的用户（号码）不能通过。如果设立了白名单，则在白名单中的用户（号码）才可通过，其他用户（号码）则直接被拒绝，安全性和快捷性都大大提高。

5.3.4.1 新建/修改/删除黑白名单

  • 点击黑名单界面右上方【新建】，填入名称等必填参数。

  • 新建黑名单后，点击名称进入黑名单界面 ⇨ 点击右上方【编辑】，即可修改黑名单信息 ⇨ 点击【保存】，保存修改后的分组信息。

  • 点击黑名单界面最右侧【删除】，即可删除时间管理信息。

5.3.4.2 添加、编辑黑名单号码列表

  • 点击名称，进入黑名单界面，点击号码列表右侧的【添加】，填写名称、起始号码等创建新的黑名单号码列表。如下所示：
黑白名单
  • 添加黑名单号码列表后，点击【编辑】，编辑完成后按回车键保存编辑好的黑白名单号码列表。

特别注意：起始号码采用相似匹配模式，当起始号码写为10时，那么此条信息就包含所有10开头的号码。当路由中采用此黑/白名单，则会针对所有10开头的号码均起作用。

5.3.5 IVR

IVR（Interactive Voice Response）即交互式语音应答，也就是我们常说的语音菜单。当来电后，播放欢迎音，然后根据语音提示，执行不同操作。

每个IVR都有个自己的名字，如“welcome”。在各自的IVR中通过配置参数实现不同功能。参数简介如下：

IVR常用参数如下：

  • 名称：IVR的名称
  • 描述：简短的描述信息
  • 欢迎音：首次进入IVR的欢迎音，如：“您好，欢迎致电XSwitch，请直拨分机号，查号请拨0……”
  • 短欢迎音：如果用户超时没有按键，或按键错误，则重复提醒用户，一般省略前面的欢迎语或广告语，直接说功能，如：“请直拨分机号，查号请拨0……”
  • 标志符：自动生成，用于XSwitch内部关联该IVR，该标志符也会出现在XSwitch的日志中。
  • 最大按键位数：收到几位开始匹配，默认为1，如果需要输入分机号的情况下，则至少要有分机号相同的位数。
  • 错键提示音：用户按错了键提示音
  • 挂断音：菜单退出时（一般超时没有按键）的声音

IVR其他默认参数如下：

  • 最大失败次数：容忍用户按键错误次数
  • 最大超时次数：最大超时次数
  • 超时时长：即多长时间没有收到按键就超时，播放其他提示音
  • 两次按键间隔：两次按键最大间隔时间
  • 失败后执行：超过最大失败次数后执行一个或一些指令，见后面“IVR内部指令”
  • 超时后执行：超过最大失败次数后执行一个或一些指令，见后面“IVR内部指令”
  • TTS嗓音：如果使用TTS语音转换则填入对应声音
  • TTS引擎：如果使用TTS语音转换则填入

5.3.5.1 IVR内部指令

通常可以在按键多次失败后或超时后执行一些指令。

5.3.5.1.1 进入另一个IVR

如

ivr ivr-name
5.3.5.1.2 执行一个Lua脚本

如：

lua /tmp/test.lua

Lua脚本内容：

session:streamFile("/tmp/test.wav")
session:hangup()
5.3.5.1.3 执行路由

执行路由表项中的指令，语法：

execute_extension dest XML context
  • execute_extension：执行路由中的动作
  • dest：被叫号码
  • XML：拨号计划类型，一般为XML
  • context：呼叫源标志符，如：context-2

示例：

execute_extension play XML context-2

在路由中配置：

  • 呼叫源：context-2
  • 被叫号码前前缀：play
  • 目的地类型：系统
  • 目的地：
    • play /tmp/test.wav
    • hangup

该路由执行完毕后会返回当前IVR，所以，如果不需要返回，则需要在路由执行完毕后transfer到其它路由或挂机。

5.3.5.1.4 转移到路由

与执行路由类似，转移后不再回到当前IVR，如：

transfer play XML context-2
5.3.5.1.5 转移到内联路由

内联路由语法比较复杂，本质上与上面相同，如：

transfer set:ivr_hangup_cause=system_hangup,playback:/tmp/test.wav,hangup inline

5.3.5.2 新建/修改/删除IVR

  • 点击IVR界面右上方【新建】，填入名称等必填参数，欢迎音，欢迎音简短提示，错键提示音等创建新的IVR。点击红色框内按钮，即可直接播放欢迎音，再次点击则暂停此音乐，其他语音文件同上进行播放。如下图所示：
添加IVR

  • 新建IVR后，点击名称，进入IVR界面，点击【编辑】，即可修改分组信息 ⇨ 点击【保存】，保存修改后的IVR信息。其中语音类文件修改，只需要点击参数右侧【...】即可弹出媒体文件选择。

  • 点击IVR界面最右侧【删除】，即可删除IVR信息。

5.3.5.3 IVR按键动作

  • 匹配前缀：默认不开启此功能。如果选择开启，则匹配按键开头的所有号码，比如：按键写10,那么当用户按10xx时均可以匹配此项。

系统默认提供如下功能：

  • 转分机：输入按键数，选择转到的分机号码，支持选择多个分机（多个分机同时振铃）
  • 转队列：输入按键数，选择转到的已创建的队列名（如没有下拉框，需前往队列界面创建）
  • 转会议室：输入按键数，选择转到已创建的会议室（如没有下拉框，需前往会议室界面创建）
  • 转临时会议：输入按键数，选择会议模版，则，用户按键后直接进入和按键相同号码会议
  • 执行脚本：输入按键数，选择脚本（如没有下拉框，需媒体文件界面上传脚本）
  • 高级指令：输入按键数，在文本框填写FS动作指令（适用于对FS指令比较熟悉的人员，文本框不支持多app）
  • 转路由：输入按键数，选择呼叫源，被叫号码（如果不填，默认为客户输入的按键数值）。通话会重新查找路由并转接出去（适用于所有已在路由界面创建的情况）
  • 播放文件：输入按键数，选择语音文件（如没有下拉框，需媒体文件界面上传）
  • 转下级菜单：转到下级IVR
  • 返回上级菜单：返回上级IVR
  • 返回主菜单：返回主IVR
  • 退出
5.3.5.3.1 高级指令参考

IVR常用指令参考如下：

按键 执行 文本 备注
0 高级指令 bridge user/1001|user/1003 桥接到1001或1003，1001如果未响应，则1003响铃
1 高级指令 bridge [leg_timeout=40]user/$1 桥接到获取的按键号码，40秒后超时挂断
2 高级指令 transfer $1 xml public 转接到获取的按键号码
3 高级指令 lua ivr.lua $1 执行Lua脚本，在脚本中可以通过argv[1]获取按键值
4 高级指令 fifo default in undef 转接到fifo，可实现多个账号順玲或全部响铃等功能

IVR如果进入callcenter队列后，在队列无人应答时如果想跳出队列回到IVR开始欢迎音处，需要在IVR对应的路由设置如下参数，

set cc_exit_keys=8

即按8跳出队列，重新听取IVR欢迎信息并重新选择。路由设置如下图所示

IVR路由设置

5.3.6 积木

该模块可通过积木组合实现大多数程序员想要的功能，并导出相对应的代码，代码形式共三种：Lua、XML、SVG。同理，也可通过导入，将代码转变成积木模式。

点击首页左侧【呼叫管理】⇨【积木】⇨ 进入积木模块。

点击【新建】⇨ 输入名称，添加描述 ⇨ 点击名称，创建积木。

5.3.6.1 生成积木

从左侧中选择合适的积木进行组合，实现各种功能。直观，易操作。

参考积木如下以及所示：

积木参考一
积木参考二

注意：逻辑、文本、列表、函数的模块中含有设置按钮，点击设置可根据需求修改模板，提供更多选择。如下图所示：

积木隐藏功能

积木完成后，点击【保存】，共生成三种保存格式：XML、SVG和Lua。

5.3.6.2 导入代码生成积木

通过导入，可将XML文件代码转换成积木。该功能仅限XML格式的代码。 点击【导入】，选中XML文件，打开即可还原成积木。

特别注意：XML文件内容必须是积木对应的XML代码。

保存路径：默认所有积木生成的文件保存在/usr/local/freeswitch/storage/blocks中。

详细说明参见《XSwitch积木使用手册》。

5.3.7 DID

DID，即直接向内拨号，该服务原本由电话公司提供的，它使用户能够直接拨打PBX或VoIP系统中的分机号码，而无需求助于总机或自动话务系统。现通过XSwitch系统也可以实现。

如果使用DID功能，需要在【呼叫】⇨【呼叫源】中启用DID。在DID页面设置好DID号码后，当有来话时如果开启了DID，则直接呼叫DID对应的分机。

DID设置如下图所示：

热线号码

5.3.8 DOD

DOD应用于分机外呼时使用哪条线路或中继组。在XSwitch中仅对路由类型为网关或分配器或集群中继时起作用。

现在以类型为网关为例：

场景说明：1001对应DOD线路号码为01086201111，那么当1001通过网关/分配器路由外呼时会优先查看01086201111下的网关，如果设置了指定网关那么会优先选01086201111下的指定网关并发送指定号码01086201111。

第一步：创建分机与线路对应关系，如下图所示：

分机与线路

第二步：创建线路与网关对应关系，如下图所示：

线路与网关

那么分机1001外呼时会选择example网关线路呼叫。其他分机外呼时则通过路由界面设定的网关线路。

5.3.9 网关

如果你拥有某个运营商提供的SIP账号、模拟网关或数字中继网关，均可通过此界面配置实现SIP拨打外部电话，该账号即为SIP网关。

点击页面左侧【呼叫管理】⇨【网关】，即可进入网关管理界面。

5.3.9.1 新建网关

点击【新建】⇨ 输入名称、服务器、用户名、密码、描述，选择SIP Profile【default】/【public】，选择模板【default】或【gateway】，选择是否注册。其中红色部分为必填。在此页面仅含基本参数，如需更详细的设置，请点击【编辑】进行重新设置。

在与对端网关使用IP对接时，服务器处输入网关地址，用户名和密码处可以随便填（底层逻辑中这两项为必填项，但可以随意填），是否注册处可选择“否”。

注意：新建网关时，名称必须为英文，否则网关无法生效。如果不想出现呼入需要鉴权的情况，SIP Profile选择public。

网关注册图如图所示：

网关

5.3.9.2 修改及删除

  • 在网关界面，如下图所示，控制一栏含有【注册】/【注销】/【开始】/【停止】共四个控制按钮。点击【注册】即可进行网关注册；点击【注销】即注销注册；点击【停止】则关闭网关功能；点击右侧【删除】，即可删除该网关。
控制网关
  • 删除网关时，需要先停止网关。当网关信息为灰色时，点击删除即可生效。
  • 点击网关名称，即可对网关信息进行编辑修改，在编辑页面中包含网关需要的更多其他参数，根据需要可自行启动。

特别注意：修改网关参数后，需要通过点击停止再开始方可生效

5.3.9.3 网关参数及变量

网关参数列出了网关可能用到的参数，默认不需要开启，如果在和其他硬件网关对接时遇到特殊情况，比如发送指定头，那么根据需求开启参数即可。

网关变量是为了更好的针对某个网关进行设置通道变量。比如，SIP中设置了全局编码，但有时我们需要根据不同网关设置不同编码，此时，我们在网关变量中设置添加即可。如下如下所示：

网关变量

其中，方向可选inbound、outbound或null，其中null表示两个方向均设置。

5.3.10 中继

SIP Server间一个点对点的连接，中继分为出、入和双向三种。网关也可以理解为一个中继。

一般中继和中继组配合Kamailio使用，普通通话，使用网关即可。

  • 点击中继界面右上方“新建”，填入名称、中继地址、类型（普通中继、GW-FS中继、国际长途中继、WAC中继）等必填参数，创建新的中继。如下图所示：
添加中继
  • 新建中继后，点击名称，进入中继详细界面 ⇨ 点击右上方【编辑】，即可修改中继信息 ⇨ 点击【保存】，保存修改后的中继信息。
  • 点击中继界面最右侧【删除】，即可删除选中的中继信息。

5.3.11 中继组

中继组主要对所包含的中继进行负载分担，策略为轮循、按百分比选择等。通常配合Kamailio使用，在不使用Kamailio时，目前仅支持轮循、百分比两种策略。

  • 点击中继组界面右上方【新建】，填入名称、类型（普通中继、GW-FS中继、国际长途中继、WAC中继）等必填参数，创建新的中继组。如下图所示：
添加中继组
  • 新建中继组后，点击名称，进入中继组详细界面 ⇨ 点击右上方【编辑】，即可修改中继组信息 ⇨ 点击【保存】，保存修改后的中继组信息。
  • 点击中继组界面最右侧【删除】，即可删除选中的中继组信息。

5.3.11.1 添加、删除中继组中继成员

点击中继组名称，进入中继组详细界面：

  • 勾选【全选】，可一次性添加全部中继成员。
  • 点击【添加中继】，可选择性添加中继成员。
  • 点击【移除所有】，可移除所有添加的中继成员。
  • 点击添加的中继成员右侧【删除】，可删除选定的中继。

5.3.12 时间管理

5.3.12.1 新建/修改/删除时间管理

  • 点击时间管理界面右上方【新建】，填入名称等必填参数，创建新的时间管理即可。
  • 新建时间管理后，点击名称，进入时间管理界面 ⇨ 点击右上方【编辑】，即可修改分时间管理信息 ⇨ 点击【保存】，保存修改后的分组信息。
  • 点击【时间范围设置】，可设置工作时间、节假日。

5.3.12.2 启用/禁用工作时间

在时间管理界面创建完成后，可进入“路由界面”，在路由详情界面的“时间段设置”中，选择该模版即可

5.3.13 路由码

路由码限制由8位字母或数字（可以包含“-_”等连字符，不能有其它字符和空格）组合，可以在主叫号码，被叫号码，或SIP头域中携带。用于区分同一中继来话不同的主叫类型，进而可以选择不同的出局路由。

系统收到一路电话，首先确定呼叫源（即呼叫是从哪里来的），呼叫源通常以字符串表示。路由码也是其中一种呼叫源。如果来话带路由码，则呼叫源等于“code-路由码”。

通常配合Kamailio使用，如无Kamailio，则忽略此界面即可。

5.4 会议

会议相关功能。系统支持立即会议，预约会议等。代替原有会议室功能。

5.4.1 立即会议

立即会议用于临时即兴发起一个会议。用户可以用话机或网页直接呼入一个临时会议，会议号会随机生成。然后用户可以将会议信息通过微信，邮件等方式分享给其它人，其它人拨打该号码或点击链接可以参会。

规则：

  • 立即会议不能进入会控界面
  • 加入立即会议不需要密码
  • 任何人知道会议号均可加入
  • 会议可以被锁定，锁定后任何人不能再加入
  • 在Web界面上使用锁定按钮锁定，任何人都有权限锁定，在话机上使用功能码锁定
  • 会议号随机生成

立即会议可以使用以下方式创建：

  • 在页面右下角【电话】按钮上点“立即会议” （仅部分版本支持）
  • 在话机上拨打“立即会议接入码”，默认为*86

相关路由设置：

  • 让有权限呼叫源都能呼叫到“立即会议接入码”，默认为*86
  • 在全局变量中设置，立即会议字冠，所有立即会议号码均由此开头，默认为72，固定为两位数字
  • 在路由中设置，设置立即会议字冠，路由到立即会议，固定为两位数字

会议号生成规则：

两位立即会议字冠 + 7位随机数字

5.4.2 预约会议

预约会议用于预约计划的会议。

预约会议字冠规则：

  • 在全局变量中设置预约会议字冠，默认为71
  • 需要在所有路由呼叫源上设置预约会议字冠，路由到预约会议
  • 预约会议号由预约会议字冠加后面7位随机数字组成，共9位

呼叫规则：

  • 无论普通会议还是预约会议一旦取消，则不可再呼入此会议中。
  • 如果是周期性会议，取消仅取消即将到来的下一次会议（如本周临时有事取消一次周例会），后面的会议不受影响。
  • 如果为普通会议，只有开始时间和结束时间当天可以呼叫，其会议号码7天（可配置）内不可重复使用。
  • 如果为周期性会议，在会议前以及下一次会议开始时间前内均可呼叫本次会议，会议话单数据会累积在本次会议中。
  • 会议号为随机数字，为支持固定会议号，可以使用“短号”呼入。短号必须在号码池中选择。

5.4.2.1 短号和号码池

短号用于一种特殊情况的呼叫。有时候，创建一个会议，希望不管时候都用同一个号码呼入。这时候，可以通过创建一个永远存在的周期性预约会议解决，关联一个短号码然后就可以永远呼叫该号码入会。

内部呼叫，短号可以相对固定，比如用户记住一个会议短号为3000。则可以通过拨打该号码入会。

短号必须从号码池中选择，号码池由管理员分配，号码池与用户所在的组相关。

多个会议短号不能冲突，如果一个组中有多个管理员管理会议，则短号的使用规则由使用的人自行协调，系统不限制任何使用规则。

路由规则：需要在路由中设置规则，短号对应的号码路由到预约会议。

5.4.2.2 会议详情

普通会议，点击会议详情，会显示改会议相关信息，当天会议配置均可以修改（在详情界面增加“修改日志”记录链接）

如果为周期性会议，则显示周期性会议最近一次会议信息。如：如果周期性会议为每周三会议，则会议详情中显示最近一次周三的日期及开会时间；

修改周期性会议，如果选择修改本次会议，则只允许修改开始时间和结束时间，其他参数不允许修改；

修改周期性会议，如果选择修改周期性会议，则可修改所有参数；

修改界面和创建预约会议界面相同，在之前已创建好的界面上继续增删改动作。

5.4.3 分享会议

分享会议中的网页链接信息，包含内部账号呼叫号码。

  • 内部人员可以直接呼叫会议号入会
  • 外部人员可以通过一次性Token进行验证，实现网页呼叫到分享的会议。（暂未实现）

5.4.4 取消会议

如果为普通会议，点击“取消会议”，则取消本次会议；

如果为周期性会议，点击“取消会议”，选择取消本次会议还是周期性会议；如果取消本地会议，则周期性会议自动选择下一次会议时间；如果取消周期性会议则整个会议自动默认结束；

已取消的会议会自动进入历史会议，且与会者不可再入会（如拨打已取消的会议号码则提示会议已取消）。

如果为周期性会议，在会议详情中，取消会议默认为取消本次会议。取消后会议详情中开始时间自动下延到下一次会议时间。

5.4.5 我发起的会议

我创建的会议或作为辅助者的会议

我创建的会议以及被选为辅助者的会议均在此界面显示，且可以进行编辑、进入会议控制等

5.4.6 我参与的会议

显示所有我作为与会者加入的会议

我参与的会议只能显示会议，不可进入会议详情，编辑会议，不可进入会议控制。

如果我参与的会议被设置为管理员，则可进入会议详情，可显示会议控制

5.4.7 历史会议

显示我参与的所有会议，包括我创建、辅助以及参与的其他会议，显示其会议名称、号码、开始时间、结束时间、会议总时长、会议类型、会议状态。其中，如果为已开始的会议，历史会议则显示真正的开会时间和结束时间，如果是已取消等情况则显示预约时的时间。

如果为当天创建的会议（非即时会议），当到达会议结束时间，依然未发起会议，则放到历史会议中；

如果为当天创建的会议，如果已经开过会，当历史会议中话单则关联所有和此会议相关的话单。如果在其他时间内（限制一个月）有人再次呼入该会议则只更新历史会议信息，不再在我的会议中显示。

历史会议中，如果是我创建的会议或我参与的（但被设置为管理员），则可显示“话单详情”按钮，“话单详情”中显示会议预定“开始时间”、“结束时间”、“会议名称”、“会议类型”、“最早人会时间”、“最晚退会时间”、“会议总时长”以及涉及到的会议话单ID。通过会议话单ID可跳转到相关会议话单，查看详细信息（如与会者、会议录像等）

如果是我参与的会议（未被设置管理员），则仅显示历史会议信息，不可点击“会议话单详情”，即，不可查看此会议与会者等信息。

5.4.8 会议

该功能在未来的版本中会取消，请使用预约会议代替。

可创建多个会议室，如3000，可根据实际需求对此会议进行特别设置。通过界面控制按钮，进入会议控制界面从而对某个会议进行操作控制。

5.4.8.1 新建会议室

  • 点击菜单栏【会议设置】⇨【会议室】⇨【新建】，输入名称、描述（对会议简单介绍）、号码即可。
  • 新建完成后，点击会议室名称，进入编辑界面。
  • 会议室命名只能使用字母数字和下划线，描述栏中可以使用中文对会议室进行描述。

5.4.8.2 与会者

  • 通过【添加组成员】，可按组加入成员并排序。
  • 通过【添加与会者】，可新建并加入创建的与会者。
  • 通过【编辑】，可编辑添加的与会者信息。
  • 点击【设为】则可将与会者设置为管理员。

5.4.8.3 会议室参数

1、画布

画布为会议人员所在区域，通常设置为1，即所有成员均在一个区域内。

根据需要也可设置为2，画布设置为2后，默认除管理员外，其他成员均在画布2上，会议默认除管理员均禁言。

2、管理员

管理员为会议管理员，可对会议进行操作，默认管理员进入会议不禁言。

3、视频模式

通常为“透传”、“融屏”、“转码”。

  • 透传要求所有客户端编码一致；
  • 转码针对客户端编码不同进行转码使用；
  • 融屏，即对视频进行解码，是典型的MCU模式，一般使用该模式。

4、会议模版

在“会议管理”–“会议模版”中设置，通常可以通过会议模版设置进入会议播放的各种语音提示、画面布局、会议室分辨率设置等，具体参考会议模版界面。

5、呼叫权限

1）只允许认证用户呼入

只有同时符合以下两个条件才可加入会议：

  • 属于用户模块中的账号；
  • 属于会议室中的与会者。

防止他人呼叫时修改主叫号码（比如：origination_caller_id_number）混入会议。

2） 检查主叫号码

如果主叫号码属于会议室中的与会者即可参加此会议室

3）允许任何人呼入

不限制账号来源

6、字幕显示

通常设置为${caller_id_number} ${caller_id_name}

7、字幕大小

字幕宽度，数字越大，宽度越大，通常设置为1或2

8、所属用户

所属用户，即此会议室归谁所属。

例如，所属用户为1009，则，仅1009账号登录后可看到此会议室，而其他账号登录无法看到此会议室，同样也无法操作。

设置所属用户：点击此用户1009，点击“编辑”，在“类型”一行，选择会议管理员，保存即可。

9、字幕颜色

分为背景色和字体颜色，如果遇到会议中没有显示字幕，可查看背景色是否和字体颜色相同导致被覆盖。

10、容量

容量为会议成员最大数，如果设置为10，当会议中成员达到10后，其他人无法加入会议。

11、自动禁言

如果选择了自动禁言，那么默认除管理员外，其他会议成员呼入后，自动禁言。如果为否。则所有成员呼入后均可自由发言。

此功能仅针对画布数为1的情况。

12、管理员/普通用户密码

设置管理员密码/普通用户密码。如果设置了管理员密码，则普通用户密码也必须设置，否则呼入会议后会提示“您还尚未设置普通用户会议密码”。

一旦设置了管理员密码，那么只有管理员密码输入成功后，方可开启会议，否则提示“管理员尚未加入会议”。

5.4.8.4 会议控制

点击会议界面的某个会议室右侧【控制】按钮，则可进入会议控制界面，对某个会议室进行控制。如下所示：

  • 控制画布
  • 控制音视频开启
  • 呼叫成员入会
  • 录制
  • 推流
  • 控制音视频文件播放
  • 锁定
  • 挂断

5.4.9 会议模版

会议模版用于对会议进行参数设置，以下为常用参数介绍。

  • conference-flags：通常使用默认即可。当然如果想体验不一样的会议效果，也可设置为livearray-sync|minimize-video-encoding|xvideo-bridge-first-two|manage-inbound-video-bitrate|video-mute-exit-canvas进行体验
  • moderator-controls：默认不开启此参数，此参数需和会议控制进行关联使用，比如，在会议控制中设置了admin_control,将admin_control填写在此参数框内，则表示管理员可以执行admin_control里规定的指令操作。特别注意：如果想使用moderator-controls需要同时开启moderator-flag为moderator，默认开启。
  • caller-controls：此参数和moderator-controls相似，也要配合会议控制才可使用，此参数表示普通会议成员可操作的指令。
  • video-layout-name：会议画面布局，默认group:grid，表示根据会议成员数自动调节画布上画面布局。当然，如果你想固定只显示4个人，可以设置为2x2。另外，如果视频模式为透传，则此参数不起作用。
  • domain：会议号后面的域名，每个固定会议室会议名为name-domain，比如3000-xswitch.cn,通常使用默认值即可。
  • video-mode：视频模式，mux为容屏
  • *-sound：所有-sound结尾参数均为会议相关语音。根据需求修改或使用默认语音提示。

5.4.10 按键控制

按键控制主要是指管理员或普通与会者通过按键进行控制会议中通话，比如开启/关闭语音，退出会议等。

  • 新建完成后，点击会议控制名称，进入界面，添加相关参数即可。
  • 进入某个详情界面，填入按键数、功能类型等新建参数。
  • 点击参数右侧【删除】，删除选定的会议室参数。

5.4.10.1 参数

参考下图所示：

会议控制
  • mute on：开启音频
  • mute off：关掉音频
  • vmute on：开启视频
  • vmute off：关掉视频
  • deaf mute：解除静音
  • energy up：增加门限
  • energy dn：降低门限
  • vol talk up：提高讲话音量
  • vol talk zero：讲话音量设置为0
  • vol talk dn：降低讲话音量
  • vol listen up：提高收听音量
  • vol listen zero：收听音量设置为0
  • vol listen dn：降低收听音量
  • hangup：退出会议
  • lock：锁定会议
  • transfer：转移到其他路由
  • execute_applicationg：执行其他app

会议控制添加参数时，有“按键”、“功能类型”、“值”三个参数。其中，“按键”为1，2，3等按键数；“功能类型”对应按键执行的动作；“值”一般默认不填即可，只有动作类型为“transfer”或“execute_applicationg”时才需要填写对应文本。

比如“按键”9，“动作类型”为transfer,“值”可以填写ivr，那么当用户按9之后，则系统会将通话转到被叫号码为ivr的重新路由。

5.5 呼叫中心

5.5.1 坐席

  • 点击【呼叫中心】⇨ 坐席右上方【新建】，填入坐席工号、名称、密码、呼叫源、域等必填参数，创建新的坐席。
  • 点击名称，进入坐席详细页面 ⇨ 点击右上方【编辑】，可编辑坐席信息。
  • 点击名称，进入坐席详细页面 ⇨ 点击右上方【修改密码】，可修改坐席密码。
  • 点击名称，进入坐席详细页面，点击右上方【显示扩展字段】，可可查看坐席详细信息。
  • 点击【呼叫中心】⇨【坐席】⇨ 点击右侧【删除】，可删除选定的坐席。

5.5.1.1 坐席参数

  • type：callback 或者 uuid-standby
  • contact：dial string //呼叫串
  • status：Logged Out、Available、Available、On Break //状态
  • State：Idle、Waiting、In a queue call
  • max-no-answer：最大无应答次数，超过次数，status变为On Break状态
  • wrap-up-time: 通话完成间隔时间，成功处理一个通话后，多久才会有电话进入等待时长
  • reject-delay-time：挂机间隔时间，来电拒接后多久才会有电话进入的等待时长
  • busy-delay-time：忙重试间隔时间，来电遇忙后多久才会有电话进入的等待时长
  • no-answer-delay-time ：无应答重试间隔，来电无应答后多久才会有电话进入的等待时长

5.5.1.2 添加坐席

点击【呼叫中心】⇨ 【坐席名称】，进入坐席详细界面 ⇨ 点击分机右侧【新建】，填入名称、号码、密码、呼叫源、域等必填信息，添加分机。

也可点击【用户管理】⇨【用户】，修改指定用户类型，改为坐席即可。

5.5.1.3 签入/签出

坐席信息中“仅硬件话机可用”选择“是”，并且将坐席放入队列中，可使用签入签出功能。

5.5.2 队列

  • 点击【呼叫中心】⇨ 队列右上方【新建】，填入名称、类型、进入队列等待音，策略等参数创建新的队列。
  • 点击名称，进入队列详细页面：
  • 点击右上方【编辑】，可修改队列的详细信息。
  • 点击【扩展参数】⇨ 右侧【新建】或者【编辑】，可新建或编辑扩展参数 ⇨ 点击扩展参数【启用】列，可选择是否启用该参数。
  • 点击【切换显示坐席页面】⇨ 点击队列坐席右侧的【添加】，可将坐席添加到队列中。
  • 点击【加载】/【重载】/【卸载】可选择加载/重载/卸载此队列

5.5.2.1 参数

  • strategy：振铃策略
    • ring-all：所有坐席振铃
    • longest-idle-agent：空闲时长最长振铃
    • round-robin：轮循振铃
    • top-down：顺序振铃
    • agent-with-fewest-calls：接听最少振铃
    • sequentially-by-agent-order：优先级振铃
    • random：随机振铃
  • moh-sound：队列语音，如：local_stream://moh
  • announce-sound：定期播放音乐 与announce-frequency一起使用
  • announce-frequency：播放频率,即多久播放一次，与announce-sound一起使用
  • record-template：录音文件夹路径
  • time-base-score：优先级相关的时间积分选项(queue：不增加积分；system：进入系统时积分)
  • tier-rule-wait-second：梯队的等待时间（进入下个梯队的时间）
  • tier-rule-wait-multiply-level：梯队等待级别
    • false：除了第一个梯队等待tier-rule-wait-second，其他梯队不等待
    • true：每个梯队都会等待tier-rule-wait-second
  • tier-rule-no-agent-no-wait：是否跳过no-agent的梯队，(no-agent就是这个梯队中不存在状态为available的成员agent)。true：跳过；false：不跳过
  • discard-abandoned-after：最大丢弃时长（丢弃超过此时长，将不可以恢复）与abandoned_resume_allowed同时生效
  • abandoned-resume-allowed：丢弃后是否允许恢复或者重新进入队列。（true：允许恢复或重新进入，超过discard-abandoned-after将不可恢复；false：禁用不允许恢复）
  • max-wait-time：最大等待时间（超过时间未被接通将退出callcenter）0为禁用。说明：呼入到队列，有坐席，但坐席拒接，重新等待分配坐席，那么超过最大等待时间 主叫会自动挂机；（如果已经分配到坐席，坐席未接听，由于已经建立了连接，超过时间也不会自动挂断
  • max-wait-time-with-no-agent： 无坐席成员等待超时时间: 超出时间电话会退出callcenter，0为禁用。 呼入到队列，没有坐席签入，此时超过无坐席最大等待时间则主叫会自动挂机
  • max-wait-time-with-no-agent-time-reached：如果有电话因为（max-wait-time-with-no-agent）的原因退出队列， 队列将在延迟一定时间不允许新的电话呼入到队列

5.6 用户管理

5.6.1 用户

通过用户模块，可自由添加登陆账号及对应的分机号等，未建立的账号无法登录界面。

SIP终端可以使用与Web端一致的服务器地址、用户名与密码注册。修改前admin默认密码为admin，1000～1019默认密码为1234。

其中Web端新增用户建立过程如下：

5.6.1.1 新建用户

创建新用户账号有两种方法：

  • 点击【新建】，输入用户名、姓名、登录密码、类型等红色必填项 ⇨ 点击【保存】；如需创建分机，则选择【同步创建分机】，分机号码和密码如果不填写则默认和用户号码及密码相同。如下图所示：
新建用户
  • 点击【导入】（适用于创建大批量用户），可根据导出获取模版。

5.6.1.2 用户类型

  • 普通：普通用户
  • 会议管理员：设置为会议管理员后，可在会议室界面，选择该会议室管理员
  • 坐席：设置为坐席后，方可在呼叫中心界面加入某个队列

5.6.2 分组

通过分组，可将账号按用户或分机类型分成指定组，为后期角色权限分配、会议与会者等做准备。

5.6.2.1 新建分组

点击分组界面右上方【新建】，填入名称、域等必填参数，其中域需要和用户中的域相同，方可将用户分到此组。如下图所示。

新建分组

例如：

新建分组中，名称填入“办公室”，填入域为xswitch.cn，点击【办公室】，进入添加界面 ⇨ 点击【添加用户】，则会显示所有用户域为xswitch.cn的用户，选中需要加入的用户即可。

5.6.2.2 添加或删除组成员

点击组名，进入添加用户界面：

  • 勾选【全选】，可一次性添加全部成员。
  • 点击【添加用户】，可选择性添加成员。
  • 点击【移除所有用户】，可移除已经添加的成员。

5.6.3 联系人

联系人主要用于记录客户基本信息。客户信息分为公开和私有，如果设置了公开，那么所有其他人都可以看到此客户信息，如果设置了私有，那么仅对应的账号可以看到该账号下的客户信息。

为了减轻数据库查询负担，如果有需要根据客户信息来电显示的需求功能时，可通过xtra_config.lua中开启参数check_contacts实现，

即当参数为true时，那么所有来话，会检查主叫号码是否和联系人号码相同，如果相同则设置相应的联系人名称，当客服话机响铃时显示客户联系人名称。

5.7 角色权限

角色权限，主要对用户进行权限设置，即设置某些用户拥有哪些权限，比如，1001用户可以查看所有用户分机等信息，1002用户可以查看呼叫相关界面，1003用户可以查看会议界面等。

当然除了查看界面权限也可以设置增删改查权限，比如，2001用户可查看用户、分机等界面，同时可对用户、分机中的信息进行修改。

设置权限的使用流程如下：

  • 先进入【用户】⇨ 点击【角色权限】⇨ 点击【新建】，设置角色名称；
  • 点击右侧【角色】，对此角色添加用户，比如1001，那么1001用户即拥有了改角色权限。
  • 点击右侧【菜单控制】，对此角色添加菜单权限，比如分机、路由等菜单 ⇨ 点击某菜单下拉按钮，可对某菜单中具体功能进行授权，比如，“添加”、“删除”、“编辑”等

5.8 菜单管理

5.8.1 系统模块

系统模块包含系统几乎所有界面模块，可对界面进行增删。比如删除呼叫中心—坐席这个界面模块后，刷新即可发现系统界面没有了坐席这个界面。

删除或修改显示位置，如下图所示：

新建分组角色

可通过修改排序，调整各功能界面显示位置。比如，上图用户管理原本在第一个，将排序写为10，刷新界面，用户管理则放到了最后显示。

其他界面同理。

5.8.2 系统菜单

系统菜单，显示系统所有菜单信息，比如路径、状态、所属模块等。

同时可通过系统菜单界面，调整快捷栏上显示。根据使用习惯，比如将话单、媒体文件等放到最上面的快捷栏上，方便操作。具体对如下图所示：

系统菜单

系统最多只能选择5个快捷菜单，默认已有5个，如需调整，需要先删除某个快捷菜单，然后再在菜单中选择你想要的，点击提交。

5.9 AI管理

在AI时代，越来越多的设备和组件对智能语音提出了更多的要求。而电话是语音最佳的载体。所以，我们在XSwitch中实现了与主流AI平台的语音接口互通，旨在给第三方应用程序提供更丰富接接口。

5.9.1 AI

点击右上方【新建】，选择参数模板，即可完成创建AI的的参数配置。非必要不修改此配置界面。

5.9.2 事件推送

打开AI界面，找到settings参数，修改post-event-url对应的值（填入需要将事件推送到的地址）。填写成功后需要重启一下mod_ai模块。

在【高级配置】⇨【系统设置】⇨【模块】中找到mod_ai，然后点击后面的【重载】即可（如果没有此模块，将此模块添加进去后加载即可）

Bindings中包含的所有事件均将推送到上述地址。

5.9.3 百度

同样点击右上方【新建】，选择参数模板，完成创建baidu模块的的参数配置。模块参数分为tts和asr两类，即语音合成和语音识别

5.9.3.1 获取百度TTS：

在浏览器中输入“百度TTS”，进入百度语音合成界面，如下图:

百度TTS语音合成

点击上图【语音识别】⇨ 点击【立即使用】，进入注册界面，申请账号，按照提示一步步完成。

完成后，点击【应用管理】，如下图所示 ⇨ 点击【查看key】,即可获取key值。

百度TTSkey值

5.9.4 阿里

与百度模块相同

5.10 话单管理

一个运营平台往往需要有一个记录话单的能力，方便后续的计费提供数据支持。XSwitch可支持话单写入远程HTTP服务器，即你现在看到的web端提供的话单状况。

XUI采用mod_cdr_csv模块可以记录CSV格式话单。

因此，正式启用话单功能时，请确保mod_cdr_csv模块已加载启用。

5.10.1 话单

话单界面显示所有通话话单信息，包括下面会议话单、fifo话单、callcenter话单等。点击【话单】即可查看详细信息。

页面右侧显示时间轴，根据各自需求随时查询近期内7天、15天或一个月的通话情况。点击【更多】，可进行条件查询

5.10.2 会议话单

显示各个时间段的会议状况，点击【conference cdrs】即可查看详细信息。

页面右上方显示时间轴，根据各自需求随时查询近期内7天、15天或更多会议情况。点击【详细】，可查看某条会议话单的详细信息，包括参与会议的与会者信息

5.10.3 FIFO话单

显示系统FIFO队列内通话使用状态，具体包含UUID信息、队列名、主/被叫号码、服务号码、开始、接听、结束信息。

页面右侧显示时间轴，根据各自需求随时查询近期内7天、15天或一个月的通话情况。点击【更多】，可进行条件查询。

5.10.4 Callcenter话单

显示各个时间段的呼叫中心通话状况，点击【callcenter话单】即可查看详细信息。

页面右上方显示时间轴，根据各自需求随时查询近期内7天、15天或更多会议情况。点击【详细】，可查看某条会议话单的详细信息

5.10.5 话单配置

话单配置为话单模块配置文件界面，通常使用默认配置，非必要不修改（如果比较熟悉FS配置，可根据场景需要修改）

5.10.6 话单推送

话单推送目前支持JSON以及XML格式推送，分别对应mod_cdr_xml以及mod_json_cdr两个模块。

如需话单推送，请确保上述模块已被加载。

模块已加载成功的基础上，修改xml_cdr.conf.xml或json_cdr.conf.xml中如下即可。

<param name="url" value="http://localhost/cdr_curl/post.php"/>

修改完成后，重载即可。当然也可以直接参考AI界面中话单推送方法。

5.11 高级配置

这部分是系统的一些高级配置，在与不同的设备或运营商对接时可以设置一些特殊的参数等。

5.11.1 SIP

SIP是XSwitch支持的主要协议，有很多配置参数，这些配置参数通常比较复杂，建议只有高级用户使用。

系统支持多个SIP Profile，每个Profile相当于一个SIP UA，通过配置不同参数可以配置一个UA行为。多个SIP Profile监听不同的IP地址和端口。XSwitch默认的配置带有两个Profile：default以及public，前者通常用于内部，需要用户注册的端口，后者通常与外部系统对接，如运营商和网关等。

一个SIP Profile中有可以关联多个网关。网关主要用于描述远端的SIP服务器，使XSwitch可以与其他服务器通信。

5.11.1.1 添加新的Profile

点击【新建】，输入Profile名称，填写相关描述，选择模板，点击【保存】即可。

5.11.1.1.1 Profile功能控制

点击【启用】，当变为“是”时，则启用该Profile，系统启动时，该Profile自动开启。

“状态/控制”栏中，点击【停止】则关闭此时正使用的Profile，同理，点击【重启】，则重新启动该Profile。当改动某些参数后，点击【重新扫描】，自动更新状态(适用于大多数参数改动情况)。

如下图和所示：

SIP profile
SIP profile开启的详细信息

同理，再次点击【启用】，当变为“否”时，意味，下次使用时关闭该Profile。

点击SIP Profile的名称，进入详情页，可根据需求添加模块参数，同理，如果启用某个参数，点击【启用】变为“是”后，点击页面【 重新扫描】，使之生效。

特别注意：如果某个参数已启用，且有值，当停止此参数效果时，点击【启动】变为“否”后，需要重启该Profile才可生效。

5.11.1.2 实现多用户注册

XSwitch可实现多个终端同时注册，当有电话打入时，所有注册终端可实现同时响铃，方便用户使用任意终端均可及时通话。

可以在SIP Profile中开启multiple-registrations以开启该功能。

5.11.1.3 普通SIP话机

查找SIP界面中sip-port或tls-sip-port，查看或设置如下：

端口7060(TCP/UDP) 7161(TLS)

5.11.1.4 sipjs客户端

通过SIP.js实现的一种视频通话客户端，适用于支持WebRTC的浏览器进行视频通话。SIP.js是基于JavaScript编写的功能齐全的SIP堆栈。借助SIP.js利用WebRTC的功能实现语音通话和视频通话。

查找SIP界面中ws-binding的值，在界面输入wss://demo.xswitch.cn:7443，账号，密码等。端口查询如下：

默认端口：

  • 5066（WS）
  • 7443 (WSS)

5.11.1.5 Verto

如果使用了Nginx，那么端口就对应nginx中的配置即可。如果没有配置Nginx，那么查看Verto下的端口配置。如下例子仅供参考。

  • 内网：80（WS/HTTP）443（WSS/HTTPS）
  • 外网：9080 (WS/HTTP) 4443（WSS/HTTPS）

WS/WSS url示例：

ws://192.168.3.170/ws
wss://192.168.3.170/ws

ws://freeswitch.xyt.com:9080/ws
wss://freeswitch.xyt.com:4443/ws

5.11.2 扩展功能

5.11.2.1 终端

XSwitch的前台命令客户端，实现各种命令输入，也可快捷的查看后台日志，如下图。

终端

点击上图【暂停】可以使日志界面暂停，当日志较多时，方便查看通话日志，防止被后来日志覆盖。

点击“【设置回滚行数】，可以设置显示最大数，比如，设置为1000，那么可显示最多1000行日志信息，防止重要信息被覆盖。

在终端界面可以【下载】保存当前终端中显示的日志。

当遇到问题，需要发送日志给相关技术人员时，可以点击下图所示的【SIP Flow】按钮，如果没有打开SIP跟踪，需要手动在命令行上输入“sofia global siptrace on”以打开跟踪。以后收到的SIP消息都可以在流程图上显示出来。该功能仅用于实时跟踪查看和诊断SIP消息。

重现问题后，点击下图【下载】，此时可以将流程图以及日志下载下来，发给XSwitch技术支持人员以便定位问题原因。

终端日志下载

5.11.2.2 系统

在此页面可下载系统日志、声音文件等。

5.11.2.3 话机自动配置

在此界面可以添加话机信息，支持批量导入。如下图所示

话机自动配置

在界面填入话机MAC地址以及对应账号后，如果想批量实现话机自动部署，需要在话机界面填写系统URL地址，现在以方位F3话机以及方位FA26为例：

5.11.2.3.1 潮流

进入话机管理界面，【维护】⇨【更新升级】，然后按照如下图所示填写URL。URL格式为IP:port/api/provision_auto/gs协议类型选择http，服务器地址填写系统真正的访问地址（如192.168.3.144:18081/api/provision_auto/gs）。

潮流1610/1615自动配置
5.11.2.3.2 方位F3

进入话机管理界面，【升级】⇨【自动升级】等，然后按照如下图所示填写URL。URL格式为IP:port/api/provision_auto/fw协议类型选择http，服务器地址填写系统真正的访问地址（如192.168.3.1:8081/api/provision_auto/fw）

F3自动配置
5.11.2.3.3 方位FA26

进入话机管理界面，【话机配置】⇨【自动更新】，然后按照如下图所示填写URL。URL格式为IP:port/api/provision_auto/fwA26协议类型选择HTTP，服务器地址填写系统真正的访问地址（如http://192.168.3.144:18081/api/provision_auto/fwA26)

A26自动配置

5.11.2.4 智能安全帽对接

智能安全帽通过对接XSwitch系统平台实现WebRTC实时音视频通话。

智能安全帽注册到该系统平台后，其他设备（如SIP话机或手机等）可通过路由设置实现直接呼叫相应智能安全帽；当安全帽需要帮助时，可通过按SOS直接呼叫相应的客服人员。

5.11.2.4.1 准备
  • 准备一个域名
  • 域名必须有在备案
  • 申请该域名对应的ssl证书
  • 域名以及对应的ssl证书在系统安装时配置完成即可。

在系统安装时，请.env文件中FreeSWITCH_NAME填写了正确域名

特别注意

证书类型优先选择适用于Nginx类型的SSL证书。

5.11.2.4.2 系统界面配置
  • 点击菜单栏【高级】⇨【SIP】⇨【default】，找到ws-binding和wss-binding参数并检查该参数是否已自动开启，若未开启，则开启后点击该界面上“重启”或“重新扫描”，使其生效。
  • 点击菜单栏【高级】⇨【扩展功能】⇨【话机自动配置】，输入名称、MAC及分机号

特别说明

  • 名称：输入安全帽SOS对应号码，即当该安全帽按SOS后走哪个被叫号码路由；
  • MAC：是指安全帽设备编号；
  • 分机号：则是安全帽对应的注册分机号。
5.11.2.4.3 安全帽配置

进入智能安全帽自己的配置界面，找到安全帽设置–服务器地址配置。

在服务器地址配置中，如下所示，其中test.cn替换为真实的域名即可。

https://test.cn/api/provision_auto/safety_hat?ctl=config&act=get_config
5.11.2.4.4 检查

  • 点击菜单栏【高级】⇨【状态】⇨【注册】，通过该注册界面查看安全帽有没有注册成功；

  • 如果未能成功注册，可通过访问https://www.doubango.org/sipml5/call.htm?svn=252#，输入分机配置信息，查看系统是否支持WebRTC。

5.11.2.5 媒体文件

上传文件以及保存录音。所有系统通话录音均可在此界面查看下载。

5.11.2.5.1 自定义

可根据需求，自定义媒体文件类型，将上传后的文件转到指定类型。通常用于IVR、呼叫中心、会议等需要选择语音文件的场景。

按类型分配，可解决因文件太多而不方便查询选择的问题。

5.11.2.5.2 使用TTS制作媒体文件

在使用XSwitch通信过程中，经常需要一些语音文件，有时录制起来比较麻烦。在配置了TTS（语音合成功能）的情况下，XSwitch可以直接使用TTS生成语音文件，供以后使用。

TTS使用方法：

点击【TTS】，在TTS文本框内填写内容，点击TTS即可生成声音文件。

提示：使用TTS之前请确保在相关语音识别模块已自动加载，比如使用百度TTS，确保mod_baidu已加载。

5.11.2.5.3 使用离线TTS

XSwitch也支持离线生成TTS语音，详细操作办法可参考如何使用XSwitch内置的离线ASR及TTS

5.11.2.5.4 使用Edge TTS

由于XSwitch提供配套的espeak-ng播放出的中文声音不太好听，我们给出了一个更“好听”的解决方案，详细可参考如何在XSwitch中使用Edge TTS

5.11.2.6 日志

点击【设置】⇨【日志】，此界面记录了XUI界面每一次的修改状态及内容。通过此界面，可随时查看历史修改记录，根据修改记录，查看配置变化。

此界面功能默认不开启，如需使用日志记录，请在配置文件中（xtra_config.lua）设置auto_log为true。

5.11.3 系统管理

5.11.3.1 访问控制列表

访问控制列表，主要用于免鉴权，默认是安全。如果你想将某个域名或IP可通过鉴权端口且无须密码即可通信，那么将其填入如下界面中，然后加载即可。

访问控制列表

特别注意，如果是域名，节点数据类型选domain，然后填入domain值，如果是IP类型选择cidr，然后输入IP及子网掩码即可，切记，不要忘了子网掩码。另外，如果sip profile开启了ban-ipv4-domain，cidr方式不可用。

5.11.3.2 全局变量

全局变量，和名称一样，设置后，可全局使用。比如，保持音乐hold_music，设置某个音乐文件后，所有通话保持均播放此音乐。

其他参数，如默认播放语音（默认中文，也可设置英文），默认语音文件路径，默认rtp_video_max_bandwidth_in视频带宽默认最大最小值等。

全局变量

5.11.3.3 系统模块

可以对模块进行添加和删除，开启、加载、卸载、重载等操作。模块中【启用】按钮表示系统每次启动后默认加载此模块。如果针对某模块，第一次点击【启用】，仅表示下次会自启动；如果想立即使用，需要点击【加载】实现。模块名字由灰色变为黑色则表示加载成功。

5.11.3.4 参数

此界面为系统内部参数配置界面，非必要不修改。

该界面可以对某个模块内所有profile的参数进行增删改查操作，有些模块没有提供单独的配置界面，例如mod_agora，此时，如果修改其配置参数，需要通过模块参数，找到AGORA，然后，点进去修改即可。

5.11.4 分配器

5.11.4.1 新建/修改/删除分配器

  • 点击分配器界面右上方【新建】，填入名称、总权重等必填参数，创建新的分配器。
  • 新建分配器后，点击名称，进入分配器详细界面 ⇨ 点击右上方【编辑】，即可修改分配器信息 ⇨ 点击【保存】，保存修改后的分配器信息。
  • 点击分配器界面最右侧【删除】，即可删除分配器信息。

5.11.4.2 添加、编辑、删除分配器节点

  • 点击分配器名称，进入分配器详细界面 ⇨ 点击节点右侧【新建】，填写名称、权重等信息创建新的节点。现在以网关为例子，gw_1和gw_2均为网关名称，下图所示：
添加节点
  • 新建节点后，点击节点右侧【编辑】，即可编辑黄色显示部分信息，修改完成后回车即可保存修改。
  • 点击节点最右侧【删除】，即可删除选定的节点。

添加节点后，只需要在路由或其他脚本中调用即可，路由中使用时参考sofia/gateway/${distributor(xui)}/$1，其中xui即分配器名称。当有通话时，会根据权重使用gw_1或gw_2。

5.11.4.3 XCC

XCC模块主要是实现控制XSwitch，程序员不用纠结于XSwitch的内部逻辑，从更高的视角分析业务需求，进而调用合适的API进行控制。

5.11.4.3.1 XCC-SETTINGS
  • debug：调试日志级别， 0~7。
  • nats‑url：NATS的地址，如nats://127.0.0.1:4222，如果不配置则不连接NATS。
  • publish‑events‑subject‑prefix：事件的Subject前缀，如.event，将会变为cn.xswitch.ctrl.event.CHANNEL_ANSWER之类。
  • cdr‑format：CDR的格式，可以在CDR中选一种格式，目前支持CUSTOM。
  • xml‑handler‑bindings：XML绑定，不同的Section以￨分隔，如directory￨config。
  • cdr-subject：CDR事件名，如填写cn.xswitch.cdr。
5.11.4.3.2 XCC-BINDINGS

绑定哪些事件。绑定的事件会向NATS发送，如果设置为ALL则会绑定所有事件。发送的Topic可以由publish‑events‑subject‑prefix参数改变，如：

  • cn.xswitch.ctrl.event.CHANNEL_ANSWER
  • cn.xswitch.ctrl.event.CUSTOM.sofia::register

如果你想订阅通话相关事件，可以绑定如下几个事件

  • CHANNEL_CREATE //通话创建事件
  • CHANNEL_STATE //状态
  • CHANNEL_ANSWER //应答
  • CHANNEL_HANGUP_COMPLETE //挂机结束
5.11.4.3.3 XCC-CDR

挂机结束后话单指定事件，默认如下字段参数说明：

  • caller_id_name //主叫号码
  • destination_number // 被叫号码
  • uuid //通话uuid
  • start_stamp //开始时间
  • answer_stamp //应答时间
  • end_stamp //结束时间
  • duration //总时长
  • billsec //计费时长
  • hangup_cause //挂机原因
  • context //呼叫源
  • direction //方向
  • caller_id_name //主叫名称
5.11.4.3.4 订阅事件示例
  • 第一步：开启mod_xcc模块
  • 第二步：点【高级配置】⇨【系统设置】⇨ XCC修改相关参数并重载生效

参数设置：

  • XCC-SETTINGS: nats-url设置（默认无须修改）
  • XCC-SETTINGS: publish-events-subject-prefix设置（定义订阅事件前缀，主要用于后续订阅需要统一），比如cn.xswitch.ctrl.events，然后开启即可；
  • XCC-SETTINGS: cdr-format设置（话单格式），默认CUSTOM即可，只需要开启
  • XCC-SETTINGS: cdr-subject设置（话单订阅事件名，用于后续客户订阅话单信息），比如cn.xswitch.cdr

如下图所示：

XCC配置
  • XCC-BINDINGS：CHANNEL_CREATE
  • XCC-BINDINGS：CHANNEL_STATE
  • XCC-BINDINGS：CHANNEL_ANSWER
  • XCC-BINDINGS：CHANNEL_HANGUP_COMPLETE

如下图所示：

XCC配置

第三步：写订阅代码，现提供nodejs下的demo，如events.js，代码如下：

const NATS = require('nats')
// nats_url对应配置文件中nats‑url的值
let nats_url = process.env.NATS_URL;
console.log("Connecting to " + nats_url)
const nc = NATS.connect(nats_url);
console.log("Event started, waiting ...")

// controller handler 订阅事件，其中`cn.xswitch.ctrl.events`对应xcc配置文件中的`publish‑events‑subject‑prefix`中的值
nc.subscribe('cn.xswitch.ctrl.events', function (msg, reply, subject, sid) {
    console.log('Received a message: ' + subject)
    console.log(msg)
})

function wait() {
    // console.log('tick ... ');
    setTimeout(wait, 3000);
}

wait();
// Close connection
// nc.close()

关于XCC，请参阅《XSwitch XCC API手册》，以及示例代码：https://git.xswitch.cn/xswitch/xcc-examples 。

5.11.4.4 微信小程序

微信小程序配置文件界面，通常不需要修改。

5.11.4.5 数据字典

数据字典（Data dictionary）是一种用户可以访问的记录数据库和应用程序元数据的目录，用来描述数据库中基本表的设计，主要包括字段名、数据类型、主键、外键等描述表的属性的内容。在对数据库或应用程序结构进行修改时，其内容可以由DBMS自动更新的数据字典。

数据字典主要仅系统内部使用，用户一般不需要修改。如需修改，请咨询XSwitch工程师。

5.11.4.5.1 使用方法：

点击【新建】，输入域、键、值、描述等，点击【保存】即可。

点击右上角【编辑】，只能改动“值”对应的内容，或者点击蓝色的“域”或者“键”，进入编辑界面，可对所有文本框进行修改。

5.11.4.6 EventSocket

Event Soket配置文件界面，非必要不用修改。在做二次开发时可以修改监听IP等信息。

5.11.5 系统状态

5.11.5.1 状态

显示系统运行时间、版本信息、CPU、呼叫并发等各种系统信息。

5.11.5.2 呼叫

显示系统中当前是否存在通话以及查看正在通信中的账号及信息。

此页面显示当前正在通话的Session状况，具体包含UUID、主/被叫号码、来/去话状态、通话创建时间。

5.11.5.3 通道

正在通信中的电话，通常一个通话有两个通道，可查看通道信息。如果是呼入会议一般一个成员只有一个通道。

5.11.5.4 注册

此界面显示所有注册上的账号信息。

分机注册成功后，才可作为被叫呼叫，可查看账号是否注册成功。

5.11.5.5 坐席

此界面显示所有已经签入队列坐席状态信息

5.11.5.6 Show

显示所有FreeSWITCH多中模块状态报告信息，其中各部分所代表含义如下：

  • application ：列出所有应用程序
  • Registrations ：列出所有注册用户
  • Modules ：列出所有模块
  • Endpoints ：列出所有endpoint类型模块
  • Codecs ：列出所有编码
  • Files ：列出所有支持的文件类型
  • APIs ：列出所有的API
  • Aliases ：列出所有别名
  • Complete ：列出完整的命令表
  • Chat ：列出所有chat模块，包括api、sms、conf
  • Management ：列出所有管理系统
  • NAT Map ：列出所有地址映射表
  • Say ：列出支持语言的say模块
  • Interfaces ：列出所有接口
  • Interface Types ：列出所有接口类型
  • Tasks ：列出任务
  • Limit ：列出受限模块

5.12 LDAP服务器

LDAP（Lightweight Directory Access Protocol，轻量目录访问协议），是一种 C/S（即“客户端/服务器”）模式的协议，基于此协议可实现“客户端访问服务器目录”的功能。

LDAP服务器方便用户集中管理电话簿。支持LDAP功能的IP话机通过设置LDAP服务器，可实现在话机上快速查找LDAP上的联系人信息，而不需要在本地维护电话簿。

5.12.1 启动LDAP服务器

LDAP服务为新的镜像服务，服务取系统中分机和联系人信息。该功能默认不启动，默认端口为3893。如需LDAP服务，请提前联系相关负责人。

5.12.2 LDAP客户端配置示例

5.12.2.1 配置Grandstream话机的LDAP功能

本文以Grandstream GXP1625话机的LDAP功能。

登录话机网页，进入【电话本】 ⇨ 【LDAP】，配置LDAP客户端，参数设置如下图所示：：

LDAP设置
  • 服务器地址: 填写系统的IP地址192.168.3.70；
  • 端口: 填写LDAP服务器地址的端口，如3893；
  • 根节点: 填写LDAP服务器的目录节点，dc=xswitch,dc=cn；
  • 用户名: 填写LDAP服务器的用户名，cn=admin,dc=xswitch,dc=cn；
  • 密码: 填写LDAP服务器的密码，password；
  • 号码过滤值: 设置话机通过“号码”搜索联系人信息。“*”代表任意字母，“%”代表输入的字符串，用于筛选条件的前缀(|(cn=%))；
  • 姓名过滤值: 设置话机通过“姓氏”搜索联系人信息。“*”代表任意字母，“%”代表输入的字符串，用于筛选条件的前缀(|(cidName=%))；
  • 版本号: LDAP服务器协议的版本，默认即可；
  • 名字属性: 设置要获取的名字属性，cidName；
  • 号码属性: 设置要获取的号码属性，cn；
  • 显示名称: 设置LDAP服务器搜索结果的显示名称。显示名称格式必须以“%”开头，如：%cidName；
  • 最大返回数: 设置LDAP服务器搜索结果的最大条目。有效值范围1至3000。默认为50条；
  • 搜索超时值: 设置LDAP服务器执行搜索联系人的请求时间，单位为秒，有效值范围0至180，默认即可；
  • 对结果排序: 设置IP话机是否对搜索结果进行排序，默认为“否”；
  • LDAP查号: 当有“来电”或“拨打电话时”，是否在LDAP电话簿中搜索号码；
  • LDAP查号显示名: 设置LDAP查找呼入呼出电话的显示名称，%cidName。

5.12.2.2 配置方位话机的LDAP功能

登录方位话机网页，在页面点击【电话薄】⇨【LDAP】，配置LDAP客户端，参数设置如下图所示：：

LDAP设置
  • 服务器地址: 填写系统的IP地址192.168.3.70，端口对应3893；
  • 基础: 填写LDAP服务器的目录节点，dc=xswitch,dc=cn；
  • 用户名称: 填写LDAP服务器的用户名，cn=admin,dc=xswitch,dc=cn；
  • 密码: 填写LDAP服务器的密码，password；
  • LDAP名称过滤: 设置话机通过“号码”搜索联系人信息。“*”代表任意字母，“%”代表输入的字符串，用于筛选条件的前缀（|(cn=%)）；
  • LDAP号码过滤: 设置话机通过“姓氏”搜索联系人信息。“*”代表任意字母，“%”代表输入的字符串，用于筛选条件的前缀（|(cidName=%)）；
  • 最大查询结果: 设置LDAP服务器搜索结果的最大条目。有效值范围1至32000。默认为50条；
  • LDAP名字属性: 设置要获取的名字属性，cidName；
  • LDAP号码属性: 设置要获取的号码属性，cn；
  • 协议版本: LDAP服务器协议的版本，默认即可；
  • LDAP搜索排序: 启用；
  • LDAP匹配来电: 启用；
  • 拨号/预拨号查询: 启用；

5.12.2.3 配置Zoiper软电话的LDAP功能

  • 运行Zopier Biz软电话。
  • 进入Settings > Preferences > Contacts > LDAP Options。
  • 勾选Use this server to search for contacts。
  • 配置LDAP客户端。
参数设置 说明 值
LDAP server 系统IP地址 192.168.3.x
Password 管理员的密码 password
CN LDAP服务器的用户名 cn=admin,dc=xswitch,dc=cn
DN LDAP服务器的目录节点 dc=xswitch,dc=cn
Result limit 设置LDAP服务器搜索结果的最大条目 0
Min Chars to Search 设置LDAP服务器搜索条件的最少字符 1
Fields to Search 设置要获取的名字属性 cn, cidName
XMPP presence LDAP中此栏的名称指向XMPP联系人的状态名称 Do not use

注意：LDAP功能需要在XSwitch端额外配置并启用LDAP服务器组件。

6 使用场景说明

XSwitch功能强大，但强大就代表复杂、配置繁琐。没有一种系统能很好的适应所有情况，XSwitch在各种使用场景中做了一些权衡。

本章列举了一些典型的使用场景，在实际使用中可以参考进行配置，以便最大限度地发挥XSwitch的功能，同时以不失简洁高效。

6.1 基本策略

你首先应该规划号段和号长，最好是有规律的，内部分机的号长最好也一致。XSwitch支持多种号长并存，但变长通常意味着你需要设置比较复杂的路由逻辑。以下是几种通用的分机号设置：

  • 600~699：所有分机都以6开头，支持100个分机
  • 800~899：所有分机都以8开头，支持100个分机
  • 600~999：分机以6、7、8、9开头，需要对每位数字设置路由，这时候建议扩展为4位
  • 1000~1999：4位分机号

6.2 小型IP-PBX

小型IP-PBX通常只有一个管理员，管理员可以管理多个分机（如50）。这时候没有必须建立多个管理员，除非用户需要登录系统进行一些自助服务，如看话单，听语音留言等。但国内用户不习惯使用语音留言，因而应用场景比较少。

如果需要用户账号，带来的复杂性不仅仅是创建账号那么简单，还要求管理员理解用户和分机的对应关系，用户密码的分发逻辑，重置账号密码、甚至权限管理等。

在小型IP-PBX中，大家都使用同样的域登录系统。如果在系统安装时在后台配置了force_domain选项，则话机可以使用任何域注册，系统强制使用默认的域。

小型IP-PBX一般放在企业内网，员工也不会主动攻击系统，因而不需要太多考虑安全性。

所以，对于100人以下的小公司，一种典型的分机和会议室配置是：

  • 600~699：分机
  • 300~399：会议室
  • 800~899：IVR
  • 0：拨打外线，路由在送出号码前做号码变换“吃掉”0
  • 1：直接送到外线，如110、119以及所有手机号等

6.3 有分支机构的配置

如果你有多个分支机构，建议把系统放到公网服务器或云服务器上。不同分支机构规划不同的号段。

为了防止有人在公网上扫描系统，SIP服务器最好不使用默认的5060端口，并且，把默认SIP Profile启用ban-ipv4-domain参数。使用该参数要求使用域注册到系统，而不能使用IP地址。

6.4 多地组网

有时候，可能每个地方都放一台XSwitch服务器，这样，可以在XSwitch系统间互相做路由，跨地区的呼叫必须经过两个XSwitch才能接通。

两个XSwitch间可以使用IP认证。假设两个XSwitch服务器分别为XS1和XS2，则：

在XS1上创建分机xs2，CIDR属性填入XS2的IP地址。同时，主叫名称和号码都设置为“PASS”，这样即开启了主叫号码透传，所有从XS2上来的呼叫都认为是xs2这个分机发起的呼叫，但是，仍能显示原来的主叫号码。

如果想为从XS2上来的呼叫指定不同的路由逻辑，则可以修改xs2分机的呼叫源。

在XS2上做出局路由指向XS1的IP，如：

  • 目的地类型：IP地址
  • 目的地：XS1的IP地址

在XS2上也做对应的设置，双方就可以互拨，也可以使用对方的中继和路由规则出局。

6.5 多租户

XSwitch的设计理念是为了保持简单，仅支持一个租户，如果需要多租户，就为每个租户跑一个XSwitch Docker容器或者一个独立的虚拟机，每个租户都有自己的数据库和域名，XSwitch云就是这么做的。但是在有些情况下，这种强隔离手段有些重，因此，我们也提供轻量级的隔离。

系统有限的支持多租户功能。XSwitch底层完全支持多租户，但在系统界面上没有强隔离手段。

  • 每个用户都有一个“域”字段，为不同用户填入不同的域
  • 每个分机都有一个“域”字段，为不同分机填入不同的域
  • 路由呼叫源可以为不同域的用户指定不同的呼叫源，这样他们的路由就不会交叉
  • 为会议室指定域
  • 为FiFo队列指定域
  • 为Callcenter指定域

注意：如果用户登录XUI Web界面，则可以看到其它租户的分机等信息。如果是基本XSwitch API做二次开发，则完全可以忽略这个限制，在自己的界面上做租户隔离。

6.6 无XUI配置

XSwitch支持无XUI运行，又分为以下几种：

  • 无XUI，但使用XSwitch后台的API接口访问数据库，相当于自己写了一套XUI配置界面
  • 无XUI，也不使用XUI的数据库，相当于原生的XSwitch
  • 有XUI，但是不使用部分功能，如仅使用用户功能，但不使用路由功能。可以联系我们的工程师修改后台XML配置。
  • 有XUI，但是不使用部分功能，如仅使用路由，但不使用用户和分机。可以联系我们的工程师修改后台XML配置。

6.7 弹性伸缩

XSwitch支持弹性伸缩，但弹性伸缩通常需要二次开发，跟多种运维系统和工具对接。详情请咨询我们的工程师。

7 与其它系统对接

与其它系统对接有很多方法，根据不同的使用场景大约有以下几种方式。

7.1 对接运营商IMS

如果运营商提供IMS线路，通常需要注册，根据运营商提供的以下信息建一个网关：

  • 域：如ims.beijing.chinamobile.com之类
  • 注册代理服务器：IP地址
  • 外呼代理服务器：IP地址
  • From域：域
  • 用户名：用户名
  • 密码：密码
  • 其它参数

将网关挂在public这个SIP Profile上，以便能接收来话。

去话：本地电话拨打IMS

做一条路由，目的地选择这个新建的网关。

来话：IMS拨打XSwitch

根据运营商提供的DID（通常跟用户名差不多），做一条路由，可以路由到IVR，也可以根据DID与分机一一对应（在DID菜单中设置）。

7.2 与其它系统IP对接

需要的参数：

  • 对端IP
  • 号码格式，如E.164格式或其它格式，长途是否加0之类
  • 支持的音、视频编码

给对端提供的参数：

  • 本端IP

去话：

  • 加一个网关，将去话路由到该网关，或
  • 做一条路由，将去话路由到IP地址，格式有：
    • ip
    • ip:port
    • ip:port;transport=tcp
  • 加一条中继，路由到该中继
  • 加一个中继组，路由到该中继组

来话：

  • 不验证对方IP：直接让对方将来话路由到public Profile对应的IP地址和端口（默认为5080）
  • 验证对方IP：新建一个分机，将对方IP段填入分机的CIDR字段
  • 根据DID建一条路由

7.3 本地FXS模拟网关IP对接

FXS口的模拟网关用于把普通的模拟话机（老式话机）变成SIP话机。

  • 在XSwitch上添加一个分机
  • 将模拟话机插到网关的S口，在网关上设置，注册到XSwitch

7.4 本地FXO模拟网关IP对接

FXO口的模拟网关用户连接外线，即运营商的线路。

来话：

  • 将FXO口网关来话指向XSwitch的public Profile指定的端口
  • 根据DID做路由处理来话
  • 如果使用IP验证收可以建一个分机，将网关的地址填入分机的CIDR字段

去话：

  • 做路由指向网关的IP

7.5 模拟网关注册到XSwitch

有时候，模拟网关的IP不可预测，或在NAT后面不可达，如XSwitch在云端但模拟网关在办公室的场景。

来话：

  • 模拟网关注册到XSwitch
  • 将来话送给XSwitch
  • XSwitch做相应路由处理来话

去话：

  • 模拟网关注册到XSwitch
  • 做路由，目的地选择【分机网关】

7.6 会议

XSwitch提供音视频会议功能，功能强大而灵活，但在使用前需要做一些基本的配置。

  • 立即会议接入码：默认为*86
  • 立即会议字冠：默认为72，位长9
  • 预约会议字冠：默认为71，位长9
  • 以上信息需要在全局变量及路由中进行相关设置

最好选一个专用号段作为会议号段以免与系统冲突。如果直拨本地网号码（外线不加0），一般来说本地网号码都是7-8位，因此可以设置更严格的路由，与位长为9的会议字冠区分。

如果需要邀请，则还需要进行邀请相关的接入设置，如规划DID等，详询系统支持工程师。

7.7 其它

IP与IP对接需要根据使用场景考虑是否对对端的IP进行验证，以保证呼叫的安全性。

8 结束语

感谢您使用XSwitch。

XSwitch可谓功能极其强大，使用起来极其灵活。但并不是任何人都能驾驭极其强大的“野马”，因此，我们花了很大精力驯服它并给它套上了Web管理界面的“枷锁”。如果您觉得这些这些枷锁限制了您的想象力及使用空间，欢迎联系我们，获取更深入的支持，一起探索XSwitch背后更深层的秘密。

您可以用以下方式联系我们，获取更多技术支持和文档资料。

  • https://xswitch.cn
  • https://x-y-t.cn
  • info@x-y-t.cn

如果您是通过代理商或服务商购买我们的产品，请优先联系您的服务商，他们往往比我们更了解您及您的使用场景，离您更“近”也能提供更贴心的服务。

  1. 目前，并不是所有的名称字段都允许输入空格和中文。具体命名规则见各对象的使用说明。↩︎

  2. 注意，通常直接设置系统hosts文件在本地指向相应IP的方法是不好用的，因为大多数软电话都不支持本地的hosts解析。↩︎