Coexistence numarasında Node.js ve Python ile WhatsApp yapay zeka ajanı oluşturun
Numaranın mesajlarını, doğrulayacağınız HMAC imzasıyla (X-EC-Signature) iletilmiş olarak ya da URL'deki gizli anahtarla doğrudan Meta'nın webhook'undan alın. Ardından daha önce işlenmiş her mesaj kimliğini atlayın, bir yankının telefondan birinin yanıt verdiğini gösterdiği sohbette sessiz kalın ve modelinizin yanıtını yalnızca müşterinin son mesajından itibaren 24 saat içinde Cloud API üzerinden gönderin.
easyCoexistence, işletmenin WhatsApp Business uygulamasında kullanmaya devam ettiği numarayı Meta'nın Cloud API'sine bağlar, kodunuza kimlik bilgilerini get_api_credentials üzerinden verir ve Automations açıkken mesajları Meta'dan doğrudan sunucunuza ya da imzalı bir iletmeyle yönlendirir.
İmzadaki t değeri ile sizin saatiniz arasında kabul edilebilecek en büyük fark; her yeniden deneme taze bir t ile yeniden imzalanır.
easyCoexistence'ın iletilen bir POST isteği için 2xx yanıtını ne kadar bekleyeceği; bu süreden sonra o teslimat için yeniden deneme planlanır.
Meta'nın HTTP 200 dönmeyen doğrudan webhook'unu ne kadar süreyle yeniden denediği; bu durum aynı mesajın iki kez teslim edilmesine neden olabilir.
Kullanıcının son mesajından sonraki müşteri hizmetleri penceresi; bu süre dışında Meta yalnızca şablon mesajlarını kabul eder.
WhatsApp Business uygulamasıyla ve Cloud API'yle birlikte kullanılan bir numaranın sabit iletim hızı.
Kodlanmış bir ajan hangi yolu izlemeli?
İletilmiş mod, numarayı Automations açık modunda tutar: Meta olayları easyCoexistence'a teslim eder, otomasyonlar yine çalışabilir ve her Meta değişikliğinin imzalı bir kopyası Forward URL'nize gider. Bir varyant hiç iletim gerektirmez: bir otomasyonun 'Call my webhook' adımı mesajı uç noktanıza POST eder ve 20 saniye içinde döndürdüğünüz {"reply"} değerini gönderir; tekrar kontrolü, telefon duraklatması ve 24 saat denetimi sizin için yapılır.
Doğrudan mod, Meta'nın kendi webhook'unu doğrudan uç noktanıza göndermesi anlamına gelir; bu webhook set_webhook_destination ile ayarlanır ve easyCoexistence mesajları hiç görmez. Bu numara için Automations kapalıdır, dolayısıyla tüm korumalar sizin sorumluluğunuzdadır; bağlandıktan sonraki 24 saat içinde hedef kaydedilirse 6 aylık geçmiş içe aktarımı da öyledir. Aşağıdaki örnekler üç giriş noktasını da tek ortak bir çekirdekle işler.
| 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'te bir mesajla ajan ne yapar?
agent.mjs, iki yolun da paylaştığı mantığı içerir. Müşterinin son mesaj zamanını kaydeder; bir smb_message_echoes olayı birinin WhatsApp Business uygulamasından yanıt verdiğini gösterdiğinde (easyCoexistence otomasyonlarının varsayılan davranışı) o sohbette 4 saat geri çekilir, daha önce işlenmiş bir mesaj kimliğini atlar ve yalnızca 24 saatlik pencerede yanıt gönderir. Pencere, mesajın size ulaştığı andan değil, mesajın kendi zaman damgasından ölçülür; çünkü yeniden denenen bir teslimat saatler sonra gelebilir.
Kullanıcılar BSUID ile anahtarlanır (from_user_id veya yankılarda to_user_id), telefon numarası yedek olarak kullanılır; yalnızca BSUID ile bilinen bir kullanıcıya to yerine recipient ile yanıt verilir. Model çağrısı OpenAI uyumlu herhangi bir chat completions API'si kullanır; tercih ederseniz sağlayıcınızın SDK'sını kullanın.
// 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'te olayları nasıl doğrular ve yönlendirirsiniz?
server.mjs üç giriş noktasını açar. /ec/forward, yönetilen numaraların iletilmelerini alır: X-EC-Signature değerini numaranın iletme gizli anahtarıyla ham bayt üzerinde doğrular, herhangi bir işlemden önce 200 yanıtı verir ve daha önce kabul edilmiş bir teslimat kimliğini atlar; çünkü yeniden deneme aynı kimliği taze bir imzayla taşır. Gövdedeki event, Meta'nın alan adıdır ve value, Meta'nın değişikliğidir; hiçbir şekilde değiştirilmez. /ec/agent, bir Call my webhook adımından gelen istekleri o otomasyonun kendi Signing secret değeriyle imzalanmış olarak yanıtlar ve geçmişi sohbet turlarına dönüştürür. /meta/:secret doğrudan rotadır: Meta'nın GET el sıkışmasını ham hub.challenge ile yanıtlar ve POST isteklerini yalnızca gizli yoldan kabul eder.
HMAC anahtarı, whsec_ öneki dahil, tüm gizli değerdir ve UTF-8 metin olarak kullanılır. express.raw baytları bozulmadan tutar; 5 MB sınırı, en fazla 3 MB'lık Meta yüklerine yer bırakır.
// 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);Aynı ajan Python'da nasıl görünür?
Aynı üç rotayı ve aynı kuralları içeren tek bir Flask dosyası. request.get_data() HMAC için ham gövdeyi döndürür, hmac.compare_digest sabit zamanlı karşılaştırmayı yapar ve iş, 200 yanıtından sonra arka plan iş parçacığında çalışır; böylece ne easyCoexistence ne de Meta modelinizi beklemek zorunda kalır. Geliştirme sırasında flask --app agent run ile, üretimde ise gunicorn veya başka bir WSGI sunucusunun arkasında çalıştırın.
Bellek içi küme ve sözlükler tek süreç için uygundur. Birden çok işçi veya örnek varsa, bunları Redis'e ya da veritabanınıza taşıyın; mesaj kimlikleri için son kullanma süresi olan, yalnızca yoksa yaz (set-if-absent) işlemi kullanın, aksi halde iki işçi aynı mesaja yanıt verir.
# 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 "", 200Yinelenen yanıtlardan nasıl kaçınırsınız?
Yinelenmelerin altı yaygın nedeni vardır; yukarıdaki örnekler ilk beşini ele alır:
- Meta'nın yeniden denemeleri. Doğrudan webhook, HTTP 200 dışında herhangi bir yanıt sonrasında 7 güne kadar yeniden denenir; mesaj kimliklerinin bir deposunu tutun ve daha önce işlenmiş kimlikleri atlayın.
- İletme yeniden denemeleri. easyCoexistence, 10 saniye içinde 2xx almayan bir teslimatı aynı kimlikle yeniden dener; daha önce kabul edilmiş kimlikleri atlayın, sonra mesaj kimliğine göre tekrarları eleyin, çünkü Meta'nın yeniden gönderdiği bir değişiklik yeni bir kimlikle yeniden iletilir.
- Yavaş onaylar. Önce yanıt verin, işi sonra yapın; modeli bekleyen bir işleyici zaman aşımına uğrar ve aynı olay geri gelir.
- Telefondaki bir kişi.
smb_message_echoesolayı birinin uygulamadan yanıt verdiği anlamına gelir; o sohbette birkaç saat sessiz kalın. - Birden çok işçi. Bellek içi kümeler süreçler arasında paylaşılmaz; depoları Redis'e ya da veritabanınıza taşıyın.
- İki yanıtlayıcı. Yapay zeka yanıtlama otomasyonu ile kendi ajanınız aynı sohbetlerde ikisi de yanıt verir; Graph API gönderimleriniz yankı değildir, dolayısıyla otomasyonları duraklatmaz. Numara başına yalnızca bir yanıtlayıcı seçin.
Gizli anahtarlar ve kimlik bilgileri nereden gelir?
Panelden veya MCP bağlayıcısından gelir ve yalnızca sunucunuzun ortam değişkenlerinde bulunmalıdır. get_api_credentials, graph_api_base, waba_id, phone_number_id, send_endpoint ve access_token değerlerini döndürür; access_token, işletmenin kendi token'ıdır. Numaranın sayfası aynı değerleri Plug in your own system altında gösterir. access_token değeri null ise numarayı bir bilgisayardan Reconnect ile yeniden bağlayarak token üretin. Token'ı bir parola gibi koruyun, çünkü onu elinde tutan herkes işletme adına mesaj gönderebilir.
Yaygın hatalar
- Gövdeyi yeniden serileştirilmiş JSON üzerinden HMAC kontrolü. Python'un json.dumps fonksiyonu varsayılan olarak ayraçlardan sonra boşluk ekler; bu yüzden ayrıştırılıp yeniden dökülen bir gövde artık eşleşmez. Ham baytları doğrulayın.
- Gizli anahtarı base64 ile çözmek ya da whsec_ önekini atmak. Anahtar, size bir kez gösterildiği gibi, tüm dizenin UTF-8 metni olarak kullanılır.
- Doğrudan rotada X-Hub-Signature-256 değerini kendi Meta uygulama gizli anahtarınızla doğrulamak. Meta, paylaşılmayan easyCoexistence uygulama gizli anahtarıyla imzalar; bu yüzden gerçek olaylar başarısız olur. Bunun yerine yoldaki gizli değerle kimlik doğrulayın.
- Pencereyi ulaşma zamanından okumak. Saatler sonra yeniden denenen bir iletme yine Meta'nın özgün zaman damgasını taşır; ona göre karşılaştırın, yoksa ajan 24 saat sonra yanıt verir ve Meta gönderimi reddeder.
Her numara 24/7 izlenir; bağlantı koptuğunda uyarı gelir. Numara başına aylık US$ 9'dan US$ 0.75'e kadar, numara ekledikçe düşer; ilk 3 gün ücretsiz denemedir.
Sık sorulan sorular
Yapay zeka ajanı sesli notları ve fotoğrafları anlayabilir mi?
Evet, kendi kodunuzla. Meta'nın payload'u medya kimliğini taşır: GET /<media-id> ve numaranın token'ı ile indirin, dönen URL'yi aynı Authorization başlığıyla çekin, sonra modelinizle yazıya dökün ya da tarif edin. Automations yalnızca [voice message] gibi yer tutucuları görür.
Örnekler hangi modelleri kullanabilir?
OpenAI uyumlu bir chat completions uç noktasının arkasındaki herhangi bir model; buna OpenAI'ınkiler ve OpenRouter üzerinden erişilenler de dahildir. Ya da askModel ve ask_model yerine sağlayıcınızın SDK'sını koyun. easyCoexistence yapay zeka için asla ücret almaz: sağlayıcınız size doğrudan faturalandırır.
Ajan bir konuşmayı başlatabilir mi?
Yalnızca onaylı bir şablonla; aynı gönderim uç noktasına type template ile gönderilir. Coexistence numarasında şablonlar yalnızca API üzerinden gider, asla telefon uygulamasından gitmez; Meta bunları işletmenin kendi WhatsApp Business Account hesabına mesaj başına faturalandırır.
Tek bir ajan birden çok numaraya hizmet eder mi?
Evet. value.metadata.phone_number_id veya connection.phone_number_id ile yönlendirin ve her numara için ayrı bir gönderim uç noktası, bir token ve bir iletme gizli anahtarı tutun; çünkü her numaranın kendisine ait olanları vardır.
Okumaya devam edin
Başlamaya hazır mısınız?
WhatsApp Coexistence'ı aylar değil, dakikalar içinde kurun. Uygulama telefonda çalışmaya devam eder.
Ücretsiz denemeyi başlatınDoğrulama tarihi