API referansı

Messages

Metin mesajı gönderimi, sıradaki gönderimin sonucu, kuyruk ve hız limiti durumu, içerik doğrulama.

post/messages/send

Metin mesajı gönder

Varsayılan olarak asenkron çalışır: mesaj gönderim sırasına alınır ve `202 Accepted` döner. Teslimat durumunu webhook üzerinden takip edin. `sync: true` ile yanıtı gönderim tamamlanana kadar bekletebilirsiniz — bu mod zaman aşımına (504) açıktır, toplu işlerde kullanmayın (`sync` yalnız whatsapp-web.js hatlarında geçerlidir). **Evolution hatları:** bu uç 19 Ekim 2026'dan beri Evolution hatlarında da çalışıyor; istek hattın köprüsüne iletilir, anti-ban kapıları (aynı metnin çok alıcıya gitmesi, hiç yazışılmamış numara günlük tavanı) ve çift gönderim koruması devrededir. Yanıtta `provider: "evolution"` döner. Evolution hatlarında gönderim sırası (mesajlar arasına hattın olgunluğuna göre bekleme koyan anti-ban sırası) açıktır: metin mesajı istek anında GİTMEZ, yanıt `202` + `queued: true` + `queue_id` döner ve `message_id` içermez. Sonucu (gitti mi, `message_id` ne, ulaştı mı, okundu mu) `GET /messages/queue/{queueId}` ile ya da `message.sent` / `message.status` webhook'larıyla izleyin; webhook gövdesindeki `queue_id` alanı 202 yanıtındaki numarayla eşleşir. Gönderim sırası o an kullanılamazsa mesaj doğrudan gönderilir ve `200` + `message_id` döner — istemciniz iki yanıtı da işleyebilmelidir. Anti-ban kapısı mesajı kestiğinde `429 blocked_by_antiban` döner ve mesaj GÖNDERİLMEZ; hat bağlı değilse `409 account_not_connected` döner.

Gerekli yetki: messages:send

Gövde alanları

`to`zorunlu	`string`	Alıcı telefon numarası (ülke kodlu) veya sohbet kimliği.
`message`zorunlu	`string`	Mesaj metni.
`type`	`string`	Değerler: `text`Varsayılan: `"text"`
`priority`	`integer`	Kuyruk önceliği. Küçük değer daha önce gönderilir (1 = en yüksek). Yalnız whatsapp-web.js (`web_qr`) hatlarında geçerli — Evolution hatlarında yok sayılır.Varsayılan: `3`
`sync`	`boolean`	true ise gönderim tamamlanana kadar bekler ve 200 döner. Yalnız whatsapp-web.js (`web_qr`) hatlarında geçerli — Evolution hatlarında yok sayılır; o hatta metin her durumda gönderim sırasına girer ve yanıt `202` + `queue_id` olur (sonuç `GET /messages/queue/{queueId}` ile izlenir).Varsayılan: `false`
`quoted_message_id`	`string`	Yanıtlanacak mesajın kimliği (alıntılı yanıt). Yalnız Evolution hatlarında.
`idempotency_key`	`string`	Aynı anahtarla gönderilen ikinci istek yeni mesaj göndermez, ilk denemenin sonucunu döndürür. Yalnız Evolution hatlarında. Biçim: 8-128 karakter, yalnız `A-Z a-z 0-9 _ -`. Uymayan anahtar `400 invalid_idempotency_key` döndürür.

İstek örneği

curl -X POST "https://api.zenwapp.com/api/v1/whatsapp/external/messages/send" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"905551234567","message":"Merhaba, siparişiniz kargoya verildi."}'

Yanıt 200

{
  "success": true,
  "message_id": "3EB0C5A7F2D94B1E8A6D",
  "timestamp": "2026-10-20T09:14:02.511Z",
  "queued": false,
  "provider": "evolution"
}

Yanıt kodları

200Mesaj doğrudan gönderildi; `message_id` WhatsApp'ın mesaj kimliğidir. whatsapp-web.js hatlarında `sync: true` ile, Evolution hatlarında yalnız gönderim sırası o an kullanılamadığında görülür.
202Mesaj gönderim sırasına alındı, HENÜZ GÖNDERİLMEDİ. `message_id` yoktur; `estimated_send_at` tahmini gönderim zamanı, `wait_ms` gönderime kalan tahmini süredir (milisaniye). Sonucu `queue_id` ile `GET /messages/queue/{queueId}` üzerinden ya da `message.sent` / `message.status` webhook'larıyla izleyin. Örnek bir Evolution hattının yanıtıdır; whatsapp-web.js hatlarında `provider` alanı gelmez, bunun yerine `chat_id`, `warnings`, `risk` gibi ek alanlar gelir.
400Gövde veya sorgu parametreleri geçersiz
429Hız limiti aşıldı. `Retry-After` başlığındaki saniye kadar bekleyin; gövdedeki `retry_after` aynı değerdir. `error` değerleri: `rate_limit_exceeded` — API anahtarının dakikalık hakkı (varsayılan 60) ya da IP adresinin dakikalık tavanı (600) aşıldı; `too_many_failed_auth` — bu IP adresinden 10 dakikada 30 istek `401` aldı, adres 15 dakika boyunca geçerli anahtarla bile reddedilir.
503Hattın sağlayıcısı çözümlenemedi (`provider_unresolved`). İstek tekrar denenebilir.
504`sync: true` modunda gönderim zaman aşımına uğradı. Mesaj yine de teslim edilmiş olabilir — webhook ile doğrulayın.

