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

如何透過 Webhook 接收客戶的 WhatsApp 訊息及社交平台留言

每個連接都有自己的 Webhook,用於接收客戶的 WhatsApp 訊息或社交平台留言,經由 easyCoexistence 的 Partner API 傳送。WhatsApp 訊息由 Meta 直接傳送到該 URL,簽署使用的是 Tech Provider 應用程式的密鑰,而非您持有的密鑰,因此 URL 路徑中一組夠長的隨機密鑰就是驗證方式。Instagram 及 Facebook 的留言與私訊,以及 TikTok 的留言,會在到達時即時轉發,並以各帳戶專屬的 X-EC-Signature 簽署。

200 characters

Meta 對替代回調 URL 所設的最大長度,該 URL 會將號碼的訊息傳送到您的端點。

7 days

Meta 重試您端點未接受之 WhatsApp Webhook 的時間長短,重試頻率逐步降低,可能會產生重複訊息。

AS32934

Meta 的網絡;whois 路由查詢會列出 WhatsApp Webhook 的來源位址,Meta 會定期更改這些位址。

3 MB

Meta 所定的 WhatsApp Webhook 負載最大容量。

5 minutes

轉發事件的簽署時間戳超過此時限即應拒絕;HMAC 須以常數時間比較。

每個連接如何獲得自己的目的地?

透過每項資源各一次調用。WhatsApp 號碼使用 PUT /connections/{id}/webhook,並提供 url 與 verify_token;或在其連接會話中提供相同組合的 webhook_url 與 webhook_verify_token,使號碼自第一分鐘起即路由至您。社交帳戶連接後,則使用 PUT /channels/{id}/webhook 並提供 url。任一項的 url 設為 null 即會停止傳送。兩條路徑的分別在於由誰傳送,以及您如何驗證:

WhatsApp numberInstagram, Facebook, TikTok
Set withwebhook_url on the session, or PUT /connections/{id}/webhookPUT /channels/{id}/webhook, after it connects
Delivered byMeta, straight to your URLeasyCoexistence, forwarding each event as it arrives
BodyMeta's webhook, unchangedplatform, account_id, external_id and the network's entry
AuthenticateA long random secret in the URL pathX-EC-Signature, keyed with the account's secret
RetriesMeta's own, for up to 7 daysNone: one attempt
Copy keptNoneNone

如何將號碼的訊息指向您的端點?

請提供一個 HTTPS URL,其路徑包含一組夠長的隨機密鑰,並提供驗證權杖:連接會話上的 webhook_verify_token(8 至 200 個字元),或 PUT 上的 verify_token。Meta 會立即以附帶 hub.mode=subscribe、hub.verify_token 及 hub.challenge 的 GET 請求檢查該 URL,權杖相符時,您的端點必須回覆 hub.challenge 的值。若該握手失敗,PUT 會返回 502 meta_rejected 及 Meta 的原始訊息;在連接會話中,號碼仍會連接,而該會話的 last_error 會說明 URL 未能套用的原因。

Node.js: Meta's handshake and the path secret
import express from "express";
import { timingSafeEqual } from "node:crypto";

const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();

function same(a, b) {
  const x = Buffer.from(String(a)), y = Buffer.from(String(b));
  return x.length === y.length && timingSafeEqual(x, y);
}

// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
  if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
  if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
    return res.sendStatus(403);
  }
  res.send(req.query["hub.challenge"]);
});

// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
  if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
  res.sendStatus(200); // answer first: Meta retries for up to 7 days
  enqueue(req.body); // deduplicate on each message id before acting
});

為何無法驗證 Meta 的簽署?該如何替代?

Meta 會以 X-Hub-Signature-256 簽署每次傳送,即以接收應用程式的 App Secret 為密鑰,對負載作 HMAC-SHA256。就您客戶的號碼而言,該應用程式是 easyCoexistence 的 Tech Provider 應用程式,其密鑰從不分享,因此您無法在本地驗證該標頭。取而代之的憑證是 URL 路徑中的隨機密鑰:請以常數時間比較,並拒絕其他一切請求。作為第二層保護,請將註冊給 Meta AS32934 的路由列入白名單,並定期更新該清單,因為 Meta 會定期更改其 IP 位址。

