调用API发起语音互动并接收按键回执-语音服务-阿里云

语音互动（语音IVR）是通过API接口向指定号码发起交互式语音通话，用户接听电话后，播放一段指定音频，用户根据音频引导，通过手机按键信息返回意图。

工作原理

语音互动（IVR）的完整工作流程包含API调用、云端处理、用户交互和结果回调四个环节：

IVR

发起呼叫：业务服务器调用IvrCall接口，请求阿里云语音服务向指定用户发起呼叫。请求中包含了交互逻辑的核心——MenuKeyMap，它定义了用户按不同按键后应播放的后续语音。
云端处理与外呼：语音服务平台收到请求后，使用指定的号码呼叫最终用户。
用户交互：用户接听电话后，系统首先播放开场语音。用户根据语音提示按下按键。
结果回调：语音服务平台捕获到用户的按键（如 1、2、# 等），并将该按键信息（digits）连同本次通话的唯一标识（call_id）等数据，通过预设的HTTP回调地址或消息队列（MNS）实时推送给您的业务服务器。
业务处理：服务器接收到按键信息后，根据自身的业务逻辑进行处理，例如记录调研结果、验证用户身份或触发下一步操作。

操作步骤

本章节将引导您完成一次最基本的IVR呼叫：向用户手机播放一段欢迎语，并接收用户按下的第一个按键。

步骤1：完成准备工作

在调用API前，需要完成以下准备工作，以确保服务可以正常使用。

完成企业认证：本服务仅限企业实名认证用户使用。必须先在语音服务控制台企业资质管理并通过审核。
申请话术报备：申请话术并审核通过。申请话术的目的是业务场景报备，话术内容后续不会应用于语音通话，详情请参见新增话术。
申请真实号：必须提前在语音服务控制台申请真实号。具体操作，请参见真实号申请。
创建AccessKey：确保已创建并获取AccessKey ID和AccessKey Secret，用于API调用身份验证。
准备回执接收地址：准备一个公网可访问的URL，用于接收语音平台推送的按键回执消息。推荐使用 HTTP批量推送，因为它具有更好的实时性。
- 在语音服务控制台，点击通用设置 > 订阅回执消息。
- 选择HTTP批量推送，并填写准备好的公网URL。

步骤2：准备语音素材

所有用于通话的语音文件或文本转语音（TTS）模板，都必须提前在控制台上传或创建，并通过审核后方可使用。审核通常在1个工作日内完成。

选项一：使用语音文件：登录语音服务控制台，上传一个WAV或MP3格式的语音文件并等待审核通过，获取语音ID。
选项二：使用TTS模板：登录语音服务控制台，创建一个TTS模板并等待审核通过，获取模板ID。请注意，不支持通过API接口直接创建或传递任意文本的TTS模板，所有TTS播报内容必须基于已在控制台审核通过的模板。具体操作，请参见创建语音模板。

步骤3：发起IVR呼叫

通过IvrCall接口发起交互式语音通话。
通过QueryCallDetailByCallId查询呼叫详情。

步骤4：接收并处理按键回执

当用户在通话中按下按键后，语音服务会向您在步骤1中配置的HTTP地址发送一个POST请求，请求体为JSON格式。

1. 分析回执消息

假设用户在上述通话中按下了 1，服务器将收到类似以下的JSON数据：

{
  "call_id": "115480011020^1034120****_12345",
  "call_time": "2023-03-15 14:20:30",
  "called_num": "1390000****",
  "digits": "1",
  "out_id": "your-unique-business-id-123",
  "event": "dyvms.Ivr.Digits"
}

digits: 用户按下的按键，这是您最关心的字段。
call_id: 本次通话的唯一ID，可用于后续查询通话详情。
out_id: 在调用API时传入的外部业务ID，便于将回执与自己的业务数据关联。

2. 保证接收服务安全与稳定

签名验证：为确保回调请求来自阿里云，请根据回执消息简介与配置流程文档中的逻辑对收到的请求进行验签。
IP白名单：在服务器或网络防火墙上，设置IP白名单。
幂等处理：在网络异常情况下，语音平台可能会重试推送回执消息。接收服务需要具备幂等处理能力，可以基于call_id和digits的组合来判断是否为重复消息，避免重复处理。