play | SignalWire

Play audio or text-to-speech on an active call. The response confirms that the command was accepted; playback state arrives asynchronously at status_url.

control_id is a caller-chosen identifier for this operation, unique per active operation of this kind on the call. The TypeScript SDK types it as optional, but the API requires it — a request that omits it is rejected.

Keep it to manage the playback later with playPause(), playResume(), playStop(), and playVolume().

Request

idstringRequiredformat: "uuid"

The unique identifying ID of an existing call.

paramsobjectRequired

An object of parameters that will be utilized by the active command.

Response

Call LegobjectRequired

Returned when the call is a standard PSTN, SIP, or WebRTC call.

Fabric Subscriber Device LegobjectRequired

Returned when the call is a Fabric subscriber device leg. The status field is always null for this type.

Examples

Play TTS

import { RestClient } from "@signalwire/sdk";
const client = new RestClient({
  project: "your-project-id",
  token: "your-api-token",
  host: "your-space.signalwire.com"
});
// Choose a control ID and keep it for later play commands
const controlId = "greeting-1";
await client.calling.play(
  "call-id-xxx",
  [{ type: "tts", params: { text: "Hello from the REST API!" } }],
  { control_id: controlId },
);

Play Audio File

import { RestClient } from "@signalwire/sdk";
const client = new RestClient({
  project: "your-project-id",
  token: "your-api-token",
  host: "your-space.signalwire.com"
});
await client.calling.play("call-id-xxx", [
  { type: "audio", params: { url: "https://example.com/greeting.mp3" } },
], { control_id: "greeting-1" });

Play Multiple Items

import { RestClient } from "@signalwire/sdk";
const client = new RestClient({
  project: "your-project-id",
  token: "your-api-token",
  host: "your-space.signalwire.com"
});
await client.calling.play(
  "call-id-xxx",
  [
    { type: "tts", params: { text: "Please hold while we connect you." } },
    { type: "silence", params: { duration: 1 } },
    { type: "audio", params: { url: "https://example.com/hold-music.mp3" } },
  ],
  { control_id: "hold-sequence-1", loop: 2 },
);