哪些 WhatsApp Webhook 會傳送到您的 URL?

Meta 允許覆寫 URL 攜帶的欄位包括:messages,用於客戶的來訊及您所發訊息的狀態;smb_message_echoes,用於商家從 WhatsApp Business 應用程式發出的訊息;以及一次性匯入的 history 與 smb_app_state_sync。Meta 從不會將訊息範本 Webhook,或 account_update 等帳戶 Webhook,傳送至覆寫 URL。這些會改為傳送至 easyCoexistence 的回調,因此範本審核須透過輪詢讀取,而遭拒的範本會以狀態事件通知您。

  • 目的地設於 WhatsApp Business Account 上,因此同一帳戶內的兩個號碼共用該目的地:請以 value.metadata.phone_number_id 作路由。
  • 媒體以 ID 形式傳入;請以客戶的權杖(取自憑證調用)從 Meta 取回檔案。
  • 負載可達 3 MB,請把任何低於此值的主體大小上限調高。

轉發的社交事件是什麼樣子?

一個 POST 請求,Content-Type 為 application/json,並附 X-EC-Signature 標頭,包含四個鍵:platform;account_id,即 Partner API 使用的頻道 ID;external_id,即帳戶在該網絡上的 ID;以及 entry。Instagram 及 Facebook 的 entry 保持 Meta 原本的 Webhook entry,留言與提及包含 changes,私訊則為 messaging。TikTok 的 entry 包含已解析內容的 comment.update 事件,並將 comment_id、video_id 與 parent_comment_id 以字串傳送,因此 64 位元 ID 不會被捨入。

  • Instagram 帳戶訂閱 comments、messages 及 mentions;Facebook 專頁訂閱 feed、messages 及 mention;TikTok 傳送 comment.update。
  • easyCoexistence 不會接收 YouTube 或 LinkedIn 的留言事件:其 PUT 會回應 400 not_supported,您可透過各網絡的 API,配合憑證讀取其留言。
  • 轉發時不會附上 X-EC-Event 或 X-EC-Delivery 標頭,因此請以網絡本身的 ID 去重,例如留言 ID 或訊息 mid。
A forwarded Instagram comment
{
  "platform": "instagram",
  "account_id": "<CHANNEL_ID>",
  "external_id": "<INSTAGRAM_ACCOUNT_ID>",
  "entry": {
    "id": "<INSTAGRAM_ACCOUNT_ID>",
    "time": 1793440800,
    "changes": [
      {
        "field": "comments",
        "value": {
          "id": "<COMMENT_ID>",
          "from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
          "text": "<COMMENT_TEXT>",
          "media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
        }
      }
    ]
  }
}

如何逐步驗證 X-EC-Signature?

使用 PUT /channels/{id}/webhook 所返回的 signing_secret,該密鑰只會顯示一次,並為該帳戶專屬。標頭格式為 t=<unix>,v1=<hex>。然後,對每次傳送執行以下步驟:

  • 以原始位元組讀取請求主體,須在任何 JSON 解析之前進行。
  • 以逗號拆分標頭,取得 t(以秒計的 Unix 時間)及 v1(十六進位摘要)。
  • 若 t 與您的時鐘相差超過 5 分鐘,則拒絕該次傳送。
  • 以該帳戶的密鑰,對 t、一個句點及原始主體計算 HMAC-SHA256,並以十六進位表示。
  • 以常數時間與 v1 比較,然後回覆 2xx,並將工作排入隊列。
Node.js: verifying a forwarded event
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database

