API Dokümantasyonu — WhatsApp API Gateway

Kimlik Doğrulama

Tüm API istekleri kimlik doğrulama gerektirir. Token'ınızı Ayarlar sayfasından alabilirsiniz.

Doğrulama Yöntemleri

API token'ınızı aşağıdaki üç yöntemden biriyle gönderebilirsiniz:

Authorization Header (Önerilen)

Authorization: Bearer YOUR_TOKEN

Query Parametresi

?token=YOUR_TOKEN

Tüm instance'a özel endpoint'ler /api/instance/{instanceId}/... formatındadır. Instance ID'nizi Instance Yönetimi sayfasından öğrenebilirsiniz.

Base URL

Instance Yönetimi

WhatsApp bağlantılarını (instance) oluşturma, listeleme, bağlama ve yönetme.

GET /api/instance Tüm instance'ları listele

Tüm oluşturulmuş instance'ları ve bağlantı durumlarını döndürür.

Yanıt

{
  "instances": ["default", "inst_a1b2c3d4"],
  "statuses": {
    "default": { "accountStatus": { "status": "open" } },
    "inst_a1b2c3d4": { "accountStatus": { "status": "disconnected" } }
  }
}

POST /api/instance Yeni instance oluştur

Yeni bir WhatsApp instance'ı oluşturur. ID belirtilmezse otomatik üretilir.

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
id	string	opsiyonel	Instance ID (boş bırakılırsa `inst_xxxx` üretilir)
description	string	opsiyonel	Instance açıklaması

Örnek İstek

{ "description": "İş Hattı" }

Yanıt

{ "success": true, "instanceId": "inst_a1b2c3d4" }

DELETE /api/instance/{instanceId} Instance sil

Instance'ı ve tüm oturum verilerini kalıcı olarak siler.

Yanıt

{ "success": true }

Bu işlem geri alınamaz. Tüm oturum ve auth verileri silinir.

GET /api/instance/{instanceId}/status Bağlantı durumu

Instance'ın WhatsApp bağlantı durumunu döndürür.

Yanıt

{
  "accountStatus": { "status": "open" }
}

Olası durumlar: open, connecting, disconnected

GET /api/instance/{instanceId}/qr QR kodu (JSON)

QR kodunu base64 data URI formatında döndürür. Zaten bağlıysa qrCode null döner.

Yanıt

{ "qrCode": "data:image/png;base64,iVBOR...", "status": "connecting" }

GET /api/instance/{instanceId}/qrcode QR kodu (PNG)

QR kodunu doğrudan PNG resim olarak döndürür. <img> etiketinde kullanılabilir.

Yanıt

Content-Type: image/png — QR yoksa JSON döner.

GET /api/instance/{instanceId}/me Hesap bilgileri

Bağlı WhatsApp hesabının bilgilerini döndürür.

Yanıt

{ "id": "905xx:xx@s.whatsapp.net", "name": "Ahmet", "phone": "905xxxxxxxxx" }

POST /api/instance/{instanceId}/connect Bağlantıyı başlat

Instance'ın WhatsApp bağlantısını başlatır. Bağlantı başarılı olunca QR kodu üretilir.

Yanıt

{ "success": true }

POST /api/instance/{instanceId}/restart Yeniden başlat

WhatsApp bağlantısını kapatıp yeniden başlatır. İşlem arka planda gerçekleşir.

Yanıt

{ "success": true, "message": "Restarting..." }

POST /api/instance/{instanceId}/logout Oturumu kapat

WhatsApp oturumunu kapatır. Tekrar bağlanmak için yeni QR taraması gerekir.

Yanıt

{ "success": true }

Logout sonrası oturum verileri temizlenir ve QR taramasını tekrar yapmanız gerekir.

POST /api/instance/{instanceId}/clear Mesajları temizle

Instance'a ait tüm mesaj geçmişini veritabanından siler.

Yanıt

{ "success": true }

Mesajlar

Metin, resim, dosya, ses, video, konum, kişi kartı, sticker, anket ve tepki gönderme. to alanı telefon numarası (+905xxxxxxxxx) veya grup ID'si (xxxxx@g.us) olabilir. Medya URL veya Base64 data URI destekler.

POST/api/instance/{instanceId}/messages/chatMetin mesajı

Metin mesajı gönderir.

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
to	string	zorunlu	Alıcı telefon numarası veya grup ID
body	string	zorunlu	Mesaj metni

Örnek İstek

{ "to": "+905xxxxxxxxx", "body": "Merhaba!" }

Yanıt

