Kirjaudu sisäänAloita ilmainen kokeilu
Meta Tech Provider

Rakenna WhatsApp-tekoälyagentti Node.js- ja Python-kielillä Coexistence-numerolla

Vastaanota numeron viestit joko välitettyinä HMAC-allekirjoituksella, jonka tarkistat (X-EC-Signature), tai suoraan Metan webhookista salaisuudella URL:ssa. Ohita sen jälkeen jo käsitelty viestitunnus ja ole hiljaa keskustelussa, jossa kaiku näyttää ihmisen vastanneen puhelimesta. Lähetä mallin vastaus Cloud API:n kautta vain 24 tunnin sisällä asiakkaan viimeisimmästä viestistä.

easyCoexistence yhdistää numeron, jota yritys käyttää WhatsApp Business -sovelluksessa, Metan Cloud API:in, antaa koodillesi tunnukset get_api_credentials-funktiolla ja reitittää viestit suoraan Metasta palvelimellesi tai allekirjoitetulla välityksellä automaatioiden ollessa päällä.

5 min

Suurin sallittu ero allekirjoituksen t-arvon ja kellon välillä; jokainen uudelleenyritys allekirjoitetaan uudelleen tuoreella t-arvolla.

10 s

Kuinka kauan välitetty POST odottaa 2xx-vastausta, ennen kuin easyCoexistence ajastaa tämän toimituksen uudelleenyrityksen.

7 days

Kuinka kauan Meta yrittää uudelleen suoraa webhookia, joka ei saanut HTTP 200 -vastausta, mikä voi toimittaa saman viestin kahdesti.

24 hours

Asiakaspalveluikkuna käyttäjän viimeisimmästä viestistä; sen ulkopuolella Meta hyväksyy vain viestipohjat.

20 mps

Kiinteä läpimenoteho numerolle, jota käytetään sekä WhatsApp Business -sovelluksen että Cloud API:n kanssa.

Mitä reittiä koodattu agentti kannattaa käyttää?

Välitetty tarkoittaa, että numero pysyy automaatioissa päällä-tilassa: Meta toimittaa easyCoexistenceen, automaatiot voivat yhä ajaa, ja jokainen Metan muutos lähetetään allekirjoitettuna kopiona Forward URL:iin. Eräs muunnelma ei tarvitse välitystä lainkaan: automaation vaihe Call my webhook lähettää viestin omaan endpointiisi POST-pyynnöllä ja lähettää palautetun {"reply"}-kentän sisällön 20 sekunnin kuluessa. Duplikaattien esto, ihmisen vastauksen tauko ja 24 tunnin tarkistus hoidetaan puolestasi.

Suoraan tarkoittaa, että Meta lähettää oman webhookinsa suoraan endpointiisi, asetettuna set_webhook_destination-funktiolla, eikä easyCoexistence näe viestejä lainkaan. Automaatiot ovat pois päältä tälle numerolle, joten kaikki suojaukset ovat sinun vastuullasi, samoin 6 kuukauden historian tuonti, kun kohde tallennetaan 24 tunnin sisällä yhdistämisestä. Alla olevat esimerkit käsittelevät kaikki kolme sisääntulokohtaa yhdellä yhteisellä ytimellä.

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

Mitä agentti tekee viestille Node.js:ssä?

agent.mjs sisältää logiikan, jonka molemmat reitit jakavat. Se tallentaa asiakkaan viimeisimmän viestin ajan, vetäytyy 4 tunniksi keskustelussa, kun smb_message_echoes-tapahtuma näyttää jonkun vastanneen WhatsApp Business -sovelluksesta (oletus easyCoexistence-automaatioille), ohittaa jo käsitellyn viestitunnuksen ja lähettää vain 24 tunnin ikkunassa. Ajan mittaus perustuu viestin omaan aikaleimaan eikä siihen, milloin se saapui sinulle, koska uudelleen yritetty toimitus voi saapua tunteja myöhässä.

