Webhook事件验证与消息处理 - WOZTELL官方文档

网页钩子

验证

所有 webhook 事件的请求头都会携带签名（"X-Woztell-Signature"）用于验证。每个 webhook 事件可以通过以下方法进行验证。
  1. 使用 HMAC-SHA256 算法，以频道密钥作为密钥，计算请求体的摘要。
  2. 确认 Base64 编码的摘要是否与 X-Woztell-Signature 请求头中的签名匹配。

入站消息

订阅此 webhook 后，您将收到 WOZTELL 为所有支持的平台预处理的标准化事件。

来自 WhatsApp 的示例

文本消息：

{
  "from": "85260903521",
  "to": "85268227287",
  "timestamp": "1599536864",
  "type": "TEXT",
  "data": {
    "text": "你好"
  }
  "member": "memberId",
  "channel": "channeId",
  "app": "appId",
  "memberExtraData": {
    "field": "测试元数据",
    "path": "gender"
  }
}

视频消息：

{
  "from": "85260903521",
  "to": "85268227287",
"timestamp": "1599536864",
"type": "MISC",
"data": {
  "attachments": [{
    "type": "VIDEO",
    "waMediaId": "e8a85916-2386-49dc-8f05-1cd0527bfb68"
  }],
},
"member": "memberId",
"channel": "channeId",
"app": "appId",
"memberExtraData": {
  "field": "测试元数据",
  "path": "gender"
}
}

消息状态更新

除了消息事件之外，通过订阅入站消息，您还可以收到消息状态更新，例如 WhatsApp 的 已发送、 已送达 和 已读 事件。

来自 WhatsApp 的示例

当消息状态变为 已读 时：

{
  "to": "85268227287",
  "timestamp": 1701914905000,
  "messageId": "wamid.ABcLODUyNTQwNjM1OTgVAgARGBJCRDc4MkU4QTUzREFCMkU3REEA",
  "from": "85254063598",
  "data": {
    "messageId": "wamid.ABcLODUyNTQwNjM1OTgVAgARGBJCRDc4MkU4QTUzREFCMkU3REEA"
  },
  "type": "READ",
  "eventType": "INBOUND",
  "member": "MEMBER_ID",
  "channel": "CHANNEL_ID",
  "app": "APP_ID"
}

出站消息

body


属性类型描述
type字符串可以是 BOT 或 MANUAL，表示出站消息是来自聊天机器人还是 API/Broadcast
member字符串成员的 ID
channel字符串频道的 ID
app字符串应用的 ID
meta对象apiSource，包含源集成的信息
memberExtraData对象额外的成员数据和有效的成员路径
customHeadersData对象自定义请求头键和值
messageEvent对象包含标准化消息的 messageEvent 对象


messageEvent


属性类型描述
from字符串发送者的 ID
to字符串接收者的 ID
timestamp数字Unix 时间戳
type字符串消息类型
data对象对应消息类型的消息数据
messageId字符串外部平台的消息 ID （此属性可能不存在）


meta


属性类型描述
agentUserId字符串发送消息的用户 ID。
source对象源集成信息；与 apiSource 相同
apiSource对象源集成信息；即将废弃


_source_


属性类型描述
integrationId字符串源集成类型
build数字集成版本
appIntegration字符串集成 ID


示例事件

{
  "type": "MANUAL",
  "app": "APP_ID",
  "channel": "CHANNEL_ID",
  "member": "MEMBER_ID",
  "eventType": "API_OUTBOUND",
  "meta": {
    "agentUserId": "59cb495865243d002c6fc1f5",
    "apiSource": {
      "integrationId": "inbox",
      "build": 1,
      "appIntegration": "6420ffb53e65b445d4657ee1"
    },
    "__source__": {
      "integrationId": "inbox",
      "build": 1,
      "appIntegration": "6420ffb53e65b445d4657ee1"
    }
  },
  "messageEvent": {
    "from": "14132521446",
    "to": "85260903521",
    "data": {
      "text": "hihi"
    },
    "type": "TEXT",
    "timestamp": 1712807869354,
    "messageId": "wamid.HBgLODUyNjA5MDM1MjEVAgARGBJFMkI5MkQwODQ1NDc3Q0UwM0QA"
  }
}
想法
注意

出站消息中的 agentUserId 可用于通过 开放 API 查询团队成员信息：

query getTeamMembersUserIdAndEmail
{
  apiViewer {
    app {
      teamMembers {
        user {
          _id
          email {
            email
          }
        }
      }
    }
  }
}

机器人出站消息

机器人响应消息将发送到您指定的 webhook。

API 出站消息

通过SendResponse API发送的消息将发送到您指定的 webhook。

Broadcast 出站消息

