RELAYCall

playAndCollect

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
Record<string, unknown>[]Required

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

collect
Record<string, unknown>Required

Input collection configuration.

collect.digits
Record<string, unknown>

DTMF digit collection settings.

collect.digits.max
number

Maximum number of digits to collect.

collect.digits.digit_timeout
number

Seconds to wait between digits before completing.

collect.digits.terminators
string

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

collect.speech
Record<string, unknown>

Speech recognition settings.

collect.speech.end_silence_timeout
number

Seconds of silence to wait before finalizing speech input.

collect.speech.speech_timeout
number

Maximum seconds to listen for speech.

collect.speech.language
string

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

collect.speech.hints
string[]

Words or phrases to boost recognition accuracy.

volume
number | undefined

Volume adjustment in dB for the prompt audio.

controlId
string | undefined

Custom control ID. Auto-generated if not provided.

onCompleted
(event: RelayEvent) => void | Promise<void>

Callback invoked when collection completes.

Returns

Promise<CollectAction> — An action handle with stop(), volume(), startInputTimers(), and wait() methods.

Example

1import { RelayClient } from '@signalwire/sdk';
2
3const client = new RelayClient({
4  project: process.env.SIGNALWIRE_PROJECT_ID!,
5  token: process.env.SIGNALWIRE_TOKEN!,
6  contexts: ['default']
7});
8
9client.onCall(async (call) => {
10  await call.answer();
11
12  const action = await call.playAndCollect(
13    [{ type: 'tts', text: 'Press 1 for sales, 2 for support.' }],
14    { digits: { max: 1, digit_timeout: 5, terminators: '#' } }
15  );
16  const event = await action.wait();
17
18  const result = event.params.result as Record<string, unknown> ?? {};
19  const digits = (result.digits ?? '') as string;
20  if (digits === '1') {
21    await call.transfer('sales');
22  } else if (digits === '2') {
23    await call.transfer('support');
24  } else {
25    await call.hangup();
26  }
27});
28
29await client.run();