> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes. # play > Play audio or text-to-speech on an active call via REST. [play-pause]: /docs/server-sdks/reference/typescript/rest/calling/play-pause [play-resume]: /docs/server-sdks/reference/typescript/rest/calling/play-resume [play-stop]: /docs/server-sdks/reference/typescript/rest/calling/play-stop [play-volume]: /docs/server-sdks/reference/typescript/rest/calling/play-volume 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()`][play-pause], [`playResume()`][play-resume], [`playStop()`][play-stop], and [`playVolume()`][play-volume]. ## **Request** ### Schema (`calling.play`) ```yaml components: schemas: uuid: type: string format: uuid description: Universal Unique Identifier. title: uuid CallingPlayAudioItemType: type: string enum: - audio title: CallingPlayAudioItemType Calling.PlayAudioParams: type: object properties: url: type: string format: uri description: HTTP or HTTPS URL of the audio file to play. required: - url description: Audio file playback parameters. title: Calling.PlayAudioParams Calling.PlayMediaType: type: string enum: - audio - tts - silence - ringtone description: The type of media to play. title: Calling.PlayMediaType Calling.PlayAudioItem: type: object properties: type: $ref: '#/components/schemas/Calling.PlayMediaType' description: The type of media to play. params: $ref: '#/components/schemas/Calling.PlayAudioParams' description: Audio playback parameters. required: - type - params description: Play an audio file from a URL. title: Calling.PlayAudioItem CallingPlayTtsItemType: type: string enum: - tts title: CallingPlayTtsItemType Calling.TtsGender: type: string enum: - male - female description: Text-to-speech voice gender. title: Calling.TtsGender Calling.PlayTtsParams: type: object properties: text: type: string description: The text to speak. language: type: string description: >- BCP-47 language tag. Falls back to the request-level `language`, then `en-US`. gender: $ref: '#/components/schemas/Calling.TtsGender' description: >- Voice gender. Falls back to the request-level `gender`, then `female`. voice: type: string description: >- Specific voice name (provider-dependent, no special characters except `.` and `-`). Falls back to the request-level `voice`, then to `gender`. required: - text description: Text-to-speech playback parameters. title: Calling.PlayTtsParams Calling.PlayTtsItem: type: object properties: type: $ref: '#/components/schemas/Calling.PlayMediaType' description: The type of media to play. params: $ref: '#/components/schemas/Calling.PlayTtsParams' description: TTS parameters. required: - type - params description: >- Play text-to-speech. Per-item `language`/`voice`/`gender` override the request-level fallbacks. title: Calling.PlayTtsItem CallingPlaySilenceItemType: type: string enum: - silence title: CallingPlaySilenceItemType Calling.PlaySilenceParams: type: object properties: duration: type: number format: double description: Duration of silence in seconds (must be positive). required: - duration description: Silence playback parameters. title: Calling.PlaySilenceParams Calling.PlaySilenceItem: type: object properties: type: $ref: '#/components/schemas/Calling.PlayMediaType' description: The type of media to play. params: $ref: '#/components/schemas/Calling.PlaySilenceParams' description: Silence parameters. required: - type - params description: Play silence for a fixed duration. title: Calling.PlaySilenceItem CallingPlayRingtoneItemType: type: string enum: - ringtone title: CallingPlayRingtoneItemType Calling.PlayRingtoneName: type: string enum: - au - be - ca - cn - cy - cz - de - dk - dz - eg - es - fi - fr - hu - il - in - jp - ko - pk - pl - ro - rs - ru - sa - tr - uk - us - at - bg - br - ch - cl - ee - gr - it - lt - mx - my - nl - 'no' - nz - ph - pt - se - sg - th - za - tw - ve - bong description: >- Ringtone name. Two-letter country code selects a country-specific ringtone cadence. title: Calling.PlayRingtoneName Calling.PlayRingtoneParams: type: object properties: name: $ref: '#/components/schemas/Calling.PlayRingtoneName' description: Country code identifying the ringtone cadence. duration: type: number format: double description: >- Maximum ringtone duration in seconds. If omitted, the ringtone plays until stopped. required: - name description: Ringtone playback parameters. title: Calling.PlayRingtoneParams Calling.PlayRingtoneItem: type: object properties: type: $ref: '#/components/schemas/Calling.PlayMediaType' description: The type of media to play. params: $ref: '#/components/schemas/Calling.PlayRingtoneParams' description: Ringtone parameters. required: - type - params description: Play a country-coded ringtone cadence. title: Calling.PlayRingtoneItem CallingCallRequestDiscriminatorMappingCallingPlayParamsPlayItems: oneOf: - $ref: '#/components/schemas/Calling.PlayAudioItem' - $ref: '#/components/schemas/Calling.PlayTtsItem' - $ref: '#/components/schemas/Calling.PlaySilenceItem' - $ref: '#/components/schemas/Calling.PlayRingtoneItem' title: CallingCallRequestDiscriminatorMappingCallingPlayParamsPlayItems Calling.PlayDirection: type: string enum: - listen - speak - both description: The direction of audio playback relative to the call participants. title: Calling.PlayDirection CallingCallRequestDiscriminatorMappingCallingPlayParams: type: object properties: control_id: type: string description: >- Unique identifier for this play operation, used to control it later. Must be unique per active play on this call. play: type: array items: $ref: >- #/components/schemas/CallingCallRequestDiscriminatorMappingCallingPlayParamsPlayItems description: Ordered list of media items to play. Items play sequentially. volume: type: number format: double minimum: -40 maximum: 40 default: 0 description: Volume adjustment in dB. Must be between -40 and 40. direction: $ref: '#/components/schemas/Calling.PlayDirection' default: listen description: The direction of audio playback relative to the call participants. loop: type: integer minimum: 0 default: 1 description: >- Number of times the full `play` sequence is repeated. `0` loops forever; `N > 0` plays a total of N times. language: type: string default: en-US description: >- Default BCP-47 language tag applied to any TTS item that does not set its own `language`. voice: type: string description: >- Default voice applied to any TTS item that does not set its own `voice`. Defaults to the request-level `gender` when unset. gender: $ref: '#/components/schemas/Calling.TtsGender' default: female description: >- Default voice gender applied to any TTS item that does not set its own `gender`. status_url: type: string format: uri description: >- HTTP or HTTPS URL that receives playback lifecycle webhooks (`playing`, `paused`, `finished`, `error`). required: - control_id - play description: An object of parameters that will be utilized by the active command. title: CallingCallRequestDiscriminatorMappingCallingPlayParams Calling.CallPlayRequest: type: object properties: id: $ref: '#/components/schemas/uuid' description: The unique identifying ID of an existing call. params: $ref: >- #/components/schemas/CallingCallRequestDiscriminatorMappingCallingPlayParams description: An object of parameters that will be utilized by the active command. required: - id - params title: Calling.CallPlayRequest ``` ## **Response** ### Schema (`Calling.CallResponse`) ```yaml components: schemas: uuid: type: string format: uuid description: Universal Unique Identifier. title: uuid Calling.CallDirection: type: string enum: - inbound - outbound - outbound-api description: The direction of the call. title: Calling.CallDirection CallingCallLegSource: type: string enum: - realtime_api description: Source of this call. title: CallingCallLegSource Calling.ChargeDetails: type: object properties: description: type: string description: Description for this charge. charge: type: number format: double description: Charged amount. required: - description - charge description: One itemized charge applied to the call. title: Calling.ChargeDetails Calling.CallResponseStatus: type: string enum: - queued - initiated - created - ringing - answered - ending - ended - failed - canceled - completed description: The status of the call throughout its lifecycle. title: Calling.CallResponseStatus CallingCallLegType0: type: string enum: - relay_pstn_call title: CallingCallLegType0 CallingCallLegType1: type: string enum: - relay_sip_call title: CallingCallLegType1 CallingCallLegType2: type: string enum: - relay_webrtc_call title: CallingCallLegType2 CallingCallLegType: oneOf: - $ref: '#/components/schemas/CallingCallLegType0' - $ref: '#/components/schemas/CallingCallLegType1' - $ref: '#/components/schemas/CallingCallLegType2' description: Type of this call. title: CallingCallLegType Calling.CallLeg: type: object properties: id: $ref: '#/components/schemas/uuid' description: >- The unique identifier of the call on SignalWire. This can be used to update the call programmatically. from: type: string description: The origin number or address. to: type: string description: The destination number or address. direction: $ref: '#/components/schemas/Calling.CallDirection' description: The direction of the call. source: $ref: '#/components/schemas/CallingCallLegSource' description: Source of this call. url: type: - string - 'null' description: The URL associated with this call. charge: type: number format: double description: Total charge for this call. created_at: type: string format: date-time description: The date and time when the call was created. charge_details: type: array items: $ref: '#/components/schemas/Calling.ChargeDetails' description: Details on charges associated with this call. status: oneOf: - $ref: '#/components/schemas/Calling.CallResponseStatus' - type: 'null' description: The status of the call. duration: type: - integer - 'null' description: The duration of the call in seconds. duration_ms: type: - integer - 'null' description: The duration of the call in milliseconds. billing_ms: type: - integer - 'null' description: The billable duration of the call in milliseconds. type: $ref: '#/components/schemas/CallingCallLegType' description: Type of this call. parent_id: oneOf: - $ref: '#/components/schemas/uuid' - type: 'null' description: The parent call ID if this is a child call. required: - id - from - to - direction - source - url - charge - created_at - charge_details - status - duration - duration_ms - billing_ms - type - parent_id description: Returned when the call is a standard PSTN, SIP, or WebRTC call. title: Calling.CallLeg CallingFabricDeviceLegSource: type: string enum: - realtime_api description: Source of this call. title: CallingFabricDeviceLegSource CallingFabricDeviceLegType: type: string enum: - fabric_subscriber_device_leg description: Type of this call. title: CallingFabricDeviceLegType Calling.FabricDeviceLeg: type: object properties: id: $ref: '#/components/schemas/uuid' description: >- The unique identifier of the call on SignalWire. This can be used to update the call programmatically. from: type: string description: The origin number or address. to: type: string description: The destination number or address. direction: $ref: '#/components/schemas/Calling.CallDirection' description: The direction of the call. source: $ref: '#/components/schemas/CallingFabricDeviceLegSource' description: Source of this call. url: type: - string - 'null' description: The URL associated with this call. charge: type: number format: double description: Total charge for this call. created_at: type: string format: date-time description: The date and time when the call was created. charge_details: type: array items: $ref: '#/components/schemas/Calling.ChargeDetails' description: Details on charges associated with this call. status: description: >- The status of the call. Always null for Fabric subscriber device legs. type: $ref: '#/components/schemas/CallingFabricDeviceLegType' description: Type of this call. required: - id - from - to - direction - source - url - charge - created_at - charge_details - status - type description: >- Returned when the call is a Fabric subscriber device leg. The `status` field is always null for this type. title: Calling.FabricDeviceLeg Calling.CallResponse: oneOf: - $ref: '#/components/schemas/Calling.CallLeg' - $ref: '#/components/schemas/Calling.FabricDeviceLeg' title: Calling.CallResponse ``` ## **Examples** ### Play TTS ```typescript {9-14} 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 ```typescript {9-11} 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 ```typescript {9} 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 }, ); ``` > Play audio or text-to-speech on an active call via REST.