登入開始免費試用
easyCoexistence 官方 API

如何讓用戶將 WhatsApp、Instagram 和 TikTok 帳戶連接至您的應用程式

如要讓用戶將 WhatsApp、Instagram 和 TikTok 帳戶連接到您的應用程式,請使用 easyCoexistence 的 Partner API 建立連接會話,並將用戶導向其託管 URL。用戶可在該頁面透過 Meta 的 Embedded Signup 連接 WhatsApp 號碼,或登入 Instagram、Facebook、TikTok、YouTube、LinkedIn 及更多渠道,之後返回您的 redirect_url,並附上新的連接或渠道 id。連結有效期為一小時。

1 hour

連接連結的有效時限;時限過後,會話會顯示為已過期,需建立新的連結。

50 open

同一帳戶可同時開啟的連接會話數量,以及每小時 100 個新會話的上限。

5 statuses

GET /connect-sessions/:id 所報告的會話狀態:已建立、已開啟、已連接、已取消或已過期。

200 characters

Meta 接受用於將 WhatsApp 號碼的訊息 Webhook 轉發至其他地方的替代 callback URL 最長長度。

連接連結如何運作?

類似結帳頁面。您的後端建立會話,您的介面將客戶導向其 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

請求中包含哪些內容?

向 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 會自號碼連接的那一刻起,將其訊息發送至此處。
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:

  • 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 完成這項設定

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 監察

驗證日期