> 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.

# Call

> Live call control object with media, AI, and event methods.

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

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

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

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

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

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

[waitforended]: /docs/server-sdks/reference/python/relay/call/wait-for-ended

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

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

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

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

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

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

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

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

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

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

[playandcollect]: /docs/server-sdks/reference/python/relay/call/play-and-collect

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

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

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

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

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

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

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

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

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

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

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

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

[cleardigitbindings]: /docs/server-sdks/reference/python/relay/call/clear-digit-bindings

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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`][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`][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](/docs/server-sdks/reference/python/relay/call/on)

Register an event listener on a call.

#### [wait\_for](/docs/server-sdks/reference/python/relay/call/wait-for)

Wait for a specific event on a call.

#### [wait\_for\_ringing](/docs/server-sdks/reference/python/relay/call/wait-for-ringing)

Wait until the call is ringing.

#### [wait\_for\_answered](/docs/server-sdks/reference/python/relay/call/wait-for-answered)

Wait until the call is answered.

#### [wait\_for\_ending](/docs/server-sdks/reference/python/relay/call/wait-for-ending)

Wait until the call is ending.

#### [wait\_for\_ended](/docs/server-sdks/reference/python/relay/call/wait-for-ended)

Wait for a call to reach the ended state.

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

Answer an inbound Relay call.

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

End a Relay call.

#### [pass\_](/docs/server-sdks/reference/python/relay/call/pass)

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

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

Disconnect (unbridge) a connected call.

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

Transfer call control to another Relay application or SWML script.

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

Bridge a call to one or more destinations.

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

Put a call on hold.

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

Resume a held call.

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

Play audio content on a call.

#### [play\_tts](/docs/server-sdks/reference/python/relay/call/play-tts)

Play text-to-speech.

#### [play\_audio](/docs/server-sdks/reference/python/relay/call/play-audio)

Play an audio file from a URL.

#### [play\_silence](/docs/server-sdks/reference/python/relay/call/play-silence)

Play silence for a number of seconds.

#### [play\_ringtone](/docs/server-sdks/reference/python/relay/call/play-ringtone)

Play a named ringtone.

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

Record audio from a call.

#### [play\_and\_collect](/docs/server-sdks/reference/python/relay/call/play-and-collect)

Play audio and collect DTMF or speech input.

#### [prompt\_tts](/docs/server-sdks/reference/python/relay/call/prompt-tts)

Play text-to-speech, then collect input.

#### [prompt\_audio](/docs/server-sdks/reference/python/relay/call/prompt-audio)

Play an audio file, then collect input.

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

Collect DTMF or speech input without playing media.

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

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

#### [detect\_digit](/docs/server-sdks/reference/python/relay/call/detect-digit)

Detect DTMF digits.

#### [detect\_answering\_machine](/docs/server-sdks/reference/python/relay/call/detect-answering-machine)

Detect a human versus an answering machine.

#### [detect\_fax](/docs/server-sdks/reference/python/relay/call/detect-fax)

Detect a fax tone.

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

Start an AI agent session on a call.

#### [amazon\_bedrock](/docs/server-sdks/reference/python/relay/call/amazon-bedrock)

Connect a call to an Amazon Bedrock AI agent.

#### [ai\_hold](/docs/server-sdks/reference/python/relay/call/ai-hold)

Put an AI agent session on hold.

#### [ai\_unhold](/docs/server-sdks/reference/python/relay/call/ai-unhold)

Resume an AI agent session from hold.

#### [ai\_message](/docs/server-sdks/reference/python/relay/call/ai-message)

Send a message to an active AI agent session.

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

Start noise reduction on a call.

#### [denoise\_stop](/docs/server-sdks/reference/python/relay/call/denoise-stop)

Stop noise reduction on a call.

#### [send\_digits](/docs/server-sdks/reference/python/relay/call/send-digits)

Send DTMF digits on a call.

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

Echo call audio back to the caller for testing.

#### [bind\_digit](/docs/server-sdks/reference/python/relay/call/bind-digit)

Bind a DTMF digit sequence to trigger a Relay method.

#### [clear\_digit\_bindings](/docs/server-sdks/reference/python/relay/call/clear-digit-bindings)

Clear DTMF digit bindings on a call.

#### [user\_event](/docs/server-sdks/reference/python/relay/call/user-event)

Send a custom user-defined event on a call.

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

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

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

Intercept call media and stream it to an external destination.

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

Stream call audio to a WebSocket endpoint.

#### [send\_fax](/docs/server-sdks/reference/python/relay/call/send-fax)

Send a fax document on a call.

#### [receive\_fax](/docs/server-sdks/reference/python/relay/call/receive-fax)

Receive a fax on a call.

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

Collect payment information on a call.

#### [live\_transcribe](/docs/server-sdks/reference/python/relay/call/live-transcribe)

Start or stop live transcription on a call.

#### [live\_translate](/docs/server-sdks/reference/python/relay/call/live-translate)

Start or stop live translation on a call.

#### [join\_conference](/docs/server-sdks/reference/python/relay/call/join-conference)

Join an ad-hoc audio conference.

#### [leave\_conference](/docs/server-sdks/reference/python/relay/call/leave-conference)

Leave an audio conference.

#### [join\_room](/docs/server-sdks/reference/python/relay/call/join-room)

Join a video/audio room.

#### [leave\_room](/docs/server-sdks/reference/python/relay/call/leave-room)

Leave a video/audio room.

#### [queue\_enter](/docs/server-sdks/reference/python/relay/call/queue-enter)

Place a call into a named queue.

#### [queue\_leave](/docs/server-sdks/reference/python/relay/call/queue-leave)

Remove a call from a queue.

## **Example**

```python {16}
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()`][call-on] to react
to state changes, errors, and operation completions.

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

> Live call control object with media, AI, and event methods.

## Docs

- [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.