mod_callcenter：概念与加载
mod_callcenter 默认情况下是不加载的。要启用它，请在 autoload_configs/modules.conf.xml 中取消注释相关行：
xml
<load module="mod_callcenter"/>该模块引入了三种对象类型：
- 队列 (Queue)：用于存放呼入电话的命名保持池。每个队列都有自己的路由策略、保持音乐和等待时间限制。
- 坐席 (Agent)：可以接收队列来电的命名终端（人或设备）。坐席具有工作状态 (Status)（如：Available 可用, On Break 休息, Logged Out 登出, Available (On Demand) 按需可用），以及由模块管理的当前运行状态 (State)。
- 层级 (Tier)：将一个坐席分配给一个队列的映射关系，包含级别 (level，即优先级组) 和位置 (position，即该级别内的顺序)。
默认情况下，状态数据存储在 SQLite 数据库中。也可以配置 ODBC 数据源以实现共享访问。
XML 配置文件 (callcenter.conf.xml) 定义了队列、坐席和层级，这些配置会在启动时同步到数据库中。
重要提示：每次重启时，XML 中的坐席和层级配置都会重新应用到数据库中。如果 XML 中提供了坐席的级别 (level) 和位置 (position)，它们将被重置为配置的值。这种行为不适合多个 FreeSWITCH 共享数据库的部署场景。
呼叫中心队列配置 (Queue Configuration)
队列在 callcenter.conf.xml 的 <queues> 元素下定义。
xml
<queues>
<queue name="support@default">
<param name="strategy" value="longest-idle-agent"/>
<param name="moh-sound" value="$${hold_music}"/>
<param name="time-base-score" value="system"/>
<param name="max-wait-time" value="0"/>
<param name="max-wait-time-with-no-agent" value="0"/>
<param name="max-wait-time-with-no-agent-time-reached" value="5"/>
<param name="tier-rules-apply" value="false"/>
<param name="tier-rule-wait-second" value="300"/>
<param name="tier-rule-wait-multiply-level" value="true"/>
<param name="tier-rule-no-agent-no-wait" value="false"/>
<param name="discard-abandoned-after" value="60"/>
<param name="abandoned-resume-allowed" value="false"/>
</queue>
</queues><queue> 上的 name 属性是必填项。常规格式为 name@context（例如 support@default），与坐席名称的格式相匹配。
队列参数参考
| 参数 | 用途 | 可选值 | 默认值 |
|---|---|---|---|
| strategy | 坐席选择算法。 | 见下方表格 | longest-idle-agent |
| moh-sound | 播放给等待中呼叫者的保持音乐。 | 文件路径或流 | 无 |
| announce-sound | 呼叫者等待期间定期播放的提示音文件。 | 文件路径 | 无 |
| announce-frequency | 播放提示音的间隔秒数。0 表示禁用。 | 整数 0-86400 | 0 |
| record-template | 录制桥接呼叫的路径模板。支持通道变量和 strftime 时间标记。 | 字符串 | 无 |
| time-base-score | 计算呼叫者等待时间得分（用于选择坐席）的基准点。queue 从呼叫者进入队列时开始算；system 从呼叫发起时开始算。 |
queue, system | queue |
| max-wait-time | 呼叫者被放弃（挂断/跳出）前的最大等待秒数。0 表示无限制。 | 整数 0-86400 | 0 |
| max-wait-time-with-no-agent | 当没有坐席登录时，呼叫者的最大等待秒数。0 表示无限制。 | 整数 0-86400 | 0 |
| max-wait-time-with-no-agent-time-reached | 达到上述无坐席等待时间后的宽限期（秒），之后才会将呼叫者移出队列。 | 整数 0-86400 | 5 |
| tier-rules-apply | 启用基于层级的等待时间规则（见下文）。 | true, false | false |
| tier-rule-wait-second | 呼叫者晋升到下一个层级级别之前必须等待的秒数。 | 整数 0-86400 | 0 |
| tier-rule-wait-multiply-level | 若为 true，到达第 N 级的等待时间为 N * 等待秒数。若为 false，经过一次等待间隔后，所有更高级别立即开放。 |
true, false | false |
| tier-rule-no-agent-no-wait | 若为 true，当当前层级没有可用坐席时，呼叫者跳过该层级的等待时间。 | true, false | true |
| discard-abandoned-after | 放弃呼叫的记录从数据库中删除的延迟秒数，阻止其恢复排队。0 表示无限期保留。 | 整数 0-86400 | 60 |
| abandoned-resume-allowed | 若为 true，挂断并在上述秒数内再次呼入的呼叫者，将恢复其在队列中的原位置。 | true, false | false |
| agent-no-answer-status | 分配给未在振铃超时时间内接听的坐席的状态。 | Available, Available (On Demand), On Break, Logged Out | On Break |
| ring-progressively-delay | 针对渐进式振铃策略，向振铃组依次添加下一个坐席的间隔秒数。 | 整数 0-86400 | 10 |
| skip-agents-with-external-calls | 若为 true，已经处于呼叫中心外部通话中的坐席，将不会收到队列来电。 | true, false | true |
Strategy（策略）值：
| 值 | 行为 |
|---|---|
| longest-idle-agent | 空闲时间最长的坐席接听来电。 |
| round-robin | 坐席轮流接收呼叫，从上一个呼叫结束的位置继续。 |
| top-down | 始终从头开始按层级顺序尝试；优先级最高且可用的坐席始终优先接听。 |
| agent-with-least-talk-time | 历史总通话时间最短的坐席接听来电。 |
| agent-with-fewest-calls | 已接听呼叫次数最少的坐席接听来电。 |
| sequentially-by-agent-order | 依次按层级级别和位置，然后按最后一次分配呼叫的时间戳来选择坐席。 |
| ring-all | 符合条件层级中的所有可用坐席同时振铃。 |
| ring-progressively | 坐席按照配置的延迟间隔逐一振铃，不断累加，直到有人接听。 |
坐席配置 (Agent Configuration)
坐席在 callcenter.conf.xml 的 <agents> 元素下定义。XML 坐席配置会在重启时应用到数据库中；任何通过 API 在运行期间所做的更改都会被覆盖。
xml
<agents>
<agent name="1000@default"
type="callback"
contact="[leg_timeout=10]user/1000@default"
status="Available"
max-no-answer="3"
wrap-up-time="10"
reject-delay-time="10"
busy-delay-time="60" />
</agents>name 属性是必填项，通常采用 extension@context 的格式。
坐席参数参考
| 参数 | 用途 | 可选值 | 默认值 |
|---|---|---|---|
| type | 模块联系坐席的方式。Callback 发起外呼至 contact；uuid-standby 桥接至 contact 中指定的现有通道 UUID。 |
Callback, uuid-standby | 必填 |
| contact | 坐席分支的发起字符串 (Callback 类型) 或通道 UUID (uuid-standby 类型)。方括号中可以设置通道变量。 | 字符串 | 必填 |
| status | 加载 XML 时应用于坐席的初始工作状态。该状态控制坐席是否会被分配呼叫。 | Available, Available (On Demand), On Break, Logged Out | Logged Out |
| max-no-answer | 触发坐席状态变更为无应答状态之前的连续未接听次数。0 表示禁用限制。 | 整数 >= 0 | 0 |
| wrap-up-time | 呼叫结束后，坐席处于不可用状态（整理工作）的秒数，之后才会恢复为 Available。 | 整数 >= 0 (秒) | 0 |
| reject-delay-time | 拒接了上一个呼叫的坐席，在被分配下一个呼叫前需要等待的秒数。 | 整数 >= 0 (秒) | 0 |
| busy-delay-time | 线路返回忙音的坐席，在被分配下一个呼叫前需要等待的秒数。 | 整数 >= 0 (秒) | 0 |
| no-answer-delay-time | 未接听的坐席，在被分配下一个呼叫前需要等待的秒数。 | 整数 >= 0 (秒) | 0 |
| ready_time | Unix纪元时间戳，在此之前不会向该坐席分配呼叫。由模块在无应答事件后自动设置；也可通过 API 手动设置。 | 整数 (纪元秒) | 0 (立即生效) |
Status（状态）值：
| 状态 | 行为 |
|---|---|
| Available (可用) | 正常向坐席分配呼叫。 |
| Available (On Demand) (按需可用) | 仅在明确请求时才向坐席分配呼叫（用于配合某些外部系统）。 |
| On Break (休息) | 坐席已登录但拒绝接听呼叫。 |
| Logged Out (登出) | 坐席拒绝接听呼叫，且不计入可用状态。 |
层级分配 (Tier Assignment)
层级 (Tiers) 将坐席与队列关联起来，并定义坐席在该队列中的优先级。级别 (level) 数字较小的坐席会优先于数字较大的坐席被分配呼叫。在同一级别内，由位置 (position) 决定分配顺序。
层级在 callcenter.conf.xml 的 <tiers> 元素下定义。
xml
<tiers>
<tier agent="1000@default" queue="support@default" level="1" position="1"/>
<tier agent="1001@default" queue="support@default" level="2" position="1"/>
</tiers>如果省略 level 或 position，默认为 1。重启应用层级配置时，提供的值会覆盖运行期间对级别和位置的任何修改。同时省略这两个属性将保留数据库中的现有值。
层级参数参考
| 参数 | 用途 | 可选值 | 默认值 |
|---|---|---|---|
| agent | 坐席名称，与 <agents> 中的条目匹配。 |
字符串 | 必填 |
| queue | 队列名称，与 <queues> 中的条目匹配。 |
字符串 | 必填 |
| level | 优先级组。在尝试更大的数字之前，会先耗尽较小的数字（受层级规则影响）。 | 整数 >= 1 | 1 |
| position | 当启用使用位置的策略（如 top-down, sequentially-by-agent-order）时，决定同级别内的顺序。 | 整数 >= 1 | 1 |
层级规则与升级机制 (Escalation) ：当 tier-rules-apply 为 false（默认值）时，呼叫会同时提供给所有层级，没有延迟。当其为 true 时，呼叫者从级别 1 开始，并且只有在等待指定的秒数之后（如果倍增规则为 true，则乘以层级数），才会晋升到下一个级别。如果当前层级没有坐席，且 tier-rule-no-agent-no-wait 为 true，呼叫者将立即晋升。
callcenter 拨号计划应用程序
callcenter 拨号计划应用程序 (Dialplan Application) 会将入站呼叫放入指定的队列中。呼叫将一直等待，直到找到可用的坐席并且坐席分支被桥接。
语法：
callcenter <queue_name>
示例：
xml
<extension name="inbound-support">
<condition field="destination_number" expression="^5000$">
<action application="answer"/>
<action application="callcenter" data="support@default"/>
</condition>
</extension>在调用 callcenter 之前必须先应答 (answer) 呼叫。该应用程序会一直阻塞，直到呼叫桥接到坐席或呼叫者放弃。队列等待时间限制（max-wait-time 等）会导致该应用程序返回结束，此时拨号计划可以将呼叫路由到其他地方。
一个配套的应用程序 callcenter_track 会将外部发起的呼叫注册为呼叫中心成员以进行数据跟踪，但不会将其放入队列中。这支持了呼叫在 mod_callcenter 之外被桥接，但仍需反映在坐席状态中的场景。
mod_callcenter 的全局设置
callcenter.conf.xml 中的 <settings> 块用于配置模块级选项。
xml
<settings>
<!--<param name="odbc-dsn" value="dsn:user:pass"/>-->
<!--<param name="dbname" value="/dev/shm/callcenter.db"/>-->
<!--<param name="cc-instance-id" value="single_box"/>-->
</settings>| 参数 | 用途 | 可选值 | 默认值 |
|---|---|---|---|
| odbc-dsn | 外部数据库存储的 ODBC 连接字符串。设置后，模块使用 ODBC 而不是内部的 SQLite。格式：dsn:user:pass。 |
字符串 | 无 (使用 SQLite) |
| dbname | SQLite 数据库文件的路径或名称。 | 文件路径 | callcenter |
| cc-instance-id | 实例标识符，用于命名空间数据库行。在多个 FreeSWITCH 实例共享数据库的部署中非常重要。 | 字符串 | single_box |
| debug | 调试详细程度。值越高记录的细节越多。 | 整数 | 0 |
| reserve-agents | 若为 true，在提供呼叫之前会保留坐席（状态设为 Reserved），防止同一个坐席同时被分配给两个呼叫者。 | true, false | false |
| truncate-tiers-on-load | 若为 true，在模块加载且应用 XML 层级之前，会清空 tiers 表。 | true, false | false |
| truncate-agents-on-load | 若为 true，在模块加载且应用 XML 坐席之前，会清空 agents 表。 | true, false | false |
| global-database-lock | 若为 true，模块使用全局锁串行化数据库访问。设置为 false 可允许更细粒度的锁定。 | true, false | true |
| agent-originate-timeout | 发起呼叫时，等待坐席 (Callback 类型) 接听的秒数。值为 0 会回退到默认值。 | 整数 (秒) | 60 |
mod_callcenter API 命令
mod_callcenter 通过 callcenter_config API 和独立的 callcenter_break API 公开运行时的管理功能。这两个 API 均可通过 fs_cli、事件套接字 (event socket) 以及 api/bgapi 拨号计划应用程序来使用。callcenter_config 也注册为 JSON API。命令成功时返回 +OK，失败时返回 -ERR <原因>；获取 (get)、列表 (list) 和计数 (count) 命令则会返回具体数据。
通用格式为：
callcenter_config <section> <action> <args>
选项部分 (section) 包括 agent（坐席）、tier（层级）和 queue（队列）。
callcenter_config agent
| 命令 | 用途 |
|---|---|
agent add <name> <type> |
创建坐席。type 为 callback 或 uuid-standby。 |
agent del <name> |
删除坐席。 |
agent reload <name> |
从 XML 重新加载坐席定义。 |
agent set status <agent_name> <status> |
设置坐席状态 (Logged Out, Available, Available (On Demand), On Break)。设置为 Available 会重置通话时间、已接听次数和无应答次数。 |
agent set state <agent_name> <state> |
设置坐席运行状态 (Waiting等待, Receiving接收, In a queue call通话中, Idle空闲, Reserved保留)。 |
agent set contact <agent_name> <contact> |
设置坐席的发起字符串或待机 UUID。 |
agent set ready_time <agent_name> <epoch> |
将坐席保持不可用状态，直到给定的 Unix 纪元时间。 |
agent set reject_delay_time <agent_name> <秒数> |
设置拒接后重新分配呼叫的延迟时间。 |
agent set busy_delay_time <agent_name> <秒数> |
设置遇忙后重新分配呼叫的延迟时间。 |
agent set no_answer_delay_time <agent_name> <秒数> |
设置无应答后重新分配呼叫的延迟时间。 |
agent get status <agent_name> |
返回坐席的当前配置状态 (status)。 |
agent get state <agent_name> |
返回坐席的当前运行状态 (state)。 |
agent get uuid <agent_name> |
返回坐席当前的通道 UUID。 |
agent list [<agent_name>] |
以管道符分隔的行格式，列出所有坐席或指定名称的坐席。 |
callcenter_config tier
| 命令 | 用途 |
|---|---|
tier add <queue_name> <agent_name> [<level>] [<position>] |
将坐席分配给队列。level 和 position 默认为 1。 |
tier set state <queue_name> <agent_name> <state> |
设置层级状态 (Ready就绪, No Answer无应答, Offering提供中, Active Inbound活跃呼入, Standby待机)。 |
tier set level <queue_name> <agent_name> <level> |
设置层级的优先级别。 |
tier set position <queue_name> <agent_name> <position> |
设置层级在其级别内的位置。 |
tier del <queue_name> <agent_name> |
将坐席从队列中移除。 |
tier reload <queue_name> <agent_name> |
从 XML 重新加载层级。传入 all 作为队列名称可重新加载所有层级。 |
tier list |
按照级别和位置排序列出所有层级。 |
callcenter_config queue
| 命令 | 用途 |
|---|---|
queue load <queue_name> |
将队列定义加载到内存中。 |
queue unload <queue_name> |
从内存中移除队列。 |
queue reload <queue_name> |
卸载然后重新加载队列。 |
queue list |
以管道符分隔的行格式列出所有已加载的队列。 |
queue list agents <queue_name> [<status>] [<state>] |
列出队列中的坐席，可按配置状态 (status) 和运行状态 (state) 过滤。 |
queue list members <queue_name> |
列出队列中等待的呼叫者，按得分排序（等待最久的在前）。 |
queue list tiers <queue_name> |
列出一个队列配置的层级。 |
queue count |
返回已加载的队列数量。 |
queue count agents <queue_name> [<status>] [<state>] |
统计队列中的坐席数量，可按 status 和 state 过滤。 |
queue count members <queue_name> |
统计队列中等待的呼叫者数量。 |
queue count tiers <queue_name> |
统计队列中的层级数量。 |
callcenter_break
callcenter_break 停止模块对通道 UUID 的监控并释放相关的坐席。它用于让模块正在跟踪的坐席从呼叫中脱离出来。
语法：
callcenter_break agent <uuid>
<uuid> 是要停止监控的通道 UUID。该命令会给通道打上标记，以便 mod_callcenter 在下一次循环时结束对其的监管，从而释放该坐席。