RELAY

Call

View as MarkdownOpen in Claude

The Call class represents a live RELAY call and provides methods for controlling every aspect of the call — answering, playing audio, recording, collecting input, bridging, conferencing, AI agents, and more. Call objects are created automatically by RelayClient when an inbound call arrives or when you dial an outbound call.

All call control methods are async and communicate with SignalWire over WebSocket using the RELAY JSON-RPC protocol. Methods that start long-running operations (play, record, detect, etc.) return Action objects that let you stop, pause, or wait for the operation to complete.

Properties

callId
string

Unique identifier for this call, assigned by SignalWire.

nodeId
string

Identifier of the RELAY node handling this call.

projectId
string

SignalWire project ID that owns this call.

context
string

The context (routing label) the call is associated with.

tag
string

Correlation tag for tracking related calls. Empty string if not set.

direction
string

Call direction. Valid values:

  • "inbound" — incoming call
  • "outbound" — outgoing call
device
Record<string, any>

Device information for the call endpoint. Contains type (e.g., "phone") and params (e.g., {"from_number": "+1...", "to_number": "+1..."}).

state
string

Current call state. Valid values:

  • "created" — call has been initiated
  • "ringing" — ringing at the destination
  • "answered" — call is active
  • "ending" — hangup in progress
  • "ended" — call has terminated
segmentId
string

Call segment identifier for tracking call legs.

Methods

on

Register an event listener on a call.

waitFor

Wait for a specific event on a call.

waitForEnded

Wait for a call to reach the ended state.

answer

Answer an inbound RELAY call.

hangup

End a RELAY call.

pass

Decline control of an inbound call and return it to routing.

disconnect

Disconnect (unbridge) a connected call.

transfer

Transfer call control to another RELAY application or SWML script.

connect

Bridge a call to one or more destinations.

hold

Put a call on hold.

unhold

Resume a held call.

play

Play audio content on a call.

record

Record audio from a call.

playAndCollect

Play audio and collect DTMF or speech input.

collect

Collect DTMF or speech input without playing media.

detect

Detect answering machines, fax tones, or digits on a call.

ai

Start an AI agent session on a call.

amazonBedrock

Connect a call to an Amazon Bedrock AI agent.

aiHold

Put an AI agent session on hold.

aiUnhold

Resume an AI agent session from hold.

aiMessage

Send a message to an active AI agent session.

denoise

Start noise reduction on a call.

denoiseStop

Stop noise reduction on a call.

sendDigits

Send DTMF digits on a call.

echo

Echo call audio back to the caller for testing.

bindDigit

Bind a DTMF digit sequence to trigger a RELAY method.

clearDigitBindings

Clear DTMF digit bindings on a call.

userEvent

Send a custom user-defined event on a call.

refer

Transfer a SIP call to an external endpoint via SIP REFER.

tap

Intercept call media and stream it to an external destination.

stream

Stream call audio to a WebSocket endpoint.

sendFax

Send a fax document on a call.

receiveFax

Receive a fax on a call.

pay

Collect payment information on a call.

transcribe

Start transcribing call audio.

liveTranscribe

Start or stop live transcription on a call.

liveTranslate

Start or stop live translation on a call.

joinConference

Join an ad-hoc audio conference.

leaveConference

Leave an audio conference.

joinRoom

Join a video/audio room.

leaveRoom

Leave a video/audio room.

queueEnter

Place a call into a named queue.

queueLeave

Remove a call from a queue.

Example

1import { RelayClient } from '@signalwire/sdk';
2
3const client = new RelayClient({
4  project: process.env.SIGNALWIRE_PROJECT_ID!,
5  token: process.env.SIGNALWIRE_TOKEN!,
6  contexts: ['default']
7});
8
9client.onCall(async (call) => {
10  await call.answer();
11
12  // Register an event listener
13  call.on('calling.call.play', (event) => console.log(`Play state: ${event.params.state}`));
14
15  // Play a greeting
16  const action = await call.play([{ type: 'tts', text: 'Hello from RELAY!' }]);
17  await action.wait();
18
19  // Wait for the call to end
20  await call.waitForEnded();
21  console.log(`Call ended: ${call.callId}`);
22});
23
24await client.run();

Events

Events are emitted during the lifecycle of a call and its operations. Register handlers using call.on() to react to state changes, errors, and operation completions.

See the Events reference for the full list of calling events, their parameters, and typed event classes.