Nou Safe Mode încălzește numerele noi pentru a reduce riscul de blocare pe WhatsApp. Află mai multe →

Maytapi/Documentație//webhook

/webhookEvenimente în timp real, în JSON

API 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
Webhookuri WhatsApp pentru confirmări de livrare și citire
Setările webhook în consola Maytapi și mesajul WhatsApp primit care este livrat către webhook
Evenimente

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.

Configurare

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"}'
Flux live

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
message"type": "text", "text": "Comanda mea a fost expediată?"
ack · delivered"ackCode": 1, "ackType": "delivered"
ack · reached"ackCode": 2, "ackType": "reached"
ack · seen"ackCode": 3, "ackType": "seen"
status"status": "active"
Payload

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"
}
Confirmări

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
ackTypeackCodeSemnificație
delivered1Livrat către serverele WhatsApp
reached2A ajuns pe telefonul destinatarului
seen3Văzut de destinatar
played4Mesaj vocal redat
deleted5Șters de utilizator
Răspuns

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."
    })
  });
});
Cazuri de utilizare

Ce 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

Î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.

Începe să folosești API-ul 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.