Skip to main content

​
Run a voice broadcast end to end

This guide walks the full voice-broadcast workflow an operator runs in the dashboard, from picking the audience to reading settled-cost and attribution reports. The broadcast composer lives under Outbound → Voice Broadcasts; everything it creates is a standard campaign (channel: "voice"), so the endpoints and reports below are the same ones the campaigns API exposes. Use this page for the one-shot “call these contacts, play them a message” use case. For multi-step, multi-channel campaigns see the campaign end-to-end guide; for predictive/power dialing into live agents see the outbound dialer campaign guide.

​
1. Prerequisites

  • An active voice-capable DID. The Number recipients see picker defaults to the first dialable number on the account. A number still in carrier compliance (pending_compliance) shows in the picker but cannot be selected — a broadcast pointed at one returns INVALID_FROM_NUMBER at dispatch. Buy or port DIDs in Numbers before you start.
  • An audience with reachable numbers. A contact list, live segment, or “all eligible voice-reachable contacts.” Audiences must come from opted-in recipients; suppression and opt-out handling is enforced at send time.

​
2. Pick the audience

Open Outbound → Voice Broadcasts and pick the audience source in the Recipients control: all voice-reachable contacts, a specific list, or a specific segment. Build and manage those sources under Outbound → Audiences before you open the composer. The composer runs the same suppression-, opt-out-, and reachability-aware audience preview the full campaign wizard uses (POST /campaigns/audience/preview with channel: "voice"). It shows the resolved source, the eligible recipient count, and the excluded cohorts:
  • no valid phone number,
  • opted out of calls,
  • suppressed on the do-not-call list, or unreachable.
If eligible recipients come back zero, fix the audience before writing any script — a broadcast with no eligible recipients does not call anyone.

​
3. Craft the message — TTS, recorded audio, or a voice clone

The composer offers three audio-source choices: Text to speech. Type the spoken script in the composer. {{first_name}}, {{last_name}}, and other contact tokens resolve per recipient. The TTS voice picker ships a curated set of stock voices (Rachel, Adam, Bella, Antoni) plus a platform default, and a language picker (en, en-US, en-GB, es, es-ES, fr, de, it, pt-BR, tr, ar). Recorded audio. Upload an MP3, WAV, or M4A clip up to 25 MB. The clip is uploaded to the voice asset store (POST /voice/assets) and the resulting voice-gateway-resolvable handle plays at dispatch — previewing it locally never queues a send. Voice clone. To speak the script in a cloned voice, run the same voice-clone workflow used anywhere else in the platform: create the clone in Voice → Voice Clones (requires a signed consent and a short sample script), then pick the clone’s id from the TTS voice picker. The create a voice clone guide covers the consent and quality checks; the broadcast composer only references the clone id.

​
Sample TTS script

This script is compliant out of the box: it identifies the business (Acme Dental), identifies itself as a voice message, and contains opt-out wording. When a recipient presses 2, the recording-consent disclosure plays before the call connects to the front desk. To route keypresses into a full IVR tree instead of a fixed transfer, the IVR intents reference maps each digit to a flow branch.

​
Voicemail-drop variant

When the answering-machine detector tags a call, a campaign can carry a second script the TTS engine plays as a shorter voicemail drop. The campaign already handles AMD policy at the trunk level; the variant script is what plays once the mailbox answers. Keep it under 20 seconds and leave a callback number, for example:
For sales or collections scripts, replace the direct-transfer ending with a pay link so an agent is optional: the recipient gets a static URL to finish the transaction online instead of dialing back. The outbound dialer campaign guide covers full guided-dialog parity; the lightweight fallback here is a static link pasted into the script body:
Whatever the variant, press Generate preview in the composer. It renders the script through the same TTS engine the broadcast dispatch path uses, so what you hear in the preview is what recipients will hear — pronunciation, voice, and language included. The preview flags stale when you edit the script or change voice/language. When A/B testing is on (the composer’s A/B step), Variant B needs the same listen-back before you commit it.

​
4. Cadence, quiet hours, and TCPA review

The Schedule step captures a wall-clock time converted to UTC in the workspace timezone (Settings → General). Every recipient still only receives a call inside 09:00–18:00 in their own local timezone unless you flip the business-hours switch off — the TCPA federal dialing window applies regardless of that switch. Review the federal guard first: the platform can never relax it, and any launch that comes back 422 TCPA_FEDERAL_DIALING_WINDOW_BLOCKED is a schedule fix, not a config fix. The TCPA federal voice guard concept explains exactly what stops and when. Cadence controls beyond the federal window are workspace-level:
  • Quiet hours define the per-recipient dialing window the composer preview verifies against. Configure them alongside the do-not-call list on the tenant-owned compliance side. The consent and suppression model concept covers how per-channel opt-outs land.
  • Frequency caps on the workspace side bound how often the same contact receives any outbound send.
  • Pacing is enforced by the execution worker and matches the throttle the full campaign wizard would apply.
