Broadcast a spoken message to a contact base
POST/api/v1/voice-push
One request does everything: the text is synthesised into speech, the audio is stored in your library, a campaign is created and started.
The request is synchronous — expect a few seconds while the speech is produced. In exchange you know immediately whether your text went through, instead of receiving an acknowledgement for a job that will fail silently later. Allow at least a 60-second client timeout.
Two rules shape the product:
- One message for the whole base. The text is synthesised once and the same audio is played to every contact. There is no per-contact personalisation.
- The text is frozen at launch. To send a different message, start another push.
Provide either contactGroupId or numbers — not both, not neither.
Credit is checked call by call, not at launch. A
201therefore does not guarantee that the whole base will be called: if the balance runs out along the way, the remaining contacts wait.
Required capability: TTS and CAMPAIGNS
Request
Responses
- 201
- 400
- 401
- 403
- 409
- 429
- 502
The push has been created and started, or scheduled.
Empty or over-long text, both contactGroupId and numbers supplied (or neither), or no usable number in the list.
Missing or invalid API key.
A capability required by this endpoint is not enabled on your account. Ask your account manager to switch it on.
The same text is being synthesised concurrently by another request. Retry once.
Too many requests. Back off and retry.
The speech engine is unreachable or errored. No push was created — nothing to clean up, the request can be replayed as is.