常见问题
语音通知常见问题：接入认证、发送结果、模板国家、话单推送。
语音通知接入与使用中的高频问题汇总。错误码速查见 错误代码。
接入与认证
请求要带什么凭证？
请求头 Authorization: Bearer {API_KEY}，API Key 在 Console > Developers 创建；语音接口暂不支持 CheckSum 验签。参见 鉴权。
返回 401 怎么排查？
按顺序确认：请求带了 Authorization 头、API Key 正确未删除、账号/API Key/产品授权均处于生效状态。对应场景见 错误代码 的 HTTP 401 行。
返回 403「IP 不在白名单」？
IP 白名单是必配项：API Key 未配置白名单时所有请求都会被拒绝。请在平台为 API Key 配置出口 IP 白名单后再调用；多条白名单记录取并集，变更后最长约 60 秒生效。
发送与结果
API 返回 000000，为什么被叫没接到电话？
000000 只表示任务受理成功。实际外呼可能未接通、正在重拨等待中或线路异常。用 发送记录 查看逐通状态与结束码。
重拨是什么语义？会多计费吗？
未接通的呼叫按你配置的 retry 策略（次数/间隔/触发条件）自动重拨；每次实际外呼都正常计费。不希望重拨可设 maxCount=0。
提示 120002「号码不在测试白名单」？
开发调试期间账号受测试白名单限制，仅允许呼叫白名单内号码。在 Console 快速开始流程中将号码加入白名单（上限 20 条）。
提示 120003「号码与模板国家区号不匹配」？
被叫号码必须使用模板国家的电话区号（E.164 格式）。核对号码区号与模板国家，区号表见 国家/地区编码。
定时任务什么时候发出？
scheduling.type=SCHEDULED 时，平台在你指定的 [startTime, endTime] 窗口内发起外呼；窗口最长 8 天。任务受理后不可撤回，请核对窗口再提交。
批量里部分号码失败会影响其他号码吗？
不会。受理后逐通独立外呼，单通失败不影响批次内其他号码；受理前的整批校验失败才会拒绝整个请求。
模板与国家
模板审核要多久？状态在哪看？
提交后进入审核流（0-审核中 → 1-已通过 / 2-已失败），在 Console 模板管理或 模板列表 API 查看状态；审核通过前发送会返回 120004。
能不能不改模板换国家？
不能。模板创建时绑定国家，呼叫路由与计费都由模板国家推导；面向另一个国家发送需创建对应国家的模板。
音频模板怎么创建？
通过 模板 API 上传（contentType=2，mp3/wav/m4a，base64 编码，解码后小于 2 MB）；Console 当前支持文本模板。
TTS 播报的语种怎么定？
由模板选择的 TTS 引擎决定（Console 支持引擎试听）；调用接口无需传语言编码。
话单与推送
Webhook 收不到推送？
依次检查：平台已配置回调地址、接收服务公网可达、响应 2xx、呼叫已到终态。当前版本推送失败不自动重试，可用 查询 API 兜底对账。详见 查看结果。
如何验证推送来自平台？
配置签名凭据后，推送携带 X-CALLBACK-ID 头，按 HMAC-SHA256(secret, timestamp + nonce + username) 验证小写十六进制 signature。验签示例见 话单推送。
查询 API 查不到话单？
确认查询窗口在最近 90 天内、countryCode 与呼叫国家一致、page/size 分页正确；刚受理的任务稍等片刻再查。
其他
语音通知能做按键交互（IVR）吗？
当前版本面向通知场景的单向外呼，不支持按键交互与分支流程。
想显示自己的主叫号码？
需先绑定主叫号码（联系商务/运营），发送时通过 from 指定；未绑定的号码传入会发送失败。不传则按国家默认路由。
相关资源
最后更新于