IngiaAnza kipindi cha majaribio bila malipo
Meta Tech Provider

Ujumbe wa WhatsApp unavyofika kwenye seva yako: moja kwa moja au kupitia otomatiki, na kuthibitisha saini

Kila nambari iliyounganishwa kupitia easyCoexistence ina hali moja ya ujumbe unaoingia. Moja kwa moja kwenye mfumo wako (moja kwa moja): Meta hutuma webhook zake kwenye endpoint yako ya HTTPS, siri iliyo kwenye URL ndiyo kitambulisho, na otomatiki zimezimwa. Kupitia easyCoexistence (inayosimamiwa): Meta hupeleka kwa easyCoexistence, otomatiki zinaweza kujibu, na Forward URL ya hiari hupokea thamani asili ya Meta pamoja na maelezo ya muunganisho, ikisainiwa kwa X-EC-Signature ili uithibitishe.

7 attempts

Majaribio kwa kila usambazaji, yaliyopangwa dakika 1, dakika 5, dakika 30, saa 2, saa 6 na saa 24 baada ya kila moja, jumla ya takriban saa 33.

10 s

Muda ambao kila jaribio la usambazaji husubiri jibu la 2xx kabla halijahesabiwa kuwa limeshindwa.

5 min

Kikomo kinachopendekezwa cha umri wa t ya saini; majaribio upya husainiwa tena, kwa hiyo uwasilishaji halisi unabaki ndani ya kikomo hicho.

7 days

Muda ambao Meta hurudia webhook ya moja kwa moja iliyopata kitu kingine isipokuwa HTTP 200, jambo linaloweza kurudia ujumbe.

3 MB

Payload kubwa zaidi ambayo Meta hutuma, pamoja na vipande vya historia.

30 days

Kumbukumbu za uendeshaji zinazohifadhiwa kwa nambari inayosimamiwa, pamoja na maandishi ya ujumbe na jibu; maandishi ya ujumbe yenyewe huhifadhiwa siku 30, 90 au 365, ni chaguo lako.

Tofauti kati ya moja kwa moja na inayosimamiwa ni ipi?

Mahali ambapo Meta hupeleka webhook za ujumbe wa nambari. Inayosimamiwa, inayoonyeshwa kama Kupitia easyCoexistence, inamaanisha Meta hupeleka kwa easyCoexistence, ambayo huthibitisha saini ya Meta, huendesha otomatiki zako, huhifadhi mazungumzo kwa ajili ya Conversations na, ukiweka Forward URL, hupitisha kila badiliko la Meta kwako likiwa limesainiwa kwa siri unayoishikilia wewe peke yako. Moja kwa moja, inayoonyeshwa kama Moja kwa moja kwenye mfumo wako, inamaanisha easyCoexistence huweka endpoint yako ya HTTPS kama webhook override kwenye WhatsApp Business Account ya nambari, hivyo Meta hukutumia moja kwa moja na ujumbe haufikii easyCoexistence kamwe.

Webhook za uendeshaji zinazosimamia ufuatiliaji, kama account_update na mabadiliko ya ubora, zinabaki kwa easyCoexistence katika hali zote mbili, ndiyo sababu arifa zinaendelea kufanya kazi kwa njia yoyote.

Managed: Through easyCoexistenceDirect: Straight to your system
Meta delivers toeasyCoexistence, which verifies Meta's signatureYour HTTPS endpoint
AutomationsRun on the numberOff
Your copyOptional Forward URL, one Meta change per POSTMeta's envelope, unchanged
Proof it is genuineX-EC-Signature, HMAC-SHA256 with the number's secretA long random secret in the URL path
Failed deliveries7 attempts over about 33 hoursMeta retries for up to 7 days
History importNot requestedRequested when saved within 24 hours of connecting
Kept by easyCoexistenceMessage text 30, 90 or 365 days, run logs 30 daysNothing

Unabadilishaje nambari kati ya hizi mbili?

Kwenye ukurasa wa nambari, kadi ya Ujumbe unaoingia unakwenda wapi inaonyesha hali kama chaguo mbili, Kupitia easyCoexistence na Moja kwa moja kwenye mfumo wako. Kuhifadhi lengwa la webhook, kwenye kadi ya Elekeza ujumbe unaoingia kwenye webhook yako au kwa set_webhook_destination, hufanya nambari iwe ya moja kwa moja. Kuchagua Kupitia easyCoexistence huondoa lengwa hilo kwa Meta mara moja, kwa hiyo ongeza URL ile ile kama Forward URL ili uendelee kupokea. Usambazaji uliopangwa foleni hufutwa nambari inapoondoka kwenye hali inayosimamiwa, na nambari zilizounganishwa bila webhook URL huanza zikiwa zinasimamiwa.

