Ü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
POSTisteklerini kabul eden, 100 karakter veya daha kısa, herkese açık bir URL (httpskullanın).
Dinleyici ekleyin#
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.
Yeni bir dinleyici başlatın
Add New Listener kartına tıklayın.
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.
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.
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:
| İşlem | Ne olur |
|---|---|
| Düzenle | Webhook 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. |
| Sil | Onayladı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ı#
| Durum | Anlamı |
|---|---|
| Aktif | Numara bağlıyken mesajlar senkronize edilir ve webhook'lar gönderilir. |
| Beklemede | Dinleyici oluşturulduğunda (örneğin Zapier tarafından) numara bağlı değildi. Numara bağlandıktan sonra Enable'a tıklayın. |
| Pasif | Devre dışı. Hiçbir şey senkronize edilmez ve webhook gönderilmez. |
İstatistikler#
| Kart | Ne 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#
Dinleyiciyi açın
Karttaki ⋮ simgesine, ardından Düzenle'ye tıklayın.
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.
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çinmessage_sent. Yalnızca Webhook Events içinde işaretlenen olaylar gönderilir. - Unibox gelen kutusundan verilen yanıtlar genellikle
message_senttetiklemez, çünkü senkronizasyon çalıştığında gelen kutusunda zaten bulunurlar. - Yanıt: 8 saniye içinde herhangi bir HTTP
2xxdurumuyla yanıt verin. - Yeniden denemeler: zaman aşımı, bağlantı hatası,
429veya5xxyanıtı 30 saniye, 1 dakika ve 2 dakika sonra olmak üzere en fazla 3 kez yeniden denenir.400veya404gibi 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.timestampdeğerine göre sıralayın.
Başlıklar#
| Başlık | Değer |
|---|---|
Content-Type | application/json |
X-Wbiztool-Event | message_received veya message_sent |
X-Wbiztool-Timestamp | Webhook'un gönderildiği zaman, ISO 8601 UTC olarak. Gövdedeki timestamp ile aynıdır. |
X-Wbiztool-Webhook-Id | Dinleyicinin kimliği. Gövdedeki webhook_id ile aynıdır. |
X-Wbiztool-Signature | sha256= ve ardından imza. Dinleyicinin gizli anahtarı olduğunda her zaman gönderilir; bir URL ayarlandığında bu her zaman geçerlidir. |
İçerik (payload)#
{
"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"
}
}{
"event": "message_sent",
"timestamp": "2026-09-16T10:33:40.117205+00:00",
"webhook_id": 42,
"whatsapp_client_id": "678",
"whatsapp_phone": "919812345678",
"message": {
"id": "[email protected]_3EB0F9E8D7C6B5A40312",
"type": "chat",
"content": "Yes, it will reach you today by 6 PM.",
"from": "919876543210",
"from_name": "Aman",
"to": "919812345678",
"timestamp": "2026-09-16T10:31:04+00:00",
"whatsapp_timestamp": 1789554664,
"direction": "outgoing",
"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"
}
}{
"event": "message_received",
"timestamp": "2026-09-16T10:36:02.904311+00:00",
"webhook_id": 42,
"whatsapp_client_id": "678",
"whatsapp_phone": "919812345678",
"message": {
"id": "[email protected]_3EB0A7B6C5D4E3F20109",
"type": "image",
"content": "📸 Image",
"from": "919876543210",
"from_name": "Aman",
"to": "919812345678",
"timestamp": "2026-09-16T10:34:51+00:00",
"whatsapp_timestamp": 1789554891,
"direction": "incoming",
"status": "pending",
"is_forwarded": false,
"forwarding_score": 0,
"media": {
"filename": "",
"mimetype": "image/jpeg",
"size": 245760
}
},
"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"
}
}{
"event": "message_received",
"timestamp": "2026-09-16T10:40:15.330187+00:00",
"webhook_id": 42,
"whatsapp_client_id": "678",
"whatsapp_phone": "919812345678",
"message": {
"id": "[email protected][email protected]",
"type": "chat",
"content": "Is the store open on Sunday?",
"from": "120363041234567890",
"from_name": "Acme Loyalty Club",
"to": "919812345678",
"timestamp": "2026-09-16T10:39:02+00:00",
"whatsapp_timestamp": 1789555142,
"direction": "incoming",
"status": "pending",
"is_forwarded": false,
"forwarding_score": 0
},
"contact": {
"whatsapp_id": "[email protected]",
"phone": "120363041234567890",
"lid": null,
"phone_hidden": false,
"name": "Acme Loyalty Club",
"is_group": true,
"is_business": false
},
"organisation": {
"id": "10314",
"name": "Acme Stores"
},
"group": {
"name": "Acme Loyalty Club"
}
}Yukarıdaki numaralar, kimlikler ve adlar örnektir.
Üst düzey alanlar#
| Alan | Tür | Açıklama |
|---|---|---|
event | string | message_received veya message_sent. |
timestamp | string | Webhook'un gönderildiği zaman (ISO 8601, UTC). |
webhook_id | integer | Dinleyicinin kimliği. |
whatsapp_client_id | string | WhatsApp ayarları sayfasında gösterildiği şekliyle WhatsApp numaranızın kimliği. |
whatsapp_phone | string | WhatsApp numaranız. |
message | object | Mesaj. Aşağıya bakın. |
contact | object | Konuşmanın yapıldığı kişi veya grup. Aşağıya bakın. |
organisation | object | Çalışma alanınızın id (string) ve name değerleri. |
group | object | Yalnızca grup sohbetleri için: name, grubun adı. |
message alanları#
| Alan | Tür | Açıklama |
|---|---|---|
id | string | WhatsApp'ın mesaj kimliği. Yinelenenleri yok saymak için kullanın. |
type | string | Metin için chat. Aksi halde WhatsApp'ın türü; örneğin image, video, audio, ptt (sesli not), document, sticker veya location. |
content | string | chat 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. |
from | string | Her iki yönde de her zaman kişinin numarası (veya grubun kimliği). |
from_name | string | Kişinin veya grubun adı. Boş olabilir. |
to | string | Her iki yönde de her zaman sizin WhatsApp numaranız. |
timestamp | string | Mesajın WhatsApp'ta gönderildiği zaman (ISO 8601, UTC). |
whatsapp_timestamp | integer | Aynı zaman, saniye cinsinden Unix zaman damgası olarak. |
direction | string | incoming veya outgoing. Yönü anlamak için from ve to yerine bunu kullanın. |
status | string | Şu anda her zaman pending. Teslim veya okunma durumu için buna güvenmeyin. |
is_forwarded | boolean | Mesajın iletilip iletilmediği. |
forwarding_score | integer | Mesajın kaç kez iletildiği. |
media | object | Ayrıntılar mevcut olduğunda medya mesajları için: filename, mimetype ve bayt cinsinden size. Dosyanın kendisi dahil edilmez. |
quoted_message_id | string | Yalnızca mesaj başka bir mesajı yanıtladığında. |
contact alanları#
| Alan | Tür | Açıklama |
|---|---|---|
whatsapp_id | string | WhatsApp kimliği; örneğin bir kişi için [email protected], bir grup için …@g.us. |
phone | string | + olmadan numara ya da gruplar için grubun kimliği. WhatsApp kişinin numarasını gizlediğinde boştur. |
lid | string veya null | WhatsApp bir gizlilik kimliği kullandığında kişinin 62337239240946@lid gibi gizlilik kimliği. Aksi halde null. |
phone_hidden | boolean | WhatsApp kişinin numarasını paylaşmadığında true. Wbiztool, WhatsApp numarayı kullanılabilir hale getirdiğinde onu doldurur. |
name | string | Wbiztool'un kişi için sahip olduğu ad ya da grup adı. Boş olabilir. |
is_group | boolean | Grup sohbetleri için true. |
is_business | boolean | Biliniyorsa 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);# Flask
import hashlib
import hmac
import json
import os
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["WBIZTOOL_WEBHOOK_SECRET"].encode()
@app.post("/wbiztool/webhook")
def wbiztool_webhook():
raw_body = request.get_data() # raw bytes, before parsing
expected = "sha256=" + hmac.new(SECRET, raw_body, hashlib.sha256).hexdigest()
received = request.headers.get("X-Wbiztool-Signature", "")
if not hmac.compare_digest(expected, received):
abort(401)
data = json.loads(raw_body)
if data["event"] == "message_received":
print(f"New message from {data['contact']['phone']}: {data['message']['content']}")
return "", 200<?php
$secret = getenv('WBIZTOOL_WEBHOOK_SECRET');
$rawBody = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$received = $_SERVER['HTTP_X_WBIZTOOL_SIGNATURE'] ?? '';
if (!hash_equals($expected, $received)) {
http_response_code(401);
exit('Invalid signature');
}
$data = json_decode($rawBody, true);
if ($data['event'] === 'message_received') {
error_log('New message from ' . $data['contact']['phone'] . ': ' . $data['message']['content']);
}
http_response_code(200);İ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 sorun | Ne 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 limit | Artık ihtiyacınız olmayan bir dinleyiciyi silin veya eklenti adedini artırın. |
| No available WhatsApp numbers | Başka bir numara bağlayın; ya da numara zaten bir dinleyicidir. |
This WhatsApp number is already a listener | Bunun yerine mevcut kartı düzenleyin. |
Invalid WhatsApp client | Numaranın bağlantısı kesildi. WhatsApp ayarları sayfasında yeniden bağlayın ve sayfayı yenileyin. |
Kaydederken value too long içeren hata | Webhook URL'si 100 karakterden uzun. Daha kısa bir URL kullanın. |
| Hiç webhook gelmiyor | Dinleyicinin 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 eksik | Sunucunuz 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 kayboldu | Sunucunuz 410 Gone yanıtı verdi; bu yüzden Wbiztool oraya göndermeyi durdurdu. URL'yi Edit Listener içinde yeniden ekleyin. |
| İmza eşleşmiyor | Yeniden 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österiyor | Numara henüz kontrol edilmedi. Bağlı olmalı ve mesaj göndermekle meşgul olmamalıdır. |
