跳转到主要内容
对于收到的每个WhatsApp事件:消息、收据,GOWA POSTs 一个 JSON 文档到您的 URL 反应、编辑、删除、输入指标、组更改、标签、通讯和通话。 没有用于注册 webhook 的端点。请在启动时配置 webhook,或通过 /devices/{device_id}/webhook 为各设备单独配置。

交货工作方式

每个目标 URL 都是独立发送的,有自己的保密和检索。

配置

等效标志:--webhook、--webhook-secret、--webhook-events、--webhook-ignore-jids、--webhook-insecure-skip-verify 和 --webhook-all-device-receipts。 明确设置私有签名密钥。 一个未设定的密钥或旧发布的值 secret 会导致GOWA生成一个随机的密钥,并在重启后记录一个警告。 接收者需要一个明确的共享密钥来验证整个重启过程中的签名。HTTPS证书默认会被验证。

事件

允许列表中的事件名称不区分大小写。

有效载荷

每个请求都有相同的信封:
回复会添加 replied_to_id 和 quoted_body。回执使用 ids(数组)和 receipt_type。群组成员事件包含 chat_id、type 和 jids。群组名称变更使用独立的 group.info 数据结构。 sender_display_name 只有在from 是非空字符串时才出现。 对于另一个发送者,GOWA更喜欢保存的联系人名称、实时事件推送名称、存储的推送名称、企业名称、以及JID用户部分。 对于活跃帐户,它更喜欢帐户推送名称,然后是它的JID身份。 分辨率是最佳努力。留下的 from_name 仍然是消息事件推送名称。 当WhatsApp 提供验证名称证书时,传入的消息可能包括is_business: true、verified_name和verified_level。这些字段以其他方式被省略。 缺失并不能确定发件人是否为企业,verified_level是原始的上游价值,而不是官方徽章的担保。

媒体

使用 WHATSAPP_AUTO_DOWNLOAD_MEDIA=true (默认),媒体保存在statics/media/ 中,媒体字段保持路径:
存在说明文字时,该字段会变为 {"path": "...", "caption": "..."},说明文字也会包含在 body 中。关闭自动下载时,该字段为 {"url": "https://mmg.whatsapp.net/...", "caption": "..."};之后可使用 GET /message/{message_id}/download?phone=<chat> 获取文件。 有效载荷的完整目录(民意测验、位置、联系人、查看一次、广告推荐等)位于上游webhook payload引用。

专辑和结构化消息

一个专辑会在几个message事件时到达。标题没有消息正文并带着预期的项目计数:
每张照片或每个视频都会通过各自的普通媒体事件送达,并带有 album_id: "ALBUM_HEADER_ID"。请按该 ID 对媒体项进行分组。相册头部不是可下载的媒体项,也不会转发到 Chatwoot。 投票创建、投票、编辑和添加选项也使用 message。检查结构化的 poll 对象,而不是依靠body。 选项哈希值是精确选项名称的小写十六进制SHA-256哈希值。现有的WHATSAPP_WEBHOOK_EVENTS=message订阅接收这些交互。

在线和离线存在

使用接收事件的相同设备订阅每个联系人:
成功的响应包含 results.subscribed: true 和 results.jid。群组和频道 JID 会被拒绝。订阅不会覆盖设备的在线状态设置。如需持续接收更新,请使用以下方式启动 GOWA:
默认存在脉冲结束时标记设备不可用,停止联系人状态更新。 在设备运行时标记可用的 WhatsApp 在手机上推送通知。在启用持续跟踪之前计入此交易。
state是available或unavailable。如果联系人的隐私设置未知或隐藏,last_seen将被省略。 from_lid 在适用时包含。输入和录制仍然是分开的 chat_presence 事件,不使用此订阅。

群组名称更改

name_set_by 可能时从LID解析为电话JID,当WhatsApp 未识别演员时省略。 如果您的事件允许列表排除其他事件,请明确订阅group.info。

通讯计数器更新

newsletter.message报告在线计数器而不是一个有保障的新帖子。条目总是包含 server_id。 message_id、type和timestamp被省略了。WhatsApp 没有提供它们。零或缺少计数器可能被省略。
如果可用,reaction_counts 包含 WhatsApp的反应计数。 通过通讯ID和服务器ID消费更新。请不要将缺失的计数器重置为零。

