Node.js と Python で、Coexistence 番号の WhatsApp AI エージェントを構築する
番号宛てのメッセージは、検証すべき HMAC 署名 (X-EC-Signature) 付きで転送されるか、URL 内のシークレットを付けて Meta の Webhook から直接受け取れます。そのあと、処理済みのメッセージ ID はスキップし、人が電話から返信したことがエコーで分かったチャットでは応答を控えます。モデルの回答は、お客様の最後のメッセージから 24 時間以内に限って、Cloud API から送信してください。
easyCoexistence は、ビジネスが WhatsApp Business アプリで使い続けている番号を Meta の Cloud API に接続し、get_api_credentials 経由で認証情報をコードに渡します。
署名の t と自分のクロックの間で許容する最大のずれです。再試行はそれぞれ新しい t で再署名されます。
転送された POST が 2xx の応答を待つ時間です。この時間を過ぎると、easyCoexistence がその配信の再試行を予定します。
HTTP 200 が返らなかった直接 Webhook を Meta が再試行する期間。同じメッセージが 2 回届く場合があります。
ユーザーの最後のメッセージから始まるカスタマーサービスウィンドウ。この期間外では、Meta はテンプレートメッセージのみを受け付けます。
WhatsApp Business アプリと Cloud API の両方で使われる番号の、固定のスループットです。
コードで実装したエージェントは、どのルートを使うべきですか?
転送方式では、番号は自動化がオンのままになります。Meta は easyCoexistence に配信し、自動化は引き続き実行できます。Meta の各 change の署名付きコピーは、Forward URL に送られます。転送を使わない変形もあります。自動化の「Call my webhook」ステップが、メッセージをエンドポイントに POST し、20 秒以内に返された {"reply"} を送信します。重複排除、電話による一時停止、24 時間の確認はこのステップが行います。
直接方式では、Meta が自身の Webhook を、set_webhook_destination で設定したエンドポイントに直接 POST します。easyCoexistence はメッセージを一切見ません。その番号では自動化がオフになるため、すべての保護は自分で実装します。接続後 24 時間以内に送信先を保存した場合の 6 か月分の履歴インポートも、同じく自分で行います。以下のサンプルは、3 つの入口すべてを 1 つの共通コアで処理します。
| Forwarded, signed | Direct from Meta | |
|---|---|---|
| Number mode | Automations on (managed) | Direct to your server |
| Body | One Meta change: id, event, received_at, connection, value | Meta's envelope: object, entry, changes |
| Authentication | X-EC-Signature, HMAC-SHA256 with a per-number secret | A secret in the URL path |
| Acknowledge | Any 2xx within 10 seconds | HTTP 200; Meta retries other codes |
| Retries | 7 attempts over about 33 hours | Up to 7 days |
| Reply | Graph API, or {"reply"} to a Call my webhook step | Graph API |
| History import | Not requested | Requested if saved within 24 hours of connecting |
Node.js でエージェントはメッセージをどう処理しますか?
agent.mjs には、両方のルートで共有するロジックがあります。顧客の最後のメッセージ時刻を記録し、smb_message_echoes イベントで WhatsApp Business アプリから誰かが返信したと分かったチャットでは、4 時間の間、応答を控えます(easyCoexistence の自動化のデフォルトです)。すでに処理したメッセージ ID はスキップし、24 時間ウィンドウ内でのみ送信します。ウィンドウは、メッセージが届いた時刻ではなく、そのメッセージ自体のタイムスタンプを基準に計ります。再試行された配信は数時間遅れて届くことがあるためです。
ユーザーは BSUID(from_user_id、エコーでは to_user_id)をキーとし、電話番号をフォールバックにします。BSUID のみで識別されるユーザーには、to ではなく recipient を使って応答します。モデル呼び出しには、OpenAI 互換の chat completions API を使えます。お好みのプロバイダーの SDK に置き換えることもできます。
// 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 は 3 つの入口を公開します。/ec/forward は管理対象の番号の転送を受け取ります。番号ごとの転送シークレットで生のバイト列に対して X-EC-Signature を検証し、どんな処理の前にも 200 を返します。すでに受け付けた配信 ID はスキップします。再試行は同じ ID を新しい署名とともに送ってくるためです。ボディの event は Meta のフィールド名、value は Meta の change をそのまま格納しています。/ec/agent は Call my webhook ステップに応答します。そのオートメーション専用の Signing secret で署名され、履歴をチャットのターンに変換します。/meta/:secret は直接ルートです。Meta の GET ハンドシェイクには生の hub.challenge で応答し、POST はシークレットを含むパスでのみ受け付けます。
HMAC 鍵はシークレット全体で、whsec_ の接頭辞も含め、UTF-8 テキストとして使います。express.raw はバイト列をそのまま保持します。その 5 MB の上限は、最大 3 MB までの Meta ペイロードに余裕を持たせるためのものです。
// 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 ではどう書きますか?
同じ 3 つのルートと同じルールを持つ、1 つの Flask ファイルです。HMAC 用に request.get_data() で生のボディを取得し、定数時間比較には hmac.compare_digest を使います。200 を返した後はバックグラウンドスレッドで処理するため、easyCoexistence も Meta も、お使いのモデルの応答を待ちません。開発中は flask --app agent run で実行し、本番では gunicorn などの WSGI サーバーの背後で動かしてください。
インメモリのセットと辞書は 1 つのプロセス向けです。ワーカーやインスタンスが複数ある場合は、Redis またはデータベースに移してください。メッセージ ID には、有効期限付きの set-if-absent 書き込みを使います。そうしないと、2 つのワーカーが同じメッセージに応答してしまいます。
# 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重複した返信を避けるにはどうしますか?
重複には 6 つの代表的な原因があり、上のサンプルは最初の 5 つを扱います。
- Meta の再試行。直接 Webhook は、HTTP 200 以外の応答を受けた後、最大 7 日間再試行されます。メッセージ ID のストアを保持し、処理済みの ID はスキップしてください。
- 転送の再試行。easyCoexistence は、10 秒以内に 2xx が返らなかった配信を、同じ ID で再試行します。受け付け済みの ID はスキップし、Meta が再配信した変更は新しい ID で再び転送されるため、メッセージ ID でも重複排除してください。
- 応答の遅延。先に応答し、後で処理してください。モデルの応答を待つハンドラーはタイムアウトし、同じイベントが戻ってきます。
- 電話での返信。
smb_message_echoesイベントは、アプリから誰かが返信したことを示します。数時間の間、そのチャットでは応答を控えてください。 - 複数のワーカー。インメモリのセットはプロセスをまたぎません。ストアを Redis またはデータベースに移してください。
- 二重の応答者。AI 返信の自動化と自分のエージェントが同じチャットに応答すると、両方が返信します。Graph API による送信はエコーではないため、自動化は一時停止しません。番号ごとに応答者を 1 つに決めてください。
シークレットと認証情報はどこから取得しますか?
ダッシュボードまたは 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」で再接続し、トークンを発行してください。トークンはパスワードと同様に扱ってください。トークンを持つ人は、ビジネスとしてメッセージを送信できてしまいます。
よくある間違い
- 再シリアライズした JSON に対して HMAC を検証すること。Python の json.dumps は、既定でセパレーターの後にスペースを加えるため、一度解析して再度ダンプしたボディは一致しなくなります。生のバイト列を検証してください。
- シークレットを Base64 デコードしたり、whsec_ の接頭辞を外したりすること。鍵は、一度表示されたとおりの文字列全体を、UTF-8 テキストとして使います。
- 直接ルートで、自分の Meta アプリシークレットを使って X-Hub-Signature-256 を検証すること。Meta は easyCoexistence のアプリシークレットで署名し、それは共有されていないため、正規のイベントが失敗します。パスのシークレットで認証してください。
- 到着時刻からウィンドウを判定すること。数時間後に再試行された転送も、Meta の元のタイムスタンプを持っています。そのタイムスタンプと比較しないと、エージェントが 24 時間を過ぎて返信し、Meta が送信を拒否します。
さらに、自動化をオンにした状態で、Meta からのメッセージをサーバーへ直接ルーティングするか、署名付きの転送を通じて届けます。すべての番号は 24 時間体制で監視され、接続が切れた場合にはアラートを送ります。料金は、番号 1 件あたり月額 US$ 9 から US$ 0.75 までで、番号を増やすほど下がります。最初の 3 日間は無料です。
よくある質問
エージェントは音声メモや写真を理解できますか?
はい、自分のコードで実装できます。Meta のペイロードにはメディア ID が含まれます。GET /<media-id> と番号のトークンでダウンロードし、返された URL に同じ Authorization ヘッダーを付けて取得してから、モデルで文字起こしや説明を行ってください。自動化では [voice message] のようなプレースホルダーしか見えません。
サンプルではどのモデルを使えますか?
OpenAI 互換の chat completions エンドポイントの背後にあるどのモデルでも使えます。OpenAI のモデルや、OpenRouter 経由で利用できるモデルを含みます。または askModel と ask_model を、お使いのプロバイダーの SDK に置き換えてください。easyCoexistence は AI の料金を一切請求しません。プロバイダーが直接請求します。
エージェントから会話を開始できますか?
承認済みのテンプレートのみ可能です。同じ送信エンドポイントに、type template を指定して送ります。Coexistence 番号では、テンプレートは API からのみ送信でき、スマートフォンのアプリからは送れません。Meta は、メッセージごとに、ビジネス自身の WhatsApp Business Account に料金を請求します。
1 つのエージェントで複数の番号を扱えますか?
はい。value.metadata.phone_number_id または connection.phone_number_id でルーティングし、番号ごとに送信エンドポイント、トークン、転送シークレットを用意してください。各番号は独立しているためです。
続きを読む
始める準備はできましたか?
WhatsApp Coexistence の設定は数分で完了し、数か月もかかりません。スマートフォン上のアプリも引き続き使えます。
無料トライアルを始める確認日