İçeriğe geç
Wbiztool

Ürün kılavuzları

Gelen mesaj webhook'ları (dinleyiciler)

Bir dinleyici, WhatsApp numaralarınızdan birini Unibox'a bağlar ve sunucunuza gelen mesaj webhook'u gönderebilir. Panelde dinleyiciler Incoming Triggers (Gelen tetikleyiciler) sayfasında yönetilir. Bir numara dinleyici olduğunda sohbetleri Unibox gelen kutusuna senkronize edilir ve bir webhook URL'si eklerseniz Wbiztool her yeni mesajı sunucunuza gönderir. Konuşmaları bir CRM'e kaydetmek, ekibinizi uyarmak veya otomatik yanıt oluşturmak için webhook'ları kullanın.

Başlamadan önce#

  • Unibox eklentisi. WhatsApp numarası başına aylık 20 $ veya yıllık 200 $'dır ve sahip olabileceğiniz dinleyici sayısı eklenti adedine eşittir. Panel içindeki Faturalandırma ve planlar sayfasında Available Add-ons (Kullanılabilir eklentiler) altından satın alın. Eklenti olmadan Incoming Triggers sayfası yine açılır, ancak Add New Listener (Yeni dinleyici ekle) düğmesine tıklamak Subscribe to Unibox Add-on (Unibox eklentisine abone ol) düğmesiyle birlikte Unibox eklentisi gerekli uyarısını gösterir.
  • WhatsApp ayarları sayfasında bağlı bir WhatsApp numarası. Yalnızca henüz dinleyici olmayan bağlı numaralar eklenebilir.
  • Çalışma alanının sahibi veya editörü olmanız gerekir.
  • Webhook'lar için: JSON gövdeli POST isteklerini kabul eden, 100 karakter veya daha kısa, herkese açık bir URL (https kullanın).

Dinleyici ekleyin#

  1. Incoming Triggers sayfasını açın

    Kenar çubuğunda Unibox menüsünü açın ve Incoming Triggers'a tıklayın veya Incoming Triggers sayfasına gidin.

  2. Yeni bir dinleyici başlatın

    Add New Listener kartına tıklayın.

  3. Numarayı seçin

    Numarayı Select WhatsApp Number (WhatsApp numarası seçin) alanında seçin. Liste No available WhatsApp numbers (Kullanılabilir WhatsApp numarası yok) diyorsa, bağlı tüm numaralar zaten dinleyicidir veya bağlı numara yoktur.

  4. Webhook ekleyin (isteğe bağlı)

    Webhook URL’si (isteğe bağlı) alanını girin. Bir URL yazdığınızda Webhook Events (Webhook olayları) görünür: Incoming Messages (Gelen mesajlar), Outgoing Messages (Giden mesajlar) veya ikisini birden işaretli tutun. URL'yi daha sonra ekleyebilir veya değiştirebilirsiniz.

  5. Kaydedin

    Add Listener (Dinleyici ekle) düğmesine tıklayın. Dinleyici, Aktif durumuyla bir kart olarak görünür. Bir URL girdiyseniz bunun için bir webhook gizli anahtarı oluşturulur.

Dinleyicileri yönetin#

Her kart numarayı, durumunu, Webhook URL: değerini (veya Not configured – yapılandırılmadı), Last Activity: (Son etkinlik; numaranın en son ne zaman mesajlar için kontrol edildiği ya da Never – hiç) ve göz düğmesine tıklayana kadar gizli kalan Webhook gizli anahtarı değerini gösterir.

Bir karttaki ⋮ menüsünü açarak şunları yapabilirsiniz:

İşlemNe olur
DüzenleWebhook URL'sini, webhook olaylarını veya gizli anahtarı değiştirin. Numara değiştirilemez.
Disable / Enable (Devre dışı bırak / Etkinleştir)Devre dışı bırakmak dinleyiciyi Pasif yapar: numaranın gelen kutusuna senkronizasyonu durur ve webhook gönderilmez. Etkinleştirmek onu yeniden Aktif yapar.
SilOnayladıktan sonra dinleyiciyi kaldırır. Gelen kutusunda zaten bulunan konuşmalar kalır. Aynı numarayı daha sonra yeniden eklemek dinleyiciyi geri getirir. Yeniden eklerken bir webhook URL'si girerseniz dinleyici, varsa önceki webhook gizli anahtarını korur ve yenisini almaz.

