IngiaAnza kipindi cha majaribio bila malipo
easyCoexistence API rasmi

Jinsi ya kupokea jumbe za WhatsApp na maoni ya mitandao ya kijamii ya wateja wako kwa webhook

Kila muunganisho hupata webhook yake kwa jumbe za WhatsApp za wateja wako au maoni ya mitandao ya kijamii, kupitia Partner API ya easyCoexistence. Jumbe za WhatsApp huenda moja kwa moja kutoka Meta hadi URL hiyo, zikisainiwa kwa siri ya programu ya Tech Provider wala si siri unayoshikilia wewe. Kwa hiyo siri ndefu ya nasibu kwenye njia ya URL ndiyo inayozithibitisha. Maoni na DM za Instagram na Facebook, pamoja na maoni ya TikTok, husambazwa yanavyofika, yakisainiwa kwa X-EC-Signature ya kila akaunti.

200 characters

Urefu wa juu zaidi ambao Meta inaruhusu kwa URL mbadala ya callback inayopeleka jumbe za nambari kwenye endpoint yako.

7 days

Muda ambao Meta hujaribu tena webhook ya WhatsApp ambayo endpoint yako haikuikubali, kwa mzunguko unaopungua, jambo linaloweza kuzalisha marudio.

AS32934

Mtandao wa Meta; utafutaji wa njia za whois kwake huorodhesha anwani ambazo webhook za WhatsApp hutoka, ambazo Meta hubadilisha mara kwa mara.

3 MB

Ukubwa mkubwa zaidi wa payload ya webhook ya WhatsApp, kwa mujibu wa Meta.

5 minutes

Umri ambao baada yake muhuri wa muda uliosainiwa wa tukio lililosambazwa unapaswa kukataliwa, huku HMAC ikilinganishwa kwa constant time.

Kila muunganisho hupataje lengwa lake?

Kupitia ombi moja kwa kila rasilimali. Nambari ya WhatsApp huchukua PUT /connections/{id}/webhook yenye url na verify_token, au jozi hiyo hiyo kama webhook_url na webhook_verify_token kwenye connect session yake, ili nambari ielekezwe kwako tangu dakika yake ya kwanza. Akaunti ya mitandao ya kijamii huchukua PUT /channels/{id}/webhook yenye url baada ya kuunganishwa. URL yenye thamani null kwenye yoyote kati ya hizo huzima uwasilishaji. Njia hizi mbili zinatofautiana kwa nani anayewasilisha na jinsi unavyothibitisha:

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

Jumbe za nambari yako zinaelekezwaje kwenye endpoint yako?

Mpe URL ya HTTPS ambayo njia yake ina siri ndefu ya nasibu, pamoja na verify token: webhook_verify_token kwenye connect session, herufi 8 hadi 200, au verify_token kwenye PUT. Meta huangalia URL mara moja kwa GET yenye hub.mode=subscribe, hub.verify_token na hub.challenge, na endpoint yako lazima ijibu kwa thamani ya hub.challenge token ikilingana. Ukaguzi huu wa awali ukishindwa, PUT hurudisha 502 meta_rejected pamoja na ujumbe wa Meta wenyewe. Kwenye connect session nambari bado huunganishwa, na last_error ya kipindi hicho inaeleza kwa nini URL haikutumika.

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

Kwa nini huwezi kukagua sahihi ya Meta, na nini kinachochukua nafasi yake?

Meta husaini kila uwasilishaji kwa kichwa cha X-Hub-Signature-256, HMAC-SHA256 ya payload iliyofungwa kwa App Secret ya programu inayopokea. Kwa nambari za wateja wako programu hiyo ni programu ya Tech Provider ya easyCoexistence, na siri yake haishirikishwi kamwe, kwa hiyo kichwa hicho hakiwezi kuthibitishwa upande wako. Siri ndefu ya nasibu kwenye njia ya URL ndiyo kitambulisho badala yake: ilinganishe kwa constant time na ukatae kila kitu kingine. Kama safu ya pili, weka kwenye orodha ya ruhusa njia zilizosajiliwa kwa AS32934 ya Meta na uisasishe, kwa sababu Meta hubadilisha anwani zake za IP mara kwa mara.

Ni webhook zipi za WhatsApp zinazofika kwenye URL yako?

