RELAYCall

play_and_collect

View as MarkdownOpen in Claude

Play audio content as a prompt and simultaneously collect user input via DTMF digits or speech recognition. Returns a CollectAction that resolves when input is collected, the operation times out, or an error occurs.

The CollectAction resolves only on collect events, not on play events. This means await action.wait() blocks until the user provides input (or the operation terminates), not when the audio finishes playing.

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

Parameters

media
list[dict]Required

List of media items to play as the prompt. Same format as play() media items.

collect
dictRequired

Input collection configuration.

collect.digits
dict

DTMF digit collection settings.

collect.digits.max
int

Maximum number of digits to collect.

collect.digits.digit_timeout
float

Seconds to wait between digits before completing.

collect.digits.terminators
str

Characters that terminate digit collection (e.g., "#").

collect.speech
dict

Speech recognition settings.

collect.speech.end_silence_timeout
float

Seconds of silence to wait before finalizing speech input.

collect.speech.speech_timeout
float

Maximum seconds to listen for speech.

collect.speech.language
str

Speech recognition language code (e.g., "en-US").

collect.speech.hints
list[str]

Words or phrases to boost recognition accuracy.

volume
Optional[float]

Volume adjustment in dB for the prompt audio.

control_id
Optional[str]

Custom control ID. Auto-generated if not provided.

on_completed
Optional[Callable[[RelayEvent], Any]]

Callback invoked when collection completes.

Returns

CollectAction — An action handle with stop(), volume(), start_input_timers(), and wait() methods.

Example

1from signalwire.relay import RelayClient
2
3client = RelayClient(
4    project="your-project-id",
5    token="your-api-token",
6    host="your-space.signalwire.com",
7    contexts=["default"],
8)
9
10@client.on_call
11async def handle_call(call):
12    await call.answer()
13
14    action = await call.play_and_collect(
15        media=[{"type": "tts", "text": "Press 1 for sales, 2 for support."}],
16        collect={
17            "digits": {"max": 1, "digit_timeout": 5, "terminators": "#"},
18        },
19    )
20    event = await action.wait()
21
22    result = event.params.get("result", {})
23    digits = result.get("digits", "")
24    if digits == "1":
25        await call.transfer("sales")
26    elif digits == "2":
27        await call.transfer("support")
28    else:
29        await call.hangup()
30
31client.run()