登录开始免费试用
Meta Tech Provider

一个号码。应用和 API,同时使用。

Coexistence 是 Meta 的官方模式,让 WhatsApp Business 应用和 Cloud API 同时在同一个号码上运行。团队继续用手机回复,聊天和历史记录都不变,同时软件在同一条线路上收发消息。

EasyCoexistence 会连接号码并持续监控连接。

开始免费试用免费 3 天。试用结束前不收取任何费用。
+1 415 555 0188
WhatsApp Business 应用团队照常用手机回复
Cloud API您的系统或 AI 助手,使用同一条线路
两端看到的是同一个对话。API 发送的内容会出现在应用中,团队在应用中输入的内容会以 smb_message_echoes 事件送达,因此软件绝不会在已经有人回复之后再重复回复。
默认不储存消息Business 应用 + Cloud API为 Claude 和 ChatGPT 提供 MCP2 分钟即可开始使用

曾经必须做的选择,如今不再需要

Coexistence 不是一个新的 API。它消除了一个岔路口,而正是这个岔路口让几乎所有小型企业都无法实现任何自动化。

以前一个号码,只能二选一
保留应用

团队用手机回复。无法自动化、无法对接,也无法衡量。

没有 API
迁移到 API

软件可以访问这个号码。Business 应用在该号码上停止工作,团队只能换工具。

没有应用
现在一个号码,两者兼得
一个号码
WhatsApp Business 应用Cloud API

Meta 将 Cloud API 连接到一个仍在使用 WhatsApp Business 应用的号码。两端在同一条线路上同时运行,并且都能看到对方发送的内容。

谁会这样使用号码

两类用户,对同一功能有着相反的需求,因此连接本身比其上的任何控制台都更重要。

保留手机只有一个号码的企业

一个小团队,一个印在货车或店面上的号码,每天晚上都在回答同样的四个问题。他们不是要取代任何人。他们希望确认消息、提醒和下班后的第一条回复无需人工即可完成,而手机仍然照常处理其他一切。

多个号码,一个账户代理机构、咨询公司或开发者

客户众多,每个客户都有一个不允许迁移、也不能改动的号码。他们需要让自己构建的系统能够访问这些号码,并且无需销售洽谈就能添加下一个号码。对于客户员工仍在手动回复的号码,Coexistence 是唯一的官方接入途径。

号码如何同时用于两端,以及消息事件流向何处

