***

title: Call
slug: /reference/python/relay/call
description: Live call control object with media, AI, and event methods.
max-toc-depth: 3
---------------------

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

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

<ParamField path="call_id" type="str" toc={true}>
  Unique identifier for this call, assigned by SignalWire.
</ParamField>

<ParamField path="node_id" type="str" toc={true}>
  Identifier of the RELAY node handling this call.
</ParamField>

<ParamField path="project_id" type="str" toc={true}>
  SignalWire project ID that owns this call.
</ParamField>

<ParamField path="context" type="str" toc={true}>
  The context (routing label) the call is associated with.
</ParamField>

<ParamField path="tag" type="str" toc={true}>
  Correlation tag for tracking related calls. Empty string if not set.
</ParamField>

<ParamField path="direction" type="str" toc={true}>
  Call direction. Valid values:

  * `"inbound"` -- incoming call
  * `"outbound"` -- outgoing call
</ParamField>

<ParamField path="device" type="dict" toc={true}>
  Device information for the call endpoint. Contains `type` (e.g., `"phone"`) and
  `params` (e.g., `{"from_number": "+1...", "to_number": "+1..."}`).
</ParamField>

<ParamField path="state" type="str" toc={true}>
  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
</ParamField>

<ParamField path="segment_id" type="str" toc={true}>
  Call segment identifier for tracking call legs.
</ParamField>

## **Methods**