{ "sent": true, "id": "BAQE..." }

POST/api/instance/{instanceId}/messages/imageResim gönder

Resim gönderir. URL veya Base64 data URI destekler.

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
to	string	zorunlu	Alıcı
image	string	zorunlu	Resim URL'i veya Base64 data URI
caption	string	opsiyonel	Resim altı açıklama

Örnek İstek

{
  "to": "+905xxxxxxxxx",
  "image": "https://example.com/photo.jpg",
  "caption": "Ürün görseli"
}

Yanıt

{ "sent": true, "id": "BAQE..." }

POST/api/instance/{instanceId}/messages/videoVideo gönder

Video gönderir. URL veya Base64 data URI destekler.

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
to	string	zorunlu	Alıcı
video	string	zorunlu	Video URL'i veya Base64 data URI
caption	string	opsiyonel	Video açıklaması

Örnek İstek

{
  "to": "+905xxxxxxxxx",
  "video": "https://example.com/video.mp4",
  "caption": "Tanıtım videosu"
}

Yanıt

{ "sent": true, "id": "BAQE..." }

POST/api/instance/{instanceId}/messages/documentDosya gönder

Dosya/döküman gönderir.

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
to	string	zorunlu	Alıcı
document	string	zorunlu	Dosya URL'i veya Base64 data URI
filename	string	opsiyonel	Dosya adı (varsayılan: "document")
caption	string	opsiyonel	Dosya açıklaması

Örnek İstek

{ "to": "+905xxxxxxxxx", "document": "https://example.com/rapor.pdf", "filename": "rapor.pdf" }

Yanıt

{ "sent": true, "id": "BAQE..." }

POST/api/instance/{instanceId}/messages/audioSes dosyası

Ses dosyası gönderir (müzik çalar olarak görünür).

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
to	string	zorunlu	Alıcı
audio	string	zorunlu	Ses URL'i veya Base64 data URI

Örnek İstek

{ "to": "+905xxxxxxxxx", "audio": "https://example.com/audio.mp3" }

POST/api/instance/{instanceId}/messages/voiceSesli mesaj (PTT)

Push-to-talk sesli mesaj gönderir (yeşil dalga ikonu ile görünür).

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
to	string	zorunlu	Alıcı
audio	string	zorunlu	Ses URL'i veya Base64 (tercihen OGG Opus)

Örnek İstek

{ "to": "+905xxxxxxxxx", "audio": "https://example.com/voice.ogg" }

/messages/audio ile aradaki fark: voice mesaj PTT olarak gönderilir ve WhatsApp'ta yeşil mikrofon ikonu ile görünür.

POST/api/instance/{instanceId}/messages/stickerSticker gönder

Sticker gönderir. WebP formatı önerilir.

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
to	string	zorunlu	Alıcı
sticker	string	zorunlu	Sticker URL'i veya Base64 (WebP)

Örnek İstek

{ "to": "+905xxxxxxxxx", "sticker": "https://example.com/sticker.webp" }

POST/api/instance/{instanceId}/messages/locationKonum gönder

Harita konumu gönderir.

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
to	string	zorunlu	Alıcı
lat	number	zorunlu	Enlem
lng	number	zorunlu	Boylam
name	string	opsiyonel	Konum adı
address	string	opsiyonel	Adres metni

Örnek İstek

{ "to": "+905xxxxxxxxx", "lat": 41.0082, "lng": 28.9784, "name": "İstanbul" }

POST/api/instance/{instanceId}/messages/contactKişi kartı

vCard formatında kişi kartı gönderir.

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
to	string	zorunlu	Alıcı
contact_name	string	opsiyonel	Kişi adı (varsayılan: "Contact")
contact_phone	string	opsiyonel	Kişi telefon numarası

Örnek İstek

{ "to": "+905xxxxxxxxx", "contact_name": "Ahmet", "contact_phone": "905xxxxxxxxx" }

POST/api/instance/{instanceId}/messages/pollAnket gönder

Anket (poll) gönderir.

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
to	string	zorunlu	Alıcı
name	string	zorunlu	Anket sorusu
values	string[]	zorunlu	Seçenekler (2-12 arası)
selectableCount	number	opsiyonel	`0` = çoklu, `1` = tekli seçim (varsayılan: 0)

Örnek İstek

{ "to": "+905xxxxxxxxx", "name": "Toplantı?", "values": ["Pzt", "Çar", "Cum"], "selectableCount": 1 }

POST/api/instance/{instanceId}/messages/reactionEmoji tepkisi

