IngiaAnza kipindi cha majaribio bila malipo
Meta Tech Provider

Jenga wakala wa AI wa WhatsApp kwa Node.js na Python kwenye nambari ya Coexistence

Pokea jumbe za nambari hii ama ukisambazwa ukiwa na saini ya HMAC unayoithibitisha (X-EC-Signature), au moja kwa moja kutoka kwenye webhook ya Meta yenye siri kwenye URL. Kisha ruka kila kitambulisho cha ujumbe kilichoshughulikiwa tayari, kaa kimya kwenye mazungumzo ambapo echo inaonyesha mtu alijibu kutoka simuni, na tuma jibu la modeli yako kupitia Cloud API ndani ya saa 24 tu tangu ujumbe wa mwisho wa mteja.

easyCoexistence inaunganisha nambari ambayo biashara inaendelea kuitumia kwenye programu ya WhatsApp Business na Cloud API ya Meta, inatoa vitambulisho vya msimbo wako kupitia get_api_credentials, na huelekeza ujumbe moja kwa moja kutoka Meta kwenda kwenye seva yako au kupitia usambazaji uliosainiwa huku Automations zikiwa zimewashwa.

5 min

Pengo kubwa zaidi linaloruhusiwa kati ya t ya saini na saa yako; kila jaribio upya husainiwa tena kwa t mpya.

10 s

Muda ambao POST iliyosambazwa inasubiri jibu la 2xx kabla easyCoexistence haijapanga jaribio upya la uwasilishaji huo.

7 days

Muda ambao Meta hujaribu upya webhook ya moja kwa moja isiyopata HTTP 200, jambo linaloweza kuwasilisha ujumbe uleule mara mbili.

24 hours

Dirisha la huduma kwa wateja baada ya ujumbe wa mwisho wa mtumiaji; nje yake, Meta inakubali template pekee.

20 mps

Kiwango kisichobadilika cha uchakataji wa nambari inayotumika pamoja na programu ya WhatsApp Business na Cloud API.

Ni njia ipi wakala aliyeandikwa kwa msimbo anapaswa kutumia?

Kusambaza kunamaanisha nambari inabaki kwenye Automations zikiwa zimewashwa: Meta inawasilisha kwa easyCoexistence, Automations bado zinaweza kufanya kazi, na nakala iliyosainiwa ya kila mabadiliko ya Meta inatumwa kwenye Forward URL yako. Tofauti moja haihitaji usambazaji wowote: hatua ya Automations ya Call my webhook hutuma POST ya ujumbe kwenye endpoint yako na kutuma chochote {"reply"} unachorudisha ndani ya sekunde 20, huku kuondoa marudio, kusimama kwa simu na ukaguzi wa saa 24 vikifanywa kwa ajili yako.

Moja kwa moja maana yake Meta inatuma webhook yake moja kwa moja kwenye endpoint yako, iliyowekwa kwa set_webhook_destination, na easyCoexistence haioni ujumbe kamwe. Automations zimezimwa kwa nambari hiyo, kwa hiyo kila ulinzi ni wako, na pia uingizaji wa historia wa miezi 6 ni wako ikiwa lengwa limehifadhiwa ndani ya saa 24 tangu kuunganisha. Mifano iliyo hapa chini inashughulikia njia zote tatu kwa msingi mmoja wa pamoja.

Forwarded, signedDirect from Meta
Number modeAutomations on (managed)Direct to your server
BodyOne Meta change: id, event, received_at, connection, valueMeta's envelope: object, entry, changes
AuthenticationX-EC-Signature, HMAC-SHA256 with a per-number secretA secret in the URL path
AcknowledgeAny 2xx within 10 secondsHTTP 200; Meta retries other codes
Retries7 attempts over about 33 hoursUp to 7 days
ReplyGraph API, or {"reply"} to a Call my webhook stepGraph API
History importNot requestedRequested if saved within 24 hours of connecting

Wakala hufanya nini na ujumbe, kwenye Node.js?

