> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# Relay

## Docs

- [Actions](https://signalwire.com/docs/server-sdks/reference/python/relay/actions.md): Action classes returned from call control methods.
- [AIAction](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/ai-action.md): Action handle for an active AI agent session.
- [stop](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/ai-action/stop.md): Stop the AI agent session.
- [CollectAction](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/collect-action.md): Action handle for a play-and-collect operation.
- [pause](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/collect-action/pause.md): Pause an active play-and-collect operation.
- [resume](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/collect-action/resume.md): Resume a paused play-and-collect operation.
- [start_input_timers](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/collect-action/start-input-timers.md): Manually start the initial_timeout timer on an active collect.
- [stop](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/collect-action/stop.md): Stop the play-and-collect operation.
- [volume](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/collect-action/volume.md): Adjust the prompt playback volume during a play-and-collect operation.
- [DetectAction](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/detect-action.md): Action handle for an active detection operation.
- [stop](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/detect-action/stop.md): Stop detection immediately.
- [FaxAction](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/fax-action.md): Action handle for an active fax send or receive operation.
- [stop](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/fax-action/stop.md): Stop the fax operation.
- [PayAction](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/pay-action.md): Action handle for an active payment collection operation.
- [stop](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/pay-action/stop.md): Stop payment collection.
- [PlayAction](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/play-action.md): Action handle for an active audio playback operation.
- [pause](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/play-action/pause.md): Pause audio playback.
- [resume](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/play-action/resume.md): Resume paused audio playback.
- [stop](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/play-action/stop.md): Stop audio playback immediately.
- [volume](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/play-action/volume.md): Adjust audio playback volume.
- [RecordAction](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/record-action.md): Action handle for an active recording operation.
- [pause](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/record-action/pause.md): Pause an active recording.
- [resume](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/record-action/resume.md): Resume a paused recording.
- [stop](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/record-action/stop.md): Stop recording immediately.
- [StandaloneCollectAction](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/standalone-collect-action.md): Action handle for a standalone input collection operation.
- [start_input_timers](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/standalone-collect-action/start-input-timers.md): Manually start the initial_timeout timer on an active collect.
- [stop](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/standalone-collect-action/stop.md): Stop the collect operation.
- [StreamAction](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/stream-action.md): Action handle for an active audio stream operation.
- [stop](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/stream-action/stop.md): Stop audio streaming.
- [TapAction](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/tap-action.md): Action handle for an active media tap operation.
- [stop](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/tap-action/stop.md): Stop media interception.
- [TranscribeAction](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/transcribe-action.md): Action handle for an active transcription operation.
- [stop](https://signalwire.com/docs/server-sdks/reference/python/relay/actions/transcribe-action/stop.md): Stop transcription.
- [Call](https://signalwire.com/docs/server-sdks/reference/python/relay/call.md): Live call control object with media, AI, and event methods.
- [ai](https://signalwire.com/docs/server-sdks/reference/python/relay/call/ai.md): Start an AI agent session on a call.
- [ai_hold](https://signalwire.com/docs/server-sdks/reference/python/relay/call/ai-hold.md): Put an AI agent session on hold.
- [ai_message](https://signalwire.com/docs/server-sdks/reference/python/relay/call/ai-message.md): Send a message to an active AI agent session.
- [ai_unhold](https://signalwire.com/docs/server-sdks/reference/python/relay/call/ai-unhold.md): Resume an AI agent session from hold.
- [amazon_bedrock](https://signalwire.com/docs/server-sdks/reference/python/relay/call/amazon-bedrock.md): Connect a call to an Amazon Bedrock AI agent.
- [answer](https://signalwire.com/docs/server-sdks/reference/python/relay/call/answer.md): Answer an inbound Relay call.
- [bind_digit](https://signalwire.com/docs/server-sdks/reference/python/relay/call/bind-digit.md): Bind a DTMF digit sequence to trigger a Relay method.
- [clear_digit_bindings](https://signalwire.com/docs/server-sdks/reference/python/relay/call/clear-digit-bindings.md): Clear DTMF digit bindings on a call.
- [collect](https://signalwire.com/docs/server-sdks/reference/python/relay/call/collect.md): Collect DTMF or speech input without playing media.
- [connect](https://signalwire.com/docs/server-sdks/reference/python/relay/call/connect.md): Bridge a call to one or more destinations.
- [denoise](https://signalwire.com/docs/server-sdks/reference/python/relay/call/denoise.md): Start noise reduction on a call.
- [denoise_stop](https://signalwire.com/docs/server-sdks/reference/python/relay/call/denoise-stop.md): Stop noise reduction on a call.
- [detect](https://signalwire.com/docs/server-sdks/reference/python/relay/call/detect.md): Detect answering machines, fax tones, or digits on a call.
- [detect_answering_machine](https://signalwire.com/docs/server-sdks/reference/python/relay/call/detect-answering-machine.md): Detect whether a human or an answering machine answered a call.
- [detect_digit](https://signalwire.com/docs/server-sdks/reference/python/relay/call/detect-digit.md): Detect DTMF digits on a call.
- [detect_fax](https://signalwire.com/docs/server-sdks/reference/python/relay/call/detect-fax.md): Detect a fax tone on a call.
- [disconnect](https://signalwire.com/docs/server-sdks/reference/python/relay/call/disconnect.md): Disconnect (unbridge) a connected call.
- [echo](https://signalwire.com/docs/server-sdks/reference/python/relay/call/echo.md): Echo call audio back to the caller for testing.
- [hangup](https://signalwire.com/docs/server-sdks/reference/python/relay/call/hangup.md): End a Relay call.
- [hold](https://signalwire.com/docs/server-sdks/reference/python/relay/call/hold.md): Put a call on hold.
- [join_conference](https://signalwire.com/docs/server-sdks/reference/python/relay/call/join-conference.md): Join an ad-hoc audio conference.
- [join_room](https://signalwire.com/docs/server-sdks/reference/python/relay/call/join-room.md): Join a video/audio room.
- [leave_conference](https://signalwire.com/docs/server-sdks/reference/python/relay/call/leave-conference.md): Leave an audio conference.
- [leave_room](https://signalwire.com/docs/server-sdks/reference/python/relay/call/leave-room.md): Leave a video/audio room.
- [live_transcribe](https://signalwire.com/docs/server-sdks/reference/python/relay/call/live-transcribe.md): Start or stop live transcription on a call.
- [live_translate](https://signalwire.com/docs/server-sdks/reference/python/relay/call/live-translate.md): Start or stop live translation on a call.
- [on](https://signalwire.com/docs/server-sdks/reference/python/relay/call/on.md): Register an event listener on a call.
- [pass_](https://signalwire.com/docs/server-sdks/reference/python/relay/call/pass.md): Decline control of an inbound call and return it to routing.
- [pay](https://signalwire.com/docs/server-sdks/reference/python/relay/call/pay.md): Collect payment information on a call.
- [play](https://signalwire.com/docs/server-sdks/reference/python/relay/call/play.md): Play audio content on a call.
- [play_and_collect](https://signalwire.com/docs/server-sdks/reference/python/relay/call/play-and-collect.md): Play audio and collect DTMF or speech input.
- [play_audio](https://signalwire.com/docs/server-sdks/reference/python/relay/call/play-audio.md): Play an audio file from a URL on a call.
- [play_ringtone](https://signalwire.com/docs/server-sdks/reference/python/relay/call/play-ringtone.md): Play a named ringtone on a call.
- [play_silence](https://signalwire.com/docs/server-sdks/reference/python/relay/call/play-silence.md): Play silence on a call for a number of seconds.
- [play_tts](https://signalwire.com/docs/server-sdks/reference/python/relay/call/play-tts.md): Play text-to-speech on a call.
- [prompt_audio](https://signalwire.com/docs/server-sdks/reference/python/relay/call/prompt-audio.md): Play an audio file, then collect digits or speech.
- [prompt_tts](https://signalwire.com/docs/server-sdks/reference/python/relay/call/prompt-tts.md): Play text-to-speech, then collect digits or speech.
- [queue_enter](https://signalwire.com/docs/server-sdks/reference/python/relay/call/queue-enter.md): Place a call into a named queue.
- [queue_leave](https://signalwire.com/docs/server-sdks/reference/python/relay/call/queue-leave.md): Remove a call from a queue.
- [receive_fax](https://signalwire.com/docs/server-sdks/reference/python/relay/call/receive-fax.md): Receive a fax on a call.
- [record](https://signalwire.com/docs/server-sdks/reference/python/relay/call/record.md): Record audio from a call.
- [refer](https://signalwire.com/docs/server-sdks/reference/python/relay/call/refer.md): Transfer a SIP call to an external endpoint via SIP REFER.
- [send_digits](https://signalwire.com/docs/server-sdks/reference/python/relay/call/send-digits.md): Send DTMF digits on a call.
- [send_fax](https://signalwire.com/docs/server-sdks/reference/python/relay/call/send-fax.md): Send a fax document on a call.
- [stream](https://signalwire.com/docs/server-sdks/reference/python/relay/call/stream.md): Stream call audio to a WebSocket endpoint.
- [tap](https://signalwire.com/docs/server-sdks/reference/python/relay/call/tap.md): Intercept call media and stream it to an external destination.
- [transcribe](https://signalwire.com/docs/server-sdks/reference/python/relay/call/transcribe.md): Start transcribing call audio.
- [transfer](https://signalwire.com/docs/server-sdks/reference/python/relay/call/transfer.md): Transfer call control to another Relay application or SWML script.
- [unhold](https://signalwire.com/docs/server-sdks/reference/python/relay/call/unhold.md): Release a call from hold.
- [user_event](https://signalwire.com/docs/server-sdks/reference/python/relay/call/user-event.md): Send a custom user-defined event on a call.
- [wait_for](https://signalwire.com/docs/server-sdks/reference/python/relay/call/wait-for.md): Wait for a specific event on a call.
- [wait_for_answered](https://signalwire.com/docs/server-sdks/reference/python/relay/call/wait-for-answered.md): Wait until the call is answered.
- [wait_for_ended](https://signalwire.com/docs/server-sdks/reference/python/relay/call/wait-for-ended.md): Wait for a call to reach the ended state.
- [wait_for_ending](https://signalwire.com/docs/server-sdks/reference/python/relay/call/wait-for-ending.md): Wait until the call is ending.
- [wait_for_ringing](https://signalwire.com/docs/server-sdks/reference/python/relay/call/wait-for-ringing.md): Wait until the call is ringing.
- [Constants](https://signalwire.com/docs/server-sdks/reference/python/relay/constants.md): Relay constants for call states, events, and message states.
- [Events](https://signalwire.com/docs/server-sdks/reference/python/relay/events.md): Typed event classes for all Relay events.
- [Message](https://signalwire.com/docs/server-sdks/reference/python/relay/message.md): SMS/MMS message tracking and state management.
- [on](https://signalwire.com/docs/server-sdks/reference/python/relay/message/on.md): Register an event listener for state changes on this message.
- [wait](https://signalwire.com/docs/server-sdks/reference/python/relay/message/wait.md): Block until the message reaches a terminal state.
- [RelayClient](https://signalwire.com/docs/server-sdks/reference/python/relay/client.md): WebSocket client for real-time call and message control.
- [connect](https://signalwire.com/docs/server-sdks/reference/python/relay/client/connect.md): Establish the WebSocket connection and authenticate.
- [dial](https://signalwire.com/docs/server-sdks/reference/python/relay/client/dial.md): Initiate an outbound call.
- [disconnect](https://signalwire.com/docs/server-sdks/reference/python/relay/client/disconnect.md): Close the WebSocket connection cleanly.
- [execute](https://signalwire.com/docs/server-sdks/reference/python/relay/client/execute.md): Send a raw JSON-RPC request to Relay.
- [receive](https://signalwire.com/docs/server-sdks/reference/python/relay/client/receive.md): Subscribe to additional contexts for inbound events.
- [run](https://signalwire.com/docs/server-sdks/reference/python/relay/client/run.md): Start the client with automatic reconnection.
- [send_message](https://signalwire.com/docs/server-sdks/reference/python/relay/client/send-message.md): Send an outbound SMS or MMS message.
- [unreceive](https://signalwire.com/docs/server-sdks/reference/python/relay/client/unreceive.md): Unsubscribe from inbound event contexts.
- [RelayError](https://signalwire.com/docs/server-sdks/reference/python/relay/relay-error.md): Exception raised when the Relay server returns an error.


> **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page.

> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# Relay

> Real-time WebSocket client for call and message control.

[agents]: /docs/server-sdks/reference/python/agents

[client]: /docs/server-sdks/reference/python/relay/client

[call]: /docs/server-sdks/reference/python/relay/call

[message]: /docs/server-sdks/reference/python/relay/message

[actions]: /docs/server-sdks/reference/python/relay/actions

[events]: /docs/server-sdks/reference/python/relay/events

[constants]: /docs/server-sdks/reference/python/relay/constants

[relay-error]: /docs/server-sdks/reference/python/relay/relay-error

The Relay namespace provides imperative, event-driven control over voice calls and
SMS/MMS messages through a persistent WebSocket connection to SignalWire. While the
[Agents][agents] namespace handles AI-driven conversations
declaratively via SWML, Relay gives you fine-grained, async control over every step
of a call -- answering, playing prompts, collecting digits, recording, bridging,
conferencing, and more.

Relay uses the JSON-RPC 2.0 protocol over WebSocket (`wss://`). The client
authenticates once, subscribes to contexts for inbound events, and processes
call and message events in an async event loop. Automatic reconnection with
exponential backoff ensures resilience against transient network failures.

## Context Routing

Contexts are routing labels that control which inbound calls and messages are
delivered to your application. When you assign a phone number to a context in
the SignalWire dashboard, all calls to that number are routed to Relay clients
subscribed to that context.

```python
from signalwire.relay import RelayClient

# Subscribe to specific contexts
client = RelayClient(
    project="your-project-id",
    token="your-api-token",
    contexts=["support", "sales"],
)

@client.on_call
async def handle_call(call):
    await call.answer()

    # Or subscribe/unsubscribe dynamically
    # await client.receive(["billing"])     # Add a context
    # await client.unreceive(["sales"])     # Remove a context

client.run()
```

A client only receives events for its subscribed contexts. This enables multiple
applications or workers to handle different call flows on the same project by
subscribing to different contexts.

## Example

An IVR that answers calls, plays a menu, collects a digit, and routes accordingly:

```python
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()

    # Play a menu and collect one digit
    action = await call.play_and_collect(
        media=[{"type": "tts", "params": {"text": "Press 1 for sales, 2 for support."}}],
        collect={"digits": {"max": 1, "digit_timeout": 5.0}},
    )
    event = await action.wait()

    digit = event.params.get("result", {}).get("digits", "")

    if digit == "1":
        await call.play([{"type": "tts", "params": {"text": "Transferring to sales."}}])
        await call.transfer(dest="+15551234567")
    elif digit == "2":
        await call.play([{"type": "tts", "params": {"text": "Transferring to support."}}])
        await call.transfer(dest="+15559876543")
    else:
        await call.play([{"type": "tts", "params": {"text": "Goodbye."}}])
        await call.hangup()

client.run()
```

## Classes

#### [RelayClient](/docs/server-sdks/reference/python/relay/client)

WebSocket client for connecting, authenticating, dialing calls, and sending messages.

#### [Call](/docs/server-sdks/reference/python/relay/call)

Call object with methods for answer, hangup, play, record, collect, connect, and more.

#### [Message](/docs/server-sdks/reference/python/relay/message)

Message object for tracking SMS/MMS state and waiting for delivery confirmation.

#### [Actions](/docs/server-sdks/reference/python/relay/actions)

Async action handles returned from call control methods like play, record, and detect.

#### [Events](/docs/server-sdks/reference/python/relay/events)

Typed event dataclasses for call state changes, playback, recording, and messaging.

#### [Constants](/docs/server-sdks/reference/python/relay/constants)

Call states, connect states, message states, and event type string constants.

#### [RelayError](/docs/server-sdks/reference/python/relay/relay-error)

Exception raised when the Relay server returns an error response.