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

call_id
str

Unique identifier for this call, assigned by SignalWire.

node_id
str

Identifier of the Relay node handling this call.

project_id
str

SignalWire project ID that owns this call.

context
str

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

tag
str

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

direction
str

Call direction. Valid values:

  • "inbound" — incoming call
  • "outbound" — outgoing call
device
dict

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

state
str

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
segment_id
str

Call segment identifier for tracking call legs.

Methods

on

Register an event listener on a call.

wait_for

Wait for a specific event on a call.

wait_for_ringing

Wait until the call is ringing.

wait_for_answered

Wait until the call is answered.

wait_for_ending

Wait until the call is ending.

wait_for_ended

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.

play_tts

Play text-to-speech.

play_audio

Play an audio file from a URL.

play_silence

Play silence for a number of seconds.

play_ringtone

Play a named ringtone.

record

Record audio from a call.

play_and_collect

Play audio and collect DTMF or speech input.

prompt_tts

Play text-to-speech, then collect input.

prompt_audio

Play an audio file, then collect input.

collect

Collect DTMF or speech input without playing media.

detect

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

detect_digit

Detect DTMF digits.

detect_answering_machine

Detect a human versus an answering machine.

detect_fax

Detect a fax tone.

ai

Start an AI agent session on a call.

amazon_bedrock

Connect a call to an Amazon Bedrock AI agent.

ai_hold

Put an AI agent session on hold.

ai_unhold

Resume an AI agent session from hold.

ai_message

Send a message to an active AI agent session.

denoise

Start noise reduction on a call.

denoise_stop

Stop noise reduction on a call.

send_digits

Send DTMF digits on a call.

echo

Echo call audio back to the caller for testing.

bind_digit

Bind a DTMF digit sequence to trigger a Relay method.

clear_digit_bindings

Clear DTMF digit bindings on a call.

user_event

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.

send_fax

Send a fax document on a call.

receive_fax

Receive a fax on a call.

pay

Collect payment information on a call.

live_transcribe

Start or stop live transcription on a call.

live_translate

Start or stop live translation on a call.

join_conference

Join an ad-hoc audio conference.

leave_conference

Leave an audio conference.

join_room

Join a video/audio room.

leave_room

Leave a video/audio room.

queue_enter

Place a call into a named queue.

queue_leave

Remove a call from a queue.

Example

from signalwire.relay import RelayClient
client = RelayClient(
    project="your-project-id",
    token="your-api-token",
    contexts=["default"],
)
@client.on_call
async def handle_call(call):
    await call.answer()
    # Register an event listener
    call.on("calling.call.play", lambda event: print(f"Play state: {event.params.get('state')}"))
    # Play a greeting
    action = await call.play([{"type": "tts", "params": {"text": "Hello from Relay!"}}])
    await action.wait()
    # Wait for the call to end
    await call.wait_for_ended()
    print(f"Call ended: {call.call_id}")
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.