agent.mjs ina mantiki ambayo njia zote mbili zinashiriki. Inarekodi muda wa ujumbe wa mwisho wa mteja, inasimama nyuma kwa saa 4 kwenye mazungumzo pale tukio la smb_message_echoes linapoonyesha mtu alijibu kutoka programu ya WhatsApp Business (ambayo Automations za easyCoexistence hutumia kwa chaguo-msingi), inaruka kitambulisho cha ujumbe ambacho tayari kimeshughulikiwa, na hutuma tu ndani ya dirisha la saa 24. Dirisha hupimwa kutoka kwenye timestamp ya ujumbe wenyewe, si kutoka wakati ulipokufikia, kwa sababu uwasilishaji uliojaribiwa upya unaweza kufika saa kadhaa baadaye.

Watumiaji wanatambulishwa kwa BSUID (from_user_id, au to_user_id kwenye echo) huku nambari ya simu ikiwa mbadala, na mtumiaji anayejulikana kwa BSUID pekee hujibiwa kwa recipient badala ya to. Wito wa modeli hutumia API yoyote ya chat completions inayooana na OpenAI; badilisha na SDK ya mtoa huduma wako ukipendelea.

agent.mjs: the shared logic
// agent.mjs: what the agent does with one Meta change, whichever route brought it.
const DAY = 24 * 3600 * 1000;
const PAUSE = 4 * 3600 * 1000;   // quiet time after a person replies (automations default to 4 h)
const seen = new Set();          // handled ids: use Redis or your database in production
const lastInbound = new Map();   // user -> ms of their last message
const quietUntil = new Map();    // user -> ms until which a person has the chat

export function firstTime(id) {
  if (seen.has(id)) return false;
  seen.add(id);
  return true;
}

export async function handleChange(field, value) {
  if (field === "smb_message_echoes") {
    // Someone answered from the WhatsApp Business app: step back on that chat.
    for (const e of value.message_echoes ?? []) {
      quietUntil.set(e.to_user_id ?? e.to, Number(e.timestamp) * 1000 + PAUSE);
    }
    return;
  }
  if (field !== "messages") return;              // statuses ride in value.statuses: ignored here
  for (const m of value.messages ?? []) {
    if (!firstTime(m.id)) continue;               // Meta delivered this message before
    const user = m.from_user_id ?? m.from;        // BSUID first, phone number as fallback
    lastInbound.set(user, Math.max(Number(m.timestamp) * 1000, lastInbound.get(user) ?? 0));
    if ((quietUntil.get(user) ?? 0) > Date.now()) continue; // a person has this chat
    if (m.type !== "text") continue;              // media: fetch it by id first (see the FAQ)
    const reply = await askModel([{ role: "user", content: m.text.body }]);
    if (!reply) continue;
    if (Date.now() - lastInbound.get(user) >= DAY) continue; // window closed: template only
    await sendText({ phone: m.from, bsuid: m.from_user_id }, reply);
  }
}

// Any OpenAI-compatible chat completions API (OpenAI, OpenRouter...).
export async function askModel(turns) {
  const res = await fetch(`${process.env.AI_BASE_URL}/chat/completions`, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.AI_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      model: process.env.AI_MODEL,
      messages: [{ role: "system", content: process.env.AI_INSTRUCTIONS ?? "Answer briefly." }, ...turns],
    }),
  });
  if (!res.ok) throw new Error(`AI provider answered ${res.status}`);
  const data = await res.json();
  return data.choices?.[0]?.message?.content?.trim() ?? "";
}

// send_endpoint and access_token come from get_api_credentials.
async function sendText({ phone, bsuid }, text) {
  const res = await fetch(process.env.SEND_ENDPOINT, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.WA_TOKEN}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      messaging_product: "whatsapp",
      recipient_type: "individual",
      ...(phone ? { to: phone } : { recipient: bsuid }), // a BSUID-only user gets recipient
      type: "text",
      text: { body: text.slice(0, 4096) },
    }),
  });
  if (!res.ok) throw new Error(`Graph API answered ${res.status}: ${await res.text()}`);
}

Je, unathibitisha na kuelekeza matukio vipi kwenye Node.js?

