Understanding Voice Notifications
Introduction to the voice notification product: the call pipeline, capability overview, and onboarding path.
A voice notification places a real voice call to a phone number and, once answered, plays the template content via TTS (or plays a recorded audio file). It suits scenarios that need high-impact reach, such as order reminders, logistics notifications, meeting invitations, risk alerts, and verification reminders. Compared with SMS, a phone call is much harder to miss, making it a good fit for important, time-sensitive notifications.
Prerequisites
- The voice product is enabled and you have created an API Key (see the preparation steps in Quickstart)
- Understand two basic concepts: the template (the content played on the call, which must pass review) and the task (one run of calls placed to a batch of numbers)
Call Pipeline
The complete lifecycle of a voice notification:
- Submit: Submit a batch of numbers and a template via a Console call task or the Send API
- Acceptance: The platform validates the parameters, template, and balance, then accepts the task (the API returns
000000andcallId) - Outbound call: The platform selects a route based on the country bound to the template and places the call; calls that do not connect are retried per the configured redial policy
- Final state: Each call reaches a final state (answered then hung up / no answer / unreachable)
- Results: Get the result of each call from send records, the query API, or CDR push
000000 means the task was accepted; it does not mean every call was answered. For per-call results, rely on send records, the query API, or CDR push.
Capability Overview
| Capability | Description |
|---|---|
| Text template (TTS) | Variable placeholders {1}…{n}, with values passed per number |
| Audio template | Upload mp3/wav/m4a (under 2 MB) and play the recorded content |
| Per-number variables | Each recipient can carry its own variable values |
| Scheduled task | Send within a specified time window |
| Redial policy | Configurable count / interval / trigger conditions |
| Hang-up SMS | Send a follow-up SMS to the recipient after the call |
| Result retrieval | Three channels: Console records / query API / Webhook push |
Boundaries: The current product is a one-way outbound call service for notification scenarios. It does not support IVR keypress interaction, inbound call answering, or any voice processing other than recorded-audio upload.
FAQ
Why can a call still fail after the API accepts it?
Acceptance only completes parameter and resource validation; the actual outbound call is subject to the recipient's status, the route, and country routing. Check send records for per-call results, and see Error Codes for failure reasons.
Where should I start?
Recommended order: Quickstart (place a real call with the test whitelist) → Using the Voice Console → Placing Calls → API reference.
Related Resources
Last updated on