Verify the per-number compliance posture before you launch:
  • Tenant-owned DNC. The broadcast composer already excludes tenant-suppressed and opted-out recipients from the eligible count — verify the do-not-call source under Outbound → Audiences and the DNC preflight scrub guide before the first send of the day.
  • Recording-consent posture. Every voice broadcast saves with an explicit recording-consent acknowledgement the create-campaign endpoint enforces unconditionally. If you record calls, still verify the number’s recording-consent posture in the workspace settings; the gate is acknowledgement, not a substitute for line-level consent.

​
5. Cost preview

Before launch, read the estimated cost against the voice-cost rollup — the same server-side aggregate the campaign page calculates from (GET /campaigns/:id/voice-cost-rollup). On a draft campaign it returns the projected per-minute pricing; on a settled one it returns the actual roll-up. The cost intelligence guide shows the rollup in the broader campaign-economics context, including the fields the rollup emits. Check the returned sufficiency fields against the wallet before you send; a broadcast launch blocked on funds returns 402.

​
6. Approvals gates

Voice broadcasts are campaigns, so they pass through the workspace approvals queue like any other channel. When the org requires supervisor sign-off, the launch returns a pending-approval state instead of sending; approvers clear the queue in Outbound → Approvals. The outbound goals, approvals, and direct send guide covers the queue mechanics, and the campaign end-to-end guide covers the same gate from the API side (GET /campaigns/approvals/pending).

​
7. Launch and monitor on the wallboard

Press Create broadcast. The composer creates the campaign, stamps ab_test_enabled if you configured variants, forwards the caller ID, TTS voice, language, and business-hours flag, and routes you to the campaign detail page. From there:
  • The wallboard shows the in-flight broadcast next to every other live campaign — per-script answer rates, still-queuing vs. completed, and the A/B winner-selection rule once the test resolves (each variant needs at least 30 answered calls, the 24-hour evaluation window must elapse, and the winner leads by at least 10% or clears the platform’s confidence threshold; you can override the winner any time from the campaign page). The wallboard alarm rules guide covers threshold alerts for the same surface.
  • The campaign page’s stats endpoints (GET /campaigns/:id/stats) return the voice cohorts — answered, failed, and the delivered-count answer rate the A/B test is scored against. The execution worker retries retryable failures until the policy exhausts them.
Pause, resume, or cancel from the campaign page if exclusions or the script need to change mid-flight.

​
8. Post-settle cost and ROAS attribution

Once the broadcast completes, reconcile spend and attributed revenue:
  • GET /campaigns/:id/voice-cost-rollup — settled per-minute cost for the voice cohort.
  • GET /campaigns/:id/cost and GET /campaigns/:id/export — wallet reconciliation and raw rows.
  • GET /campaigns/:id/roas — attributed revenue with the last-touch and multi-touch funnel, and holdout-incremental revenue when you ran a holdout cohort. The campaign ROAS attribution guide interprets each field.
Fold the winning script into the next broadcast — answer rate is the metric the A/B engine reports — or iterate the script body and rerun this sequence.

​
9. Troubleshooting

  • Eligible recipients is zero. Re-run the audience step with a list or segment picked; the exclusion breakdown tells you which cohort emptied it (all suppressed, all opted out, no reachable number). Fix the list or DNC source, not the broadcast.
  • 422 TCPA_FEDERAL_DIALING_WINDOW_BLOCKED. The scheduled start lands outside the 8 AM–9 PM recipient-local federal window. Move the schedule; the window cannot be disabled.
  • Launch returns 402 or a pending-approval shape. Insufficient wallet funds, or the approvals workflow is on. Top up the wallet or wait for the queue in Outbound → Approvals.
  • TTS preview is unavailable. The broadcast still creates; the preview is a convenience, not a gate. Verify the script body length (at least 8 characters) and the voice id — the picker only ships provider-catalogue voices, and the platform default resolves when you leave the field at its placeholder; it never blocks the send.
  • Recording-consent acknowledgement refused. The create-campaign gate enforces the acknowledgement unconditionally; verify recording policy at the workspace level, then retry. A pre-recorded clip the voice-gateway can resolve has to come through the composer’s upload — re-upload it if the upload banner appears.