WhatsApp 群组设置更新 Webhook 示例

有关基于 Schema 生成的完整目录，请参阅所有示例。

概述

处理 WhatsApp 群组主题和描述的更新。

准备工作

在您的应用程序中创建一个公开的 HTTPS 端点。
针对您需要的事件类型配置 YCloud Webhook 端点。
安全存储端点签名密钥。
确保事件处理具备幂等性。

工作原理

事件发生时，YCloud 会发送 HTTP POST 请求。验证签名、持久化记录事件、返回 2xx 响应，并异步处理耗时任务。

请求

以下场景展示了发送到您的 Webhook URL 的请求。请将事件 id 作为投递标识符，并使用 type 路由有效负载。

响应

接收事件后返回 2xx 状态。

HTTP/1.1 200 OK

有关端点设置、签名验证和重试机制，请参阅配置 Webhook。

设置已更新

当 WhatsApp 群组设置成功更新时，您将收到包含以下有效负载结构的 Webhook：

请求

{
  "id": "evt_group_settings_123",
  "type": "whatsapp.group.settings_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_settings_update",
    "type": "group_settings_update",
    "requestId": "REQ_2",
    "status": "updated",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "subject": "Updated Purchase Inquiry",
    "description": "Updated group description.",
    "settings": [
      {
        "name": "group_subject",
        "text": "Updated Purchase Inquiry",
        "updateSuccessful": true
      },
      {
        "name": "group_description",
        "text": "Updated group description.",
        "updateSuccessful": true
      }
    ],
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}

响应

在持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

通过 type 路由事件，通过 id 进行去重，并将耗时或易失败的任务移至异步处理器。

设置更新失败

当 WhatsApp 群组设置更新失败或部分失败时，您将收到包含以下有效负载结构的 Webhook：

请求

{
  "id": "evt_group_settings_124",
  "type": "whatsapp.group.settings_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_settings_update",
    "type": "group_settings_update",
    "requestId": "REQ_SETTINGS",
    "status": "failed",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "subject": "New subject",
    "settings": [
      {
        "name": "group_subject",
        "text": "New subject",
        "updateSuccessful": false,
        "errors": [
          {
            "code": 131201,
            "title": "Invalid group subject"
          }
        ]
      }
    ],
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}

响应

在持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

type：对于群组设置事件始终为 whatsapp.group.settings_update
whatsappGroup：包含群组设置更新结果详情
- field：始终为 group_settings_update
- type：始终为 group_settings_update
- requestId：异步群组设置 API 操作返回的请求 ID
- status：标准化的设置更新状态，取值为 updated 或 failed
- groupId：WhatsApp 群组 ID
- subject 和 description：群组文本设置（如果存在）
- settings：每项设置的更新结果。name 可以是 profile_picture、group_subject 或 group_description
- settings[].updateSuccessful：指示单个设置更新是否成功
- settings[].errors：WhatsApp 针对单个设置返回的错误

开始使用

指南

接口

Webhooks

WhatsApp 群组设置更新 Webhook 示例

概述

准备工作

工作原理

请求

响应

设置已更新

请求

响应

说明

设置更新失败

请求

响应

说明

​概述

​准备工作

​工作原理

​请求

​响应

​设置已更新

​请求

​响应

​说明

​设置更新失败

​请求

​响应

​说明

概述

准备工作

工作原理

请求

响应

设置已更新

请求

响应

说明

设置更新失败

请求

响应

说明