Kutoka kwa AI yako, set_inbound_mode hubadilisha hali na kuweka forward kwa wito mmoja, na hurudisha siri ya Forward mara moja tu:

set_inbound_mode: arguments and result
// set_inbound_mode arguments
{
  "connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "mode": "managed",
  "forward_url": "https://agent.example.com/ec/forward"
}

// result: forward_secret is shown once
{
  "connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "mode": "managed",
  "forward_url": "https://agent.example.com/ec/forward",
  "forward_secret": "whsec_Qm9vbXRoZXNlY3JldHNhcmVmYWtlMTIz",
  "secret_note": "Shown once. Verify X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with it; the body's value is Meta's original payload.",
  "direct_destination": null
}

Ni nini kilichomo kwenye POST iliyosambazwa?

Badiliko moja la Meta kwa kila ombi, limefungwa ndani yake, badala ya bahasha ya Meta ya object, entry na changes. id ni kitambulisho cha uwasilishaji, kinachorudiwa katika X-EC-Delivery na kisichobadilika katika majaribio upya. event ni jina la uga wa Meta: messages, smb_message_echoes, history au smb_app_state_sync, linalorudiwa katika X-EC-Event. received_at ni wakati easyCoexistence ilipopokea badiliko kutoka Meta, connection hutambulisha nambari, na value ni kile hasa Meta walichotuma, kwa hiyo msimbo wa kuchanganua uliondikwa kwa payload ya Meta unafanya kazi juu yake. Hali za uwasilishaji hufika ndani ya matukio ya messages, chini ya value.statuses.

A forwarded messages event: headers and body
POST /ec/forward HTTP/1.1
Content-Type: application/json
User-Agent: easyCoexistence-forward/1
X-EC-Event: messages
X-EC-Delivery: 8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13
X-EC-Signature: t=1794405732,v1=<64 hex characters>

{
  "id": "8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13",
  "event": "messages",
  "received_at": "2026-11-11T14:02:11.482Z",
  "connection": {
    "id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
    "phone": "+1 631-555-0142",
    "phone_number_id": "106540352242922",
    "waba_id": "102290129340398",
    "external_ref": null
  },
  "value": {
    "messaging_product": "whatsapp",
    "metadata": { "display_phone_number": "16315550142", "phone_number_id": "106540352242922" },
    "contacts": [{ "profile": { "name": "Ana Souza" }, "wa_id": "5511987654321", "user_id": "BR.13491208655302741918" }],
    "messages": [{
      "from": "5511987654321",
      "from_user_id": "BR.13491208655302741918",
      "id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjBDNzE4RjQ2QjI5RDkxQTNFAA==",
      "timestamp": "1794405731",
      "type": "text",
      "text": { "body": "Do you deliver on Sundays?" }
    }]
  }
}

Unathibitishaje X-EC-Signature kwenye Node.js?

Soma kichwa cha ombi kama t=<sekunde za unix>,v1=<herufi 64 za hex>. Kataa t inayotofautiana zaidi ya dakika 5 na saa yako, hesabu HMAC-SHA256 juu ya t, nukta, kisha raw body, ukitumia siri kamili ya Forward kama maandishi ya UTF-8, kisha linganisha matokeo na v1 kwa muda usiobadilika. Ndipo tu chambua JSON. Jibu 2xx ndani ya sekunde 10 na ufanye kazi baadaye, na kumbuka vitambulisho vya uwasilishaji ulivyokubali ili jaribio upya lisichakatwe mara mbili.

forward-receiver.mjs (Node.js, no dependencies)
// forward-receiver.mjs: node forward-receiver.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";

const SECRET = process.env.EC_FORWARD_SECRET; // the whole whsec_... string is the HMAC key
const taken = new Set(); // delivery ids already accepted: use a database in production

export function verifyEcSignature(raw, header, secret = SECRET, maxAgeSec = 300) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header ?? "").trim());
  if (!m || !secret) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(m[1])) > maxAgeSec) return false;
  const mac = crypto.createHmac("sha256", secret).update(`${m[1]}.`).update(raw).digest();
  return crypto.timingSafeEqual(mac, Buffer.from(m[2], "hex"));
}

