API Referansı

Genel Bakış

WPBot REST API iki yönlü çalışır: kendi sisteminizden WhatsApp'a mesaj gönderirsiniz (REST) ve gelen mesajları webhook ile alırsınız. Tüm entegrasyon uçları, panelde her hesap için üretilen API anahtarı ile korunur.

# Temel adres (Base URL)
https://wp.gencan.net

# Tüm entegrasyon uçları hesap kimliği (accountId) ile adreslenir
/api/wa/{accountId}/...
            

Kimlik Doğrulama

Tüm entegrasyon istekleri, panelde her WhatsApp hesabı için üretilen API anahtarı ile doğrulanır. Anahtarı X-API-Key başlığında veya api_key sorgu parametresinde gönderin.

// Başlık ile (önerilen)
X-API-Key: wba_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

// veya sorgu parametresi ile
?api_key=wba_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
            

API anahtarı tek bir hesaba özeldir; adresteki {accountId} anahtarın hesabıyla eşleşmezse istek 403 ile reddedilir. Bu uçlar QR (Baileys) ile bağlı WhatsApp hesapları içindir.

Mesaj Gönderme API

POST /api/wa/{accountId}/send

Metin veya medya mesajı gönderir. voice:true ile ses dosyası sesli mesaj (PTT) olarak iletilir. Bireysel ve grup sohbetleri desteklenir.

Alan	Zorunlu	Açıklama
`to`	Evet	Alıcı. Düz numara (`905551112233`) → kişi; `12036301234-1234567890` biçimi → grup; sonu `@g.us`/`@s.whatsapp.net` olan tam JID de kullanılabilir.
`message`	Koşullu	Metin içeriği. `media_url` yoksa zorunludur. Medya varsa ve `caption` boşsa açıklama olarak kullanılır.
`media_url`	Koşullu	Gönderilecek dosyanın herkese açık HTTP(S) URL'i. Sunucu dosyayı bu adresten çeker. Tip otomatik algılanır (resim/video/ses/doküman). `message` yoksa zorunludur.
`caption`	Hayır	Resim/video/doküman için açıklama metni.
`filename`	Hayır	Doküman tipi medyada gösterilecek dosya adı.
`voice`	Hayır	`true` ise ses dosyası sesli mesaj (PTT) olarak gönderilir.
`quoted_message_id`	Hayır	Yanıtlanacak/alıntılanacak mesajın ID'si.
`from_me`	Hayır	Alıntılanan mesajın bu hesapça gönderildiğini belirtir (grup yanıtlarında). Varsayılan `false`.
`participant`	Hayır	Grup alıntısında, alıntılanan mesajı gönderen kişinin numarası/JID'i.

// Metin mesajı
POST /api/wa/12/send
X-API-Key: wba_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "to": "905551112233",
  "message": "Merhaba! Siparişiniz hazırlandı."
}
            

// Medya (doküman) gönderme
POST /api/wa/12/send
X-API-Key: wba_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "to": "905551112233",
  "media_url": "https://cdn.orneksite.com/fatura.pdf",
  "filename": "fatura.pdf",
  "caption": "Faturanız ektedir."
}

// Başarılı yanıt
{ "success": true, "message_id": "3EB0C1A2B3C4D5E6F7" }
            

POST /api/wa/{accountId}/delete-message

Bir mesajı herkesten siler (geri çeker). Gruplarda yönetici, başkasının mesajını from_me:false + participant ile silebilir.

Alan	Zorunlu	Açıklama
`to`	Evet	Mesajın bulunduğu sohbetin numarası/JID'i.
`message_id`	Evet	Silinecek mesajın ID'si.
`from_me`	Hayır	Hedef mesaj bu hesapça mı gönderildi? Belirtilmezse varsayılan `true`.
`participant`	Hayır	Grupta başkasının mesajını silerken (`from_me:false`) mesajı gönderenin numarası/JID'i.

POST /api/wa/{accountId}/react

Bir mesaja emoji reaksiyonu ekler. Reaksiyonu kaldırmak için boş metin gönderin.

Alan	Zorunlu	Açıklama
`to`	Evet	Mesajın bulunduğu sohbetin numarası/JID'i.
`message_id`	Evet	Reaksiyon verilecek mesajın ID'si.
`emoji`	Evet	Reaksiyon emojisi (örn. `"👍"`). Reaksiyonu kaldırmak için boş metin `""` gönderin. Alan mutlaka bulunmalıdır.
`from_me`	Hayır	Hedef mesaj bu hesapça mı gönderildi? Varsayılan `false`.
`participant`	Hayır	Grupta, reaksiyon verilen mesajı gönderenin numarası/JID'i.