<CardGroup cols={3}>
  <Card title="on" href="/docs/server-sdks/reference/python/relay/call/on">
    Register an event listener on a call.
  </Card>

  <Card title="wait_for" href="/docs/server-sdks/reference/python/relay/call/wait-for">
    Wait for a specific event on a call.
  </Card>

  <Card title="wait_for_ended" href="/docs/server-sdks/reference/python/relay/call/wait-for-ended">
    Wait for a call to reach the ended state.
  </Card>

  <Card title="answer" href="/docs/server-sdks/reference/python/relay/call/answer">
    Answer an inbound RELAY call.
  </Card>

  <Card title="hangup" href="/docs/server-sdks/reference/python/relay/call/hangup">
    End a RELAY call.
  </Card>

  <Card title="pass_" href="/docs/server-sdks/reference/python/relay/call/pass">
    Decline control of an inbound call and return it to routing.
  </Card>

  <Card title="disconnect" href="/docs/server-sdks/reference/python/relay/call/disconnect">
    Disconnect (unbridge) a connected call.
  </Card>

  <Card title="transfer" href="/docs/server-sdks/reference/python/relay/call/transfer">
    Transfer call control to another RELAY application or SWML script.
  </Card>

  <Card title="connect" href="/docs/server-sdks/reference/python/relay/call/connect">
    Bridge a call to one or more destinations.
  </Card>

  <Card title="hold" href="/docs/server-sdks/reference/python/relay/call/hold">
    Put a call on hold.
  </Card>

  <Card title="unhold" href="/docs/server-sdks/reference/python/relay/call/unhold">
    Resume a held call.
  </Card>

  <Card title="play" href="/docs/server-sdks/reference/python/relay/call/play">
    Play audio content on a call.
  </Card>

  <Card title="record" href="/docs/server-sdks/reference/python/relay/call/record">
    Record audio from a call.
  </Card>

  <Card title="play_and_collect" href="/docs/server-sdks/reference/python/relay/call/play-and-collect">
    Play audio and collect DTMF or speech input.
  </Card>

  <Card title="collect" href="/docs/server-sdks/reference/python/relay/call/collect">
    Collect DTMF or speech input without playing media.
  </Card>

  <Card title="detect" href="/docs/server-sdks/reference/python/relay/call/detect">
    Detect answering machines, fax tones, or digits on a call.
  </Card>

  <Card title="ai" href="/docs/server-sdks/reference/python/relay/call/ai">
    Start an AI agent session on a call.
  </Card>

  <Card title="amazon_bedrock" href="/docs/server-sdks/reference/python/relay/call/amazon-bedrock">
    Connect a call to an Amazon Bedrock AI agent.
  </Card>

  <Card title="ai_hold" href="/docs/server-sdks/reference/python/relay/call/ai-hold">
    Put an AI agent session on hold.
  </Card>

  <Card title="ai_unhold" href="/docs/server-sdks/reference/python/relay/call/ai-unhold">
    Resume an AI agent session from hold.
  </Card>

  <Card title="ai_message" href="/docs/server-sdks/reference/python/relay/call/ai-message">
    Send a message to an active AI agent session.
  </Card>

  <Card title="denoise" href="/docs/server-sdks/reference/python/relay/call/denoise">
    Start noise reduction on a call.
  </Card>

  <Card title="denoise_stop" href="/docs/server-sdks/reference/python/relay/call/denoise-stop">
    Stop noise reduction on a call.
  </Card>

  <Card title="send_digits" href="/docs/server-sdks/reference/python/relay/call/send-digits">
    Send DTMF digits on a call.
  </Card>

  <Card title="echo" href="/docs/server-sdks/reference/python/relay/call/echo">
    Echo call audio back to the caller for testing.
  </Card>

  <Card title="bind_digit" href="/docs/server-sdks/reference/python/relay/call/bind-digit">
    Bind a DTMF digit sequence to trigger a RELAY method.
  </Card>

  <Card title="clear_digit_bindings" href="/docs/server-sdks/reference/python/relay/call/clear-digit-bindings">
    Clear DTMF digit bindings on a call.
  </Card>

  <Card title="user_event" href="/docs/server-sdks/reference/python/relay/call/user-event">
    Send a custom user-defined event on a call.
  </Card>

  <Card title="refer" href="/docs/server-sdks/reference/python/relay/call/refer">
    Transfer a SIP call to an external endpoint via SIP REFER.
  </Card>

  <Card title="tap" href="/docs/server-sdks/reference/python/relay/call/tap">
    Intercept call media and stream it to an external destination.
  </Card>

  <Card title="stream" href="/docs/server-sdks/reference/python/relay/call/stream">
    Stream call audio to a WebSocket endpoint.
  </Card>

  <Card title="send_fax" href="/docs/server-sdks/reference/python/relay/call/send-fax">
    Send a fax document on a call.
  </Card>

  <Card title="receive_fax" href="/docs/server-sdks/reference/python/relay/call/receive-fax">
    Receive a fax on a call.
  </Card>

  <Card title="pay" href="/docs/server-sdks/reference/python/relay/call/pay">
    Collect payment information on a call.
  </Card>

  <Card title="transcribe" href="/docs/server-sdks/reference/python/relay/call/transcribe">
    Start transcribing call audio.
  </Card>

  <Card title="live_transcribe" href="/docs/server-sdks/reference/python/relay/call/live-transcribe">
    Start or stop live transcription on a call.
  </Card>

  <Card title="live_translate" href="/docs/server-sdks/reference/python/relay/call/live-translate">
    Start or stop live translation on a call.
  </Card>

  <Card title="join_conference" href="/docs/server-sdks/reference/python/relay/call/join-conference">
    Join an ad-hoc audio conference.
  </Card>

  <Card title="leave_conference" href="/docs/server-sdks/reference/python/relay/call/leave-conference">
    Leave an audio conference.
  </Card>

  <Card title="join_room" href="/docs/server-sdks/reference/python/relay/call/join-room">
    Join a video/audio room.
  </Card>

  <Card title="leave_room" href="/docs/server-sdks/reference/python/relay/call/leave-room">
    Leave a video/audio room.
  </Card>

  <Card title="queue_enter" href="/docs/server-sdks/reference/python/relay/call/queue-enter">
    Place a call into a named queue.
  </Card>

  <Card title="queue_leave" href="/docs/server-sdks/reference/python/relay/call/queue-leave">
    Remove a call from a queue.
  </Card>
</CardGroup>

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