FAQ
Voice notification FAQ: onboarding and authentication, send results, template countries, and CDR push.
A collection of frequently asked questions about integrating and using voice notifications. For a quick lookup of error codes, see Error Codes.
Onboarding and Authentication
What credentials should requests carry?
Send the header Authorization: Bearer {API_KEY}; the API Key is created in Console > Developers. Voice APIs do not support the CheckSum signature yet. See Authentication.
How do I troubleshoot a 401 response?
Confirm in order: the request carries the Authorization header, the API Key is correct and not deleted, and the account / API Key / product authorization are all in effect. See the HTTP 401 rows in Error Codes for the matching scenarios.
Getting 403「IP 不在白名单」(IP not on the whitelist)?
The IP whitelist is mandatory: when no whitelist is configured for the API Key, all requests are rejected. Configure the egress IP whitelist for the API Key on the platform before calling; multiple whitelist entries are unioned, and changes take effect within about 60 seconds.
Sending and Results
The API returned 000000 — why did the recipient not get the call?
000000 only means the task was accepted. The actual outbound call may have failed to connect, may still be waiting for a redial, or the route may be faulty. Use send records to view per-call status and release codes.
What is the redial semantics? Does it cost extra?
Calls that do not connect are automatically redialed per your configured retry policy (count / interval / trigger conditions); every actual outbound call is billed normally. To disable redial, set maxCount=0.
Seeing 120002「号码不在测试白名单」(Number not on the test whitelist)?
During development and debugging, the account is restricted by the test whitelist: only numbers on the whitelist can be called. Add numbers to the whitelist in the Console quick-start flow (limit of 20 entries).
Seeing 120003「号码与模板国家区号不匹配」(Number does not match the template country dialing code)?
The recipient number must use the template country's calling code (E.164 format). Check the number's calling code against the template country; see the code table at Country/Region Codes.
When are scheduled tasks sent?
With scheduling.type=SCHEDULED, the platform places the outbound calls within the [startTime, endTime] window you specify; the window spans at most 8 days. An accepted task cannot be revoked — double-check the window before submitting.
Do failed numbers in a batch affect the others?
No. After acceptance, each call is placed independently — a single failure does not affect the other numbers in the batch. Only a whole-batch validation failure before acceptance rejects the entire request.
Templates and Countries
How long does template review take, and where is the status?
After submission the template enters the review flow (0 = Under review → 1 = Approved / 2 = Rejected); view the status in Console Template Management or via the Template List API. Sending before the review passes returns 120004.
Can I switch countries without changing the template?
No. A template is bound to its country at creation, and both call routing and billing are derived from the template country; to target another country, create a template for that country.
How do I create an audio template?
Upload via the Template API (contentType=2, mp3/wav/m4a, base64-encoded, under 2 MB after decoding); the Console currently supports text templates.
How is the TTS language determined?
It is determined by the TTS engine selected on the template (the Console supports engine audition); no language code is needed in the API call.
Call Records and Push
Not receiving Webhook pushes?
Check in order: the callback URL is configured on the platform, the receiving service is publicly reachable, responses are 2xx, and the call has reached its final state. The current version does not automatically retry failed pushes; use the query API as a reconciliation fallback. See Viewing Results for details.
How do I verify a push comes from the platform?
With signing credentials configured, each push carries the X-CALLBACK-ID header; verify the lowercase hexadecimal signature using HMAC-SHA256(secret, timestamp + nonce + username). See the verification example at CDR Status Webhook.
The query API returns no call records?
Confirm the query window is within the last 90 days, countryCode matches the call country, and the page/size pagination is correct; for a just-accepted task, wait a moment and query again.
Other
Does voice notification support keypress interaction (IVR)?
The current version is a one-way outbound call service for notification scenarios; keypress interaction and branched flows are not supported.
Want to display your own caller number?
Bind the caller number first (contact sales/operations) and specify it via from when sending; passing an unbound number fails the send. Omit it to use the country default route.
Related Resources
Last updated on