play

Play audio content on the call. Supports TTS (text-to-speech), audio file URLs, silence, and ringtone. Returns a PlayAction that you can use to pause, resume, stop, adjust volume, or wait for completion.

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

This method corresponds to the SWML play verb. See the SWML play reference for the full specification.

Parameters

media

Record<string, unknown>[]Required

Array of media items to play. Each item is an object with a type key and type-specific fields:

{ type: 'tts', text: 'Hello', language: 'en-US', gender: 'female' } — text-to-speech
{ type: 'audio', url: 'https://example.com/audio.mp3' } — audio file URL
{ type: 'silence', duration: 2 } — silence for a duration in seconds
{ type: 'ringtone', name: 'us' } — play a standard ringtone

volume

number | undefined

Volume adjustment in dB, from -40.0 to 40.0.

direction

string | undefined

Audio direction. Valid values:

"listen" — play to the caller only
"speak" — play to the remote party only
"both" — play to both sides

loop

number | undefined

Number of times to repeat the media. 0 loops indefinitely.

controlId

string | undefined

Custom control ID for this operation. Auto-generated if not provided.

onCompleted

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

Callback invoked when playback reaches a terminal state. Can be a regular function or async function.

Returns

Promise<PlayAction> — An action handle with stop(), pause(), resume(), volume(), and wait() methods.

Examples

Text-to-Speech

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   const action = await call.play([{ type: 'tts', text: 'Welcome to SignalWire!' }]);
12   await action.wait();
13 });
14 
15 await client.run();

Audio File with Loop

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   // Play hold music on loop
12   const action = await call.play(
13     [{ type: 'audio', url: 'https://example.com/hold-music.mp3' }],
14     { loop: 0, direction: 'listen' }
15   );
16   // Later, stop the music
17   await action.stop();
18 });
19 
20 await client.run();

Multiple Media Items

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   const action = await call.play([
12     { type: 'tts', text: 'Please hold while we connect you.' },
13     { type: 'silence', duration: 1 },
14     { type: 'audio', url: 'https://example.com/hold-music.mp3' },
15   ]);
16   await action.wait();
17 });
18 
19 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	const action = await call.play([{ type: 'tts', text: 'Welcome to SignalWire!' }]);
12	await action.wait();
13	});
14
15	await client.run();