whatsapp.call.status.updated

在您的 Webhook 端点处使用 whatsapp.call.status.updated 来处理此事件。

触发条件

在 WhatsApp 通话状态更新时触发。在您配置 Webhook 端点时订阅 whatsapp.call.status.updated。

语法

YCloud 会向您配置的 Webhook URL 发送 HTTP POST 请求。以下结构展示了其中一种有效负载变体。尖括号中的值为占位符；其类型列在参数下方。可选字段和其他变体在下文说明。

{
  "id": "<ID>",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "callingStatusUpdated": {
    "wabaId": "<WABA_ID>",
    "wacid": "<WACID>",
    "phoneId": "<PHONE_ID>",
    "status": "<STATUS>",
    "recipientPhone": "<RECIPIENT_PHONE>"
  }
}

参数

在处理 JSON 请求体之前，请验证 YCloud-Signature HTTP 标头。请参阅签名验证。

事件信封

参数	类型	必填	说明
`id`	string	是	事件的唯一 ID。最小长度：`6`。最大长度：`128`。
`type`	string	是	固定为 `whatsapp.call.status.updated`。
`apiVersion`	string	是	用于呈现此事件的 API 版本。
`createTime`	string (date-time)	是	此事件创建的时间，格式遵循 RFC 3339。例如，`2022-06-01T12:00:00.000Z`。

事件有效负载

参数	类型	必填	说明
`callingStatusUpdated`	object	否	特定于事件的 `callingStatusUpdated` 有效负载。

四个通用信封字段为必填项。有效负载字段取决于具体的事件变体。在每个对象表中，必填仅在其父对象存在时适用。可选字段可以省略；示例中包含某个字段并不代表该字段是必填项。

callingStatusUpdated

参数	类型	必填	说明
`id`	string	否	通话事件的唯一 ID（可选字段，可能不存在）。
`wabaId`	string	否	WhatsApp 商业账户 ID。
`wacid`	string	是	WhatsApp 通话 ID。此 ID 唯一标识该通话会话。
`phoneId`	string	否	WhatsApp Business 电话号码 ID（可选字段，可能不存在）。
`status`	string	是	通话的当前状态。 `RINGING`：商家发起的通话正在响铃。 `ACCEPTED`：商家发起的通话已被用户接听。 `REJECTED`：商家发起的通话已被用户拒接。
`recipientPhone`	string	否	采用 E.164 格式的接收者电话号码。
`recipientUserId`	string	否	接收者的 WhatsApp Business 范围用户 ID (BSUID)。
`parentRecipientUserId`	string	否	接收者的父级 WhatsApp Business 范围用户 ID。
`customerProfile`	object	否	客户的个人资料信息，包含 WhatsApp 用户名（如果可用）。

callingStatusUpdated.customerProfile

参数	类型	必填	说明
`name`	string	否	WhatsApp 账户的名称。
`username`	string	否	WhatsApp 用户名。

示例

以下 JSON 是发送给接收端的请求体。ID、电话号码和其他账户值仅作说明用途。

WhatsApp 通话状态更新事件

WhatsApp 通话状态更新时的有效负载示例

{
  "id": "evt_676e5ab57a9cb742d02d7646",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2024-12-27T07:41:28.422Z",
  "callingStatusUpdated": {
    "wabaId": "188234691048809",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "status": "RINGING",
    "recipientPhone": "+6281361905133"
  }
}

商家发起的通话正在向用户响铃

{
  "id": "evt_676e5ab57a9cb742d02d7646",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2024-12-27T07:41:28.422Z",
  "callingStatusUpdated": {
    "wabaId": "188234691048809",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "status": "RINGING",
    "recipientPhone": "+6281361905133",
    "recipientUserId": "ID.13491208655302741918",
    "parentRecipientUserId": "ID.11815799212886844830"
  }
}

商家发起的通话已被用户接听

{
  "id": "evt_67724ad42b4b206adc55f099",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2024-12-27T07:42:00.577Z",
  "callingStatusUpdated": {
    "wabaId": "188234691048809",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "status": "ACCEPTED",
    "recipientPhone": "+6281361905133",
    "recipientUserId": "ID.13491208655302741918",
    "parentRecipientUserId": "ID.11815799212886844830"
  }
}

商家发起的通话已被用户拒接

{
  "id": "evt_677258526a15af2a8c7184a3",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2024-12-27T07:41:32.093Z",
  "callingStatusUpdated": {
    "wabaId": "188234691048809",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCAB",
    "status": "REJECTED",
    "recipientPhone": "+6281361905133",
    "recipientUserId": "ID.13491208655302741918",
    "parentRecipientUserId": "ID.11815799212886844830"
  }
}

验证签名并持久化接收事件后，请返回 2xx 响应。耗时较长的任务请以异步方式处理。

HTTP/1.1 200 OK

有关场景演练，请参阅带注释的示例。

开始使用

指南

接口

Webhook reference

whatsapp.call.status.updated

触发条件

语法

参数

事件信封

事件有效负载

callingStatusUpdated

示例

​触发条件

​语法

​参数

​事件信封

​事件有效负载

​callingStatusUpdated

​示例

触发条件

语法

参数

事件信封

事件有效负载

callingStatusUpdated

示例