Dinleyici durumları#

DurumAnlamı
AktifNumara bağlıyken mesajlar senkronize edilir ve webhook'lar gönderilir.
BeklemedeDinleyici oluşturulduğunda (örneğin Zapier tarafından) numara bağlı değildi. Numara bağlandıktan sonra Enable'a tıklayın.
PasifDevre dışı. Hiçbir şey senkronize edilmez ve webhook gönderilmez.

İstatistikler#

KartNe gösterir
Active Listeners (Etkin dinleyiciler)Devre dışı olanlar dahil sayfadaki tüm dinleyiciler.
Available Numbers (Kullanılabilir numaralar)Henüz dinleyici olmayan bağlı numaralar. Dinleyicisini sildiğiniz numaralar burada hâlâ kullanılmış sayılır; bu yüzden gerçekte ekleyebileceğinizden daha az gösterebilir.
Total Limit (Toplam sınır)Unibox eklentinizin izin verdiği dinleyici sayısı.
Messages Today (Bugünkü mesajlar)Henüz izlenmiyor; her zaman 0 gösterir.

Webhook URL'sini veya olayları değiştirin#

  1. Dinleyiciyi açın

    Karttaki ⋮ simgesine, ardından Düzenle'ye tıklayın.

  2. Ayarları güncelleyin

    Webhook URL’si (isteğe bağlı) alanını ve Webhook Events seçeneklerini değiştirin. Bu numara için webhook'ları durdurmak üzere URL'yi temizleyin: gizli anahtarı da kaldırılır ve yeniden bir URL eklerseniz yenisi oluşturulur.

  3. Kaydedin

    Update Listener (Dinleyiciyi güncelle) düğmesine tıklayın.

Gizli anahtarı yeniden oluşturun#

Edit Listener (Dinleyiciyi düzenle) içinde Webhook gizli anahtarı'nın yanındaki yenile düğmesine tıklayın ve onaylayın. Yeni gizli anahtar, ardından Update Listener'a tıklamadan pencereyi kapatsanız bile hemen kaydedilir ve istekler o andan itibaren onunla imzalanır. Sunucunuzu yeni gizli anahtarla hemen güncelleyin.

Webhook'lar nasıl iletilir#

