join_conference

Join an ad-hoc audio conference. The conference is created automatically if it does not already exist. Multiple calls can join the same conference by name.

Use leave_conference() to remove the call from the conference.

This method emits calling.conference events. See Call Events for payload details.

Parameters

name

strRequired

Conference name. All calls joining the same name are in the same conference.

muted

bool | NoneDefaults to None

Join the conference muted.

beep

str | NoneDefaults to None

Play a beep when joining or leaving.

"true" — beep on both enter and exit
"false" — no beep
"onEnter" — beep only when a participant joins
"onExit" — beep only when a participant leaves

start_on_enter

bool | NoneDefaults to None

Start the conference when this participant enters. If False, the conference waits until a participant with start_on_enter=True joins.

end_on_exit

bool | NoneDefaults to None

End the conference when this participant leaves.

wait_url

str | NoneDefaults to None

URL of audio to play while waiting for the conference to start.

max_participants

int | NoneDefaults to None

Maximum number of participants in the conference.

record

str | NoneDefaults to None

Recording mode.

"record-from-start" — begin recording when the conference starts
"do-not-record" — do not record the conference

region

str | NoneDefaults to None

Region for the conference media server.

trim

str | NoneDefaults to None

Whether to trim silence from the conference recording.

coach

str | NoneDefaults to None

Call ID of a participant who can hear but not be heard (coaching mode).

status_callback

str | NoneDefaults to None

URL to receive conference status webhooks.

status_callback_event

str | NoneDefaults to None

Events that trigger status callbacks.

status_callback_event_type

str | NoneDefaults to None

Content type for status callback requests.

status_callback_method

str | NoneDefaults to None

HTTP method for status callbacks (e.g., "POST", "GET").

recording_status_callback

str | NoneDefaults to None

URL to receive recording status webhooks.

recording_status_callback_event

str | NoneDefaults to None

Events that trigger recording status callbacks.

recording_status_callback_event_type

str | NoneDefaults to None

Content type for recording status callback requests.

recording_status_callback_method

str | NoneDefaults to None

HTTP method for recording status callbacks.

stream_obj

dict | NoneDefaults to None

Attach a bidirectional WebSocket stream to the conference audio, enabling real-time audio processing, transcription, or AI agents that listen to the conference. Uses the same stream schema as the stream device type in connect.

stream_obj.url

strRequired

Secure WebSocket URL (wss://) to stream the conference audio to. Plain ws:// is not supported.

stream_obj.name

str | NoneDefaults to None

A friendly name to identify the stream at the WebSocket endpoint.

stream_obj.codec

str | NoneDefaults to None

Audio codec for the streamed audio (e.g., "PCMU", "PCMA", "G722", "L16").

stream_obj.status_url

str | NoneDefaults to None

HTTP or HTTPS URL to receive stream status webhooks.

stream_obj.status_url_method

str | NoneDefaults to POST

HTTP method for the status webhook ("GET" or "POST").

stream_obj.realtime

bool | NoneDefaults to None

When True, enables bidirectional audio so your endpoint can stream audio back into the conference (not just receive it).

stream_obj.authorization_bearer_token

str | NoneDefaults to None

Bearer token sent in the Authorization header when the WebSocket connection is opened, so your endpoint can authenticate the request.

stream_obj.custom_parameters

dict | NoneDefaults to None

Custom key-value pairs delivered to your WebSocket endpoint when the stream connects. Use them to pass context such as a session or customer ID.

Returns

dict — Server response confirming the join.

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()
    await call.play([{"type": "tts", "params": {"text": "Joining the team conference."}}])
    # Join a conference and attach a bidirectional WebSocket stream
    await call.join_conference(
        "team-standup",
        beep="onEnter",
        start_on_enter=True,
        stream_obj={
            "url": "wss://example.com/conference-audio",
            "codec": "PCMU",
            "realtime": True,
            "status_url": "https://example.com/stream-status",
        },
    )
    # The call is now in the conference until it leaves or the call ends
client.run()