GET /api/wa/{accountId}/status

Hesabın anlık WhatsApp bağlantı durumunu döndürür.

GET /api/wa/12/status
X-API-Key: wba_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

// Yanıt — status: disconnected | connecting | qr_pending | connected
{
  "success": true,
  "status": "connected",
  "phone_number": "905551112233"
}
            

GET /api/wa/{accountId}/profile-picture

Bir kişi veya grubun profil resmi URL'ini getirir.

GET /api/wa/12/profile-picture?jid=905551112233&type=image
X-API-Key: wba_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

// type: image (tam boy) veya preview (küçük). Resim gizliyse url null döner.
{ "success": true, "profile_picture_url": "https://pps.whatsapp.net/..." }
            

POST /api/wa/{accountId}/inject-incoming

Dışarıdan gelen bir mesajı, WhatsApp'tan gelmiş gibi akışa enjekte eder (test/köprüleme için).

Alan	Zorunlu	Açıklama
`from`	Evet	Gönderen numara/JID.
`message`	Evet	Enjekte edilecek mesaj metni.
`sender_name`	Hayır	Gönderenin görünen adı. Belirtilmezse `from` değeri kullanılır.

Gelen Mesajlar — Webhook

Hesabı panelde Webhook moduna alıp bir Webhook URL girdiğinizde, gelen her mesaj bu adrese POST edilir.

İstek Başlıkları

Content-Type: application/json
X-WPBot-Account: 12                // her zaman gönderilir
X-Webhook-Signature: <hmac_sha256>   // yalnızca webhook_secret tanımlıysa
            

Standart Payload (metin mesajı)

{
  "account_id": 12,
  "phone_number": "905551112233",
  "from": "905559876543",
  "sender_name": "Ahmet Yılmaz",
  "message_type": "text",
  "content": "Merhaba, siparişim nerede?",
  "message_id": "3EB0C1A2B3C4D5E6F7",
  "timestamp": "2026-07-07T12:34:56.000Z",
  "direction": "incoming"
}
            

direction: gelen mesajlarda incoming, kendi cihazınızdan gönderilenlerde outgoing. Mesaj bir yanıtsa (bireysel veya grup fark etmez) payload'a quoted_message_id alanı eklenir.

Grup Mesajı (ek alanlar)

{
  // ...standart alanlar...
  "is_group": true,
  "group_name": "Müşteri Destek",
  "participant": "905559876543"
}
            

Medya İçeren Mesaj (ek alan)

{
  // ...standart alanlar... message_type: image | video | audio | document | sticker
  "media": {
    "mimetype": "image/jpeg",
    "filename": null,
    "size": 84213,
    "base64": "/9j/4AAQSkZJRgABAQAA...",
    "data_uri": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA..."
  }
}
            

İmza Doğrulama

webhook_secret tanımlıysa gövde HMAC-SHA256 ile imzalanıp X-Webhook-Signature başlığında gönderilir. Kendi tarafınızda aynı imzayı üretip karşılaştırın.

// Node.js
const crypto = require('crypto');

function dogrula(rawBody, imza, secret) {
  const beklenen = crypto
    .createHmac('sha256', secret)
    .update(rawBody)   // JSON.stringify edilmiş ham gövde
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(imza), Buffer.from(beklenen));
}
            

// PHP
$beklenen = hash_hmac('sha256', $rawBody, $secret);
if (!hash_equals($beklenen, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'])) {
    http_response_code(401);
    exit;
}
            

Hata Yanıtları

Tüm hatalar { success: false, error: "..." } biçiminde döner.

Kod	Anlamı
`400`	Eksik veya geçersiz parametre.
`401`	API anahtarı eksik veya geçersiz.
`403`	API anahtarı bu hesapla eşleşmiyor.
`429`	Hız sınırı aşıldı (dakikada 60 istek).
`503`	WhatsApp bağlantısı aktif değil (hesap bağlı değil).
`500`	Sunucu hatası.

Hız Sınırları

Gönderim uçları (send, delete-message, react, inject-incoming) hesap başına dakikada 60 istek ile sınırlıdır; sınır aşılırsa 429 döner. Durum ve profil resmi uçları sınırlandırılmamıştır.