Wbiztool, numara senkronize edildiğinde bulunan her yeni mesaj için URL'nize bir POST isteği gönderir; senkronizasyon, numara bağlıyken ve mesaj göndermekle meşgul değilken birkaç dakikada bir gerçekleşir.

  • Olaylar: insanların numaranıza gönderdiği mesajlar için message_received, numaranızdan (telefondan, kampanyalardan veya API'den) gönderilen mesajlar için message_sent. Yalnızca Webhook Events içinde işaretlenen olaylar gönderilir.
  • Unibox gelen kutusundan verilen yanıtlar genellikle message_sent tetiklemez, çünkü senkronizasyon çalıştığında gelen kutusunda zaten bulunurlar.
  • Yanıt: 8 saniye içinde herhangi bir HTTP 2xx durumuyla yanıt verin.
  • Yeniden denemeler: zaman aşımı, bağlantı hatası, 429 veya 5xx yanıtı 30 saniye, 1 dakika ve 2 dakika sonra olmak üzere en fazla 3 kez yeniden denenir. 400 veya 404 gibi diğer yanıtlar yeniden denenmez.
  • 410 Gone: Wbiztool webhook URL'sini dinleyiciden kaldırır ve oraya göndermeyi durdurur. Mesajlar yine Unibox'a aktarılır.
  • Sıralama: istekler birbirinden bağımsız gönderilir ve sırasız ulaşabilir. Sıra önemliyse message.timestamp değerine göre sıralayın.

Başlıklar#

BaşlıkDeğer
Content-Typeapplication/json
X-Wbiztool-Eventmessage_received veya message_sent
X-Wbiztool-TimestampWebhook'un gönderildiği zaman, ISO 8601 UTC olarak. Gövdedeki timestamp ile aynıdır.
X-Wbiztool-Webhook-IdDinleyicinin kimliği. Gövdedeki webhook_id ile aynıdır.
X-Wbiztool-Signaturesha256= ve ardından imza. Dinleyicinin gizli anahtarı olduğunda her zaman gönderilir; bir URL ayarlandığında bu her zaman geçerlidir.

İçerik (payload)#

Örnek webhook gövdeleri
{
  "event": "message_received",
  "timestamp": "2026-09-16T10:31:12.482913+00:00",
  "webhook_id": 42,
  "whatsapp_client_id": "678",
  "whatsapp_phone": "919812345678",
  "message": {
    "id": "[email protected]_3EB0C1A2B3D4E5F60718",
    "type": "chat",
    "content": "Hi, is my order #4821 out for delivery?",
    "from": "919876543210",
    "from_name": "Aman",
    "to": "919812345678",
    "timestamp": "2026-09-16T10:29:58+00:00",
    "whatsapp_timestamp": 1789554598,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "919876543210",
    "lid": null,
    "phone_hidden": false,
    "name": "Aman",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Acme Stores"
  }
}

Yukarıdaki numaralar, kimlikler ve adlar örnektir.

Üst düzey alanlar#

AlanTürAçıklama
eventstringmessage_received veya message_sent.
timestampstringWebhook'un gönderildiği zaman (ISO 8601, UTC).
webhook_idintegerDinleyicinin kimliği.
whatsapp_client_idstringWhatsApp ayarları sayfasında gösterildiği şekliyle WhatsApp numaranızın kimliği.
whatsapp_phonestringWhatsApp numaranız.
messageobjectMesaj. Aşağıya bakın.
contactobjectKonuşmanın yapıldığı kişi veya grup. Aşağıya bakın.
organisationobjectÇalışma alanınızın id (string) ve name değerleri.
groupobjectYalnızca grup sohbetleri için: name, grubun adı.

message alanları#

AlanTürAçıklama
idstringWhatsApp'ın mesaj kimliği. Yinelenenleri yok saymak için kullanın.
typestringMetin için chat. Aksi halde WhatsApp'ın türü; örneğin image, video, audio, ptt (sesli not), document, sticker veya location.
contentstringchat mesajları için metin. Medya için bunun yerine bir etiket: 📸 Image, 🎥 Video, 🎵 Audio, 🎤 Voice Message, 😊 Sticker, Document: ve ardından belgenin metni (metin yoksa Document) ya da diğer her şey için baş harfleri büyük tür adı, örneğin Location. Açıklamalar (caption) dahil edilmez.
fromstringHer iki yönde de her zaman kişinin numarası (veya grubun kimliği).
from_namestringKişinin veya grubun adı. Boş olabilir.
tostringHer iki yönde de her zaman sizin WhatsApp numaranız.
timestampstringMesajın WhatsApp'ta gönderildiği zaman (ISO 8601, UTC).
whatsapp_timestampintegerAynı zaman, saniye cinsinden Unix zaman damgası olarak.
directionstringincoming veya outgoing. Yönü anlamak için from ve to yerine bunu kullanın.
statusstringŞu anda her zaman pending. Teslim veya okunma durumu için buna güvenmeyin.
is_forwardedbooleanMesajın iletilip iletilmediği.
forwarding_scoreintegerMesajın kaç kez iletildiği.
mediaobjectAyrıntılar mevcut olduğunda medya mesajları için: filename, mimetype ve bayt cinsinden size. Dosyanın kendisi dahil edilmez.
quoted_message_idstringYalnızca mesaj başka bir mesajı yanıtladığında.

contact alanları#

AlanTürAçıklama
whatsapp_idstringWhatsApp kimliği; örneğin bir kişi için [email protected], bir grup için …@g.us.
phonestring+ olmadan numara ya da gruplar için grubun kimliği. WhatsApp kişinin numarasını gizlediğinde boştur.
lidstring veya nullWhatsApp bir gizlilik kimliği kullandığında kişinin 62337239240946@lid gibi gizlilik kimliği. Aksi halde null.
phone_hiddenbooleanWhatsApp kişinin numarasını paylaşmadığında true. Wbiztool, WhatsApp numarayı kullanılabilir hale getirdiğinde onu doldurur.
namestringWbiztool'un kişi için sahip olduğu ad ya da grup adı. Boş olabilir.
is_groupbooleanGrup sohbetleri için true.
is_businessbooleanBiliniyorsa WhatsApp Business hesapları için true.

İmzayı doğrulayın#

Her istek, dinleyicinizin gizli anahtarıyla HMAC-SHA256 kullanılarak imzalanır. İmza, ham istek gövdesi üzerinde, tam olarak alındığı şekliyle hesaplanır ve X-Wbiztool-Signature içinde sha256= artı küçük harfli onaltılık özet olarak gönderilir.

İmzayı her zaman JSON'u ayrıştırmadan önce ham baytlardan hesaplayın. Gövdeyi ayrıştırıp yeniden kodlamak onu değiştirir (örneğin İngilizce olmayan karakterler ve emojiler \uXXXX olarak kaçışlı gelir) ve imza eşleşmez.

// Express: keep the raw body for this route
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.WBIZTOOL_WEBHOOK_SECRET;

app.post("/wbiztool/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const received = req.get("X-Wbiztool-Signature") || "";

  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).send("Invalid signature");

  const data = JSON.parse(req.body.toString("utf8"));
  if (data.event === "message_received") {
    console.log(`New message from ${data.contact.phone}: ${data.message.content}`);
  }
  res.sendStatus(200); // reply quickly; do slow work in the background
});

