跳转到主要内容
Infinity links AI助理
我是您的AI小助手，有什么不清楚的您可以问我哦！
AI助手

sip客户端 - 电话接口文档

SIP 客户端前端调用接口说明

适用版本：3.22.16

1. 调用方式

前端通过 Windows 自定义 URL 协议唤起客户端，不是 HTTP 接口。

客户端 协议名称
InfinitySip infinitySip://

网页中可使用以下方式调用：

window.location.href = 'infinitySip://answer';

返回数据

所有接口均无返回数据。调用属于“发送命令后不等待结果”的方式：

  • 不返回 HTTP 状态码。
  • 不返回 JSON、通话状态或错误信息。
  • 不提供 Promise、回调函数或浏览器事件。
  • 前端无法根据协议唤起结果判断呼叫、接听或挂机是否成功。

因此，前端调用后只能提示“已提交到客户端”，不应直接提示“呼叫成功”或“操作成功”。如需获取最终通话结果，应通过服务端通话事件、CDR 或其他业务接口查询。

2. 发起呼叫

接口地址

infinitySip://call?calleeNumber=1001&customerId=C8899&businessId=B20260925001&traceId=550e8400-e29b-41d4-a716-446655440000

参数说明

参数 必填 含义 最大长度 SIP 中的用途
calleeNumber 是 被叫号码，例如分机号或电话号码 3-16 位；仅允许数字、字母及 + * # . _ - @ 作为呼叫目标
customerId 否 客户标识，用于关联客户资料 64 个字符 写入 X-Customer-Id 请求头
businessId 否 业务标识，例如订单号、工单号 128 个字符 写入 X-Business-Id 请求头
traceId 否 本次呼叫的链路追踪标识 64 个字符 写入 X-Trace-Id 请求头

完整协议地址最多为 2048 个字符。四个参数均不允许重复，也不接受未在表中定义的参数。三个可选标识不能包含冒号、换行或控制字符。超过限制或格式不合法时，客户端不会发起呼叫，并会显示“Call request rejected”提示；自定义 URL 协议本身仍不会向网页返回错误数据。

只传必填参数的示例：

infinitySip://call?calleeNumber=1001

JavaScript 示例：

const LIMITS = {
  calleeNumber: 16,
  customerId: 64,
  businessId: 128,
  traceId: 64,
  url: 2048,
};
const CALLEE_PATTERN = /^[0-9A-Za-z+*#._@-]+$/;
const CALLEE_MIN_LENGTH = 3;
const INVALID_HEADER_PATTERN = /[:\u0000-\u001f\u007f]/;

const params = new URLSearchParams({
  calleeNumber: '1001',
  customerId: 'C8899',
  businessId: 'B20260925001',
  traceId: crypto.randomUUID(),
});

for (const [name, value] of params) {
  if (value.length > LIMITS[name]) throw new Error(`${name} 参数过长`);
  if (name === 'calleeNumber' && value.length < CALLEE_MIN_LENGTH) {
    throw new Error('calleeNumber 不能少于 3 位');
  }
  if (name === 'calleeNumber' && !CALLEE_PATTERN.test(value)) {
    throw new Error('calleeNumber 包含不支持的字符');
  }
  if (name !== 'calleeNumber' && INVALID_HEADER_PATTERN.test(value)) {
    throw new Error(`${name} 包含冒号、换行或控制字符`);
  }
}

const url = `infinitySip://call?${params.toString()}`;
if (url.length > LIMITS.url) throw new Error('协议地址不能超过 2048 个字符');
window.location.href = url;

3. 接听来电

无参数。接听当前正在振铃的来电；没有来电时不会产生通话。

infinitySip://answer

4. 挂断通话

无参数。结束当前全部活动通话或正在振铃的来电。

infinitySip://hangup

5. 开启免打扰

无参数。开启并保存客户端免打扰状态，后续来电将按免打扰规则处理。

infinitySip://dnd/on

6. 关闭免打扰

无参数。关闭并保存客户端免打扰状态，客户端恢复正常接听来电。

infinitySip://dnd/off

7. 使用说明

  • 参数值应使用 UTF-8 URL 编码，建议使用 URLSearchParams 生成查询参数。
  • 参数名称不区分大小写，建议固定使用文档中的写法。
  • 仅支持 calleeNumber、customerId、businessId 和 traceId，未知或重复参数会被拒绝。
  • 未传递的可选参数不会生成对应的 SIP 请求头。
  • 前端应在唤起客户端前完成长度与字符校验，并向用户展示具体原因。
  • 自定义协议没有返回值，前端调用后不能直接获得通话结果。
  • 首次从浏览器调用时，Windows 或浏览器可能提示用户确认打开客户端。
  • 调用前应确保对应品牌客户端已经安装并完成账号配置。
回到顶部