Käyttäjät tunnistetaan BSUID:llä (from_user_id tai echoissa to_user_id), puhelinnumero on varavaihtoehto, ja käyttäjälle, joka tunnetaan vain BSUID:llä, vastataan kentän recipient kautta eikä kentän to kautta. Mallikutsu käyttää mitä tahansa OpenAI-yhteensopivaa chat completions API:a; vaihda palveluntarjoajasi SDK, jos haluat.

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

Miten tapahtumat varmennetaan ja reititetään Node.js:ssä?

server.mjs tarjoaa kolme sisääntulokohtaa. /ec/forward ottaa välitykset hallitusta numerosta: se varmentaa X-EC-Signature-allekirjoituksen raakabiteistä numeron välityssalaisuudella, vastaa 200 ennen mitään työtä ja ohittaa toimitustunnuksen, jonka se on jo hyväksynyt, koska uudelleenyritys kantaa saman tunnuksen tuoreella allekirjoituksella. Rungon event on Metan kentän nimi ja value on Metan muutos muuttamattomana. /ec/agent vastaa Call my webhook -vaiheelle, allekirjoitettuna kyseisen automaation omalla Signing secret -salaisuudella, ja muuntaa historian chat-vuoroiksi. /meta/:secret on suora reitti: se vastaa Metan GET-kättelyyn raakana hub.challenge-arvona ja hyväksyy POST-pyynnöt vain salaisella polulla.

HMAC-avain on koko salaisuus, whsec_-etuliite mukaan lukien, UTF-8-tekstinä. express.raw säilyttää tavut ehjinä, ja sen 5 MB:n raja jättää tilaa Metan jopa 3 MB:n payloadeille.

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

Miltä sama agentti näyttää Pythonilla?

Yksi Flask-tiedosto samoilla kolmella reitillä ja samoilla säännöillä. request.get_data() palauttaa raakarungon HMAC:ille, hmac.compare_digest tekee vakioaikaisen vertailun, ja työ suoritetaan taustasäikeessä 200-vastauksen jälkeen, joten easyCoexistence ja Meta eivät odota mallia. Aja se komennolla flask --app agent run kehityksessä ja gunicornin tai muun WSGI-palvelimen takana tuotannossa.

Muistissa oleva set ja sanakirjat sopivat yhdelle prosessille. Useilla workereilla tai instansseilla ne pitää siirtää Redisiin tai tietokantaan, ja viestitunnuksille käytetään set-if-absent-kirjoitusta vanhenemisajalla, muuten kaksi workeria vastaa samaan viestiin.

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

Miten kaksoisvastaukset vältetään?

Kaksoisviesteillä on kuusi yleistä syytä, ja yllä olevat esimerkit ratkaisevat niistä viisi ensimmäistä:

  • Metan uudelleenyritykset. Suoraa webhookia yritetään uudelleen jopa 7 päivän ajan kaikesta muusta kuin HTTP 200 -vastauksesta; pidä tallennusta viestitunnuksista ja ohita jo käsitellyt tunnukset.
  • Välityksen uudelleenyritykset. easyCoexistence yrittää uudelleen toimitusta, joka ei saanut 2xx-vastausta 10 sekunnin kuluessa, samalla tunnuksella; ohita jo hyväksytyt toimitustunnukset ja poista kaksoiskappaleet viestitunnuksen perusteella, sillä Metan uudelleen toimittama muutos välitetään uudelleen uudella tunnuksella.
  • Hitaat kuittaukset. Vastaa ensin ja tee työ sen jälkeen; käsittelijä, joka odottaa mallia, aikakatkaistaan ja sama tapahtuma palaa.
  • Ihminen puhelimella. smb_message_echoes-tapahtuma tarkoittaa, että joku vastasi sovelluksesta; ole hiljaa kyseisessä keskustelussa muutaman tunnin ajan.
  • Useita workereita. Muistissa olevat setit eivät ulotu prosessien yli; siirrä tallennukset Redisiin tai tietokantaan.
  • Kaksi vastaajaa. AI-vastausautomaatio ja oma agenttisi samoissa keskusteluissa vastaavat molemmat, ja Graph API -lähetykset eivät ole kaikuja, joten ne eivät pysäytä automaatioita. Valitse yksi vastaaja per numero.