app.listen(3000);

İmza zaman damgası başlığını kapsamaz; bu yüzden bir isteğin yeniden oynatılmasına karşı koruma sağlamaz. Bu önemliyse işlediğiniz her message.id değerini saklayın ve tekrarları yok sayın.

Sorun giderme#

Mesaj veya sorunNe yapmalı
Add New Listener'a tıkladığınızda Unibox eklentisi gerekliÇalışma alanınızda Unibox eklentisi yok. Panel içindeki Faturalandırma ve planlar sayfasında Available Add-ons altından satın alın.
You have reached your unibox numbers limitArtık ihtiyacınız olmayan bir dinleyiciyi silin veya eklenti adedini artırın.
No available WhatsApp numbersBaşka bir numara bağlayın; ya da numara zaten bir dinleyicidir.
This WhatsApp number is already a listenerBunun yerine mevcut kartı düzenleyin.
Invalid WhatsApp clientNumaranın bağlantısı kesildi. WhatsApp ayarları sayfasında yeniden bağlayın ve sayfayı yenileyin.
Kaydederken value too long içeren hataWebhook URL'si 100 karakterden uzun. Daha kısa bir URL kullanın.
Hiç webhook gelmiyorDinleyicinin Aktif olduğunu, numaranın bağlı olduğunu, olay türünün işaretli olduğunu ve URL'nizin geçerli sertifikaya sahip, herkese açık bir https adresi olduğunu kontrol edin. Mesajlar yalnızca birkaç dakika sonraki bir sonraki senkronizasyondan sonra gönderilir.
Bazı webhook'lar eksikSunucunuz bir 4xx durumu döndürdü veya 3 yeniden denemenin tamamında başarısız oldu. Eksik mesajın zamanı için sunucu günlüklerinizi kontrol edin.
Webhook URL'si dinleyiciden kaybolduSunucunuz 410 Gone yanıtı verdi; bu yüzden Wbiztool oraya göndermeyi durdurdu. URL'yi Edit Listener içinde yeniden ekleyin.
İmza eşleşmiyorYeniden kodlanmış JSON değil ham gövdeyi ve güncel gizli anahtarı kullanın. Gizli anahtarı yeniden oluşturmak onu değiştirir. Bir Zapier Zap'i numarayı kullanırken istekler Zapier'in gizli anahtarıyla Zapier'e gider.
Last Activity: Never gösteriyorNumara henüz kontrol edilmedi. Bağlı olmalı ve mesaj göndermekle meşgul olmamalıdır.

İlgili sayfalar#