app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
  const sig = Object.fromEntries(
    (req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
  );
  if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
    return res.sendStatus(401); // missing or stale timestamp
  }
  let event;
  try {
    event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
  } catch {
    return res.sendStatus(400);
  }
  const secret = secrets.get(event.account_id);
  if (!secret || !sig.v1) return res.sendStatus(401);
  const expected = createHmac("sha256", secret)
    .update(sig.t + ".")
    .update(req.body) // the raw bytes, exactly as they arrived
    .digest("hex");
  if (expected.length !== sig.v1.length ||
      !timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
    return res.sendStatus(401);
  }
  res.sendStatus(204); // one attempt and no retries: acknowledge, then work
  enqueue(event);
});

沒有設定目的地時會發生什麼事?

您不會收到任何內容,也不會有任何待稍後傳送的內容。沒有 webhook_url 的號碼會退回至 easyCoexistence 的回調,其訊息會被丟棄而不儲存,且不會進行聊天記錄匯入,該匯入只會在目的地存在後才會要求。沒有目的地的社交帳戶不會被轉發:其事件仍會到達 easyCoexistence 的應用程式,但不會為您保留任何內容。在需要流量之前,請先設定好各個目的地。

連接中斷或被移除時,其目的地會怎樣?

號碼會在記錄中保留其目的地。已中斷的號碼重新連接時,easyCoexistence 會再次向 Meta 設定您的 URL;被暫停的號碼恢復時亦然。移除社交帳戶會清除其目的地及密鑰,因此重新連接後,請再次調用 PUT /channels/{id}/webhook,並儲存新的密鑰。只要以 URL 調用該 PUT,即會發出新密鑰,而舊密鑰會立即停止簽署。

設定方法

  1. Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
  2. Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
  3. Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
  4. Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.

常見錯誤

  • 檢查客戶 WhatsApp 傳送的 X-Hub-Signature-256。Meta 是以 easyCoexistence 從不分享的應用程式密鑰計算,因此該檢查不可能通過;請改用 URL 路徑中的密鑰驗證。
  • 對已解析的 JSON 驗證 X-EC-Signature。HMAC 涵蓋原始主體的每個位元組,重新序列化會改變位元組,因此須先驗證再解析。
  • 所有頻道共用一個密鑰。每個社交帳戶以其專屬密鑰簽署,而狀態事件則以另一密鑰簽署,因此請以 account_id 查找密鑰。
  • 在回覆轉發的事件前進行耗時工作。事件只會發送一次,等候您回覆 8 秒,且從不重試,因此請先回覆 2xx,之後再處理。
使用 EasyCoexistence 完成這項設定

easyCoexistence 將每個客戶號碼的訊息由 Meta 直接路由至您的伺服器,並將 Instagram 及 Facebook 的留言與私訊,以及 TikTok 的留言,在到達時即時轉發至您的端點,以各帳戶專屬的方式簽署,不保留任何副本,並全天候 24/7 監控每項連接。每項連接每月 US$ 9 起,連接越多越便宜,最低降至 US$ 0.75,首 3 天免費。

常見問題

我能否驗證 Meta 在客戶 WhatsApp 訊息上的簽署?

不能。Meta 以 easyCoexistence 的 Tech Provider 應用程式密鑰簽署,而該密鑰從不分享。請以 URL 路徑中夠長的隨機密鑰驗證,並可選擇加上 Meta 的 IP 範圍。

YouTube 及 LinkedIn 的連接會轉發留言事件嗎?

不會。easyCoexistence 不會接收兩者的留言事件,因此 PUT /channels/{id}/webhook 會回應 400 not_supported。請透過各網絡的 API,並使用該頻道的憑證讀取其留言。

如果我的伺服器離線,轉發的社交事件會重試嗎?

不會。每項事件只傳送一次,且不保留副本。WhatsApp 的傳送則不同,因為 Meta 本身會重試,最長達 7 天。

訊息會經過 easyCoexistence 嗎?

WhatsApp 不會:Meta 會將號碼的訊息直接傳送至您設定的 Webhook。社交網絡的留言與私訊則會在到達時轉發至您的端點,以各帳戶專屬的方式簽署,且不保留副本。

繼續閱讀

兩分鐘內連接您的第一個頻道。

無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。

  • 免費試用 3 天
  • 隨時取消
  • 只用官方 API
  • 24/7 監察

驗證日期