如何在客户的 WhatsApp 或社交连接断开时及时获知
easyCoexistence 会在客户的连接建立、断开、被移除或被暂停时,向您的平台发送经过签名的状态事件。WhatsApp 号码会发送 connection.connected、附带 Meta 原因的 connection.disconnected、connection.removed、connection.suspended 或 connection.token_missing;社交账户则发送对应的 channel.* 事件,不含 token_missing。每个事件都是一个 JSON POST 请求,使用 X-EC-Signature 签名,并以退避方式重试约 33 小时,直至您的端点返回 2xx。
PRIMARY_INACTIVITY:Meta 给出的原因,表示主设备闲置约 14 天,导致 Coexistence 号码断开连接。
COMPANION_INACTIVITY:Meta 给出的原因,表示配套设备闲置约 30 天。
用于报告断开连接的 Webhook,Meta 始终将其发送到应用的默认 callback URL,从不发送到覆盖地址。
事件在返回非 2xx 响应后的重试频率:间隔从 1 分钟到 24 小时,历时约 33 小时。
端点在处理状态事件时应接受的最早签名时间戳 t,并以恒定时间比较 HMAC。
有哪些状态事件?
共 9 种,分为两类,共用同一端点和同一签名密钥。号码使用 connection.*,社交账户使用 channel.*,因此只为号码编写的接收方可按名称跳过 channel 事件。在控制台中依次进入 Profile 和 Developers 设置端点,或使用 MCP 工具 set_partner_events_url;签名密钥只在保存 URL 时显示一次。
连接事件包含哪些内容?
投递的 id(一个 UUID)、事件名称、ISO 8601 格式的 occurred_at,以及一个 connection 对象,其字段包括 id、external_ref、connect_session_id、phone、name、waba_id、phone_number_id、status 和 token_ready。部分事件会在顶层增加字段:connection.disconnected 和 connection.suspended 带有 reason;当 easyCoexistence 自身的定期检查(而非 Meta 的 Webhook)发现断开时,detected_by 设为 health_check;当连接会话产生该事件时,则包含 connect_session_id。
{
"id": "5c2a9e70-…",
"event": "connection.disconnected",
"occurred_at": "2026-10-31T10:15:02.114Z",
"connection": {
"id": "<CONNECTION_ID>",
"external_ref": "customer_4821",
"connect_session_id": "cs_…",
"phone": "+55 11 9…",
"name": "Clínica Sorriso",
"waba_id": "<WABA_ID>",
"phone_number_id": "<PHONE_NUMBER_ID>",
"status": "disconnected",
"token_ready": true
},
"reason": "PRIMARY_INACTIVITY"
}渠道事件包含哪些内容?
与连接事件结构相同,只是以 channel 对象代替 connection。该对象与 GET /channels/{id} 的视图一致,包括 id、channel(所属网络)、external_ref、connect_session_id、name、username、external_id、status、token_ready、webhook_url、disconnected_reason、last_checked_at 和 created_at。渠道没有 token_missing,因为社交登录总会返回客户本人的访问令牌。由连接会话产生的 channel.connected 也会在顶层带有 connect_session_id。
{
"id": "0b7e41d2-…",
"event": "channel.disconnected",
"occurred_at": "2026-10-31T10:15:02.114Z",
"channel": {
"id": "<CHANNEL_ID>",
"channel": "tiktok",
"external_ref": "customer_4821",
"connect_session_id": "cs_…",
"name": "Clínica Sorriso",
"username": "clinicasorriso",
"external_id": "<TIKTOK_OPEN_ID>",
"status": "disconnected",
"token_ready": false,
"webhook_url": "https://hooks.example.com/social",
"disconnected_reason": "<THE_NETWORK'S_MESSAGE>",
"last_checked_at": "2026-10-31T10:15:02.000Z",
"created_at": "2026-10-28T16:40:09.000Z"
}
}断开原因分别是什么?
connection.disconnected 上的 reason 是 Meta 放在其 account_update Webhook 的 disconnection_info 中的代码,适用于 WhatsApp Business 应用和 Cloud API 上的号码。若 Meta 未提供,则为 null。Meta 参考文档中的代码如下:
PRIMARY_INACTIVITY:运行 WhatsApp Business 应用的手机约 14 天未活动,即 14 天规则。新的连接会话可重新连接该号码。ACCOUNT_DISCONNECTED:账户因 Meta 的管控措施或客户操作而断开,客户可能已移除访问权限或删除了账户。COMPANION_INACTIVITY:配套设备约 30 天未活动。BUSINESS_DOWNGRADE:该号码已注册到消费者版 WhatsApp 应用。CHANGE_NUMBER和USER_RE_REGISTERED:客户更换了号码,或在新设备上重新注册了该号码。
状态事件随附哪些标头?
共 5 个,每次尝试都会发送:Content-Type application/json、User-Agent easyCoexistence-webhooks/1、X-EC-Event(事件名称)、X-EC-Delivery(与正文相同的 id),以及 X-EC-Signature。签名格式为 t=<unix>,v1=<hex>,其中 v1 是以 t、一个点号和原始正文拼接后,用您账户的签名密钥计算的 HMAC-SHA256。签名密钥以 whsec_ 开头。每次尝试都会重新签名,因此重试时携带的 t 不同,但对应的正文相同。
import hashlib, hmac, json, os, time
SECRET = os.environ["EC_EVENTS_SECRET"].encode() # whsec_..., shown once in Profile > Developers
def verify(raw: bytes, header: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False # missing, or more than 5 minutes off
mac = hmac.new(SECRET, t.encode() + b"." + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, v1)
def handle(raw: bytes, headers) -> int:
if not verify(raw, headers.get("X-EC-Signature", "")):
return 401
event = json.loads(raw)
if already_processed(event["id"]): # the X-EC-Delivery id, the same on every retry
return 200
enqueue(event) # act on event["event"]; the latest occurred_at wins
return 200失败的投递如何重试?
首次尝试会在事件发生时立即发出。返回非 2xx、10 秒内无响应、网络错误或重定向都视为失败,之后会以逐渐拉长的间隔重试,间隔从 1 分钟到 24 小时,共 7 次尝试,历时约 33 小时,随后丢弃该事件。投递仅发送到解析为公网 IP 的 HTTPS 地址。在未设置端点时发生的事件不会排队,删除端点会停止所有待处理的投递。
为什么要对每个 id 只处理一次,并检查 occurred_at?
因为重试会完全重复投递,正文和 X-EC-Delivery 中的 id 都相同;而且被重试的事件可能晚于较新的事件到达。请保存已处理的 id 并跳过重复项。然后将 occurred_at 与您为该连接记录的最后状态进行比较,或在依据可能已过时的事件采取行动前,读取 GET /connections/{id} 或 GET /channels/{id}。
号码断开时,平台应如何处理?
根据原因采取行动。出现 PRIMARY_INACTIVITY 后,请客户打开 WhatsApp Business 应用,并为同一号码向其发送新的连接会话。在同一 WhatsApp Business Account 上重新连接该号码,可保留其连接 ID,恢复您的 Webhook 目标,并发送 connection.connected,此后您应重新读取其凭证;connection.token_missing 则表示 Meta 在该次运行中未颁发访问令牌。Meta 仅会将导致断开的 account_update 发送到应用自身的 callback,从不发送到您的 URL,因此本事件是您的平台获知断开的途径。
社交账户断开时,平台应如何处理?
收到 channel.disconnected 后,使用同一 channel 发起新的连接会话,即可在同一 channel ID 下重新登录该账户。channel.removed 表示访问权限已失效:访问令牌会被删除,所有 Webhook 目标也会被清除,因此若客户重新连接,请再次设置目标。号码或渠道被暂停后,待订阅恢复有效,重新连接一次即可恢复。
常见错误
- 将重试视为新事件。重试的 id 与正文和 X-EC-Delivery 中的 id 相同,因此请记录已处理的 id,否则同一次断开可能让客户收到两次提醒。
- 按到达顺序应用事件。被重试的事件可能晚于较新的事件到达,因此请比较 occurred_at,或在行动前读取连接状态。
- 为修正拼写错误而再次保存事件 URL,却未更新后端。保存会颁发新的签名密钥,在您的端点使用新密钥之前,每次投递都会验证失败。
- 先做处理再回应。处理时间超过 10 秒会被视为失败,事件随后会再次发送,因此请先返回 2xx,再进行处理。
easyCoexistence 全天候监控每位客户的 WhatsApp 号码和社交账户。当号码或账户连接、断开、被移除或被暂停时,它会向您的平台发送经过签名的事件;号码断开时附带 Meta 给出的原因。每个连接每月 US$ 9 起,连接越多越便宜,最低降至 US$ 0.75,并提供首 3 天免费试用。
常见问题
PRIMARY_INACTIVITY 是什么意思?
这是 Meta 给出的原因,表示 Coexistence 号码的 WhatsApp Business 应用在主设备上约 14 天未被使用,因此该号码被断开连接。为该客户发起新的连接会话,即可重新连接该号码。
状态事件包含消息吗?
不包含。状态事件只涵盖连接的状态。号码的消息由 Meta 发送到其自身的 Webhook 目标,社交评论和私信则发送到各渠道各自的目标。
在哪里设置事件 URL?
在控制台中依次进入 Profile 和 Developers,或使用 MCP 工具 set_partner_events_url。签名密钥只显示一次,再次保存 URL 会颁发新的密钥。
如果只处理号码,可以忽略渠道事件吗?
可以。channel.* 事件有各自的名称,并携带 channel 对象而非 connection 对象,因此接收方可以跳过任何名称不以 connection 开头的事件。
继续阅读
两分钟连接您的第一个渠道。
无需等待平台审核。连接 WhatsApp、Instagram、TikTok 或其他渠道,然后让您的 AI 发布、回复或生成报告,看它如何运作。
- 免费试用 3 天
- 随时取消
- 仅使用官方 API
- 全天候 24/7 监控
验证时间