@3cx/call-control-sdk

The 3CX Call Control SDK for TypeScript provides a higher-level interface to the 3CX Call Control API.

Installation

npm install @3cx/call-control-sdk

Quick Start

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 Reconnection

On unexpected disconnects the SDK reconnects automatically with exponential backoff. By default it never gives up (maxReconnects: Infinity).

Delays grow roughly 5s → 10s → 20s → … up to the cap. Token fetch failures during reconnect use the same backoff. To limit retries:

websocket: { maxReconnects: 5 }

Extension Participant Monitoring

When extensions are attached to the app's service principal (controlled DNs), the SDK emits separate events for their call activity. This lets you monitor calls on those extensions without conflating them with calls on the app's own programmable 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`);
});

Why no audio on extension participants?

Audio streams and DTMF are only available for the app's own programmable DN (RoutePoint). Extension calls are physically handled by the extension's own device (IP phone, softphone, etc.) - the media path goes directly between the PBX and that device. The programmable extension never sits in the media path for those calls, so there is no audio to intercept or inject. Call control actions (transfer, drop, divert, routeTo) work at the signaling level; answer() on extensions requires supportsDirectControl (uaCSTA).

Event lifecycle note

A RoutePoint (the app's own DN) answers incoming calls automatically - participants almost always arrive with status Connected, so participantConnected fires immediately.

Extensions behave differently: a call first rings on the device (Ringing), and only becomes Connected after the user picks up. The extensionParticipantConnected event fires only when the extension actually answers the call. To detect incoming (ringing) calls on extensions, listen to extensionParticipantUpdated and check 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
    }
  }
});

Multi-device extensions get one participant leg per device. Call answer() on the leg with supportsDirectControl === true, not on mobile/softphone legs.

divert() redirects an unanswered call — use on a Ringing inbound leg (fails on Connected). routeTo() adds alternative routes while the participant stays in the call — valid on Ringing or Connected. Use transfer() for blind transfer on established calls. Neither applies to an outbound Dialing leg.

Outbound Calls

makeCall returns the created participant ID directly from the API response, so you don't have to wait for a WebSocket event to correlate the call:

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" });
}

The PBX may return 202 Accepted (call accepted, id not yet available). In that case makeCall resolves to undefined - track the call via WebSocket events instead.

Attached Data

Attach metadata to a call with attachParticipantData / attachPartyData. Every key must be prefixed with public_ - the PBX rejects other keys with HTTP 422.

Both methods take the same participant ID and write two different fields on that participant's record (the same call leg). They do not target the collocutor's DN or a second participant object:

Both values are read from the controlled participant handle — the collocutor is not exposed as a separate object. Attach party data on a monitored extension when you need metadata to survive transfer or similar operations.

// 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'

To inspect another DN's legs, use client.getState().callcontrol.get(dn)?.participants (or the live handle from getExtensionParticipantHandle). There is no getParticipantByDn helper.

MCP Integration

Use the SDK's token store with 3CX MCP server:

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

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

API Reference

Participant

CallControlClient

Events - RoutePoint (Own DN)

Fired for participants on the app's own programmable DN. Full control: audio streams, DTMF, and call actions.

Events - Monitored Extensions

Fired for participants on extensions attached to the service principal. Call control only - no audio or DTMF (the media path is handled by the extension's own device, not by the programmable extension).

Events - Connection

License

MIT