语音 API Webhook 参考

Nexmo 使用 Webhook 及其语音 API 来使您的应用程序能够与通话进行交互。Webhook 端点有两种：

• 应答呼叫时，发送应答 Webhook。这既适用于呼入电话，也适用于呼出电话。
• 事件 Webhook 发送给呼叫期间发生的所有事件。您的应用程序可以记录、响应或忽略每种事件类型。
• 如果发生错误，也会将其传递到事件 Webhook 端点。

有关更多一般信息，请查看我们的 Webhook 指南。

应答 Webhook

应答呼入电话后，将在设置应用程序时将 HTTP 请求发送到您指定的 answer_url。对于呼出电话，在拨打电话时指定 answer_url。

默认情况下，应答 Webhook 将是一个 GET 请求，但是可以通过设置 answer_method 字段将其覆盖为 POST。对于呼入电话，您在创建应用程序时配置这些值。对于呼出电话，您在拨打电话时指定这些值。

应答 Webhook 数据字段

使用 SIP 标头传输其他数据

除了以上字段之外，您还可以指定使用 SIP 连接时所需的任何其他标头。提供的任何标头都必须以 X- 开头，并将以前缀 SipHeader_ 发送到您的 answer_url。例如，如果您添加标头 X-UserId 且值为 1938ND9，则 Nexmo 会将 SipHeader_X-UserId=1938ND9 添加到对 answer_url 的请求中。

应答 Webhook 数据字段示例

对于 GET 请求，变量将在 URL 中，如下所示：

/answer.php?to=442079460000&from=447700900000&conversation_uuid=CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab&uuid=aaaaaaaa-bbbb-cccc-dddd-0123456789ab&SipHeader_X-UserId=1938ND9

如果将 answer_method 设置为 POST，则您将在正文中收到带有 JSON 格式数据的请求：

{
  "from": "442079460000",
  "to": "447700900000",
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "SipHeader_X-UserId": "1938ND9"
}

响应应答 Webhook

Nexmo 希望您以 JSON 格式返回 NCCO，其中包含要执行的操作。

事件 Webhook

当呼叫的状态发生任何更改时，HTTP 请求将到达事件 Webhook 端点。该 URL 将是您在创建应用程序时指定的 event_url，除非您在开始呼叫时通过设置特定的 event_url 来覆盖它。

默认情况下，传入请求是带有 JSON 正文的 POST 请求。除了 event_url 外，还可以通过配置 event_method 将方法覆盖到 GET。

包含的数据格式取决于发生了哪个事件：

• started
• ringing
• answered
• busy
• cancelled
• unanswered
• rejected
• failed
• human/machine
• timeout
• completed
• record
• input
• transfer

已开始

表示呼叫已创建。

返回事件 Webhook 列表

正在振铃

目的地可达且正在振铃。

返回事件 Webhook 列表

已应答

呼叫已应答。

返回事件 Webhook 列表

繁忙

目的地正与其他呼叫者连线。

返回事件 Webhook 列表

已取消

呼出电话在应答前已由发起方取消。

返回事件 Webhook 列表

未应答

接收方无法接通或接收方拒绝了呼叫。

返回事件 Webhook 列表

已拒绝

呼叫在连接之前已被 Nexmo 拒绝。

返回事件 Webhook 列表

失败

呼出电话无法连接。

返回事件 Webhook 列表

人工 / 机器

对于以编程方式进行的出站呼叫，如果设置了 machine_detection 选项，则将发送状态为human或machine的事件，具体取决于是否有人应答了该呼叫。

返回事件 Webhook 列表

超时

如果振铃阶段的持续时间超过指定的 ringing_timeout 持续时间，则将发送此事件。

返回事件 Webhook 列表

已完成

呼叫结束，此事件还包括有关呼叫的摘要数据。

返回事件 Webhook 列表

录音

当具有“录音”操作的 NCCO 完成时，此 Webhook 将到达。创建录音操作时，可以为此事件设置不同的 eventUrl 以进行发送。如果您要使用单独的代码来处理此事件类型，则此操作非常有用。

返回事件 Webhook 列表

输入

当具有“输入”操作的 NCCO 完成时，Nexmo 将发送此 Webhook。

返回事件 Webhook 列表

转移

当链路从一个对话转移到另一个对话时，Nexmo 将发送此 Webhook。此操作可使用 NCCO 或transfer操作来完成

返回事件 Webhook 列表

错误

如果发生错误，事件端点也将收到 Webhook。这在调试应用程序时非常有用。