Bir mesaja emoji tepkisi gönderir.

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
to	string	zorunlu	Sohbet ID'si
msgId	string	zorunlu	Mesaj ID'si
emoji	string	zorunlu	Emoji karakteri

Örnek İstek

{ "to": "+905xxxxxxxxx", "msgId": "BAQE...", "emoji": "\ud83d\udc4d" }

POST/api/instance/{instanceId}/messages/deleteMesaj sil

Gönderilmiş mesajı herkesten siler.

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
to	string	zorunlu	Sohbet ID'si
msgId	string	zorunlu	Silinecek mesaj ID'si

Yanıt

{ "deleted": true }

Sadece sizin gönderdiğiniz mesajları silebilirsiniz.

GET/api/instance/{instanceId}/messagesMesaj geçmişi

Mesaj geçmişini sayfalanmış olarak getirir.

Query Parametreleri

Parametre	Tip	Zorunlu	Açıklama
limit	number	opsiyonel	Sayfa başına mesaj (varsayılan: 100)
page	number	opsiyonel	Sayfa numarası (varsayılan: 1)
status	string	opsiyonel	Filtre: `sent`, `received`, `pending`, `failed`, `delivered`, `read`
chatId	string	opsiyonel	Sohbet ID'sine göre filtrele

GET/api/instance/{instanceId}/messages/statisticsİstatistikler

Mesaj istatistiklerini döndürür.

Yanıt

{ "total": 1250, "sent": 480, "received": 720, "pending": 5, "delivered": 460, "failed": 10 }

POST/api/instance/{instanceId}/messages/clearGeçmişi temizle

Veritabanındaki tüm mesaj geçmişini siler.

Yanıt

{ "success": true }

Sohbetler

Aktif sohbetleri listeleme, mesajlarını getirme ve yönetme.

GET/api/instance/{instanceId}/chatsSohbetleri listele

Tüm aktif sohbetleri döndürür.

Yanıt

[{ "id": "905xx@s.whatsapp.net", "name": "Ahmet", "unreadCount": 3, "lastMessage": 1711100000, "archived": false }]

GET/api/instance/{instanceId}/chats/idsSohbet ID'leri

Sadece sohbet ID'lerini döndürür.

Yanıt

["905xx@s.whatsapp.net", "120363xx@g.us"]

GET/api/instance/{instanceId}/chats/messagesSohbet mesajları

Belirli bir sohbetin mesajlarını getirir.

Query Parametreleri

Parametre	Tip	Zorunlu	Açıklama
chatId	string	zorunlu	Sohbet ID'si
limit	number	opsiyonel	(varsayılan: 50)

POST/api/instance/{instanceId}/chats/readOkundu işaretle

Sohbeti okundu olarak işaretler.

Örnek İstek

{ "chatId": "905xx@s.whatsapp.net" }

POST/api/instance/{instanceId}/chats/archiveArşivle

{ "chatId": "905xx@s.whatsapp.net" }

POST/api/instance/{instanceId}/chats/unarchiveArşivden çıkar

{ "chatId": "905xx@s.whatsapp.net" }

POST/api/instance/{instanceId}/chats/deleteSohbet sil

{ "chatId": "905xx@s.whatsapp.net" }

WhatsApp API kısıtlaması nedeniyle silme işlemi sohbeti arşivler.

Kişiler

Kişi listesi, numara sorgulama, profil fotoğrafı ve engelleme işlemleri.

GET/api/instance/{instanceId}/contactsKişileri listele

Yanıt

[{ "id": "905xx@s.whatsapp.net", "name": "Ahmet Yılmaz", "notify": "Ahmet" }]

GET/api/instance/{instanceId}/contacts/idsKişi ID'leri

Yanıt

["905xx@s.whatsapp.net", "905yy@s.whatsapp.net"]

GET/api/instance/{instanceId}/contacts/contactKişi detayı

Belirli bir kişinin bilgilerini döndürür.

Query Parametreleri

Parametre	Tip	Zorunlu	Açıklama
chatId	string	zorunlu	Kişi ID'si (ör: `905xxxxxxxxx`)

Yanıt

{ "id": "905xx@s.whatsapp.net", "name": "Ahmet", "notify": "Ahmet" }

GET/api/instance/{instanceId}/contacts/checkNumara sorgula

Numaranın WhatsApp'ta kayıtlı olup olmadığını kontrol eder.

Query Parametreleri

Parametre	Tip	Zorunlu	Açıklama
chatId	string	zorunlu	Kontrol edilecek numara

Yanıt

