Log masukMulakan percubaan percuma
easyCoexistence API rasmi

Cara menerima mesej WhatsApp dan komen media sosial pelanggan anda melalui webhook

Setiap sambungan mendapat webhook sendiri untuk mesej WhatsApp atau komen media sosial pelanggan anda melalui Partner API easyCoexistence. Mesej WhatsApp dihantar terus dari Meta ke URL tersebut, ditandatangani dengan rahsia aplikasi Tech Provider dan bukan rahsia yang anda pegang, jadi rahsia rawak yang panjang dalam laluan URL mengesahkannya. Komen dan DM Instagram serta Facebook, dan komen TikTok, diteruskan sebaik sahaja tiba, ditandatangani mengikut akaun dengan X-EC-Signature.

200 characters

Panjang maksimum Meta untuk URL panggilan balik alternatif yang menghantar mesej sesuatu nombor ke endpoint anda.

7 days

Berapa lama Meta mencuba semula webhook WhatsApp yang tidak diterima oleh endpoint anda, dengan kekerapan yang semakin berkurang, yang boleh menghasilkan pendua.

AS32934

Rangkaian Meta; carian laluan whois untuknya menyenaraikan alamat tempat webhook WhatsApp datang, yang ditukar Meta secara berkala.

3 MB

Saiz terbesar yang boleh dicapai oleh payload webhook WhatsApp, menurut Meta.

5 minutes

Tempoh selepas itu cap masa bertanda bagi peristiwa yang diteruskan hendaklah ditolak, dengan HMAC dibandingkan dalam masa malar.

Bagaimana setiap sambungan mendapat destinasinya sendiri?

Melalui satu panggilan bagi setiap sumber. Nombor WhatsApp menggunakan PUT /connections/{id}/webhook dengan url dan verify_token, atau pasangan yang sama sebagai webhook_url dan webhook_verify_token pada sesi sambungannya, supaya nombor itu menghala kepada anda sejak minit pertama. Akaun media sosial menggunakan PUT /channels/{id}/webhook sebaik sahaja ia bersambung. Url bernilai null pada mana-mana satu akan mematikan penghantaran. Kedua-dua laluan berbeza dari segi siapa yang menghantar dan bagaimana anda mengesahkan:

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

Bagaimana anda menghalakan mesej sesuatu nombor ke endpoint anda?

Berikan URL HTTPS yang laluannya memuatkan rahsia rawak yang panjang, serta verify token: webhook_verify_token pada sesi sambungan, 8 hingga 200 aksara, atau verify_token pada PUT. Meta menyemak URL itu serta-merta dengan GET yang membawa hub.mode=subscribe, hub.verify_token dan hub.challenge, dan endpoint anda mesti menjawab dengan nilai hub.challenge apabila token sepadan. Jika jabat tangan itu gagal, PUT mengembalikan 502 meta_rejected dengan mesej Meta sendiri; pada sesi sambungan nombor itu tetap bersambung, dan last_error sesi menyatakan sebab URL tidak digunakan.

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
});

Mengapa anda tidak boleh menyemak tandatangan Meta, dan apa yang menggantikannya?

Meta menandatangani setiap penghantaran dengan X-Hub-Signature-256, iaitu HMAC-SHA256 bagi payload yang dikunci dengan App Secret aplikasi penerima. Bagi nombor pelanggan anda, aplikasi itu ialah aplikasi Tech Provider easyCoexistence, dan rahsianya tidak pernah dikongsi, jadi header itu tidak dapat disahkan di pihak anda. Rahsia rawak yang panjang dalam laluan URL menjadi kelayakan sebagai gantinya: bandingkan dalam masa malar dan tolak apa-apa selainnya. Sebagai lapisan kedua, senarai putih laluan yang didaftarkan kepada AS32934 milik Meta dan kemas kini senarai itu, kerana Meta menukar alamat IP secara berkala.

Webhook WhatsApp yang manakah sampai ke URL anda?

