让用户将 WhatsApp、Instagram 和 TikTok 账户连接到您的应用
要让用户将 WhatsApp、Instagram 和 TikTok 账户连接到您的应用,请使用 easyCoexistence 的 Partner API 创建连接会话,然后将用户引导至其托管的 url。用户可在该页面通过 Meta 的 Embedded Signup 连接 WhatsApp 号码,或登录 Instagram、Facebook、TikTok、YouTube、LinkedIn 等更多渠道,随后携带新的连接或渠道 id 返回您的 redirect_url。链接有效期为一小时。
连接链接的有效时长;此后会话显示为 expired,需要重新生成链接。
单个账户可同时保持打开的连接会话数上限,另有每小时最多创建 100 个新会话的限制。
GET /connect-sessions/:id 报告会话的状态:created、opened、connected、cancelled 或 expired。
Meta 接受的备用 callback URL 最长长度,用于将 WhatsApp 号码的消息 Webhook 路由到其他地址。
连接链接如何工作?
类似结账页面。您的后端创建会话,您的界面将客户引导至其 url,客户在 easycoexistence.com 的页面上完成连接,然后浏览器返回您的 redirect_url。随后,您的后端使用 API 密钥确认结果并获取新连接的凭据。
请求中包含哪些内容?
以 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 会立即将其消息投递到该地址。
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 可随时返回相同结构。
{
"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。
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 通过一个托管链接,将您客户的 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 监控
验证时间