Sehemu ambazo Meta inaruhusu URL mbadala ya callback kubeba: messages, kwa kile wateja wanachotuma na hali ya kile unachotuma; smb_message_echoes, kwa kile biashara inachotuma kutoka programu ya WhatsApp Business; na historia ya uingizaji wa mara moja pamoja na smb_app_state_sync. Meta haitumi kamwe webhook za template, wala webhook za akaunti kama account_update, kwenye ubatilishaji. Zinafikia callback ya easyCoexistence badala yake, ndiyo maana ukaguzi wa template husomwa kwa polling, na kuondolewa kwake hukufikia kama tukio la hali.

  • Lengwa huwekwa kwenye WhatsApp Business Account, kwa hiyo nambari mbili katika akaunti moja hushiriki lengwa hilo: elekeza kwa kutumia value.metadata.phone_number_id.
  • Midia hufika kama kitambulisho; pakua faili kutoka Meta kwa token ya mteja kutoka kwenye ombi la vitambulisho.
  • Payload zinaweza kufikia MB 3, kwa hiyo ongeza kikomo chochote cha ukubwa wa mwili kilichowekwa chini ya hapo.

Tukio la mitandao ya kijamii lililosambazwa linaonekanaje?

POST yenye Content-Type application/json na kichwa cha X-EC-Signature, ikibeba funguo nne: platform; account_id, kitambulisho cha chaneli ambacho Partner API hutumia; external_id, kitambulisho cha akaunti kwenye mtandao; na entry. Kwa Instagram na Facebook, entry ni webhook entry ya Meta bila mabadiliko, pamoja na changes kwa maoni na mentions na messaging kwa DM. Kwa TikTok ina tukio la comment.update lenye maudhui yaliyochambuliwa, na comment_id, video_id na parent_comment_id kama nyuzi, ili vitambulisho vya 64-bit visizungushwe.

  • Akaunti za Instagram zimejisajili kwa comments, messages na mentions; kurasa za Facebook kwa feed, messages na mention; TikTok hutuma comment.update.
  • easyCoexistence haipokei tukio la maoni kutoka YouTube wala LinkedIn: PUT yao hujibu 400 not_supported, na maoni yao husomwa kupitia API ya kila mtandao kwa kutumia vitambulisho.
  • Usambazaji hauna kichwa cha X-EC-Event wala X-EC-Delivery, kwa hiyo ondoa marudio kwa vitambulisho vya mtandao wenyewe, kama kitambulisho cha maoni au mid ya ujumbe.
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>" }
        }
      }
    ]
  }
}

Unathibitishaje X-EC-Signature, hatua kwa hatua?

Kwa kutumia signing_secret ambayo PUT /channels/{id}/webhook ilirudisha, inayoonyeshwa mara moja tu na ya kipekee kwa akaunti hiyo. Kichwa kinasomeka t=<unix>,v1=<hex>. Kisha, kwa kila uwasilishaji:

  • Soma mwili ghafi wa ombi kama baiti, kabla ya uchambuzi wowote wa JSON.
  • Gawanya kichwa kwa koma kuwa t, muda wa Unix kwa sekunde, na v1, digest ya hex.
  • Kataa uwasilishaji ikiwa t iko zaidi ya dakika 5 mbali na saa yako.
  • Hesabu HMAC-SHA256 juu ya t, nukta, kisha mwili ghafi, ukitumia siri ya akaunti hiyo, kama hex.
  • Linganisha na v1 kwa constant time, kisha jibu kwa 2xx na uweke kazi kwenye foleni.
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);
});

Nini kinatokea pale lengwa halijawekwa?

Hakuna kinachokufikia, na hakuna kinachosubiri kutumwa baadaye. Nambari isiyo na webhook_url hurudi kwenye callback ya easyCoexistence, ambako jumbe zake hutupwa bila kuhifadhiwa, na haipati uingizaji wa historia ya mazungumzo, ambao huombwa mara tu lengwa linapokuwepo. Akaunti ya mitandao ya kijamii isiyo nalo haisambazwi: matukio yake bado hufika kwenye programu ya easyCoexistence, lakini hakuna linalohifadhiwa kwa ajili yako. Weka kila lengwa kabla hujahitaji trafiki.

Lengwa linashughulikiwaje muunganisho ukikatika au ukiondolewa?