http.createServer((req, res) => {
  const chunks = [];
  req.on("data", (c) => chunks.push(c));
  req.on("end", () => {
    const raw = Buffer.concat(chunks);
    if (req.method !== "POST" || !verifyEcSignature(raw, req.headers["x-ec-signature"])) {
      res.writeHead(401).end();
      return;
    }
    res.writeHead(200).end(); // a 2xx within 10 s, before any work
    const d = JSON.parse(raw.toString("utf8"));
    if (taken.has(d.id)) return; // a retry of a delivery already accepted
    taken.add(d.id);
    // d.event is the Meta field (messages, smb_message_echoes, history, smb_app_state_sync)
    // d.value is Meta's change value, unchanged; queue it for your worker here.
    console.log(d.event, d.connection.phone_number_id, Object.keys(d.value));
  });
}).listen(process.env.PORT ?? 3000);

Unathibitishaje kwenye Python?

Hatua nne zile zile kwa maktaba ya kawaida: muundo madhubuti wa kichwa, umri wa t, hmac.new juu ya t, nukta na raw bytes, na hmac.compare_digest. Kwenye FastAPI raw body hupatikana kwa await request.body(), na BackgroundTasks huendesha kazi baada ya 200 kutumwa. Kwenye Flask, tumia request.get_data(), na usijenge upya body kwa json.dumps kamwe, kwa sababu vitenganishi chaguo-msingi vya Python huongeza nafasi na saini hailingani tena.

forward_receiver.py (FastAPI)
# forward_receiver.py: pip install fastapi uvicorn, then uvicorn forward_receiver:app
import hashlib, hmac, json, os, re, time
from fastapi import BackgroundTasks, FastAPI, Request, Response

app = FastAPI()
SECRET = os.environ["EC_FORWARD_SECRET"].encode()  # the whole whsec_... string, as bytes
SIGNATURE = re.compile(r"t=([0-9]+),v1=([0-9a-f]{64})")
taken = set()  # delivery ids already accepted: use a database in production

def verify_ec_signature(raw: bytes, header: str, max_age: int = 300) -> bool:
    m = SIGNATURE.fullmatch(header.strip())
    if not m or abs(int(time.time()) - int(m[1])) > max_age:
        return False
    mac = hmac.new(SECRET, m[1].encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, m[2])

def process(delivery: dict) -> None:
    if delivery["id"] in taken:  # a retry of a delivery already accepted
        return
    taken.add(delivery["id"])
    print(delivery["event"], delivery["connection"]["phone_number_id"], list(delivery["value"]))

@app.post("/ec/forward")
async def forward(request: Request, tasks: BackgroundTasks):
    raw = await request.body()
    if not verify_ec_signature(raw, request.headers.get("x-ec-signature", "")):
        return Response(status_code=401)
    tasks.add_task(process, json.loads(raw))  # runs after the 200 goes out
    return Response(status_code=200)

Uwasilishaji ulioshindwa unajaribiwa upya vipi?

Usambazaji unahesabiwa kuwa umewasilishwa endpoint yako ikijibu 2xx yoyote ndani ya sekunde 10. Kitu kingine chochote, muda wa kusubiri umeisha, 4xx, 5xx au uelekezaji upya, ambao hufuatwa, hupanga jaribio linalofuata takriban dakika 1, dakika 5, dakika 30, saa 2, saa 6 na saa 24 baadaye, na baada ya jaribio la saba uwasilishaji unaachwa. Kila jaribio husainiwa upya kwa t mpya, na URL lazima iwe HTTPS ya umma, inayokaguliwa inapohifadhiwa na tena kabla ya kila utumaji. Usambazaji hutoka wa zamani kwanza, lakini uliojaribiwa upya unaweza kufika baada ya mpya zaidi, kwa hiyo panga kwa timestamps za Meta.

Kwenye lengwa la moja kwa moja Meta ndiye anayejaribu upya: chochote isipokuwa HTTP 200 hujaribiwa upya kwa kupungua kwa mara kwa mara kwa hadi siku 7, na majaribio hayo yanaweza kurudia ujumbe. Ondoa marudio kwa kitambulisho cha ujumbe cha Meta katika hali zote mbili, kwa sababu badiliko ambalo Meta alituma tena hutumwa tena chini ya kitambulisho kipya cha uwasilishaji.

Endpoint ya moja kwa moja inajuaje kwamba POST ni halisi?

