> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

# 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**

Unique identifier for this call, assigned by SignalWire.

Identifier of the RELAY node handling this call.

SignalWire project ID that owns this call.

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

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

Call direction. Valid values:

* `"inbound"` -- incoming call
* `"outbound"` -- outgoing call

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

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

Call segment identifier for tracking call legs.

## **Methods**

Register an event listener on a call.

Wait for a specific event on a call.

Wait for a call to reach the ended state.

Answer an inbound RELAY call.

End a RELAY call.

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

Disconnect (unbridge) a connected call.

Transfer call control to another RELAY application or SWML script.

Bridge a call to one or more destinations.

Put a call on hold.

Resume a held call.

Play audio content on a call.

Record audio from a call.

Play audio and collect DTMF or speech input.

Collect DTMF or speech input without playing media.

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

Start an AI agent session on a call.

Connect a call to an Amazon Bedrock AI agent.

Put an AI agent session on hold.

Resume an AI agent session from hold.

Send a message to an active AI agent session.

Start noise reduction on a call.

Stop noise reduction on a call.

Send DTMF digits on a call.

Echo call audio back to the caller for testing.

Bind a DTMF digit sequence to trigger a RELAY method.

Clear DTMF digit bindings on a call.

Send a custom user-defined event on a call.

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

Intercept call media and stream it to an external destination.

Stream call audio to a WebSocket endpoint.

Send a fax document on a call.

Receive a fax on a call.

Collect payment information on a call.

Start or stop live transcription on a call.

Start or stop live translation on a call.

Join an ad-hoc audio conference.

Leave an audio conference.

Join a video/audio room.

Leave a video/audio room.

Place a call into a named queue.

Remove a call from a queue.

## **Example**

```python {17}
from signalwire.relay import RelayClient

client = RelayClient(
    project="your-project-id",
    token="your-api-token",
    host="your-space.signalwire.com",
    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", "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.