如何讓用戶將 WhatsApp、Instagram 和 TikTok 帳戶連接至您的應用程式
如要讓用戶將 WhatsApp、Instagram 和 TikTok 帳戶連接到您的應用程式,請使用 easyCoexistence 的 Partner API 建立連接會話,並將用戶導向其託管 URL。用戶可在該頁面透過 Meta 的 Embedded Signup 連接 WhatsApp 號碼,或登入 Instagram、Facebook、TikTok、YouTube、LinkedIn 及更多渠道,之後返回您的 redirect_url,並附上新的連接或渠道 id。連結有效期為一小時。
連接連結的有效時限;時限過後,會話會顯示為已過期,需建立新的連結。
同一帳戶可同時開啟的連接會話數量,以及每小時 100 個新會話的上限。
GET /connect-sessions/:id 所報告的會話狀態:已建立、已開啟、已連接、已取消或已過期。
Meta 接受用於將 WhatsApp 號碼的訊息 Webhook 轉發至其他地方的替代 callback URL 最長長度。
連接連結如何運作?
類似結帳頁面。您的後端建立會話,您的介面將客戶導向其 URL,客戶在 easycoexistence.com 的頁面上完成連接,瀏覽器隨後返回您的 redirect_url。之後您的後端會確認結果,並取得新連接的憑證,全程使用您的 API 金鑰。
請求中包含哪些內容?
向 https://easycoexistence.com/api/v1/connect-sessions 以 POST 方式發送 JSON 主體,並以 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:
- 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 登入可一次帶入多個專頁:重定向會指明第一個,而篩選器會列出其餘項目。請使用您自己資料庫中的穩定 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 應用程式掃描的 QR 碼。若為社交帳戶,頁面只會顯示一個按鈕,例如「Continue with TikTok」,它會在同一分頁開啟該網絡自己的同意畫面,因此在手機上也能使用。
常見錯誤
- 僅信任查詢字串。任何人都可以在網址中輸入 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 上,一次登入可帶入多個專頁。完成後,連結會顯示為 connected,因此如需下一個連接,請建立新的會話。
我可以透過電郵或聊天工具發送連結嗎?
可以,只要客戶在一小時內開啟即可。網址中的會話 id 即是授權該頁面的憑證,因此請僅將每個連結發送給為其建立的客戶。
託管頁面在手機上能使用嗎?
社交登入可以,因為它們在同一分頁中開啟。WhatsApp 號碼最好在電腦上連接:在手機上,Meta 的彈出視窗會以新分頁開啟,而掃描 QR 碼則需要用手機本身。
如何在無需輪詢的情況下得知客戶已完成連接?
在控制台中依序選擇「Profile」、「Developers」,設定狀態事件 URL。easyCoexistence 隨後會在連接完成後立即發送 connection.connected 或 channel.connected,並附上簽名及您的 external_ref。
繼續閱讀
兩分鐘內連接您的第一個頻道。
無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。
- 免費試用 3 天
- 隨時取消
- 只用官方 API
- 24/7 監察
驗證日期