Mistä salaisuudet ja tunnukset tulevat?

Hallintapaneelista tai MCP-liittimestä, ja niiden kuuluu olla vain palvelimesi ympäristömuuttujissa. get_api_credentials palauttaa kentät graph_api_base, waba_id, phone_number_id, send_endpoint ja access_token, eli yrityksen oman tokenin; numeron sivu näyttää samat arvot kohdassa Plug in your own system. Jos access_token on null, yhdistä numero uudelleen tietokoneelta Reconnect-painikkeella tokenin myöntämiseksi. Käsittele tokenia salasanana, sillä kuka tahansa, jolla se on, voi viestiä yrityksen nimissä.

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

Yleiset virheet

  • HMAC:n tarkistus uudelleen sarjoitetusta JSON:sta. Pythonin json.dumps lisää oletuksena välilyönnit erottimien jälkeen, joten rungon jäsentäminen ja uudelleen dumppaus ei enää täsmää; varmenna raakatavut.
  • Salaisuuden Base64-purkaminen tai whsec_-etuliitteen poistaminen. Avain on koko merkkijono UTF-8-tekstinä, täsmälleen niin kuin se näytettiin sinulle kerran.
  • X-Hub-Signature-256:n varmentaminen suoralla reitillä oman Meta-sovelluksesi salaisuudella. Meta allekirjoittaa easyCoexistencen sovellussalaisuudella, jota ei jaeta, joten aidot tapahtumat epäonnistuvat; todenna polun salaisuudella.
  • Ikkunan lukeminen saapumisajasta. Myöhemmin uudelleen yritetty välitys kantaa yhä Metan alkuperäistä aikaleimaa; vertaa siihen, tai agentti vastaa yli 24 tunnin kuluttua ja Meta hylkää lähetyksen.
Näin teet tämän EasyCoexistencen avulla

Jokainen numero on valvonnassa 24/7, ja hälytykset tulevat, kun yhteys katkeaa. Hinta laskee US$ 9:stä US$ 0.75:een numeroa kohden kuukaudessa, kun numeroita lisätään. Ensimmäiset 3 päivää ovat ilmaisella kokeilulla.

Usein kysytyt kysymykset

Voiko agentti ymmärtää ääniviestejä ja kuvia?

Kyllä, omalla koodilla. Metan payloadissa on median tunniste: lataa se GET /<media-id> -pyynnöllä ja numeron tokenilla, hae palautettu URL samalla Authorization-otsakkeella ja litteroi tai kuvaile se mallillasi. Automaatiot näkevät vain paikkamerkkejä, kuten [voice message].

Mitä malleja esimerkit voivat käyttää?

Mitä tahansa mallia, joka on OpenAI-yhteensopivan chat completions -päätepisteen takana, mukaan lukien OpenAI:n ja OpenRouterin kautta saavutettavat, tai korvaa askModel ja ask_model palveluntarjoajasi SDK:lla. easyCoexistence ei laskuta tekoälystä koskaan: palveluntarjoajasi laskuttaa sinulta suoraan.

Voiko agentti aloittaa keskustelun?

Vain hyväksytyn viestipohjan avulla, lähetettynä tyypillä template samaan lähetyspäätepisteeseen. Coexistence-numerolla viestipohjat lähtevät vain API:n kautta, ei koskaan puhelinsovelluksesta, ja Meta laskuttaa ne viestikohtaisesti yrityksen omalle WhatsApp Business -tilille.

Voiko yksi agentti palvella useita numeroita?

Kyllä. Reititä kentän value.metadata.phone_number_id tai connection.phone_number_id perusteella, ja pidä lähetyspäätepiste, token ja välityssalaisuus jokaiselle numerolle erikseen, sillä jokaisella numerolla on omansa.

Lue lisää

Valmis aloittamaan?

Ota WhatsApp Coexistence käyttöön minuuteissa, ei kuukausissa. Sovellus toimii edelleen puhelimessa.

Aloita ilmainen kokeilu

Vahvistettu