Medan yang dibenarkan Meta untuk dibawa oleh URL panggilan balik alternatif: messages, bagi apa yang dihantar pelanggan dan status apa yang anda hantar; smb_message_echoes, bagi apa yang dihantar perniagaan dari aplikasi WhatsApp Business; dan history serta smb_app_state_sync bagi import sekali sahaja. Meta tidak pernah menghantar webhook template, atau webhook akaun seperti account_update, ke gantian. Ia sebaliknya sampai ke panggilan balik easyCoexistence, dan sebab itulah semakan template dibaca melalui pengundian dan penurunan dilaporkan kepada anda sebagai peristiwa status.

  • Destinasi ditetapkan pada WhatsApp Business Account, jadi dua nombor dalam satu akaun berkongsinya: halakan mengikut value.metadata.phone_number_id.
  • Media tiba sebagai ID; ambil fail itu dari Meta dengan token pelanggan daripada panggilan kelayakan.
  • Payload boleh mencapai 3 MB, jadi naikkan had saiz badan yang ditetapkan di bawah nilai itu.

Apa bentuk peristiwa media sosial yang diteruskan?

Satu POST dengan Content-Type application/json dan header X-EC-Signature, membawa empat kunci: platform; account_id, ID saluran yang digunakan oleh Partner API; external_id, ID akaun di rangkaian; dan entry. Bagi Instagram dan Facebook, entry ialah entri webhook Meta tanpa diubah, dengan changes bagi komen dan sebutan serta messaging bagi DM. Bagi TikTok ia memuatkan peristiwa comment.update dengan kandungannya dihuraikan, dan comment_id, video_id serta parent_comment_id sebagai string, supaya ID 64-bit tidak dibundarkan.

  • Akaun Instagram dilanggan kepada komen, mesej dan sebutan; halaman Facebook kepada feed, mesej dan sebutan; TikTok menghantar comment.update.
  • easyCoexistence tidak menerima peristiwa komen daripada YouTube atau LinkedIn: PUT mereka menjawab 400 not_supported, dan komen mereka dibaca melalui API setiap rangkaian dengan kelayakan.
  • Penghantaran tidak membawa header X-EC-Event atau X-EC-Delivery, maka buang pendua menggunakan ID asal rangkaian, seperti ID komen atau mid mesej.
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>" }
        }
      }
    ]
  }
}

Bagaimana anda mengesahkan X-EC-Signature, langkah demi langkah?

Dengan signing_secret yang dikembalikan oleh PUT /channels/{id}/webhook, yang hanya dipaparkan sekali dan unik bagi akaun itu. Header berbunyi t=<unix>,v1=<hex>. Kemudian, bagi setiap penghantaran:

  • Baca badan permintaan mentah sebagai bait, sebelum sebarang penghuraian JSON.
  • Pisahkan header dengan koma kepada t, masa Unix dalam saat, dan v1, digest hex.
  • Tolak penghantaran jika t lebih daripada 5 minit daripada jam anda.
  • Kira HMAC-SHA256 ke atas t, titik dan badan mentah, dikunci dengan rahsia akaun itu, sebagai hex.
  • Bandingkan dengan v1 dalam masa malar, kemudian jawab 2xx dan masukkan kerja ke dalam giliran.
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);
});

Apa yang berlaku apabila tiada destinasi ditetapkan?

Tiada apa yang sampai kepada anda, dan tiada apa yang menunggu untuk dihantar kemudian. Nombor tanpa webhook_url akan jatuh balik ke panggilan balik easyCoexistence, tempat mesejnya digugurkan tanpa disimpan, dan ia tidak menerima import sejarah sembang, yang hanya diminta selepas destinasi wujud. Akaun media sosial tanpa destinasi tidak diteruskan: peristiwanya masih sampai ke aplikasi easyCoexistence, tetapi tiada satu pun disimpan untuk anda. Tetapkan setiap destinasi sebelum anda memerlukan trafiknya.

Apa yang berlaku kepada destinasi apabila sambungan terputus atau dibuang?