{ "exists": true, "jid": "905xx@s.whatsapp.net" }

GET/api/instance/{instanceId}/contacts/imageProfil fotoğrafı

Query:

Parametre	Tip	Zorunlu	Açıklama
chatId	string	zorunlu	Kişi ID'si

Yanıt

{ "url": "https://pps.whatsapp.net/..." }

POST/api/instance/{instanceId}/contacts/blockEngelle

{ "chatId": "905xxxxxxxxx" }

Yanıt

{ "success": true }

POST/api/instance/{instanceId}/contacts/unblockEngeli kaldır

{ "chatId": "905xxxxxxxxx" }

Yanıt

{ "success": true }

Gruplar

Grup listesi, detayları ve katılımcı bilgileri.

GET/api/instance/{instanceId}/groupsGrupları listele

Yanıt

[{ "id": "120363xx@g.us", "name": "Ekip", "participants": 12, "creation": 1700000000, "desc": "..." }]

GET/api/instance/{instanceId}/groups/idsGrup ID'leri

["120363xx@g.us", "120363yy@g.us"]

GET/api/instance/{instanceId}/groups/groupGrup detayı

Query:

Parametre	Tip	Zorunlu	Açıklama
groupId	string	zorunlu	Grup ID'si

Yanıt

{ "id": "120363xx@g.us", "name": "Ekip", "description": "...", "participants": [{ "id": "905xx@s.whatsapp.net", "admin": "admin" }], "owner": "905xx@s.whatsapp.net" }

Medya

Dosya yükleme, listeleme ve silme. Yüklenen dosyalar mesaj gönderiminde kullanılabilir (maks. 64MB).

POST/api/instance/{instanceId}/media/uploadDosya yükle

multipart/form-data formatında dosya yükler.

Form Parametreleri

Parametre	Tip	Zorunlu	Açıklama
file	File	zorunlu	Yüklenecek dosya (maks. 64MB)

Örnek (curl)

curl -X POST -H "Authorization: Bearer TOKEN" -F "file=@photo.jpg" /api/instance/default/media/upload

Yanıt

{ "success": true, "file": { "filename": "171...-123.jpg", "originalname": "photo.jpg", "mimetype": "image/jpeg", "size": 245000, "url": "https://domain.com/media/default/171...-123.jpg" } }

Dönen url değerini mesaj gönderme endpoint'lerinde medya kaynağı olarak kullanabilirsiniz.

GET/api/instance/{instanceId}/media/listDosyaları listele

Yanıt

[{ "filename": "171...-123.jpg", "size": 245000, "url": "...", "created": "2026-03-22T10:00:00.000Z" }]

POST/api/instance/{instanceId}/media/deleteDosya sil

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
filename	string	zorunlu	Silinecek dosya adı

Yanıt

{ "success": true, "deleted": "171...-123.jpg" }

Chatbot

Gelen mesajlara otomatik yanıt kuralları. Kurallar öncelik sırasına göre (priority, düşük = önce) işlenir.

GET/api/instance/{instanceId}/chatbot/rulesKuralları listele

Yanıt

{ "rules": [{ "id": 1, "match_type": "contains", "trigger_text": "fiyat", "response": "...", "delay": 2, "enabled": 1, "priority": 0 }], "enabled": true }

POST/api/instance/{instanceId}/chatbot/rulesKural oluştur/güncelle

id verilirse günceller, boş bırakılırsa yeni kural oluşturur.

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
id	number	opsiyonel	Güncellenecek kural ID
match_type	string	opsiyonel	`exact`, `contains`, `startswith`, `regex` (varsayılan: "exact")
trigger_text	string	zorunlu	Tetikleyici metin
response	string	zorunlu	Otomatik yanıt
delay	number	opsiyonel	Gecikme (sn) (varsayılan: 1)
enabled	boolean	opsiyonel	(varsayılan: true)
priority	number	opsiyonel	Öncelik (varsayılan: 0)

Yanıt metninde değişkenler: {name}, {phone}, {time}

DELETE/api/instance/{instanceId}/chatbot/rules/{id}Kural sil

{ "success": true }

POST/api/instance/{instanceId}/chatbot/toggleChatbot aç/kapat

{ "enabled": true }

Yanıt

{ "success": true, "enabled": true }

Toplu Mesaj

Birden fazla alıcıya aynı mesajı gecikmeyle gönderin. İşlem arka planda çalışır.

