Maytapi/Documentație//webhook
/webhookEvenimente în timp real, în JSONAPI webhook WhatsApp
Primește pe propriul server mesajele WhatsApp, confirmările de livrare și citire și schimbările de stare ale sesiunii chiar în momentul în care au loc. Setezi o adresă, iar toate numerele conectate trimit acolo evenimentele în JSON.
- mesaje primite
- confirmări de livrare și citire
- starea sesiunii
- o adresă pentru toate numerele

Patru tipuri de evenimente, un singur endpoint
Fiecare eveniment are un câmp type, așa că un singur endpoint poate direcționa mesajele, confirmările și schimbările de stare pentru toate numerele tale.
-
type: message
Mesaje primite
Text, imagini, video, audio, documente, locații și carduri de contact trimise către numărul tău, cu expeditorul și id-ul conversației.
-
type: ack
Confirmări de livrare și citire
Află când un mesaj trimis a fost livrat, a ajuns pe telefon, a fost văzut, redat sau șters.
-
type: status
Starea sesiunii
Primești o notificare când un telefon devine activ, așteaptă scanarea QR, intră în inactivitate sau raportează o eroare.
-
live chat
Evenimente live chat
Dacă folosești API-ul împreună cu LiveChat, evenimentele agenților ajung la același webhook.
-
phone_id
Rutare pentru mai multe numere
Fiecare eveniment conține product_id și phone_id, deci un endpoint deservește toate numerele din cont.
-
reply
Adresă de răspuns gata făcută
Mesajele primite includ o adresă reply: răspunsul către client este o singură cerere POST.
Setează webhookul cu o singură cerere
Trimite o dată endpointul HTTPS către /setWebhook. De atunci, fiecare telefon conectat la produsul tău trimite evenimentele la acea adresă în JSON.
- ✓O adresă pentru toate numerele conectate
- ✓JSON simplu prin HTTPS POST
- ✓O schimbi oricând din panou sau prin API
curl -X POST "https://api.maytapi.com/api/$PID/setWebhook" \
-H "x-maytapi-key: $TOKEN" \
-H "Content-Type: application/json" \
-d '{"webhook": "https://example.com/maytapi/webhook"}'await fetch(`https://api.maytapi.com/api/${PID}/setWebhook`, {
method: "POST",
headers: { "x-maytapi-key": TOKEN, "Content-Type": "application/json" },
body: JSON.stringify({ webhook: "https://example.com/maytapi/webhook" })
});import requests
requests.post(
f"https://api.maytapi.com/api/{PID}/setWebhook",
headers={"x-maytapi-key": TOKEN},
json={"webhook": "https://example.com/maytapi/webhook"},
timeout=10,
)$ch = curl_init("https://api.maytapi.com/api/$pid/setWebhook");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["x-maytapi-key: $token", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode(["webhook" => "https://example.com/maytapi/webhook"]),
]);
echo curl_exec($ch);Mesaje și confirmări pe loc
Clientul scrie, serverul tău află. Trimiți un mesaj, iar confirmările de livrare și citire sosesc în câteva secunde, fără interogări repetate.
- ✓Returnează HTTP 200 pentru a confirma evenimentul
- ✓Procesează evenimentele asincron la volum mare
- ✓Folosește msgId pentru a lega confirmările de mesaje
"type": "text", "text": "Comanda mea a fost expediată?""ackCode": 1, "ackType": "delivered""ackCode": 2, "ackType": "reached""ackCode": 3, "ackType": "seen""status": "active"Cum arată un eveniment
Evenimentele sunt obiecte JSON compacte. Câmpul type îți spune cum să-l tratezi; product_id și phone_id îți spun cărui cont și număr îi aparține.
- ✓message: text, media, locație, vCard și altele
- ✓ack: progresul livrării cu ackCode și ackType
- ✓status: active, qr-code, idle, phone-error, loading, disabled
{
"type": "message",
"product_id": "1a2b3c4d-…",
"phone_id": 12345,
"user": {
"id": "4072xxxxx67@c.us",
"name": "Customer",
"phone": "4072xxxxx67"
},
"message": {
"id": "3EB081AF26FADE6416D8",
"type": "text",
"text": "Is my order shipped?",
"fromMe": false
},
"conversation": "4072xxxxx67@c.us",
"receiver": "4072xxxxx21",
"timestamp": 1574081887,
"reply": "https://api.maytapi.com/api/1a2b3c4d-…/12345/sendMessage"
}{
"type": "ack",
"product_id": "1a2b3c4d-…",
"data": [
{
"ackType": "seen",
"ackCode": 3,
"chatId": "4072xxxxx67@c.us",
"msgId": "3EB0A1B2C3D4E5F6",
"time": 1586874663
}
]
}{
"type": "status",
"pid": "1a2b3c4d-…",
"phone_id": 12345,
"status": "active"
}Livrare și citire, cod cu cod
Evenimentele ack arată cât de departe a ajuns fiecare mesaj trimis. Dacă nu ai nevoie de ele, dezactivează-le cu /setAckPreference și primește doar mesajele primite.
- ✓Mesajele vocale raportează și când sunt redate
- ✓Sunt raportate și mesajele șterse
| ackType | ackCode | Semnificație |
|---|---|---|
| delivered | 1 | Livrat către serverele WhatsApp |
| reached | 2 | A ajuns pe telefonul destinatarului |
| seen | 3 | Văzut de destinatar |
| played | 4 | Mesaj vocal redat |
| deleted | 5 | Șters de utilizator |
Răspunde din același eveniment
Mesajele primite includ o adresă reply gata făcută. Confirmă rapid webhookul, apoi trimite răspunsul — un model simplu pentru răspunsuri automate și chatboți.
- ✓Funcționează cu orice limbaj sau framework
- ✓Ignoră propriile mesaje cu message.fromMe
app.post("/maytapi/webhook", express.json(), async (req, res) => {
res.sendStatus(200); // acknowledge first
const event = req.body;
if (event.type !== "message" || event.message.fromMe) return;
await fetch(event.reply, {
method: "POST",
headers: { "x-maytapi-key": TOKEN, "Content-Type": "application/json" },
body: JSON.stringify({
to_number: event.conversation,
type: "text",
message: "Thanks! We received your message."
})
});
});@app.post("/maytapi/webhook")
def webhook():
event = request.get_json()
if event.get("type") == "message" and not event["message"]["fromMe"]:
requests.post(
event["reply"],
headers={"x-maytapi-key": TOKEN},
json={
"to_number": event["conversation"],
"type": "text",
"message": "Thanks! We received your message.",
},
timeout=10,
)
return "", 200Ce construiesc echipele cu webhookul
-
Sincronizare CRM și helpdesk
Fiecare mesaj WhatsApp primit devine automat un tichet sau o înregistrare în CRM.
-
Chatboți și agenți AI
Trimite mesajele primite botului sau agentului AI și răspunde în timp real prin adresa reply.
-
Urmărirea livrărilor
Păstrează confirmările de livrare și citire ca să știi ce notificări de comandă au văzut clienții.
-
Monitorizarea sesiunilor
Anunță echipa când un număr are nevoie de o nouă scanare QR sau raportează o eroare.
-
Automatizări fără cod
Direcționează webhookul către n8n sau Make și construiește fluxuri fără backend.
-
Inbox partajat
Direcționează conversațiile de pe mai multe numere către persoana potrivită din echipă.
Întrebări frecvente despre webhookul WhatsApp
Întreabă echipa de suport orice pe WhatsApp. Timpul mediu de răspuns este sub 24 de ore.
Centru de ajutor →Ce este un webhook WhatsApp?
Un webhook este o adresă de pe serverul tău pe care Maytapi o apelează printr-o cerere HTTPS POST ori de câte ori se întâmplă ceva pe numărul tău de WhatsApp: un mesaj nou, o confirmare de livrare sau citire ori o schimbare de stare a sesiunii.
Ce evenimente ajung la webhookul meu?
Mesaje primite (type: message), confirmări de livrare și citire (type: ack), schimbări de stare a sesiunii (type: status) și, dacă folosești API-ul cu LiveChat, evenimente live chat.
Am nevoie de o adresă HTTPS publică?
Da. Webhookul trebuie să fie accesibil de pe internet. În timpul dezvoltării poți expune serverul local printr-un tunel precum ngrok.
Un webhook poate deservi mai multe numere?
Da. Webhookul se setează per produs și fiecare eveniment conține phone_id, deci un singur endpoint deservește toate numerele din cont.
Pot dezactiva confirmările de livrare și citire?
Da. Apelează /setAckPreference cu ack_delivery setat pe false, iar webhookul va primi doar mesaje și schimbări de stare.
Alte funcționalități ale API-ului WhatsApp

Obține cheia și trimite primul mesaj în zece minute
Fără aprobare, fără șabloane, fără card. Toate endpointurile sunt deschise timp de trei zile.