Si kwa X-Hub-Signature-256. Meta husaini kwa siri ya programu inayomiliki usajili, ambayo kwa nambari iliyounganishwa hapa ni ya easyCoexistence na haishirikishwi, kwa hiyo kukagua kichwa hicho kwa siri ya programu yako ya Meta kunakataa uwasilishaji halisi. Verify token inathibitisha endpoint mara moja tu, wakati wa handshake ya GET ya Meta. Kinachofanya kazi badala yake:

  • Weka herufi 32 au zaidi nasibu kwenye njia ya callback URL na kataa maombi yasiyoinayo; kubadilisha, hifadhi URL mpya.
  • Tumia kipokezi cha jumla, kama node ya n8n Webhook, si WhatsApp trigger inayotarajia programu yako ya Meta.
  • Pakua media kwa kitambulisho kutoka Meta kwa token ya nambari, ili kitambulisho bandia kishindwe tu.
  • Kwenye seva unazozisimamia wenyewe, unaweza kuruhusu mtandao wa Meta pekee, yaani njia zinazotangazwa na AS32934.
  • Au badilisha hadi inayosimamiwa na Forward URL, ambapo X-EC-Signature inathibitisha kila POST.

Makosa ya kawaida

  • Kuelekeza msimbo ulioandikwa kwa bahasha ya Meta kwenye Forward URL bila mabadiliko. Forward hubeba badiliko moja: soma event na value, si object, entry na changes.
  • Kusubiri X-EC-Event ya statuses. Hali za uwasilishaji hufika ndani ya matukio ya messages, katika value.statuses, na majibu yaliyoandikwa kwenye programu hufika kama smb_message_echoes.
  • Kufanya kazi kabla ya kujibu. Forward husubiri sekunde 10, kisha uwasilishaji uleule unarudi na t mpya; jibu 2xx kwanza na uchakate kutoka kwenye foleni.
  • Kubadilisha hadi inayosimamiwa ukidhani URL ya zamani bado inapokea. Lengwa la moja kwa moja linaondolewa wakati huo; pitisha forward_url kwenye wito ule ule wa set_inbound_mode.
Kufanya hili ukitumia EasyCoexistence

easyCoexistence huunganisha nambari ya programu ya WhatsApp Business kwenye Cloud API ya Meta kupitia Coexistence, na hukuruhusu kuchagua, kwa kila nambari, ujumbe wake unakwenda wapi: moja kwa moja kutoka Meta kwenda kwenye seva yako, au kupitia easyCoexistence ili otomatiki ziweze kujibu na nakala iliyosainiwa ifike kwenye Forward URL yako. Ufuatiliaji na arifa hufanya kazi katika hali zote mbili. Kuanzia US$ 9 hadi US$ 0.75 kwa kila nambari kwa mwezi, inashuka kadri unavyoongeza nambari, na siku 3 za kwanza ni bila malipo.

Maswali yanayoulizwa mara kwa mara

Je, seva yangu itaona kile ambacho otomatiki ilijibu?

Si maandishi. Meta huripoti jumbe zinazotumwa na API kama hali (imetumwa, imewasilishwa, imesomwa) ndani ya matukio ya messages, pamoja na kitambulisho cha ujumbe; maandishi yenyewe yako kwenye kumbukumbu ya uendeshaji ya otomatiki, yanayohifadhiwa siku 30 kwenye kichupo cha Runs, na kwenye Conversations kwa muda uliochagua.

Ninabadilishaje siri ya Forward?

Bofya Siri mpya kwenye ukurasa wa nambari, au piga set_inbound_mode ukiweka rotate_secret kuwa true. Siri mpya huonyeshwa mara moja tu na husaini kila kitu kuanzia hapo, pamoja na majaribio upya ya uwasilishaji wa zamani, kwa hiyo sasisha seva yako mara moja.

Je, Forward URL inahitaji handshake ya GET ya Meta?

Hapana. Lengwa la moja kwa moja pekee ndilo linaloitwa na Meta na lazima lirudishe hub.challenge. Forward URL huitwa na easyCoexistence na hupokea POST zilizosainiwa tu.

Je, nambari inaweza kuwa na lengwa la moja kwa moja na Forward URL kwa wakati mmoja?

Hapana. Forward URL hufanya kazi tu wakati nambari inasimamiwa, na kuhifadhi lengwa la moja kwa moja hufanya nambari iwe ya moja kwa moja. Forward URL na siri yake huhifadhiwa, kwa hiyo kurudi kwenye hali inayosimamiwa kunaanzisha tena usambazaji.

Endelea kusoma

Uko tayari kuanza?

Sanidi WhatsApp Coexistence kwa dakika chache, si miezi. Programu inaendelea kufanya kazi kwenye simu.

Anza kipindi cha majaribio bila malipo

Imethibitishwa kwenye