Call Class

The Call object represents a voice call. It’s created by client.newCall() (outbound) or received via telnyx.notification (inbound).

Getting a Call Object

Outbound call

const call = client.newCall({
  destinationNumber: '+12345678900',
  audio: true,
});

Inbound call

client.on('telnyx.notification', (notification) => {
  if (notification.type === 'callUpdate' && notification.call.state === 'ringing') {
    const call = notification.call;
    call.answer();
  }
});

Properties

Property	Type	Description
`id`	`string`	Unique call identifier
`state`	`CallState`	Current call state (see Call States)
`direction`	`'inbound' \| 'outbound'`	Call direction
`remotePartyNumber`	`string`	Remote party’s phone number
`remotePartyName`	`string`	Remote party’s display name (if available)
`localPartyNumber`	`string`	Local party’s phone number
`active`	`boolean`	Whether the call is currently active
`recoveredCallId`	`string`	Previous call ID if this call was recovered after reconnection
`peerConnection`	`RTCPeerConnection`	Underlying WebRTC PeerConnection (for advanced use)

Call States

State	Description
`new`	Call object created, not yet dialed
`requesting`	Outbound INVITE sent to server
`ringing`	Inbound: INVITE received. Outbound: remote ringing
`answering`	Inbound call being answered (media negotiation)
`active`	Call connected — media flowing
`held`	Call on hold
`hangup`	Call ended (local or remote hangup)
`destroy`	Call object cleaned up
`recovering`	Call being recovered after reconnection

Methods

`answer()`

Answer an incoming call.

client.on('telnyx.notification', (notification) => {
  if (notification.type === 'callUpdate' && notification.call.state === 'ringing') {
    notification.call.answer();
  }
});

Only call answer() when the call state is ringing. Calling answer() on an already-active call creates a duplicate PeerConnection, which causes one-way audio issues.

`hangup()`

End the call.

// SDK 2.25.x — synchronous
call.hangup();

// SDK 2.26.x — async (returns Promise)
await call.hangup();

See Migration Guide for upgrading from 2.25.x.

`muteAudio()` / `unmuteAudio()`

Toggle the microphone.

call.muteAudio();    // Mute
call.unmuteAudio();  // Unmute

`hold()` / `unhold()`

Put the call on hold or resume it.

call.hold();    // Put on hold (remote hears hold music)
call.unhold();  // Resume

`dtmf(digit)`

