playAndCollect

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

1 import { RelayClient } from '@signalwire/sdk';
2 
3 const client = new RelayClient({
4   project: process.env.SIGNALWIRE_PROJECT_ID!,
5   token: process.env.SIGNALWIRE_API_TOKEN!,
6   contexts: ['default']
7 });
8 
9 client.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 
29 await client.run();

1	import { RelayClient } from '@signalwire/sdk';
2
3	const client = new RelayClient({
4	project: process.env.SIGNALWIRE_PROJECT_ID!,
5	token: process.env.SIGNALWIRE_API_TOKEN!,
6	contexts: ['default']
7	});
8
9	client.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
29	await client.run();