登录开始免费试用
Meta Tech Provider

WhatsApp calls Webhook:Calling API 事件,以及 Coexistence 号码上的通话

calls Webhook 字段汇报 WhatsApp Business Calling API 的事件:connect 事件附带 SDP answer 或 offer,通话状态包括 RINGING、ACCEPTED 和 REJECTED,terminate 事件附带 COMPLETED 或 FAILED 状态及通话时长,另有 call_recording_available 和 call_transcription_available。Meta 的 Coexistence 指南列明,语音和视频通话在 WhatsApp Business 应用中保持不变,而 Cloud API 不支持这些通话,因此它们仍留在手机上。

EasyCoexistence 通过 Coexistence 将您的 WhatsApp Business 应用号码连接到 Meta 的 Cloud API,因此您的 AI 和自动化功能可以回复消息并发送消息模板,而通话仍在您手机的应用中响铃。

Not supported

Cloud API 上的语音和视频通话(适用于通过 WhatsApp Business 应用接入的号码);在应用中,通话保持不变。

2,000

号码使用 Calling API 前所需的最低每日消息限额(按不同收件人计算)。

7 days

通话录音和转写文本在其 Webhook 送达后可下载的时长。

wacid

通话 ID 的前缀,它把同一通话的 connect、状态和 terminate Webhook 关联起来。

whatsapp_business_messaging

应用接收 calls Webhook 所需的权限,与接收消息所需的权限相同。

calls Webhook 字段汇报什么?

通过 Calling API 拨打或接听的通话所发生的一切,都汇集在这一个字段中,每个阶段对应一个事件。企业发起的通话会产生 connect 事件、状态更新和 terminate 事件。通过 SIP 处理的通话则报告 call_created,而不是 connect,且不包含 SDP 会话。另有一个相关事件位于其他字段:客户响应通话权限请求时,回复会以 call_permission_reply 类型的交互式消息,出现在 messages 字段中。

connectThe call is ready to connect; session carries the SDP to apply to your WebRTC stack.
call_createdA SIP call was attempted, business- or user-initiated.
statuses (type call)RINGING, ACCEPTED or REJECTED for a business-initiated call.
terminateThe call ended: status COMPLETED or FAILED, with times and duration when answered.
call_recording_availableA media id for the finished audio recording.
call_transcription_availableA media id for the transcript, a JSON document.

calls Webhook 的样子是怎样的?

外层结构与每个 WhatsApp Webhook 相同,在 value 下有一个 calls 数组,field 设为 calls。direction 的值为 BUSINESS_INITIATED 或 USER_INITIATED,from 和 to 携带电话号码,to_user_id 为客户的 BSUID;对于使用用户名的客户,两个号码中任何一个都可能缺失。metadata.phone_number_id 标识您的号码,与其他字段一样。以下为 Meta 的 Call Connect 示例,占位符按 Meta 的原样保留:

Meta's example: the Call Connect webhook
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16315553601",
              "phone_number_id": "<PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<CALLEE_NAME>",
                  "username": "<USERNAME>"
                },
                "wa_id": "16315553602",
                "user_id": "<BSUID>",
                "parent_user_id": "<PARENT_BSUID>"
              }
            ],
            "calls": [
              {
                "id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
                "to": "16315553601",
                "to_user_id": "<BSUID>",
                "to_parent_user_id": "<PARENT_BSUID>",
                "from": "16315553602",
                "event": "connect",
                "timestamp": "1671644824",
                "direction": "BUSINESS_INITIATED",
                "session": {
                  "sdp_type": "answer",
                  "sdp": "<<RFC 8866 SDP>>"
                }
              }
            ]
          },
          "field": "calls"
        }
      ]
    }
  ]
}

terminate 事件会增加哪些字段?

terminate 是多数系统会存储的事件,因为它会结束通话。其字段依据 Meta 参考文档如下:

  • status:通话在没有意外错误的情况下结束时为 COMPLETED,包括未接听的通话;未能接通或中途中断时为 FAILED。
  • start_time、end_time 和以秒为单位的 duration:仅当对方接听时才会出现。
  • errors:在 FAILED 通话中包含 code、message、href 和 error_data.details。
  • biz_opaque_callback_data:在发起或接听通话时若已传入,则为您自定义的跟踪字符串。