Nambari huhifadhi lengwa lake kwenye rekodi. Nambari iliyokatika ikiunganishwa tena, easyCoexistence huweka URL yako tena kwa Meta, na hilo hilo hutokea nambari iliyosimamishwa ikirudi. Kuondoa akaunti ya mitandao ya kijamii hufuta lengwa lake na siri yake, kwa hiyo baada ya kuunganishwa tena, piga PUT /channels/{id}/webhook tena na uhifadhi siri mpya. PUT hiyo hutoa siri mpya kila inapoitwa na URL, na ile ya zamani huacha kusaini papo hapo.

Jinsi ya kuisanidi

  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.

Makosa ya kawaida

  • Kukagua X-Hub-Signature-256 kwenye uwasilishaji wa jumbe za WhatsApp za wateja wako. Meta huihesabu kwa siri ya programu ya easyCoexistence, ambayo haishirikishwi kamwe, kwa hiyo ukaguzi hauwezi kupita. Thibitisha kwa siri iliyo kwenye njia ya URL.
  • Kuthibitisha X-EC-Signature juu ya JSON iliyochambuliwa. HMAC inafunika mwili ghafi baiti kwa baiti, na kuuandika upya kunabadilisha baiti, kwa hiyo thibitisha kabla ya uchambuzi.
  • Kutumia siri moja kwa kila chaneli. Kila akaunti ya mitandao ya kijamii husaini kwa siri yake, na matukio ya hali kwa nyingine, kwa hiyo tafuta siri kwa account_id.
  • Kufanya kazi nzito kabla ya kujibu tukio lililosambazwa. Hutumwa mara moja, husubiri sekunde 8 kwa jibu lako na haijaribiwi tena kamwe, kwa hiyo jibu 2xx kwanza kisha uchakate baadaye.
Kufanya hili ukitumia EasyCoexistence

easyCoexistence huelekeza jumbe za kila nambari ya mteja kutoka Meta moja kwa moja hadi seva yako, na husambaza maoni na DM za Instagram na Facebook, pamoja na maoni ya TikTok, kwenye endpoint yako yanavyofika, yakisainiwa kwa kila akaunti, bila nakala yoyote kuhifadhiwa. Kila muunganisho uko chini ya ufuatiliaji wa saa 24 kwa siku. Kuanzia US$ 9 hadi US$ 0.75 kwa kila muunganisho kwa mwezi, bei hupungua kadri unavyoongeza muunganisho, pamoja na siku 3 za kwanza bila malipo.

Maswali yanayoulizwa mara kwa mara

Naweza kukagua sahihi ya Meta kwenye jumbe za WhatsApp za wateja wako?

Hapana. Meta huzisaini kwa siri ya programu ya Tech Provider ya easyCoexistence, ambayo haishirikishwi kamwe. Thibitisha kwa siri ndefu ya nasibu kwenye njia ya URL yako, na hiari, kwa safu za IP za Meta.

Je, muunganisho wa YouTube na LinkedIn husambaza matukio ya maoni?

Hapana. easyCoexistence haipokei matukio ya maoni kutoka yoyote kati ya hayo, kwa hiyo PUT /channels/{id}/webhook hujibu 400 not_supported. Soma maoni yao kupitia API ya kila mtandao kwa kutumia vitambulisho vya chaneli.

Je, matukio ya mitandao ya kijamii yanayosambazwa hujaribiwa tena seva yako ikiwa chini?

Hapana. Kila moja hutumwa mara moja na hakuna nakala inayohifadhiwa. Uwasilishaji wa WhatsApp ni tofauti, kwa sababu Meta yenyewe hujaribu tena hadi siku 7.

Je, ujumbe hupita kwenye easyCoexistence?

Si kwenye WhatsApp: Meta hupeleka jumbe za nambari moja kwa moja kwenye webhook uliyoweka. Maoni na DM kutoka mitandao ya kijamii husambazwa kwenye endpoint yako yanavyofika, yakisainiwa kwa kila akaunti, bila nakala yoyote kuhifadhiwa.

Endelea kusoma

Unganisha chaneli yako ya kwanza ndani ya dakika mbili.

Hakuna ukaguzi wa majukwaa wa kusubiri. Unganisha WhatsApp, Instagram, TikTok au chaneli nyingine, kisha mwombe AI wako achapishe, ajibu au atoe ripoti, na uone akifanya kazi.

  • Siku 3 bila malipo
  • Ghairi wakati wowote
  • API rasmi pekee
  • Hufuatiliwa saa 24/7

Imethibitishwa kwenye