server.mjs inaonyesha njia tatu za kuingia. /ec/forward hupokea usambazaji wa nambari zinazosimamiwa: inathibitisha X-EC-Signature kwenye bytes ghafi kwa siri ya kusambaza ya nambari hiyo, inajibu 200 kabla ya kazi yoyote, na inaruka kitambulisho cha uwasilishaji ambacho tayari kimekubaliwa, kwa sababu jaribio upya hubeba kitambulisho kile kile chenye saini mpya. Thamani ya event ya mwili ni jina la uga wa Meta na value ni change ya Meta bila kubadilishwa. /ec/agent hujibu hatua ya Call my webhook, ikisainiwa kwa Signing secret ya automation hiyo yenyewe, na hugeuza historia kuwa zamu za mazungumzo. /meta/:secret ndiyo njia ya moja kwa moja: hujibu uthibitisho wa GET wa Meta kwa hub.challenge ghafi, na hukubali POST kwenye njia ya siri pekee.

Ufunguo wa HMAC ni siri nzima, pamoja na kiambishi whsec_, kama maandishi ya UTF-8. express.raw huhifadhi bytes zikiwa sawa, na kikomo chake cha 5 MB kinaacha nafasi kwa payload za Meta hadi 3 MB.

server.mjs: verification and routes (Express)
// server.mjs: Node 18+, npm i express, then node server.mjs
import crypto from "node:crypto";
import express from "express";
import { askModel, firstTime, handleChange } from "./agent.mjs";

const app = express();

// X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, keyed with the whole secret.
export function verifyEc(raw, header, secret, toleranceSec = 300) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header ?? "").trim());
  if (!m || !Buffer.isBuffer(raw) || !secret) return false;
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > toleranceSec) return false; // stale or replayed
  const expected = crypto.createHmac("sha256", secret).update(`${m[1]}.`).update(raw).digest();
  return crypto.timingSafeEqual(expected, Buffer.from(m[2], "hex"));
}

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

// Route A, forwarded: a managed number's Forward URL. One Meta change per POST.
app.post("/ec/forward", express.raw({ type: "*/*", limit: "5mb" }), (req, res) => {
  if (!verifyEc(req.body, req.get("X-EC-Signature"), process.env.EC_FORWARD_SECRET)) return res.sendStatus(401);
  res.sendStatus(200);                                   // acknowledge inside 10 s, then work
  const d = JSON.parse(req.body.toString("utf8"));
  if (!firstTime(`delivery:${d.id}`)) return;            // a retry of a delivery already taken
  handleChange(d.event, d.value).catch(console.error);   // d.event is the Meta field name
});

// Route A, synchronous: a "Call my webhook" step. Answer {"reply"} within 20 s.
app.post("/ec/agent", express.raw({ type: "*/*", limit: "1mb" }), async (req, res) => {
  if (!verifyEc(req.body, req.get("X-EC-Signature"), process.env.EC_AUTOMATION_SECRET)) return res.sendStatus(401);
  const step = JSON.parse(req.body.toString("utf8"));
  const turns = step.history.map((h) => ({ role: h.direction === "in" ? "user" : "assistant", content: h.text }));
  while (turns[0]?.role === "assistant") turns.shift();
  if (!turns.length) turns.push({ role: "user", content: step.message?.text ?? "" }); // tests carry no history
  res.json({ reply: await askModel(turns) });            // step.dry_run is true on "Test it"
});

// Route B, direct: Meta's own envelope. The secret path is the credential.
app.get("/meta/:secret", (req, res) => {
  if (!sameSecret(req.params.secret, process.env.PATH_SECRET)) return res.sendStatus(404);
  if (req.query["hub.mode"] === "subscribe" && req.query["hub.verify_token"] === process.env.VERIFY_TOKEN) {
    return res.type("text/plain").send(String(req.query["hub.challenge"]));
  }
  res.sendStatus(403);
});

app.post("/meta/:secret", express.json({ limit: "5mb" }), (req, res) => {
  if (!sameSecret(req.params.secret, process.env.PATH_SECRET)) return res.sendStatus(404);
  res.sendStatus(200);                                   // Meta retries anything but 200
  for (const entry of req.body.entry ?? []) {
    for (const change of entry.changes ?? []) handleChange(change.field, change.value).catch(console.error);
  }
});