get/messages/rate-limit

Hız limiti durumu

Hesabın anlık gönderim limiti ve kalan kotasını döndürür.

Gerekli yetki: messages:read

İstek örneği

curl -X GET "https://api.zenwapp.com/api/v1/whatsapp/external/messages/rate-limit" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY"

Yanıt 200

{
  "success": true,
  "data": {
    "limit": 30,
    "remaining": 24,
    "window": "1m",
    "reset_at": "2026-07-30T09:13:00.000Z"
  }
}

Yanıt kodları

200Limit durumu

get/messages/queue

Kuyruk durumu

Bekleyen, işlenen ve başarısız iş sayılarını döndürür. Toplu gönderim sırasında ilerlemeyi izlemek için kullanın.

Gerekli yetki: messages:read

İstek örneği

curl -X GET "https://api.zenwapp.com/api/v1/whatsapp/external/messages/queue" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY"

Yanıt 200

{
  "success": true,
  "data": {
    "waiting": 12,
    "active": 1,
    "failed": 0,
    "delayed": 3
  }
}

Yanıt kodları

200Kuyruk durumu

get/messages/queue/{queueId}

Sıradaki gönderimin sonucu

Evolution hatlarında `POST /messages/send` yanıtındaki `queue_id` ile gönderimin sonucunu döndürür: mesaj gitti mi, WhatsApp mesaj kimliği (`message_id`) ne, karşı tarafa ulaştı mı. `status` değerleri: `queued` — sırada bekliyor, tahmini gönderim zamanı `estimated_send_at`; `sending` — WhatsApp'a veriliyor; `sent` — WhatsApp kabul etti (`message_id`, `sent_at`); `delivered` — karşı tarafa ulaştı; `read` — okundu (`delivered` ve `read` da `message_id` ve `sent_at` taşır); `failed` — gönderilemedi, mesaj GİTMEDİ (`error`: `send_failed` | `rate_limited`, `failed_at`), yeniden gönderebilirsiniz; `unknown` — mesaj gitmiş de olabilir, gitmemiş de (`failed_at`): tekrar göndermeden önce `GET /chats/{chatId}/messages` ile sohbete bakın, yoksa alıcı mesajı iki kez alabilir. Sonuçlar 24 saat tutulur; süre dolunca (ya da numara başka bir hatta aitse) `404` döner. Sürekli sorgulamak yerine `message.sent` / `message.status` webhook'larını kullanın; sorgulayacaksanız `estimated_send_at` zamanı geçmeden sormanız gerekmez. whatsapp-web.js hatlarında bu uç desteklenmez (`501`).

Gerekli yetki: messages:read

Yol parametreleri

queueIdzorunlu string `POST /messages/send` yanıtındaki `queue_id` (olduğu gibi; en fazla 200 karakter, yalnız `A-Z a-z 0-9 _ -`).

İstek örneği

curl -X GET "https://api.zenwapp.com/api/v1/whatsapp/external/messages/queue/905551234567" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY"

Yanıt 200

{
  "success": true,
  "data": {
    "queue_id": "6e170999-ac8d-4286-80b8-5e2adf70c2ee-1792494823117-k3x9qa",
    "status": "delivered",
    "message_id": "3EB0C5A7F2D94B1E8A6D",
    "sent_at": "2026-10-20T09:14:06.482Z"
  }
}

Yanıt kodları

200Gönderimin güncel durumu. Örnekteki mesaj karşı tarafa ulaşmış; `status` alanının diğer değerleri için açıklamaya bakın.
400`queueId` biçimi geçersiz
401API anahtarı eksik veya geçersiz
403API anahtarının bu uç için yetkisi yok
404Bu numarayla bir gönderim bulunamadı: sonuç 24 saatten eski ya da numara bu hatta ait değil.
501Hat whatsapp-web.js (`web_js`) sağlayıcısında; bu uç yalnız Evolution hatlarında çalışır.
502WhatsApp köprüsüne ulaşılamadı ya da köprü hata verdi (`evolution_bridge_unreachable` vb.). Kısa süre sonra tekrar deneyin; mesajın kendisi bu hatadan etkilenmez.
503Hattın sağlayıcısı çözümlenemedi (`provider_unresolved`). İstek tekrar denenebilir.
504WhatsApp köprüsü zamanında cevap vermedi (`evolution_bridge_timeout`). Kısa süre sonra tekrar deneyin.

post/messages/validate

Mesaj içeriğini doğrula

Mesajı göndermeden önce içerik politikası ve uzunluk kontrolünden geçirir. Toplu gönderim öncesi ön kontrol için kullanışlıdır.

Gerekli yetki: messages:read

Gövde alanları

messagezorunlu string

İstek örneği

curl -X POST "https://api.zenwapp.com/api/v1/whatsapp/external/messages/validate" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Kampanya metni burada"}'

Yanıt 200

{
  "success": true,
  "valid": true,
  "warnings": []
}

Yanıt kodları

200Doğrulama sonucu
400Gövde veya sorgu parametreleri geçersiz