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 和自动化功能可以回复消息并发送消息模板,而通话仍在您手机的应用中响铃。
Cloud API 上的语音和视频通话(适用于通过 WhatsApp Business 应用接入的号码);在应用中,通话保持不变。
号码使用 Calling API 前所需的最低每日消息限额(按不同收件人计算)。
通话录音和转写文本在其 Webhook 送达后可下载的时长。
通话 ID 的前缀,它把同一通话的 connect、状态和 terminate Webhook 关联起来。
应用接收 calls Webhook 所需的权限,与接收消息所需的权限相同。
calls Webhook 字段汇报什么?
通过 Calling API 拨打或接听的通话所发生的一切,都汇集在这一个字段中,每个阶段对应一个事件。企业发起的通话会产生 connect 事件、状态更新和 terminate 事件。通过 SIP 处理的通话则报告 call_created,而不是 connect,且不包含 SDP 会话。另有一个相关事件位于其他字段:客户响应通话权限请求时,回复会以 call_permission_reply 类型的交互式消息,出现在 messages 字段中。
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 的原样保留:
{
"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 天内下载,之后便无法再获取。
每个号码都全天候 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,而不是几个月。应用会继续在手机上运行。
开始免费试用验证时间