Yeni Safe Mode yeni numaraları ısıtarak WhatsApp ban riskini azaltır. Detaylı bilgi →

Maytapi/Dokümanlar//webhook

/webhookAnlık olaylar, JSON olarak

WhatsApp Webhook API

Gelen WhatsApp mesajlarını, teslim ve okundu bilgilerini ve oturum durum değişikliklerini gerçekleştiği anda kendi sunucunuzda alın. Tek bir adres tanımlayın; bağlı tüm numaralar olaylarını oraya JSON olarak gönderir.

  • gelen mesajlar
  • teslim ve okundu bilgisi
  • oturum durumu
  • tüm numaralar için tek adres
Teslim ve okundu bildirimleri için WhatsApp webhook
Maytapi panelinde webhook ayarları ve webhook'a iletilen gelen WhatsApp mesajı
Olaylar

Dört olay tipi, tek uç nokta

Her olayda bir type alanı bulunur; böylece tek bir uç nokta tüm numaralarınızın mesajlarını, bildirimlerini ve durum değişikliklerini yönlendirebilir.

  • type: message

    Gelen mesajlar

    Numaranıza gelen metin, görsel, video, ses, doküman, konum ve kişi kartları; gönderen ve sohbet kimliğiyle birlikte.

  • type: ack

    Teslim ve okundu bilgisi

    Gönderdiğiniz mesajın ne zaman teslim edildiğini, telefona ulaştığını, görüldüğünü, dinlendiğini veya silindiğini öğrenin.

  • type: status

    Oturum durumu

    Bir telefon aktif olduğunda, QR okutulmayı beklediğinde, boşta kaldığında veya telefon hatası verdiğinde haberdar olun.

  • live chat

    Canlı destek olayları

    API'yi LiveChat ile birlikte kullandığınızda temsilci tarafındaki olaylar da aynı webhook'a gelir.

  • phone_id

    Çoklu numara yönlendirme

    Her olay product_id ve phone_id içerir; tek uç nokta hesabınızdaki tüm numaralara hizmet verebilir.

  • reply

    Hazır yanıt adresi

    Gelen mesaj olayları bir reply adresi taşır; müşteriye yanıt vermek tek bir POST isteğidir.

Kurulum

Webhook'u tek istekle tanımlayın

HTTPS adresinizi bir kez /setWebhook ucuna gönderin. Bundan sonra ürününüze bağlı her telefon olaylarını bu adrese JSON olarak iletir.

  • ✓Bağlı tüm numaralar için tek adres
  • ✓HTTPS POST üzerinden sade JSON
  • ✓Panelden veya API'den istediğiniz zaman değiştirin
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"}'
Canlı akış

Mesajlar ve bildirimler anında

Müşteri yazar, sunucunuz bilir. Siz mesaj gönderirsiniz, teslim ve okundu bilgileri saniyeler içinde gelir — sürekli sorgulama gerekmez.

  • ✓Olayı onaylamak için HTTP 200 döndürün
  • ✓Yüksek hacimde olayları asenkron işleyin
  • ✓Bildirimleri gönderilen mesajlarla msgId üzerinden eşleştirin
message"type": "text", "text": "Siparişim kargoya verildi mi?"
ack · delivered"ackCode": 1, "ackType": "delivered"
ack · reached"ackCode": 2, "ackType": "reached"
ack · seen"ackCode": 3, "ackType": "seen"
status"status": "active"
Veri yapısı

Bir olay neye benzer

Olaylar sade JSON nesneleridir. type alanı nasıl işleyeceğinizi, product_id ve phone_id ise olayın hangi hesaba ve numaraya ait olduğunu söyler.

  • ✓message: metin, medya, konum, vCard ve daha fazlası
  • ✓ack: ackCode ve ackType ile teslim durumu
  • ✓status: active, qr-code, idle, phone-error, loading, disabled
{
  "type": "message",
  "product_id": "1a2b3c4d-…",
  "phone_id": 12345,
  "user": {
    "id": "90532xxxxx67@c.us",
    "name": "Customer",
    "phone": "90532xxxxx67"
  },
  "message": {
    "id": "3EB081AF26FADE6416D8",
    "type": "text",
    "text": "Is my order shipped?",
    "fromMe": false
  },
  "conversation": "90532xxxxx67@c.us",
  "receiver": "90532xxxxx21",
  "timestamp": 1574081887,
  "reply": "https://api.maytapi.com/api/1a2b3c4d-…/12345/sendMessage"
}
Bildirimler