共四步。唯一需要动手机的是一次扫码,而决定您架构的是第一步。

  1. 在开始接入之前准备好端点

    Meta 在向目标地址投递之前会先验证它。它会向您的 URL 发送一个 GET 请求,其中带有 hub.mode=subscribe、您的 hub.verify_token 和一个 hub.challenge,您的端点必须原样返回这个 challenge 值。

    目标地址必须使用 HTTPS,并且必须提供验证令牌。我们会在发起调用之前校验这两项,因此格式错误的 URL 会在我们这一关就失败,而不会看起来已经连接、实际上却什么也收不到。

    前提
    一个能在 Meta 发出 GET 请求时返回 hub.challenge 的 HTTPS 端点
    耗时
    约 1 分钟
    结果
    号码一连接,Meta 就能立即验证的目标地址
    此时还没有任何连接。这一步决定消息最终送达哪里。
    路径中有服务商存储在他们的服务器上
    Meta
    他们的平台接收并存储消息
    您一份副本,按他们的节奏送达
    EasyCoexistence仅限配置
    Meta
    您的端点尚未验证
    我们我们设置路由,但不在路由上
  2. 运行 Meta 的 Embedded Signup,并在应用中扫码

    Meta 自己的弹出窗口会打开。您选择 Business Portfolio、WhatsApp Business 账户,以及已经在 WhatsApp Business 应用中注册的号码,然后在手机上扫描二维码来批准连接。

    您也在这一步选择是否共享现有聊天记录。这是接入时的一次性决定,之后无法更改。扫码完成的那一刻,Business 应用就会照常继续工作。

    前提
    Business Portfolio 的访问权限,以及使用该号码的手机
    耗时
    2 到 3 分钟
    结果
    Cloud API 连接到一个应用仍在使用的号码上
    第二端出现了,第一端并没有被移除。
    迁移之后只有一端
    该号码
    仅 Cloud API该号码上的 Business 应用已无法使用
    使用 Coexistence 之后两端并存
    该号码
    WhatsApp Business 应用相同的聊天和历史记录
    Cloud API在同一条线路上
  3. 将消息事件指向您自己的系统

    Meta 允许应用覆盖某个 WhatsApp Business 账户的 Webhook 投递位置。我们将这项覆盖设置指向您的 URL,从而让 messages 和 smb_message_echoes 这两个消息路径字段直接从 Meta 发送给您。

    我们保留运营字段,因为监控正是由它们构成的:account_update、phone_number_quality_update、account_alerts、account_review_update、business_capability_update 和 phone_number_name_update。因此控制台依然有用,而对话内容从不经过我们。

    前提
    第 1 步中的端点,现已通过 Meta 验证
    耗时
    接入完成后立即生效
    结果
    消息从 Meta 直接投递给您,我们不在消息路径上
    覆盖设置生效后,各类事件的去向。
    运营事件投递给我们
    account_update连接状态变化
    phone_number_quality_update质量和吞吐量
    account_review_update审核结果
    消息路径投递给您
    messages客户发送的所有内容
    smb_message_echoes团队从应用中发送的内容
    您的服务器直接送达,从不经过我们
  4. 保持连接活跃,并在重新连接后依然有效

    主设备连续约 14 天没有活动后,Meta 会断开 Coexistence 号码的连接。这种断开可以重新连接,我们将其记录为一种独立状态,而不是当作客户流失。

    容易让人踩坑的是断开连接对路由的影响。Meta 将目标地址作为一项覆盖设置,存放在我们的应用对该账户的订阅上,因此一次 PARTNER_REMOVED 会卸载应用,覆盖设置也随之消失。重新连接会恢复发送和监控,但不会恢复您的目标地址。我们会自动把它重新设置回去,因为第一个触发这条规则的号码虽然顺利重新连接,却悄无声息地停止了向客户服务器投递消息。

    前提
    不时在主设备上打开应用
    耗时
    持续进行
    结果
    一个有人监控的连接,以及一条在重新连接后依然有效的路由
    重新连接会自动恢复什么,以及哪些需要重新设置。
    由 Meta 恢复自动
    发送Cloud API 恢复工作
    运营事件监控恢复
    随应用一起丢失需要重新应用
    您的 Webhook 覆盖设置随应用一起被卸载
    向您投递消息悄无声息地停止
    我们重新应用每次重新连接时

为什么团队会这样使用号码

  • 保留已经印在货车、收据和网站上的号码,以及围绕它的手机工作流程。
  • 添加 API 发送、Webhook 处理和消息模板,无需让任何人迁移到新工具。
  • 让消息流量不经过服务商的共享收件箱,这样对话就不会存放在别人的平台上。
  • 让代理机构可以在一个账户中管理众多客户的号码,每个号码都连接在客户自己的 Business Portfolio 中。

资格要求与实际限制

  • 号码必须已经在 WhatsApp Business 应用中启用。使用普通 WhatsApp 应用的号码需要先转移到 WhatsApp Business 应用。
  • 是否共享现有聊天记录是在接入过程中做出的一次性选择,之后无法更改。
  • 在所有服务商中,Coexistence 号码的群聊都不在 API 范围内。
  • 主设备需要定期活动。如果连续约 14 天没有活动,Meta 会断开连接。
  • Coexistence 号码的 Meta 验证和徽章流程有所不同,各地区的可用性也会随 Meta 政策变化。
自由文本客户最后一条消息后的 0 到 24 小时仅限模板之后,直到客户再次发来消息
客户每发送一次消息,计时就会重新开始。这条规则会让集成在生产环境中出问题,因为测试总是在一条消息之后几秒内进行,那时自由文本仍然可以发送。

哪些内容转发给您,哪些由我们保留

Meta 允许应用覆盖 WhatsApp Business 账户投递 Webhook 的位置。我们将这项覆盖设置指向您的 URL,从而把事件分成两部分。

直接投递到您的端点消息路径。默认情况下从不经过我们。
  • messages客户发送到该号码的所有内容
  • smb_message_echoes您的团队通过 WhatsApp Business 应用发送的内容
投递给我们运营路径。监控正是由这些事件构成的。
  • account_update连接状态:已移除、已下线、已重新连接、已受限
  • phone_number_quality_update质量评级和吞吐量的变化
  • account_alertsMeta 针对该账户发出的警报
  • account_review_updateMeta 审核的结果
  • business_capability_update消息限额和功能的变化
  • phone_number_name_update显示名称的批准和拒绝