Nombor mengekalkan destinasinya dalam rekod. Apabila nombor yang terputus bersambung semula, easyCoexistence menetapkan semula URL anda dengan Meta, dan perkara yang sama berlaku apabila nombor yang digantung kembali aktif. Membuang akaun media sosial mengosongkan destinasi dan rahsianya, jadi selepas ia bersambung semula, panggil PUT /channels/{id}/webhook sekali lagi dan simpan rahsia baharu. PUT itu mengeluarkan rahsia baharu setiap kali ia dipanggil dengan URL, dan rahsia lama berhenti menandatangani serta-merta.

Cara menetapkannya

  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.

Kesilapan biasa

  • Menyemak X-Hub-Signature-256 pada penghantaran WhatsApp pelanggan anda. Meta mengiranya dengan rahsia aplikasi easyCoexistence, yang tidak pernah dikongsi, jadi semakan itu tidak akan lulus; sahkan dengan rahsia dalam laluan URL.
  • Mengesahkan X-EC-Signature ke atas JSON yang sudah dihuraikan. HMAC meliputi badan mentah bait demi bait, dan menyerialisasi semula data akan menukar bait, jadi sahkan sebelum menghurai.
  • Menggunakan satu rahsia untuk setiap saluran. Setiap akaun media sosial menandatangani dengan rahsianya sendiri, dan peristiwa status dengan rahsia yang lain, jadi cari rahsia mengikut account_id.
  • Melakukan kerja yang perlahan sebelum menjawab peristiwa yang diteruskan. Ia dihantar sekali, menunggu 8 saat untuk jawapan anda dan tidak pernah dicuba semula, jadi jawab 2xx dahulu dan proses kemudian.
Menggunakan EasyCoexistence untuk ini

easyCoexistence menghala mesej setiap nombor pelanggan dari Meta terus ke pelayan anda dan meneruskan komen serta DM Instagram dan Facebook, dan komen TikTok, ke endpoint anda sebaik sahaja tiba, ditandatangani mengikut akaun, tanpa salinan disimpan dan setiap sambungan dipantau 24/7. US$ 9 hingga US$ 0.75 setiap sambungan sebulan, menurun apabila anda menambah sambungan, dengan 3 hari pertama percuma.

Soalan lazim

Bolehkah saya mengesahkan tandatangan Meta pada mesej WhatsApp pelanggan saya?

Tidak. Meta menandatanganinya dengan rahsia aplikasi Tech Provider easyCoexistence, yang tidak pernah dikongsi. Sahkan dengan rahsia rawak yang panjang dalam laluan URL anda, dan jika mahu, julat IP Meta.

Adakah sambungan YouTube dan LinkedIn meneruskan peristiwa komen?

Tidak. easyCoexistence tidak menerima peristiwa komen daripada mana-mana satu, jadi PUT /channels/{id}/webhook menjawab 400 not_supported. Baca komen mereka melalui API setiap rangkaian dengan kelayakan saluran.

Adakah peristiwa media sosial yang diteruskan dicuba semula jika pelayan saya tidak aktif?

Tidak. Setiap satu dihantar sekali dan tiada salinan disimpan. Penghantaran WhatsApp berbeza, kerana Meta sendiri mencuba semula sehingga 7 hari.

Adakah mesej melalui easyCoexistence?

Tidak di WhatsApp: Meta menghantar mesej sesuatu nombor terus ke webhook yang anda tetapkan. Komen dan DM daripada rangkaian media sosial diteruskan ke endpoint anda sebaik sahaja tiba, ditandatangani mengikut akaun, tanpa salinan disimpan.

Teruskan membaca

Sambungkan saluran pertama anda dalam masa dua minit.

Tidak perlu menunggu semakan platform. Sambungkan WhatsApp, Instagram, TikTok atau saluran lain, kemudian minta AI anda menyiarkan, membalas atau melaporkan, dan lihat ia bekerja.

  • 3 hari percuma
  • Batal bila-bila masa
  • API rasmi sahaja
  • Dipantau 24/7

Disahkan pada