app.listen(process.env.PORT ?? 3000);

Agent yuleyule anaonekanaje kwenye Python?

Faili moja ya Flask yenye njia zile zile tatu na sheria zile zile. request.get_data() hurudisha mwili ghafi kwa HMAC, hmac.compare_digest hufanya ulinganisho wa muda usiobadilika, na kazi hufanyika kwenye thread ya usuli baada ya 200, kwa hiyo easyCoexistence wala Meta hawasubiri modeli yako. Iendeshe kwa flask --app agent run wakati wa kuendeleza, na nyuma ya gunicorn au seva nyingine ya WSGI katika uzalishaji.

Seti na kamusi zilizo kumbukumbuni zinafaa kwa mchakato mmoja. Ukiwa na wafanyakazi au matukio kadhaa, zihamishe kwenye Redis au hifadhidata yako, ukitumia uandishi wa set-if-absent wenye muda wa kuisha kwa vitambulisho vya ujumbe, la sivyo wafanyakazi wawili watajibu ujumbe uleule.

agent.py: the whole agent (Flask)
# agent.py: pip install flask requests, then flask --app agent run
import hashlib, hmac, json, os, re, threading, time
import requests
from flask import Flask, abort, request

app = Flask(__name__)
DAY, PAUSE = 24 * 3600, 4 * 3600
seen, last_inbound, quiet_until = set(), {}, {}  # use Redis or a database in production
lock = threading.Lock()

