@ 3cx/ 呼叫控制- sdk

TypeScript的3CX呼叫控制SDK为3CX呼叫控制API提供了更高级的接口.

安装

npm install @3cx/call-control-sdk

快速启动

import { CallControlClient } from "@3cx/call-control-sdk";

const client = new CallControlClient({
  pbxBase: "https://your-pbx.example.com",
  appId: "your-app-id",
  appSecret: "your-app-secret",
});

await client.connect();

client.on("participantConnected", async (participant) => {
  console.log(`Participant ${participant.id} connected`);

  // Get audio stream from the caller (PCM 8kHz 16-bit mono)
  const audioStream = await participant.getAudioStream();

  // Create audio writer to the caller
  const audioWriter = participant.getAudioWriter();

  // Pipe audio through your AI provider (STT -> Agent -> TTS)
  // ...

  // Write PCM 8kHz 16-bit mono audio back
  audioWriter.write(pcmBuffer);

  // Call actions directly on the participant
  await participant.transfer("1001");
});

client.on("participantDisconnected", (participantId) => {
  // SDK automatically cleans up audio streams/writers
  console.log(`Participant ${participantId} disconnected`);
});

WebSocket 重新连接

在出人意料的断开时,SDK会自动与指数回放连接. 默认的 永不放弃 (单位:千美元)maxReconnects: Infinity) (中文(简体) ).

延迟会增加大约5分 10分 20分 达到上限 抓取失败 重新连接使用相同的回放. 限制重试 :

websocket: { maxReconnects: 5 }

延期参与者监测

当扩展附着在应用程序的服务本位( 受控 DNs) 时, SDK 发布单独的事件 用于他们的呼叫活动。 这样你就可以监视那些电话 扩展时不将其与应用程序自己的可编程DN的调用相混为一谈.

// Calls on the app's own DN - full control (audio + call actions)
client.on("participantConnected", async (participant) => {
  console.log(`Own DN call from ${participant.info.party_caller_id}`);
  const audio = await participant.getAudioStream(); // works
  // ...
});

// Calls on monitored extensions - call actions only, no audio
client.on("extensionParticipantConnected", async (participant) => {
  console.log(
    `Extension ${participant.dn} call from ${participant.info.party_caller_id}`,
  );
  // participant.getAudioStream() -> throws Error
  await participant.transfer("1001"); // works
});

client.on("extensionParticipantDisconnected", (participantId) => {
  console.log(`Extension call ${participantId} ended`);
});

为什么没有关于扩展参与者的音频?

音频流和DTMF仅供应用程序自己的可编程DN(RoutePoint)使用. 分机电话由分机自己的设备(IP电话、软电话、, ——媒体路径在PBX和那个设备之间直接走. 可编程 扩展从不为这些电话坐在媒体的道路上,所以没有音频可以截取 或注射 。 调用控制动作( 调用、 调用、 调用、 路由) 在信号中工作 级别; answer() 需要扩展时 supportsDirectControl (中文(简体) ).

事件周期说明

路由点( app's own DN) 自动回答来电 - 参与者 几乎总是以身份到达 Connected这样 participantConnected 立即开火.

扩展功能行为不同: 设备上的第一个调用环( S)Ringing),且仅限 变成 Connected 用户接后. 这个 extensionParticipantConnected 事件 只有在扩展部分实际响应呼叫时才开火. 检测进货( 环行) 呼叫扩展名, 请收听 extensionParticipantUpdated 检查 participant.info.status数字 :

client.on("extensionParticipantUpdated", (participant) => {
  if (participant.info.status === "Ringing") {
    console.log(`Extension ${participant.dn} is ringing`);
    if (participant.supportsDirectControl) {
      void participant.answer(); // uaCSTA leg only
    }
  }
});

多设备扩展获取 每个设备一个参与者腿调用 answer() 编辑 带脚的 supportsDirectControl === true而不是移动/软手机腿上.

divert() 重定向一个未回复的呼叫——在 Ringing 入境 脚步( 失败) Connected) (中文(简体) ). routeTo() 在参与者留在电话中时增加其他路线: 有效时间 Ringing 或者说 Connected启用 transfer() 已确认的盲转 打电话 也不适用于出入境 Dialing 脚.

外出通话

makeCall 返回直接从 API 响应中创建的参与者ID,所以您 用不着等WebSocket事件来联系到这个电话:

const participantId = await client.makeCall("101");
// or from a specific source DN:
const participantId = await client.makeCall("101", "cctest2");

if (participantId !== undefined) {
  await client.attachPartyData(participantId, { public_ticket: "1234" });
}

PBX 可返回 202 Accepted (电话已接受,id尚未提供)。 这样的话 makeCall 决定: undefined - 通过WebSocket事件追踪电话.

所附数据

将元数据附加到呼叫中 attachParticipantData 编号 : attachPartyData。 。 。 . 每把钥匙 必须是前缀 public_ - PBX 拒绝带有 HTTP 的其他密钥 422。 。 。 .

两种方法都采用 同一参与方的身份证 并撰写两个不同的字段 那个 参与人 记录(同一条呼叫腿)。 没错 没有 瞄准焦距的 DN 或第二个参与者反对:

两个值都从 受控参与人手柄 ——相机没有 暴露为单独的对象。 需要时随附缔约方关于监测扩展的数据 元数据以活过传输或类似操作.

// via the client (same participantId for both)
await client.attachParticipantData(participantId, { public_ticket: "1234" });
await client.attachPartyData(participantId, { public_peer: "181" });

// or via a participant handle
await participant.attachParticipantData({ public_ticket: "1234" });
await participant.attachPartyData({ public_peer: "181" });

console.log(participant.participantData.public_ticket); // '1234'
console.log(participant.partyData.public_peer); // '181'

await participant.attachPartyData({ public_ticket: "5678" });
await participant.refresh(); // party data is not pushed over WebSocket
console.log(participant.partyData.public_ticket); // '5678'

为了检查另一个DNA的腿,使用 client.getState().callcontrol.get(dn)?.participants (或从 getExtensionParticipantHandle) (中文(简体) ). 没有 getParticipantByDn 帮手.

MCP 一体化

使用带有 3CX MCP 服务器的 SDK 令牌商店 :

const authProvider = client.createMcpAuthProvider();
const mcpUrl = client.getMcpUrl();

const mcpServer = new MCPServerStreamableHttp({
  url: mcpUrl,
  authProvider,
});

API 参考

Participant

CallControlClient

事件 - 路由点( Own DN)

在应用程序自己的可编程DN上为参与者被炒作. 全能控制:音频流,DTMF,和调用动作.

事件 - 有监测的扩展

在服务校长的延期上为与会者解雇。 仅调用控制 - 没有音频或DTMF(媒体路径由扩展自己的设备处理,而不是由可编程扩展处理).

事件 - 连接

许可证

麻省理工学院