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.

isTerminal
boolean

true once the call has reached the ended state.

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.

waitForAnswered

Wait for a call to be answered.

waitForRinging

Wait for a call to start ringing.

waitForEnding

Wait for a call to start ending.

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.

playTTS

Play text-to-speech.

playAudio

Play an audio file from a URL.

playSilence

Play silence for a number of seconds.

playRingtone

Play a named ringtone.

record

Record audio from a call.

playAndCollect

Play audio and collect DTMF or speech input.

promptTTS

Speak a prompt, then collect input.

promptAudio

Play an audio prompt, then collect input.

collect

Collect DTMF or speech input without playing media.

detect

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

detectAnsweringMachine

Detect whether a human or a machine picked up.

detectDigit

Detect DTMF digits.

detectFax

Detect a fax tone.

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.

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

import { RelayClient } from '@signalwire/sdk';
const client = new RelayClient({
  project: process.env.SIGNALWIRE_PROJECT_ID!,
  token: process.env.SIGNALWIRE_API_TOKEN!,
  contexts: ['default']
});
client.onCall(async (call) => {
  await call.answer();
  // Register an event listener
  call.on('calling.call.play', (event) => console.log(`Play state: ${event.params.state}`));
  // Play a greeting
  const action = await call.play([{ type: 'tts', text: 'Hello from Relay!' }]);
  await action.wait();
  // Wait for the call to end
  await call.waitForEnded();
  console.log(`Call ended: ${call.callId}`);
});
await 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.