Creating a Play Audio Action
A Play Audio action plays a pre-recorded audio file from your workspace files during an automated voice flow — for example a regulatory disclosure that has to be delivered verbatim, a hold-message, or a voicemail recording dropped on an answering machine.
How it fits together: "Play Audio" is an Action type. You attach it to a workflow task (or a call event) so that when the trigger fires, the assistant plays the audio file instead of speaking text. Pair it with Allow interrupt = off for required disclosures that must be heard end-to-end.
Prerequisites
- A pre-recorded audio file uploaded to your workspace File Browser. Supported formats include 16-bit PCM WAV (mono or stereo), MP3, AAC, M4A, Ogg, Opus, WebM, FLAC, WMA, AMR, CAF and AIFF.
- A workflow with the task that should play the audio (see Workflows), or a phone-call trigger you want to attach the action to.
- A voice-enabled assistant configured for the workflow.
Steps
1. Upload the audio file
Go to File Browser in your workspace and upload the audio file the action will play. Share it, or the folder it is in, with the Members the workflow calls: the call plays the clip with their access (see Notes & limitations).
2. Open the Actions page
Go to Actions in your workspace and click New Action.
3. Configure the trigger
Choose the trigger that should play the clip — typically:
- Task Entered for a clip that plays when the call reaches a specific workflow task (e.g. an opening disclosure on the first task).
- Call Started for a clip that plays whenever a call connects, including when a human answers.
- Execute on a voice Workflow task, for a clip that plays as that task runs. On the Workflow's start task, Execute runs before the call is placed, so it cannot use an answering-machine condition; see the voicemail-only recipe below.
4. Select "Play Audio" as the action type
Pick Play Audio from the action-type dropdown. The Play Audio form appears.
5. Pick the audio clip
Use the file picker to select the audio file you uploaded. The picker lists files whose mime type begins with audio/ (plus .m4a voice-memos). Click the Preview button next to the picker to listen to the clip in the browser before saving.
6. Set the volume
The Volume slider controls server-side gain that's applied as the clip is streamed to the call leg.
- 80% is the unity default — no adjustment, the call hears the file as-recorded.
- Higher values boost the level; lower values attenuate.
- The browser preview tracks the slider for attenuation but caps at unity (it can't boost above the source's natural level). Above-unity gain only takes effect on the live call.
If your recordings are already mastered loud, leave the slider at 80%. If a recording was captured at a low level, raise the slider until the in-browser preview is comfortably audible (it will be slightly louder again on the live call).
7. Allow interrupt
The Allow interrupt switch controls whether the caller can interrupt the clip by speaking.
- On (default) — speaking interrupts the clip and hands the turn back to the assistant. Right for greetings, hold-music, and most narrative content.
- Off — the clip plays end-to-end. Server VAD ignores barge-in, and any final transcript that arrives mid-clip is deferred until playback completes (so something the caller said before the clip began doesn't interrupt the disclosure). Right for regulatory disclosures, recorded notices that must be delivered verbatim, and any clip that has to be heard in full.
8. Hang up after
The Hang up after switch ends the call immediately when the clip finishes — no further AI turns, no follow-up questions.
Pair this with Allow interrupt = off to play a voicemail recording end-to-end and then disconnect. Use the answering-machine condition in the recipe below so the recording only plays after voicemail greeting detection. This action plays audio on an existing call; a Phone Call action initiates the call.
9. Save the action
Click Save. The action is now linked to its trigger and fires whenever the trigger event happens.
Recipes
Mandatory regulatory disclosure on call connect
| Setting | Value |
|---|---|
| Trigger | Call Started |
| Audio clip | disclosure-2026.wav (your recording) |
| Volume | 80% |
| Allow interrupt | Off |
| Hang up after | Off |
Plays the disclosure verbatim the moment the call connects. The caller cannot talk over it; mid-clip transcripts are queued and delivered to the assistant once the disclosure finishes.
Voicemail Drop with Hang-Up
-
Upload the recording to File Browser as described above.
-
Turn on voicemail detection for the Workflow that places the calls: in its voice settings, set Voicemail detection to On, then publish the Workflow: calls use its published revision, not the draft. Detection adds 3–5 seconds before a person who answers hears the call, so leave Phone numbers → Defaults → Enable Voicemail Detection off unless every Workflow left on Inherit workspace setting should wait too. Detection applies to every outbound call an Agent handles, whether a Workflow places it or someone starts it from Create chat with AI as the caller. A Direct call you make yourself is not affected.
-
Create a Play Audio action on the Call Started trigger (
call:started). Add this CEL condition:call.answered_by != null && call.answered_by.startsWith("machine_end_")Use Call Started, not the start task's Execute event: Execute on the start task runs when the chat is created, before the call is placed and before voicemail detection has a result, so this condition can never match there. A Call Started action applies to every call in the workspace; the condition is what limits it to a detected voicemail.
The available variables depend on the Action event context; see the Developer CEL reference.
In the Actions view, open Conditions when you create the Action, or the Conditions tab when you edit it.
-
Configure the playback:
Setting Value Audio clip Your uploaded recording Volume 80% to start Allow interrupt Off Hang up after On -
Save the action and condition. Run the intended outbound Phone Call trigger for a test Member whose phone you control. Let voicemail answer and confirm the recording plays after the greeting and the call ends. Repeat with a human answer: this rule should be skipped and the normal voice Workflow should continue.
Without the condition, the action would also play the recording and hang up
on humans. The condition limits playback to a detected voicemail greeting
ending; human, fax, and unknown do not match. With voicemail detection
on, a detected voicemail's call connects only once the greeting has ended, so
the recording starts after it. With detection off, call.answered_by
stays empty, so this condition never matches and the recording does not play;
an action without the condition plays as soon as the call is answered, over
any voicemail greeting. See
Voicemail Detection
for the possible results.
Hold music while a tool runs
| Setting | Value |
|---|---|
| Trigger | Task Entered (a "lookup pending" task) |
| Audio clip | short-hold.wav |
| Volume | 70% (slightly attenuated below speech) |
| Allow interrupt | On |
| Hang up after | Off |
Lets the caller barge in to ask a follow-up question. The assistant resumes the conversation as soon as the lookup completes.
Notes & limitations
- Audio clips are workspace files, not member-specific recordings. If you need a per-member dynamic message (e.g. "Hi {{member.first_name}}…"), use Assistant Message with text instead — the assistant will TTS the message on the fly.
- The clip's persisted message appears in the chat transcript as an audio bubble with a play button, so reviewers can hear exactly what was delivered. The bubble shows
plays end-to-end/then hangs upannotations when those switches were set. - Replay in the web voice console plays the persisted clip (not a fresh TTS), so what you hear during replay is what the caller heard.
- The clip plays with the access of the Member the call is for. If that Member cannot open the File, nothing plays. Share the File, or the folder it is in, with the Members the workflow calls.
- When a call could not play the clip, Configuration health lists the action with the reason: "the Member the call was for cannot open its File" (share it as above), or "its File no longer exists or has no playable audio" (choose another supported recording). The error clears the next time the action runs; a call that still cannot play the clip reports it again.