通过Broadcast发送的消息将发送到您指定的 webhook。

成员更新事件

通过订阅这些事件，您将收到该频道成员状态变化时的事件通知。

成员更新事件包括：成员创建、成员订阅状态更新、成员在线状态更新、成员元数据更新、成员临时数据更新 和 成员标签更新。

body


属性类型描述
eventType字符串MEMBER_UPDATE
functionName字符串NORMAL_UPDATE_MEMBER：在成员页面手动更新成员；
BOT_UPDATE_MEMBER：通过机器人更新成员
member字符串成员 ID
channel字符串频道 ID
app字符串应用 ID
before对象变更前成员状态
after对象变更后成员状态

示例事件

{
  "eventType": "NORMAL_UPDATE_MEMBER",
  "functionName": "NORMAL_UPDATE_MEMBER",
  "member": "memberId",
  "channel": "channelId",
  "app": "appId",
  "before": {
    "liveChat": false,
    "tempData": {
      "faqAns": [],
      "listLength": 5
    },
    "tags": [
      "test_broadcast"
    ]
  },
  "after": {
    "liveChat": true,
    "tempData": {
      "faqAns": [],
      "listLength": 1
    },
    "tags": [
      "test_broadcast",
      "testing_tag_2"
    ]
  }
}

批量成员更新

当多个成员同时批量更新时，您将收到事件类型为 BATCH_MEMBER_UPDATE 的事件。

body

属性类型描述
eventType字符串BATCH_MEMBER_UPDATE
functionName字符串批量更新函数，包括 OPEN_API_BATCH_CREATE_CHAT、 OPEN_API_UPDATE_MEMBERS、 OPEN_API_BATCH_UPDATE_MEMBERS、 NORMAL_UPDATE_MEMBERS、 BATCH_ADD_TAGS、 BATCH_DELETE_TAGS、 BATCH_REPLACE_TAGS
members数组成员 ID 数组
channel字符串频道 ID
app字符串应用 ID
update对象成员更新详情

示例事件

{
  "eventType": "BATCH_MEMBER_UPDATE",
  "functionName": "BATCH_ADD_TAGS",
  "members": [
    "memberId_1",
    "memberId_2",
    "memberId_3",
    "memberId_4",
    "memberId_5",
    "memberId_6"
  ],
  "channel": "channelId",
  "app": "appId",
  "update": {
    "$addToSet": {
      "tags": {
        "$each": [
          "testing_tag_1"
        ]
      }
    }
  }
}

节点触发事件

订阅此事件后，您将在频道中节点被触发时收到通知。

body

属性类型描述
eventType字符串NODE_TRIGGER
app字符串应用 ID
字符串频道 ID频道 ID
字符串成员 ID成员 ID
字符串节点触发时间节点触发时间
字符串节点 ID节点 ID
字符串节点唯一 ID节点唯一 ID
字符串树的 ID树的 ID
对象包含标准化消息的 messageEvent 对象包含标准化消息的 messageEvent 对象

示例事件

{
  "app": "appId",
  "channel": "channelId",
  "member": "memberId",
  "timestamp": 1680605255829,
  "node": "nodeId",
  "compositeId": null,
  "tree": "treeId",
  "eventType": "NODE_TRIGGER",
  "messageEvent": {
    "to": "123461662163",
    "timestamp": 1680605248000,
    "messageId": "wamid.HLavODUyNTpRNjM1OTgVAgASGBYzRUabcjRDNTcxQjhPQ8E3MEI0MkFCAA==",
    "from": "85212345678",
    "type": "TEXT",
    "data": {
      "text": "测试"
    }
}
}

频道中管理 Webhook

新的频道 webhook 系统可以更好地控制您 webhook 接收的事件。在频道的“环境”页面，您可以管理订阅该频道各个环境的 webhook。



想法
注意

如果您的频道 webhook 系统仍处于弃用版本，每次进入频道环境时都会显示升级提醒。


创建 Webhook

  1. 要向您的频道添加 webhook，请选择“+ 创建新的 webhook”。
  1. 输入 webhook URL，选择要订阅的事件，最后点击“确认”以确认 webhook 设置。
  1. 关闭上一个弹窗后，请务必再次“保存”环境设置。

编辑 Webhook

  1. 要编辑 webhook，请点击“更多”并选择“编辑”。
  1. 记得“确认”对现有 webhook 的更改。

删除 Webhook

要删除 webhook，请点击“更多”并选择“删除”。

高级菜单

  1. 新的频道 webhook 系统还支持发送成员元数据和自定义请求头。要启用，请选择“显示高级菜单”。
  1. 然后您可以看到成员元数据和自定义请求头部分。
  1. 填写所有必填项后，点击“确认”确认设置。

最后更新于