ВойтиНачать бесплатный пробный период
Meta Tech Provider

ИИ-агент для WhatsApp на Node.js и Python на номере Coexistence

Принимайте сообщения номера либо пересланными с подписью HMAC, которую вы проверяете (X-EC-Signature), либо напрямую из вебхука Meta с секретом в URL. Затем пропускайте id сообщения, которое уже обработано, молчите в чате, где эхо-событие показывает, что человек ответил с телефона, и отправляйте ответ вашей модели через Cloud API только в течение 24 часов после последнего сообщения клиента.

easyCoexistence подключает номер, который бизнес продолжает использовать в приложении WhatsApp Business, к Cloud API Meta, передаёт вашему коду учётные данные через get_api_credentials и маршрутизирует сообщения напрямую от Meta на ваш сервер или через подписанную пересылку при включённых автоматизациях.

5 min

Наибольшая допустимая разница между параметром t подписи и вашими часами; каждая повторная доставка подписывается заново с новым t.

10 s

Сколько времени пересланный POST ждёт ответа 2xx, прежде чем easyCoexistence запланирует повтор этой доставки.

7 days

Сколько времени Meta повторяет прямой вебхук, не получивший HTTP 200, из-за чего одно и то же сообщение может прийти дважды.

24 hours

Окно обслуживания клиентов после последнего сообщения пользователя; вне его Meta принимает только сообщения по шаблону.

20 mps

Фиксированная пропускная способность номера, который используется и в приложении WhatsApp Business, и в Cloud API.

Какой маршрут выбрать для самописного агента?

Пересылка означает, что номер остаётся в режиме «Automations»: Meta доставляет сообщения в easyCoexistence, автоматизации продолжают работать, а подписанная копия каждого изменения Meta уходит на ваш URL пересылки. Есть и вариант без пересылки: шаг автоматизации «Call my webhook» отправляет POST с сообщением на ваш эндпоинт и возвращает клиенту всё, что вы передадите в поле {"reply"}, в течение 20 секунд. Дедупликация, пауза при ответе человека и проверка 24-часового окна выполняются за вас.

Прямой маршрут означает, что Meta отправляет собственный вебхук прямо на ваш эндпоинт, заданный через set_webhook_destination, и easyCoexistence сообщения не видит. Автоматизации для такого номера выключены, поэтому все защитные проверки ваши, как и импорт истории за 6 месяцев, если адрес сохранён в течение 24 часов после подключения. Примеры ниже обрабатывают все три точки входа одним общим ядром.

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

Что агент делает с сообщением в Node.js?

agent.mjs содержит логику, общую для обоих маршрутов. Он запоминает время последнего сообщения клиента, отступает на 4 часа в чате, когда событие smb_message_echoes показывает, что кто-то ответил из приложения WhatsApp Business (такое поведение по умолчанию у автоматизаций easyCoexistence), пропускает id сообщения, которое уже обработал, и отправляет ответ только внутри 24-часового окна. Окно отсчитывается от собственной метки времени сообщения, а не от момента, когда оно дошло до вас, поскольку повторная доставка может прийти с опозданием на часы.

Пользователи идентифицируются по BSUID (from_user_id, а в эхо-событиях to_user_id), номер телефона служит запасным вариантом. Пользователю, известному только по BSUID, ответ уходит через recipient вместо to. Для вызова модели подойдёт любой API chat completions, совместимый с OpenAI; если вы предпочитаете SDK своего провайдера, замените его.

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

Как проверять и маршрутизировать события в Node.js?

server.mjs открывает три точки входа. /ec/forward принимает пересылки управляемого номера: проверяет X-EC-Signature по исходным байтам секретом пересылки номера, отвечает 200 до любой работы и пропускает id доставки, который уже принял, потому что повтор несёт тот же id с новой подписью. Поле event в теле является именем поля Meta, а value является изменением Meta без правок. /ec/agent отвечает на шаг «Call my webhook», подписанный секретом подписи этой автоматизации, и превращает историю в реплики чата. /meta/:secret это прямой маршрут: он отвечает на GET-рукопожатие Meta необработанным hub.challenge и принимает POST только по пути с секретом.

Ключ HMAC это весь секрет, включая префикс whsec_, как текст в UTF-8. express.raw сохраняет байты неизменными, а лимит в 5 МБ оставляет место для тела запроса Meta размером до 3 МБ.

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

Как выглядит тот же агент на Python?

Один файл Flask с теми же тремя маршрутами и теми же правилами. request.get_data() возвращает исходное тело для HMAC, hmac.compare_digest выполняет сравнение за постоянное время, а работа идёт в фоновом потоке после ответа 200, поэтому ни easyCoexistence, ни Meta не ждут вашу модель. Запускайте командой flask --app agent run во время разработки и за gunicorn или другим WSGI-сервером в продакшене.

Множества и словари в памяти подходят для одного процесса. При нескольких воркерах или экземплярах перенесите их в Redis или базу данных, используя для id сообщений запись set-if-absent с временем жизни, иначе два воркера ответят на одно и то же сообщение.

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

Как избежать повторных ответов?

