登录开始免费试用
easyCoexistence 官方 API

让用户将 WhatsApp、Instagram 和 TikTok 账户连接到您的应用

要让用户将 WhatsApp、Instagram 和 TikTok 账户连接到您的应用,请使用 easyCoexistence 的 Partner API 创建连接会话,然后将用户引导至其托管的 url。用户可在该页面通过 Meta 的 Embedded Signup 连接 WhatsApp 号码,或登录 Instagram、Facebook、TikTok、YouTube、LinkedIn 等更多渠道,随后携带新的连接或渠道 id 返回您的 redirect_url。链接有效期为一小时。

1 hour

连接链接的有效时长;此后会话显示为 expired,需要重新生成链接。

50 open

单个账户可同时保持打开的连接会话数上限,另有每小时最多创建 100 个新会话的限制。

5 statuses

GET /connect-sessions/:id 报告会话的状态:created、opened、connected、cancelled 或 expired。

200 characters

Meta 接受的备用 callback URL 最长长度,用于将 WhatsApp 号码的消息 Webhook 路由到其他地址。

连接链接如何工作?

类似结账页面。您的后端创建会话,您的界面将客户引导至其 url,客户在 easycoexistence.com 的页面上完成连接,然后浏览器返回您的 redirect_url。随后,您的后端使用 API 密钥确认结果并获取新连接的凭据。

1CreatePOST /connect-sessions from your backend
2SendA redirect or a new tab to the session's url
3ConnectMeta's Embedded Signup, or the network's own sign-in
4ReturnYour redirect_url, with the session, status and new id
5ConfirmGET /connect-sessions/:id, then the credentials

请求中包含哪些内容?

以 JSON 正文发送到 https://easycoexistence.com/api/v1/connect-sessions,并以 Bearer 访问令牌的形式传递您的 API 密钥。只有 redirect_url 为必填项:

  • redirect_url:客户之后落地的 https URL。
  • channel:默认为 whatsapp;或对您的账户开放的社交网络,按其小写名称填写,例如 instagram、tiktok 或 youtube。
  • external_ref:您为该客户设定的 id,最多 200 个字符。
  • partner_name:托管页面显示的名称,最多 80 个字符;默认为您的账户名称。
  • webhook_url 与 webhook_verify_token:仅适用于号码,且必须同时使用。号码连接后,Meta 会立即将其消息投递到该地址。
Create a session for a WhatsApp number
curl -X POST https://easycoexistence.com/api/v1/connect-sessions \
  -H "Authorization: Bearer $EC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "redirect_url": "https://app.example.com/connect/return",
    "external_ref": "customer_4821",
    "partner_name": "ClinicApp",
    "webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
    "webhook_verify_token": "another-long-random-string"
  }'

返回的内容是什么?

返回 201 及会话对象。将客户引导至 url,并保存以 cs_ 开头的 id,以便之后查询该会话。expires_at 为创建后一小时;客户完成连接后,connection_id 或 channel_id 会根据会话的渠道填入。GET /connect-sessions/:id 可随时返回相同结构。

201 Created
{
  "id": "cs_…",
  "url": "https://easycoexistence.com/connect/cs_…",
  "channel": "whatsapp",
  "status": "created",
  "external_ref": "customer_4821",
  "connection_id": null,
  "channel_id": null,
  "token_ready": false,
  "redirect_url": "https://app.example.com/connect/return",
  "webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
  "last_error": null,
  "expires_at": "2026-10-31T15:00:00.000Z",
  "opened_at": null,
  "finished_at": null,
  "created_at": "2026-10-31T14:00:00.000Z"
}

创建会话可能返回哪些错误?

每个错误的响应结构相同,均为包含 code 和 message 字段的对象,message 字段会说明需要修正的内容。创建会话时可能返回:

  • 400 invalid_json 或 invalid_request:正文不是 JSON 对象,或某个字段未通过验证,例如 redirect_url 不是 https。
  • 400 channel_unavailable:该渠道未对此账户开放;message 字段会列出目前可用的渠道。
  • 401 unauthorized:API 密钥缺失或无效。
  • 402 billing_required:账户尚未绑定信用卡,通过该账户连接的所有内容都将向其计费。
  • 429 cap_reached:已有 50 个会话处于打开状态;请等待部分会话完成或过期。
  • 429 rate_limited:本小时内会话数超过 100 个;message 字段会说明需要等待的时长。

客户之后会落地在哪里?

客户会落地到您的 redirect_url,结果附加在其查询字符串中。相同结果也保存在会话中,您的后端可通过 GET /connect-sessions/:id 读取:

  • session:会话 id,即 cs_ 加随机字符。
  • status:connected;客户选择 Cancel and go back 时则为 cancelled。
  • external_ref:您为该客户设定的 id(若会话包含该值)。
  • connection_id:新号码的 id,可用于 /connections。
  • channel_id:新社交账户的 id,可用于 /channels。
A number connected
https://app.example.com/connect/return?session=cs_…&status=connected&external_ref=customer_4821&connection_id=…

会话有哪些状态?

共五种。GET /connect-sessions/:id 返回当前状态,并包含 opened_at、finished_at 和 last_error;last_error 说明最近一次尝试失败的原因:

  • created:由您的后端创建,尚未打开。
  • opened:客户已加载托管页面。
  • connected:号码或社交账户已连接,其 id 会写入会话。
  • cancelled:客户通过「Cancel and go back」离开。
  • expired:一小时在会话完成前已到期。

链接有效多久?

