API referansı

Media

Görsel, doküman, ses, voice ve sticker gönderimi ile medya dosyalarına erişim.

post/messages/send-media

Medya gönder

Görsel, video, ses veya doküman gönderir. Medyayı üç yoldan biriyle verebilirsiniz: `media_url` (uzak dosya), `media_data` (base64) veya `multipart/form-data` içinde `file` alanı. `as_document`, `as_voice`, `as_sticker` bayrakları gönderim biçimini belirler. **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. 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. Evolution hatlarında medya gönderim sırasına girmez: yanıt genellikle doğrudan `200` + `message_id` döner (metin mesajındaki `202` + `queue_id` davranışı medyada yoktur). Evolution hatlarında `as_sticker` ve `as_document` desteklenmez (400 `unsupported_option`). **Dosya boyutu:** Evolution hatlarında etkili tavan 64 MB; aşan dosya `413 file_too_large` döner (gövdede `limit_bytes` ve `file_size_bytes`). whatsapp-web.js hatlarında doküman tavanı 100 MB, görsel/video/ses 16 MB, sticker 500 KB olup aşım `400 file_too_large` döndürür.

Gerekli yetki: messages:send

Gövde alanları

`to`zorunlu	`string`
`media_url`	`string`	Herkese açık dosya URL'i.
`media_data`	`string`	Base64 kodlanmış dosya içeriği.
`mimetype`	`string`	`media_data` kullanıldığında zorunlu.
`filename`	`string`	Alıcıya görünecek dosya adı.
`caption`	`string`	Medya açıklaması.
`as_document`	`boolean`	Dosya olarak gönderir (önizleme yok).
`as_voice`	`boolean`	Sesli mesaj (PTT) olarak gönderir.
`as_sticker`	`boolean`	Sticker olarak gönderir.

İstek örneği

curl -X POST "https://api.zenwapp.com/api/v1/whatsapp/external/messages/send-media" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"905551234567","media_url":"https://cdn.example.com/katalog.pdf","filename":"katalog.pdf","caption":"2026 ürün kataloğu"}'

Yanıt 200

{
  "success": true,
  "message_id": "3EB0D81F4C2A97E05B13",
  "timestamp": "2026-10-20T09:15:40.208Z",
  "queued": false,
  "provider": "evolution"
}

Yanıt kodları

200Medya gönderildi (Evolution hatlarında olağan yanıt).
202Medya kuyruğa alındı
400Gövde veya sorgu parametreleri geçersiz
413Dosya çok büyük (`file_too_large`). Evolution hatlarında tavan 64 MB.
503Hattın sağlayıcısı çözümlenemedi (`provider_unresolved`). İstek tekrar denenebilir.
504Gönderim zaman aşımı

post/messages/send-image

Görsel gönder

`/messages/send-media` ile aynı gövdeyi alır; `media_type` otomatik olarak `image` atanır.

Gerekli yetki: messages:send

Gövde alanları

`to`zorunlu	`string`
`media_url`	`string`
`media_data`	`string`	Base64 içerik.
`mimetype`	`string`
`filename`	`string`
`caption`	`string`

İstek örneği

curl -X POST "https://api.zenwapp.com/api/v1/whatsapp/external/messages/send-image" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"905551234567","media_url":"https://cdn.example.com/gorsel.jpg","caption":"Yeni ürün"}'

Yanıt 400

{
  "error": "validation_error",
  "message": "Missing required field: to"
}

Yanıt kodları

202Görsel kuyruğa alındı
400Gövde veya sorgu parametreleri geçersiz

post/messages/send-document

Doküman gönder

Dosyayı önizlemesiz doküman olarak gönderir (`as_document: true` kısayolu).

Gerekli yetki: messages:send

Gövde alanları

`to`zorunlu	`string`
`media_url`	`string`
`media_data`	`string`	Base64 içerik.
`mimetype`	`string`
`filename`	`string`
`caption`	`string`

İstek örneği

curl -X POST "https://api.zenwapp.com/api/v1/whatsapp/external/messages/send-document" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"905551234567","media_url":"https://cdn.example.com/gorsel.jpg","caption":"Yeni ürün"}'

Yanıt 400

{
  "error": "validation_error",
  "message": "Missing required field: to"
}