POST/api/instance/{instanceId}/bulkToplu mesaj başlat

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
recipients	array	zorunlu	Alıcı dizisi: `[{ "id": "905xx", "name": "Ali" }]`
messageType	string	opsiyonel	`text`, `image`, `document` (varsayılan: "text")
body	string	koşullu	Mesaj metni (`body` veya `mediaUrl`'den biri zorunlu)
mediaUrl	string	koşullu	Medya URL'i
delay	number	opsiyonel	Gönderimler arası bekleme (sn) (varsayılan: 3)

Yanıt

{ "success": true, "jobId": 1 }

GET/api/instance/{instanceId}/bulkİşleri listele

Query:

Parametre	Tip	Zorunlu	Açıklama
limit	number	opsiyonel	(varsayılan: 20)
page	number	opsiyonel	(varsayılan: 1)

GET/api/instance/{instanceId}/bulk/{jobId}İş detayı

İş detayını ve alıcı bazlı durumları döndürür.

POST/api/instance/{instanceId}/bulk/{jobId}/cancelİptal et

{ "success": true }

Zamanlı Mesajlar

İleri tarihli mesajlar zamanlayın. Sistem her 30 saniyede zamanı gelen mesajları otomatik gönderir.

POST/api/instance/{instanceId}/scheduledZamanlı mesaj oluştur

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
recipient	string	zorunlu	Alıcı
recipientName	string	opsiyonel	Alıcı adı
messageType	string	opsiyonel	`text`, `image`, `document` (varsayılan: "text")
body	string	koşullu	Mesaj metni
mediaUrl	string	koşullu	Medya URL'i
filename	string	opsiyonel	Dosya adı
scheduledAt	string	zorunlu	ISO 8601 tarih (gelecekte)

Yanıt

{ "success": true, "id": 1 }

GET/api/instance/{instanceId}/scheduledListele

Query:

Parametre	Tip	Zorunlu	Açıklama
limit	number	opsiyonel	(varsayılan: 50)
page	number	opsiyonel	(varsayılan: 1)
status	string	opsiyonel	`pending`, `sent`, `failed`

DELETE/api/instance/{instanceId}/scheduled/{id}İptal et

Sadece pending durumundaki mesajlar iptal edilebilir.

{ "success": true }

Ayarlar

Instance bazlı webhook ve gönderim ayarları.

GET/api/instance/{instanceId}/settingsAyarları al

Yanıt

{ "webhookUrl": "https://...", "webhookEnabled": "true", "sendDelay": "0" }

POST/api/instance/{instanceId}/settingsAyarları güncelle

Gövde (Body)

Parametre	Tip	Zorunlu	Açıklama
webhookUrl	string	opsiyonel	Webhook URL'i
webhookEnabled	boolean	opsiyonel	Webhook aktif/pasif
sendDelay	number	opsiyonel	Mesajlar arası gecikme (ms)

Yanıt

{ "success": true }

Webhook Olayları

Webhook URL tanımlarsanız, aşağıdaki olaylar HTTP POST olarak gönderilir. Zaman aşımı: 10 saniye.

Tüm payload'lar: { "event": "...", "data": {...}, "timestamp": 171..., "instance_id": "default" }

message_receivedYeni mesaj geldiğinde

{ "event": "message_received", "data": { "id": "BAQE...", "from": "905xx@s.whatsapp.net", "to": "905yy@s.whatsapp.net", "body": "Merhaba", "type": "chat", "timestamp": 1711100000, "fromMe": false, "chatId": "905xx@s.whatsapp.net" }, "timestamp": 1711100000, "instance_id": "default" }

message_ackMesaj durumu değiştiğinde

{ "event": "message_ack", "data": { "id": "BAQE...", "chatId": "905xx@s.whatsapp.net", "status": "read", "fromMe": true }, "timestamp": 1711100000, "instance_id": "default" }

connection_statusBağlantı durumu değiştiğinde

{ "event": "connection_status", "data": { "status": "connected", "account": { "id": "905xx@s.whatsapp.net", "name": "Ahmet", "phone": "905xxxxxxxxx" } }, "timestamp": 1711100000, "instance_id": "default" }

Durum akışı: pending → sent → delivered → read → played

Hata Kodları

Tüm hatalar { "error": "Hata mesajı" } formatında döner.

Kod	Durum	Açıklama
400	Bad Request	Eksik veya geçersiz parametre
401	Unauthorized	Geçersiz veya eksik API token
404	Not Found	Instance veya kaynak bulunamadı
409	Conflict	Kaynak zaten mevcut
429	Too Many Requests	Rate limit aşıldı (200 istek/dk)
500	Server Error	Sunucu hatası