自创建起一小时。此后,托管页面会告知客户链接已过期,并提供一个返回 redirect_url 的按钮(其 status=cancelled),同时会话显示为 expired。每个账户最多可同时保持 50 个打开的会话,每小时最多创建 100 个,原因是 Meta 会将每次首次入驻计入所有账户共享的应用级限额。

external_ref 有什么作用?

它将每个连接与您的客户关联。您发送的值会保存在会话所创建的号码或渠道上,附加在重定向中,并包含在关于该连接的每个状态事件中。因此,GET /connections?external_ref=customer_4821 和 GET /channels?external_ref=customer_4821 可列出该客户已连接的内容。Facebook 或 LinkedIn 登录可能一次返回多个 Page:重定向中给出第一个,过滤结果则列出其余的。请使用您自己数据库中的稳定 id,而不要使用可能变更的电子邮件。

如果客户取消或登录失败,会怎样?

这取决于发生的位置,但会话会保留相应记录:

  • Meta 的弹窗失败或被关闭:只要链接仍然有效,客户可在同一页面再次点击 Connect。
  • 社交登录被取消或被拒绝:客户会带着原因返回托管页面,并可在链接过期前重新尝试。
  • 该账户已通过另一个 easyCoexistence 账户连接:last_error 会说明此情况,客户需使用其他账户登录。
  • 客户选择「Cancel and go back」:您的 redirect_url 会收到 status=cancelled,会话随即关闭,如需重试,请创建新会话。
  • 链接已过期:请创建新会话。

如果号码连接时没有取得客户的访问令牌,会怎样?

Meta 有时会在 Embedded Signup 完成时,未发放客户自己的业务访问令牌。此时托管页面会要求再进行一次操作,通常只需几秒钟。若客户跳过该步骤,会话将显示为 connected,且 token_ready 为 false,您的事件 URL 会收到 connection.token_missing。此时号码可以接收消息,因其 id 有效,但在新的连接会话重新连接并发放访问令牌之前,无法发送消息。

如果 webhook_url 未通过 Meta 的检查,会怎样?

号码仍会正常连接。Meta 会用 GET 握手检查 webhook_url:当 hub.verify_token 匹配时,您的端点只需原样返回 hub.challenge 即可通过检查。若未通过,会话的 last_error 会以 webhook_url was not applied 开头,并给出 Meta 的原因。端点正常响应后,可用 PUT /connections/:id/webhook 设置目标地址。若在连接后 24 小时内完成设置,仍可接收一次性的联系人导入,以及在客户同意共享的情况下接收聊天记录。

客户会看到什么?

easycoexistence.com 上的一个页面,显示 partner_name 中的您的名称,无需填写账户、电子邮件或信用卡。对于 WhatsApp 号码,页面会先显示简短的资格检查清单,然后是 Meta 的弹窗,以及可用 WhatsApp Business 应用扫描的二维码。对于社交账户,页面只显示一个按钮,例如 Continue with TikTok,点击后会在同一标签页中打开该网络自己的授权页面,因此在手机上也能使用。

常见错误

  • 仅依赖查询字符串。任何人都能在 URL 中输入 status=connected,因此请先由您的后端调用 GET /connect-sessions/:id 进行确认,再将客户标记为已连接。
  • 将链接嵌入 iframe。应通过重定向或新标签页将客户引导至链接,这是托管页面及其打开的登录流程的设计运行方式。
  • 提前生成链接。每个链接有效期为一小时,且每个打开的链接都计入 50 个的上限,因此应在客户即将连接时再创建会话。
  • 发送超过 200 个字符的 webhook_url。Meta 只接受最长 200 个字符的备用 callback URL,超出的地址不会生效,号码将在未设置该地址的情况下连接。
使用 EasyCoexistence 完成这些操作

easyCoexistence 通过一个托管链接,将您客户的 WhatsApp 号码,以及其 Instagram、Facebook、TikTok、YouTube 和 LinkedIn 账户等更多渠道,连接到您的软件,并为您的后端提供每个连接的凭据、Webhook 和带签名的状态事件。每个连接每月 US$ 9 起,连接越多越便宜,最低降至 US$ 0.75,并提供前 3 天免费试用。

常见问题

一个连接链接可以使用两次吗?

不可以。一个链接只能完成一个号码的连接,或一次社交登录;在 Facebook 或 LinkedIn 上,一次登录可能带来多个 Page。之后链接会显示为 connected,因此下一个连接需要创建新会话。

可以通过电子邮件或聊天发送链接吗?

可以,只要客户在一小时内打开。URL 中的会话 id 用于授权访问该页面,因此请只将每个链接发送给为其创建该链接的客户。

托管页面能在手机上使用吗?

社交登录可以,因为它们在同一标签页中打开。WhatsApp 号码最好在电脑上连接:在手机上,Meta 的弹窗会在新标签页中打开,而扫描二维码则需要使用手机本身。

如何在不轮询的情况下得知客户已连接?

在控制台的 Profile 下的 Developers 中设置状态事件 URL。连接完成后,easyCoexistence 会立即发送 connection.connected 或 channel.connected 事件,该事件带有签名,并包含您的 external_ref。

继续阅读

两分钟连接您的第一个渠道。

无需等待平台审核。连接 WhatsApp、Instagram、TikTok 或其他渠道,然后让您的 AI 发布、回复或生成报告,看它如何运作。

  • 免费试用 3 天
  • 随时取消
  • 仅使用官方 API
  • 全天候 24/7 监控

验证时间