如果某个号码没有设置覆盖,它的消息事件会回落到我们的默认回调地址,处理程序会直接丢弃而不保存。这一点由代码强制执行,而不只是政策上的承诺:对话内容根本没有可以进入存储的路径。

14 天规则,以及它带来的、没人提起的问题

主设备连续约 14 天没有活动后,Meta 会断开 Coexistence 连接。连接可以恢复,因此我们将其记录为一种独立状态,而不是把它算作流失的客户。

真正让人付出代价的是后续影响。您的消息目标地址不是号码上的一项设置,而是我们的应用对 WhatsApp Business 账户订阅上的一项覆盖设置。断开连接会卸载该应用,覆盖设置也随之消失。重新连接后,发送正常,监控正常,但消息不再到达您的服务器,而且没有任何地方报错。

我们在每次重新连接时都会重新应用这项覆盖设置。之所以这样做,是因为这件事真的发生过:一个号码触发了这条规则,顺利重新连接,然后悄无声息地停止了投递。

如果此时握手失败,例如您的服务器宕机或令牌已更改,失败会记录在连接时间线上,目标地址会被保留而不是丢弃,因此只需再次保存即可修复。

哪些问题会悄无声息地出现,以及我们如何发现

在下面几乎所有的故障中,WhatsApp Business 应用都照常工作,所以没人察觉。以下是我们检查的问题,以及检查方式。

号码已断开连接Webhook,权威来源

通过 Meta 的 account_update Webhook 检测,具体是 PARTNER_REMOVED,而不是根据某个字段变为 false 来推断。我们刻意不读取 is_on_biz_app 来做判断,因为它在非 Coexistence 号码上本来就是 false,曾导致误报断开。

连接已沉寂 14 天独立状态

这是 Meta 的主设备不活跃规则。连接可以恢复,因此它被记录为一种独立状态,而不是流失的客户,重新连接即可恢复发送和监控。

重新连接后,您的 Webhook 路由消失了自动重新应用

目标地址是我们的应用对该账户订阅上的一项覆盖设置,因此断开连接会将其卸载。重新连接后发送会恢复,但投递到您服务器的消息不会恢复。我们每次都会重新应用这项覆盖设置,因为曾有一个号码遇到这种情况:顺利重新连接,却悄无声息地停止了投递。

访问令牌失效两个令牌,一个答案

我们针对同一个账户同时持有客户的令牌和我们自己的 System User token。当其中一个被拒绝时,另一个会读取账户,判断究竟是哪一个出了问题,因此被撤销的令牌不会再被误认为是丢失的号码。

质量下降轮询

定期从 Meta 轮询。RED 评级会将连接标记为降级,每次检查都会记录质量、消息层级和吞吐量级别,因此在质量下降导致发送失败之前就能看到。

连接一个号码和监控一个号码是两种不同的产品。我们正是为了后者而存在。

2 minutes

通过 WhatsApp Business 应用扫描二维码连接号码所需的常见时间。

24 hours

客户回复后,自由文本回复可以保持会话开放多久。

20 msg/s

Coexistence 号码的发送吞吐量,由 Meta 固定且无法提高。

6 months

号码首次连接时,Meta 会将多少聊天记录同步到 API。

常见问题

我的团队必须停止使用手机吗?

不必。这正是 Coexistence 的意义。WhatsApp Business 应用会继续在同一号码上运行,保留相同的对话,同时 API 与它并行运行。

我会失去现有对话吗?

不会。对话会保留在应用中,号码连接时 Meta 会将大约 6 个月的历史记录同步到 API,因此软件能获得上下文,而不是从空白开始。

我可以撤销吗?

可以。您可以断开号码,应用会继续像以前一样运行。连接本身不会永久改变号码。

这和非官方 WhatsApp API 一样吗?

不一样,这是不同产品。Coexistence 是 Cloud API 上的 Meta 官方功能;非官方网关通过已连接设备驱动 WhatsApp Web,会违反条款并导致号码被封禁。其费用不包含在 EasyCoexistence 订阅中,需向各提供商另行支付。

准备开始了吗?

几分钟即可设置 WhatsApp Coexistence,而不是几个月。应用会继续在手机上运行。

开始免费试用免费 3 天。试用结束前不收取任何费用。

继续阅读