calls Webhook 能在 Coexistence 号码上使用吗?

Meta 的 Coexistence 指南在其功能表中回答了这个问题:对于以此方式接入的号码,语音和视频通话在 WhatsApp Business 应用中没有变化,而 Cloud API 不支持。Calling API 自身的前提条件从另一端给出了相同的说明:企业号码必须用于 Cloud API,而非 WhatsApp Business 应用。因此,在 Coexistence 号码上,客户仍会照常拨打电话,通话在手机的应用中响铃,而 calls 字段没有任何内容可汇报。需要通过软件处理通话的企业,应只使用 Cloud API 上的号码。

同一通话的各个事件如何衔接?

通过通话 ID 衔接,该 ID 以 wacid 开头,并在该通话的每个事件中重复出现。企业发起的通话会先报告带有 SDP answer 的 connect,接着是 RINGING 状态,然后是 ACCEPTED 或 REJECTED,最后是 terminate。用户发起的通话会报告带有 SDP offer 的 connect,供您的技术栈应答,然后是 terminate。启用后,录音和转写事件会在 terminate 之后出现。存储事件时,请以 id 加 event 作为键,因为重试会重复发送事件,且不保证到达顺序。Calling API 前提条件的完整列表,见关于 Coexistence 号码上通话的页面。

您的 AI 能为 Coexistence 号码上的通话做些什么?

AI 在聊天中工作,通话则交由手机上的真人处理。EasyCoexistence 不订阅 calls 字段,也没有通话工具;其连接器和自动化功能涵盖消息和消息模板。实际上,AI 回复可以告诉客户何时有人可以通话,以及应拨打哪个号码;关键词自动化可对 “call” 或 “phone” 作出回复,并附上这些信息;企业主则照常在 WhatsApp Business 应用中接听电话。

常见错误

  • 为 Coexistence 号码订阅 calls 并等待事件。Meta 列明,对这类号码,Cloud API 不支持通话功能。
  • 期望每个 terminate 都包含 start_time 和 duration。这两个字段只在通话被接听时出现;未接听的通话仍以 COMPLETED 结束。
  • 在 calls 字段中查找权限回复。这些回复会以交互式 call_permission_reply 的形式,出现在 messages 字段中。
  • 将录音和转写文本留在 Meta 处。两者只能在其 Webhook 之后的 7 天内下载,之后便无法再获取。
使用 EasyCoexistence 完成这些操作

每个号码都全天候 24/7 监控,并包括 14 天规则,即应用长期未打开的号码会被断开。每个号码每月从 US$ 9 降至 US$ 0.75,号码越多单价越低,并提供 3 天免费试用。

常见问题

号码通过 Coexistence 接入 API 后,客户会失去通话按钮吗?

Meta 的 Coexistence 指南列明,语音和视频通话在 WhatsApp Business 应用中保持不变。客户仍拨打同一个号码,企业主则在手机的应用中接听。

Calling API 的定价与消息相同吗?

否。Meta 的定价页面说明,Calling API 采用不同的定价,并指向单独的通话定价文档,因此通话费用不会出现在消息状态的 pricing 对象中。

Calling API 通话可以被录音或转写吗?

可以,前提是已启用录音或转写。通话结束后,Meta 会发送附有音频 media id 的 call_recording_available,或附有 JSON 文档 ID 的 call_transcription_available,通常在一分钟内送达。

通话 Webhook 能否发送到与应用不同的端点?

可以。calls 是 Meta 允许 WhatsApp Business 账户或电话号码路由到备用回调 URL 的字段之一,与 messages 和 Coexistence 相关字段并列。

继续阅读

准备开始了吗?

几分钟即可设置 WhatsApp Coexistence,而不是几个月。应用会继续在手机上运行。

开始免费试用

验证时间