def verify_ec(raw: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    m = re.fullmatch(r"t=([0-9]+),v1=([0-9a-f]{64})", (header or "").strip())
    if not m or not secret or abs(time.time() - int(m[1])) > tolerance:
        return False
    expected = hmac.new(secret.encode(), m[1].encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, m[2])

def first_time(key: str) -> bool:
    with lock:
        if key in seen:
            return False
        seen.add(key)
        return True

def ask_model(turns: list) -> str:  # any OpenAI-compatible chat completions API
    r = requests.post(f"{os.environ['AI_BASE_URL']}/chat/completions", timeout=30,
                      headers={"Authorization": f"Bearer {os.environ['AI_KEY']}"},
                      json={"model": os.environ["AI_MODEL"], "messages": [
                          {"role": "system", "content": os.environ.get("AI_INSTRUCTIONS", "Answer briefly.")}, *turns]})
    r.raise_for_status()
    return (r.json()["choices"][0]["message"]["content"] or "").strip()

def send_text(phone, bsuid, text: str) -> None:  # SEND_ENDPOINT and WA_TOKEN: get_api_credentials
    to = {"to": phone} if phone else {"recipient": bsuid}
    r = requests.post(os.environ["SEND_ENDPOINT"], timeout=15,
                      headers={"Authorization": f"Bearer {os.environ['WA_TOKEN']}"},
                      json={"messaging_product": "whatsapp", "recipient_type": "individual", **to,
                            "type": "text", "text": {"body": text[:4096]}})
    r.raise_for_status()

def handle_change(field: str, value: dict) -> None:
    if field == "smb_message_echoes":  # a person answered from the app: step back
        for e in value.get("message_echoes", []):
            quiet_until[e.get("to_user_id") or e.get("to")] = int(e["timestamp"]) + PAUSE
        return
    if field != "messages":
        return
    for m in value.get("messages", []):
        if not first_time(m["id"]):  # Meta delivered this message before
            continue
        user = m.get("from_user_id") or m.get("from")
        last_inbound[user] = max(int(m["timestamp"]), last_inbound.get(user, 0))
        if quiet_until.get(user, 0) > time.time() or m.get("type") != "text":
            continue
        reply = ask_model([{"role": "user", "content": m["text"]["body"]}])
        if reply and time.time() - last_inbound[user] < DAY:  # past 24 h: template only
            send_text(m.get("from"), m.get("from_user_id"), reply)

def later(field, value):
    threading.Thread(target=handle_change, args=(field, value), daemon=True).start()

@app.post("/ec/forward")  # route A: a managed number's Forward URL
def forward():
    raw = request.get_data()
    if not verify_ec(raw, request.headers.get("X-EC-Signature", ""), os.environ["EC_FORWARD_SECRET"]):
        abort(401)
    d = json.loads(raw)
    if first_time("delivery:" + d["id"]):  # skip retries of a delivery already taken
        later(d["event"], d["value"])
    return "", 200

@app.post("/ec/agent")  # route A: a "Call my webhook" step, answer within 20 s
def agent_step():
    raw = request.get_data()
    if not verify_ec(raw, request.headers.get("X-EC-Signature", ""), os.environ["EC_AUTOMATION_SECRET"]):
        abort(401)
    step = json.loads(raw)
    turns = [{"role": "user" if h["direction"] == "in" else "assistant", "content": h["text"]}
             for h in step["history"]]
    while turns and turns[0]["role"] == "assistant":
        turns.pop(0)
    turns = turns or [{"role": "user", "content": step["message"]["text"] or ""}]
    return {"reply": ask_model(turns)}

@app.get("/meta/<secret>")  # route B: Meta's GET handshake
def meta_handshake(secret):
    if not hmac.compare_digest(secret.encode(), os.environ["PATH_SECRET"].encode()):
        abort(404)
    if (request.args.get("hub.mode") == "subscribe"
            and request.args.get("hub.verify_token") == os.environ["VERIFY_TOKEN"]):
        return request.args.get("hub.challenge", ""), 200, {"Content-Type": "text/plain"}
    abort(403)

@app.post("/meta/<secret>")  # route B: Meta's envelope, straight from Meta
def meta_events(secret):
    if not hmac.compare_digest(secret.encode(), os.environ["PATH_SECRET"].encode()):
        abort(404)
    for entry in (request.get_json(silent=True) or {}).get("entry", []):
        for change in entry.get("changes", []):
            later(change.get("field"), change.get("value", {}))
    return "", 200

Unazuiaje majibu marudufu?

Marudufu yana sababu sita za kawaida, na mifano hapo juu inashughulikia tano za kwanza:

  • Majaribio upya ya Meta. Webhook ya moja kwa moja hujaribiwa upya hadi siku 7 baada ya kitu chochote kisicho HTTP 200; weka hifadhi ya vitambulisho vya ujumbe na uruke vitambulisho vilivyoshughulikiwa tayari.
  • Majaribio upya ya kusambaza. easyCoexistence hujaribu upya uwasilishaji usiopata 2xx ndani ya sekunde 10, kwa kitambulisho kile kile; ruka vitambulisho vilivyokubaliwa tayari, kisha ondoa marudio kwa kitambulisho cha ujumbe, kwa sababu mabadiliko ambayo Meta inawasilisha tena husambazwa tena chini ya kitambulisho kipya.
  • Kukiri polepole. Jibu kwanza kisha fanya kazi baadaye; kishughulikiaji kinachosubiri modeli hukatika kwa muda, na tukio hilohilo hurudi.
  • Mtu kwenye simu. Tukio la smb_message_echoes linamaanisha mtu alijibu kutoka programu; kaa kimya kwenye mazungumzo hayo kwa saa kadhaa.
  • Wafanyakazi kadhaa. Seti zilizo kumbukumbuni hazivuki michakato; hamisha hifadhi kwenda Redis au hifadhidata yako.
  • Wajibu wawili. Automation ya kujibu kwa AI na wakala wako mwenyewe kwenye mazungumzo yaleyale vyote vinajibu, na ujumbe unaotumwa kupitia Graph API yako si echo, kwa hiyo hauzisimamishi Automations. Chagua mjibu mmoja kwa kila nambari.

Siri na vitambulisho vinatoka wapi?

Vinatoka kwenye dashboard au kiunganishi cha MCP, na vinapaswa kuwa kwenye mazingira ya seva yako pekee. get_api_credentials hurudisha graph_api_base, waba_id, phone_number_id, send_endpoint na access_token, ambayo ni token ya biashara yenyewe; ukurasa wa nambari unaonyesha thamani zile zile chini ya Plug in your own system. Ikiwa access_token ni null, unganisha tena nambari kutoka kwenye kompyuta kwa kutumia Reconnect ili kutoa token. Itunze token kama nenosiri, kwa sababu yeyote mwenye nayo anaweza kutuma ujumbe kwa jina la biashara.

EC_FORWARD_SECRETShown once when you save a Forward URL, or returned once by set_inbound_mode; New secret rotates it
EC_AUTOMATION_SECRETSigning secret on the automation's page, under its Call my webhook step
SEND_ENDPOINT, WA_TOKENsend_endpoint and access_token from get_api_credentials
PATH_SECRET, VERIFY_TOKENDirect route: 32 or more random characters in the URL, and the handshake token you chose
AI_BASE_URL, AI_KEY, AI_MODELAny OpenAI-compatible API, such as https://api.openai.com/v1 or https://openrouter.ai/api/v1

Makosa ya kawaida

  • Kukagua HMAC kwenye JSON iliyopangwa upya. json.dumps ya Python huongeza nafasi baada ya vitenganishi kwa chaguo-msingi, kwa hiyo mwili uliochanganuliwa na kuandikwa tena hauendani tena; thibitisha bytes ghafi.
  • Kufungua base64 ya siri au kuondoa kiambishi chake cha whsec_. Ufunguo ni mfuatano mzima kama maandishi ya UTF-8, kama ulivyoonyeshwa mara moja.
  • Kuthibitisha X-Hub-Signature-256 kwenye njia ya moja kwa moja kwa siri ya programu yako ya Meta. Meta husaini kwa siri ya programu ya easyCoexistence, ambayo haishirikiwi, kwa hiyo matukio halisi hushindwa; thibitisha kwa siri ya njia.
  • Kusoma dirisha kutoka muda wa kufika. Usambazaji uliojaribiwa upya saa kadhaa baadaye bado hubeba timestamp ya asili ya Meta; linganisha nayo, la sivyo wakala atajibu baada ya saa 24 na Meta itakataa utumaji.
Kufanya hili ukitumia EasyCoexistence

Kila nambari iko chini ya ufuatiliaji 24/7, na arifa hutolewa muunganisho unapokatika. US$ 9 hadi US$ 0.75 kwa nambari kwa mwezi, inashuka unavyoongeza nambari, na siku 3 za kwanza bila malipo.

Maswali yanayoulizwa mara kwa mara

Je, wakala anaweza kuelewa ujumbe wa sauti na picha?

Ndiyo, kwa msimbo wako mwenyewe. Payload ya Meta hubeba kitambulisho cha media: kipakue kwa GET /<media-id> na token ya nambari hiyo, kisha pata URL iliyorudishwa kwa header ile ile ya Authorization, kisha nakili kuwa maandishi au eleza kwa modeli yako. Automations huona vishikilia nafasi tu kama [voice message].

Ni modeli zipi sampuli zinaweza kutumia?

Modeli yoyote nyuma ya endpoint ya chat completions inayooana na OpenAI, ikiwemo ile ya OpenAI na zile zinazofikiwa kupitia OpenRouter, au badilisha askModel na ask_model kwa SDK ya mtoa huduma wako. easyCoexistence haitozi gharama za AI kamwe: mtoa huduma wako anakutoza moja kwa moja.

Je, wakala anaweza kuanzisha mazungumzo?

Kwa template iliyoidhinishwa pekee, itumwe kwa type template kwenye endpoint ile ile ya kutuma. Kwenye nambari ya Coexistence, template hutoka kupitia API pekee, kamwe si kutoka programu ya simu, na Meta inazitoza kwa kila ujumbe kwenye akaunti ya WhatsApp Business ya biashara yenyewe.

Je, wakala mmoja anahudumia nambari kadhaa?

Ndiyo. Elekeza kwa value.metadata.phone_number_id au connection.phone_number_id, na weka send endpoint, token na siri ya kusambaza kwa kila nambari, kwa kuwa kila nambari ina yake.

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