Yanıt kodları

202Doküman kuyruğa alındı
400Gövde veya sorgu parametreleri geçersiz

post/messages/send-audio

Ses dosyası gönder

Ses dosyasını müzik/ses eki olarak gönderir.

Gerekli yetki: messages:send

Gövde alanları

`to`zorunlu	`string`
`media_url`	`string`
`media_data`	`string`	Base64 içerik.
`mimetype`	`string`
`filename`	`string`
`caption`	`string`

İstek örneği

curl -X POST "https://api.zenwapp.com/api/v1/whatsapp/external/messages/send-audio" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"905551234567","media_url":"https://cdn.example.com/gorsel.jpg","caption":"Yeni ürün"}'

Yanıt 400

{
  "error": "validation_error",
  "message": "Missing required field: to"
}

Yanıt kodları

202Ses kuyruğa alındı
400Gövde veya sorgu parametreleri geçersiz

post/messages/send-voice

Sesli mesaj (PTT) gönder

Ses dosyasını WhatsApp sesli mesajı olarak gönderir (`as_voice: true` kısayolu). Kaynak dosya OGG/Opus değilse dönüştürülür.

Gerekli yetki: messages:send

Gövde alanları

`to`zorunlu	`string`
`media_url`	`string`
`media_data`	`string`	Base64 içerik.
`mimetype`	`string`
`filename`	`string`
`caption`	`string`

İstek örneği

curl -X POST "https://api.zenwapp.com/api/v1/whatsapp/external/messages/send-voice" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"905551234567","media_url":"https://cdn.example.com/gorsel.jpg","caption":"Yeni ürün"}'

Yanıt 400

{
  "error": "validation_error",
  "message": "Missing required field: to"
}

Yanıt kodları

202Sesli mesaj kuyruğa alındı
400Gövde veya sorgu parametreleri geçersiz

post/messages/send-sticker

Sticker gönder

Görseli sticker olarak gönderir (`as_sticker: true` kısayolu).

Gerekli yetki: messages:send

Gövde alanları

`to`zorunlu	`string`
`media_url`	`string`
`media_data`	`string`	Base64 içerik.
`mimetype`	`string`
`filename`	`string`
`caption`	`string`

İstek örneği

curl -X POST "https://api.zenwapp.com/api/v1/whatsapp/external/messages/send-sticker" \
  -H "Authorization: Bearer $ZENWAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"905551234567","media_url":"https://cdn.example.com/gorsel.jpg","caption":"Yeni ürün"}'

Yanıt 400

{
  "error": "validation_error",
  "message": "Missing required field: to"
}

Yanıt kodları

202Sticker kuyruğa alındı
400Gövde veya sorgu parametreleri geçersiz

get/media/{filename}

Medya dosyasına eriş

Depolanan medya dosyasını döndürür. Varsayılan olarak tarayıcıda görüntülenir; `download=true` ile indirme başlığıyla servis edilir.

Gerekli yetki: messages:read

Yol parametreleri

filenamezorunlu string

Sorgu parametreleri

download boolean `true` ise `Content-Disposition: attachment` ile döner.

İstek örneği

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

Yanıt 404

{
  "error": "not_found",
  "message": "Resource not found"
}

Yanıt kodları

200Dosya içeriği (binary)
400Geçersiz dosya adı
404Kaynak bulunamadı

get/messages/{messageId}/media

Mesajın medyasına eriş

Bir mesaja ekli medyayı döndürür. `format=json` ile dosya yerine meta veri ve indirme bağlantısı alırsınız. > **`evolution` hatlarında bu uç henüz çalışmıyor** ve `404` döner. Bu hatlarda medyaya, mesaj listesindeki `media.presigned_url` bağlantısı üzerinden erişin (`GET /chats/{chatId}/messages`).

Gerekli yetki: messages:read

Yol parametreleri

messageIdzorunlu string

Sorgu parametreleri

`format`	`string`	`json` ise dosya yerine meta veri döner.Değerler: `json`
`download`	`boolean`
`inline`	`boolean`

İstek örneği

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

Yanıt 404

{
  "error": "no_media",
  "message": "Message has no media"
}

Yanıt kodları

200Dosya içeriği veya meta veri
404Mesaj bulunamadı ya da mesajda medya yok