Дубликаты имеют шесть частых причин, и примеры выше закрывают первые пять:

  • Повторы Meta. Прямой вебхук повторяется до 7 дней после любого ответа, кроме HTTP 200; храните хранилище id сообщений и пропускайте уже обработанные.
  • Повторы пересылки. easyCoexistence повторяет доставку, не получившую 2xx в течение 10 секунд, с тем же id; пропускайте уже принятые id, а затем проводите дедупликацию по id сообщения, поскольку изменение, которое Meta передаёт повторно, пересылается снова под новым id.
  • Медленные подтверждения. Сначала ответьте, потом работайте; обработчик, который ждёт модель, превышает таймаут, и то же событие приходит снова.
  • Человек у телефона. Событие smb_message_echoes означает, что кто-то ответил из приложения; молчите в этом чате несколько часов.
  • Несколько воркеров. Множества в памяти не работают между процессами; перенесите хранилища в Redis или базу данных.
  • Два отвечающих. Автоматизация ИИ-ответов и ваш агент в одних и тех же чатах отвечают оба, а ваши отправки через Graph API не являются эхо-событиями, поэтому не ставят автоматизации на паузу. Оставьте одного отвечающего на номер.

Откуда берутся секреты и учётные данные?

Из панели управления или из коннектора MCP, и они должны храниться только в окружении вашего сервера. get_api_credentials возвращает graph_api_base, waba_id, phone_number_id, send_endpoint и access_token, собственный токен бизнеса; страница номера показывает те же значения в разделе «Plug in your own system». Если access_token равен null, переподключите номер с компьютера кнопкой «Reconnect», чтобы выпустить токен. Относитесь к токену как к паролю: тот, кто им владеет, может писать клиентам от имени бизнеса.

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

Распространённые ошибки

  • Проверка HMAC по повторно сериализованному JSON. json.dumps в Python по умолчанию ставит пробелы после разделителей, поэтому тело, разобранное и сериализованное заново, уже не совпадает; проверяйте исходные байты.
  • Декодирование секрета из base64 или отбрасывание префикса whsec_. Ключ это вся строка как текст в UTF-8, ровно в том виде, в каком её показали один раз.
  • Проверка X-Hub-Signature-256 на прямом маршруте вашим собственным секретом приложения Meta. Meta подписывает секретом приложения easyCoexistence, который не передаётся, поэтому настоящие события не проходят; аутентифицируйте по секрету в пути.
  • Отсчёт окна от времени получения. Пересланный повтор, пришедший через часы, всё равно несёт исходную метку времени Meta; сравнивайте с ней, иначе агент ответит через 24 часа, и Meta отклонит отправку.
Настройка с EasyCoexistence

Каждый номер мониторится круглосуточно, с оповещениями при обрыве подключения. От US$ 9 до US$ 0,75 за подключённый номер в месяц, по мере добавления номеров цена снижается; первые 3 дня бесплатно.

Часто задаваемые вопросы

Может ли агент понимать голосовые сообщения и фото?

Да, с вашим собственным кодом. Тело запроса Meta содержит media id: скачайте файл через GET /<media-id> с токеном номера, затем загрузите возвращённый URL с тем же заголовком Authorization и транскрибируйте или опишите его вашей моделью. Автоматизации видят только заглушки вроде [voice message].

Какие модели могут использовать примеры?

Любую модель за эндпоинтом chat completions, совместимым с OpenAI, включая модели OpenAI и доступные через OpenRouter, либо замените askModel и ask_model на SDK вашего провайдера. easyCoexistence никогда не выставляет счёт за ИИ: счёт вам выставляет ваш провайдер напрямую.

Может ли агент начать разговор?

Только с одобренным шаблоном, отправленным с type template на тот же эндпоинт отправки. На номере Coexistence шаблоны уходят только через API, никогда из приложения на телефоне, а Meta выставляет счёт за каждое сообщение на WhatsApp Business Account самого бизнеса.

Может ли один агент обслуживать несколько номеров?

Да. Маршрутизируйте по value.metadata.phone_number_id или connection.phone_number_id и держите эндпоинт отправки, токен и секрет пересылки для каждого номера, поскольку у каждого номера свои.

Читайте дальше

Как сообщения WhatsApp доходят до вашего сервера: напрямую или через управляемый режим, и проверка подписиНапрямую: Meta шлёт вебхуки на ваш сервер. Через сервис: автоматизации отвечают, подписанная копия уходит на Forward URL.Дайте ИИ-агенту память: шесть месяцев чатов и контактов WhatsAppЗагрузите до 180 дней чатов WhatsApp и контакты в память ИИ-агента на номере Coexistence: правило 24 часов, фрагменты, прогресс и хранение.Имена пользователей WhatsApp и BSUID: что меняется в вебхуках Cloud APIКак имена пользователей WhatsApp меняют вебхуки Cloud API: BSUID в user_id, когда пропадают wa_id и from, ответ по recipient и изменения Coexistence.WhatsApp AI-агент в n8n: ответ пишет ваш сценарийЗапустите AI-агента WhatsApp в n8n: подписанный POST передаёт сообщение и недавний чат, узел AI Agent пишет ответ, и он возвращается в течение 20 секунд.Вебхук smb_message_echoesКак программа видит сообщения человека из WhatsApp Business. Поле есть только у номеров Coexistence: без него клиент может получить два ответа.WhatsApp AI по типу бизнеса: готовые сценарии для ресторанов, клиник, салонов и магазиновАвтоматизации WhatsApp для ресторанов, клиник, салонов, интернет-магазинов, недвижимости и авторов курсов: триггеры, шаги, промпт AI и передача человеку.

Готовы начать?

Настройте WhatsApp Coexistence за несколько минут, а не месяцев. Приложение продолжит работать на телефоне.

Начать бесплатный пробный период

Проверено по состоянию на