帐户限制和注销

设备事件总是包含 session_id ,因此使用相同的 WhatsApp 编号的槽位仍然可以区分。该事件使用的是释放时段的 webhook 配置。 远程登出保留栏位以重新配对,并在登出前报告身份。 插件web钩子设置在重整配对后存活。这些事件不会发送到Chatwoot
代码未变,原因文本来自whatsmeow。未知代码仍然存在。 仅注销代码 403 和 406 并不能确定确切的原因。 暂时禁用时间为零意味着WhatsApp 没有过期。延伸的时钟限制开始新的聊天,并可能导致发送错误463。

验证签名

每项请求都携带X-Hub-Signature-256: sha256=<hex>, 一个 raw 请求正文中的HMAC-SHA256用webhook 密钥。 在解析JSON之前,根据收到的字节计算它。

交货和重试

  • 每次尝试时间在 10 秒 之后。
  • 任何非 2xx 响应或网络错误都已被检索。 妇女事务办公室最多只能在 5 次尝试,在两者之间等着1 秒、2秒、4秒和8秒。 事件处理器的上下文截止日期可以在所有尝试完成之前停止送货。
  • 最后一次失败后,事件被丢弃并记录。没有持久的队列或致命的商店。
  • 几个URL是独立发送的。
在接受事件进入您自己的耐用处理队列后响应2xx。让处理器具有传染性,因为一个重试的事件可能不止一次地出现。

链接设备接收器

默认情况下,妇女事务办公室只是为了减少重复,从主要设备转发联系确认书。 当前账户的所有设备都传递给它自己的 read 和 read-self 收据。 对于这些自己的收据,payload.from是帐户JID,payload.ids是指已读到的收到消息。 设置 WHATSAPP_WEBHOOK_ALL_DEVICE_RECEIPTS=true 或 --webhook-all-device-receipts=true,即可同时接收来自关联设备的联系人回执,包括联系人手机离线时的回执。CLI 标志会覆盖环境变量设置,显式设置为 false 时也不例外。 此选中可生成重复或订单以外的确认。按帐户、聊天和消息ID应用突然更新。 从不在较旧的收据到达时降级到交付。消息ID和发送者JID将其标准表单保持在无设备后缀。

筛选事件

按类型: WHATSAPP_WEBHOOK_EVENTS=message,message.ack 只转发这些事件。 按聊天或发送者过滤: WHATSAPP_WEBHOOK_IGNORE_JIDS 会匹配 chat_id、from、chat_lid 和 from_lid。以 @ 开头的条目是匹配整个地址空间的通配符(@g.us、@s.whatsapp.net、@lid);其他条目则按完整 JID 精确匹配。
@s.whatsapp.net 也与群组信息匹配,因为他们的 from 是一个用户 JID。使用 @g.us 来静音群组。 两个过滤器组合:事件仅在允许类型为 和 不忽略它的 JID 的情况下才会发送。

每台网络钩子

给自己的网上钩,秘密和活动允许列表:
POST /devices 也接受相同的字段。使用 GET /devices/{device_id}/webhook 读取当前设置。发送 "webhook_url": "" 可清除该设置。 一个空设备 webhook_secret 或者 webhook_events 返回到相应的全局设置。存储设备 webhook_insecure_skip_verify 替换了全局的 TLS 设置。 尤其是,false 即使启用全局旁路,也仍然启用证书验证。 默认情况下,每台设备 URL 替换 全局WHATSAPP_WEBHOOK 。 通过 WHATSAPP_WEBHOOK_DEVICE_MERGE_GLOBAL=true ,它被**添加到全局URL:设备URL使用设备的保密和允许列表。 全局网址保留全局网址,两个网址都接收一次事件。 对两者都适用忽略即时调试规则。

本地测试

通过隧道对外开放本地接收端(例如 ngrok http 8080),并将 WHATSAPP_WEBHOOK 设置为隧道 URL。启用 --debug=true 后,GOWA 会记录每次投递尝试及失败情况。

其他接收事件的方式

  • WebSocket 在 /ws?device_id=<id> 中将配对和状态事件推送到仪表板客户端。使用 web钩子发送信息。
  • 轮询: GET /chats 和 GET /chat/{chat_jid}/messages 读取 GOWA 的本地聊天存储。参阅接收消息。