Teslim ve okundu bilgisi, kod kod

Ack olayları gönderilen her mesajın ne kadar ilerlediğini bildirir. İhtiyacınız yoksa /setAckPreference ile kapatıp yalnızca gelen mesajları alabilirsiniz.

  • ✓Sesli mesajların dinlendiği de bildirilir
  • ✓Silinen mesajlar da bildirilir
ackTypeackCodeAnlamı
delivered1WhatsApp sunucularına iletildi
reached2Alıcının telefonuna ulaştı
seen3Alıcı tarafından görüldü
played4Sesli mesaj dinlendi
deleted5Kullanıcı tarafından silindi
Yanıt

Aynı olaydan yanıt verin

Gelen mesaj olayları hazır bir reply adresi içerir. Webhook'u hızlıca onaylayın, ardından yanıtınızı gönderin — otomatik yanıt ve chatbot için basit bir kalıp.

  • ✓Her dil ve framework ile çalışır
  • ✓Kendi mesajlarınızı message.fromMe ile ayıklayın
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."
    })
  });
});
Kullanım alanları

Ekipler webhook ile neler kuruyor

  • CRM ve destek senkronu

    Gelen her WhatsApp mesajı CRM'inizde otomatik olarak bir kayıt veya talep olur.

  • Chatbot ve AI ajanları

    Gelen mesajları botunuza veya AI ajanınıza iletin, reply adresiyle anında yanıtlayın.

  • Teslimat takibi

    Teslim ve okundu bilgilerini saklayarak müşterinin hangi sipariş bildirimini gerçekten gördüğünü bilin.

  • Oturum izleme

    Bir numara yeniden QR okutma gerektirdiğinde veya telefon hatası verdiğinde ekibinizi uyarın.

  • Kodsuz otomasyon

    Webhook'u n8n veya Make'e yönlendirin, backend yazmadan akış kurun.

  • Ortak gelen kutusu

    Birden fazla numaradan gelen sohbetleri doğru ekip üyesine yönlendirin.

SSS

WhatsApp webhook SSS

Aklınıza takılanı destek ekibine WhatsApp'tan sorabilirsiniz. Ortalama yanıt süresi 24 saatin altında.

Destek merkezi →
WhatsApp webhook nedir?

Webhook, WhatsApp numaranızda bir şey olduğunda — yeni gelen mesaj, teslim veya okundu bilgisi ya da oturum durum değişikliği — Maytapi'nin HTTPS POST isteğiyle çağırdığı, sunucunuzdaki bir adrestir.

Webhook'uma hangi olaylar gelir?

Gelen mesajlar (type: message), teslim ve okundu bilgileri (type: ack), oturum durum değişiklikleri (type: status) ve API'yi LiveChat ile birlikte kullanıyorsanız canlı destek olayları.

Herkese açık bir HTTPS adresi gerekir mi?

Evet. Webhook adresinin internetten erişilebilir olması gerekir. Geliştirme sırasında yerel sunucunuzu ngrok gibi bir tünelle dışarı açabilirsiniz.

Tek webhook birden fazla numarayı karşılayabilir mi?

Evet. Webhook ürün bazında tanımlanır ve her olay phone_id içerir; tek uç nokta hesabınızdaki tüm numaralara hizmet verebilir.

Teslim ve okundu bildirimlerini kapatabilir miyim?

Evet. /setAckPreference ucunu ack_delivery false olarak çağırın; webhook'unuza yalnızca gelen mesajlar ve durum değişiklikleri gelir.

WhatsApp API'yi kullanmaya başlayın

Anahtarı alın, ilk mesajı on dakikada gönderin

Onay yok, şablon yok, kart yok. Üç gün boyunca tüm uçlar açık.