RELAYCall

play

View as MarkdownOpen in Claude

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

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

Audio File with Loop

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  // 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
20await client.run();

Multiple Media Items

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  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
19await client.run();