Send a DTMF tone (0-9, *, #).

call.dtmf('1');
call.dtmf('*');
call.dtmf('#');

`sendAIConversationMessage(item)`

Send an outbound AI conversation item over the active VSP WebSocket session. Use this to return the result of a client-side tool execution back to the AI backend after receiving a function_call via the telnyx.ai.conversation event, or to subscribe to ACA pre-playout assistant audio. For client-side tool results:

client.on('telnyx.ai.conversation', (event) => {
  if (
    event.params.type === 'conversation.item.created' &&
    event.params.item?.type === 'function_call'
  ) {
    const { call_id, name, arguments: argsJson } = event.params.item;

    // Execute the tool
    const result = executeTool(name, JSON.parse(argsJson));

    // Send the result back
    call.sendAIConversationMessage({
      type: 'function_call_output',
      call_id,
      output: JSON.stringify(result),
    });
  }
});

For ACA pre-playout audio subscription:

call.sendAIConversationMessage({
  type: 'response.audio_stream.subscribe',
});

The call_id must match the one from the inbound function_call. This is a fire-and-forget notification — the SDK does not wait for a response. Requires an active WebSocket connection (throws if disconnected).

`sendDigits(digits)`

Send a sequence of DTMF digits.

call.sendDigits('1');

Events

Call State Events

Event	Payload	Description
`telnyx.notification`	INotification	Call state updates, media events

const call = client.newCall({
  destinationNumber: '+12345678900',
  audio: true,
});

call.on('telnyx.notification', (notification) => {
  switch (notification.call.state) {
    case 'active':
      console.log('Call connected');
      break;
    case 'hangup':
      console.log('Call ended');
      break;
  }
});

Advanced

Access the PeerConnection

For custom WebRTC monitoring or manipulation:

const pc = call.peerConnection;

// Get current ICE connection state
console.log('ICE state:', pc.iceConnectionState);

// Get current DTLS state
console.log('DTLS state:', pc.connectionState);

// Get stats
const stats = await pc.getStats();
stats.forEach((report) => {
  if (report.type === 'candidate-pair' && report.nominated) {
    console.log('Nominated pair:', report);
  }
});

Direct PeerConnection access is for advanced use cases only. The SDK manages the PeerConnection lifecycle — calling methods like close() or setRemoteDescription() directly may break the call.

Custom headers

Add SIP headers to the INVITE for server-side correlation:

const call = client.newCall({
  destinationNumber: '+12345678900',
  audio: true,
  customHeaders: [
    { name: 'X-Call-Session', value: sessionUuid },
    { name: 'X-Agent-ID', value: agentId },
  ],
});

Common Patterns

Simple outbound call with state handling

const call = client.newCall({
  destinationNumber: '+12345678900',
  audio: true,
});

call.on('telnyx.notification', (notification) => {
  switch (notification.call.state) {
    case 'requesting':
      showDialingUI();
      break;
    case 'ringing':
      showRingingUI();
      break;
    case 'active':
      showActiveCallUI();
      break;
    case 'hangup':
      cleanupCallUI();
      break;
  }
});

// Cancel the call if not yet connected
cancelButton.addEventListener('click', () => {
  call.hangup();
});

Inbound call with accept/reject UI

client.on('telnyx.notification', (notification) => {
  if (notification.type === 'callUpdate' && notification.call.state === 'ringing') {
    const call = notification.call;

    showIncomingCallUI({
      from: call.remotePartyNumber,
      onAccept: () => call.answer(),
      onReject: () => call.hangup(),
    });
  }
});

Hold and resume

// Put call on hold
holdButton.addEventListener('click', () => {
  call.hold();
});

// Resume the call
resumeButton.addEventListener('click', () => {
  call.unhold();
});

Getting Started

Authentication

Push Notifications

Tutorials

Use Cases

Troubleshooting

SDKs

API Reference

For AI Agents

Call Class

Call Class

Getting a Call Object

Outbound call

Inbound call

Properties

Call States

Methods

`answer()`

`hangup()`

`muteAudio()` / `unmuteAudio()`

`hold()` / `unhold()`

`dtmf(digit)`

`sendAIConversationMessage(item)`

`sendDigits(digits)`

Events

Call State Events

Advanced

Access the PeerConnection

Custom headers

Common Patterns

Simple outbound call with state handling

Inbound call with accept/reject UI

Hold and resume

See Also

​Call Class

​Getting a Call Object

​Outbound call

​Inbound call

​Properties

​Call States

​Methods

​answer()

​hangup()

​muteAudio() / unmuteAudio()

​hold() / unhold()

​dtmf(digit)

​sendAIConversationMessage(item)

​sendDigits(digits)

​Events

​Call State Events

​Advanced

​Access the PeerConnection

​Custom headers

​Common Patterns

​Simple outbound call with state handling

​Inbound call with accept/reject UI

​Hold and resume

​See Also

Call Class

Getting a Call Object

Outbound call

Inbound call

Properties

Call States

Methods

`answer()`

`hangup()`

`muteAudio()` / `unmuteAudio()`

`hold()` / `unhold()`

`dtmf(digit)`

`sendAIConversationMessage(item)`

`sendDigits(digits)`

Events

Call State Events

Advanced

Access the PeerConnection

Custom headers

Common Patterns

Simple outbound call with state handling

Inbound call with accept/reject UI

Hold and resume

See Also