Mesajlar | WA2Notify Docs

Mesaj yüzeyi tekli gönderim, zamanlama, OTP ve durum takibi için kullanılır. Medya eklemek istiyorsanız önce Dosya ve Medya sayfasındaki upload akışıyla asset_id üretmeniz gerekir.

Mesaj operasyonları

Anlık gönderim

Aynı çağrıda çoklu alıcı, şablon değişkeni ve asset_id kombinasyonu kullanılabilir.

Zamanlama

Tekli mesaj veya çok alıcılı scheduled grup oluşturabilir, bekleyen kayıtları iptal edebilirsiniz.

Durum takibi

Mesaj listesi ve detay uçları sent, delivered, read ve failed statülerini aynı sözleşmede döndürür.

POST/v1/messages/send

X-API-Key200 OK

Mesaj gönder

Tekli veya çoklu alıcıya anlık mesaj gönderir. Aynı istek içinde `template_id`, `variables` ve `asset_id` birlikte kullanılabilir.

Zorunlu alanlardevice_id ve en az bir alıcı içeren to dizisi gereklidir.

İsteğe bağlı alanlartext, template_id, variables ve asset_id birlikte ya da ayrı kullanılabilir.

Numaralar normalize edilir. Kota her alıcıyı ayrı mesaj olarak sayar. `to` dizisindeki ülke kodları otomatik temizlenir.

İstek

curl --request POST \
--url {{BASE_URL}}/v1/messages/send \
--header "X-API-Key: {{API_KEY}}" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: 6f4c7081-387d-4784-a1a6-d9fda3d73a3a" \
--data '{
  "device_id": "{{DEVICE_ID}}",
  "to": ["+905551112233", "+4915112345678"],
  "text": "Merhaba {{ad}}",
  "asset_id": "{{ASSET_ID}}",
  "variables": {
    "ad": "Ayşe"
  }
}'

Yanıt

JSON

{
"data": {
  "messages": [
    {
      "id": "7ac71306-3a37-4c45-a178-81dfbbca8728",
      "to": "+905551112233",
      "status": "sent"
    },
    {
      "id": "5dc43d70-1631-4e84-8f60-9f72ac16e2f1",
      "to": "+4915112345678",
      "status": "sent"
    }
  ],
  "total_count": 2,
  "success_count": 2,
  "failed_count": 0
}
}

Güvenli tekrar deneme (Idempotency-Key)

Ağ zaman aşımı sonrası isteği yeniden gönderdiğinizde çift mesaj oluşmaması için gönderim çağrısına isteğe bağlı bir Idempotency-Key başlığı ekleyin:

Idempotency-Key: 6f4c7081-387d-4784-a1a6-d9fda3d73a3a

Aynı anahtarla 24 saat içinde yapılan sonraki istekler yeni bir gönderim tetiklemez; ilk başarılı yanıt olduğu gibi geri döner.
Tekrar oynatılan yanıtlarda Idempotent-Replayed: true yanıt başlığı bulunur.
Her mantıksal gönderim için benzersiz bir anahtar (ör. bir UUID) üretin; farklı içerik için aynı anahtarı yeniden kullanmayın.
Anahtar hesap bazında saklanır, bu yüzden farklı hesapların anahtarları birbirini etkilemez.

Ne zaman kullanmalı

İstek başladı ama yanıt gelmeden bağlantı koptuysa güvenle aynı anahtarla tekrar deneyin. Anahtar olmadan yapılan retry’lar çift mesaj gönderebilir.

GET/v1/messages

X-API-Key200 OK

Mesajları listele

Status, arama, cihaz ve sayfalama filtreleri ile mesaj geçmişini listeler.

search numara, kişi adı ve mesaj metni üstünde çalışır.
device parametresi dashboard’dan aldığınız device_id ile filtreleme yapar.

`limit` en fazla 100 olabilir. `status=all` verildiğinde durum filtresi uygulanmaz.

İstek

curl --request GET \
--url "{{BASE_URL}}/v1/messages?status=sent&page=1&limit=20&search=ayse" \
--header "X-API-Key: {{API_KEY}}"

Yanıt

JSON

{
"data": {
  "messages": [
    {
      "id": "7ac71306-3a37-4c45-a178-81dfbbca8728",
      "message_id": "MSG-20260401-0001",
      "to": "+905551112233",
      "content": "Merhaba Ayşe",
      "asset_id": "b84b4f8d-2fd8-4c6d-b90a-fc5dd7f4aef2",
      "status": "read",
      "device_id": "3baedacf-53bf-4061-a0f5-5235cab38875",
      "device_name": "Satış Hattı",
      "contact_name": "Ayşe",
      "sent_at": "2026-04-01T09:18:35Z",
      "created_at": "2026-04-01T09:18:30Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}
}

GET/v1/messages/:message_id/details

X-API-Key200 OK

Mesaj detayını al

Tek bir mesajın delivery alanlarını, cihaz kaynağını ve hata bilgisini detaylı döndürür.

Detay görünümü mesajın kampanya ilişkisi varsa campaign_id ve campaign_name bilgisini de döner.

Okundu ve teslim alanları WhatsApp receipt event’lerinden güncellenir.

İstek

curl --request GET \
--url {{BASE_URL}}/v1/messages/{{MESSAGE_ID}}/details \
--header "X-API-Key: {{API_KEY}}"

Yanıt

JSON

{
"data": {
  "id": "7ac71306-3a37-4c45-a178-81dfbbca8728",
  "message_id": "MSG-20260401-0001",
  "whatsapp_id": "wamid.HBgL...",
  "to": "+905551112233",
  "content": "Merhaba Ayşe",
  "asset_id": "b84b4f8d-2fd8-4c6d-b90a-fc5dd7f4aef2",
  "status": "read",
  "device_id": "3baedacf-53bf-4061-a0f5-5235cab38875",
  "device_name": "Satış Hattı",
  "campaign_id": null,
  "campaign_name": "",
  "contact_name": "Ayşe",
  "created_at": "2026-04-01T09:18:30Z",
  "sent_at": "2026-04-01T09:18:35Z",
  "delivered_at": "2026-04-01T09:18:42Z",
  "read_at": "2026-04-01T09:19:11Z",
  "message_type": "text",
  "retry_count": 0,
  "error_message": "",
  "metadata": {}
}
}

POST/v1/messages/schedule

X-API-Key200 OK

Planlı mesaj oluştur

Gelecekteki bir tarih için tekli veya çok alıcılı planlı mesaj kaydı oluşturur.

group_name aynı grup altında planlanan kayıtları birlikte yönetmenizi sağlar.
İsterseniz template_id ve asset_id bu akışta da kullanılabilir.

Planlı mesajlar da normal mesaj kotasına tabidir. Bekleyen kayıtlar `/v1/messages/scheduled` üzerinden listelenebilir.

İstek

curl --request POST \
--url {{BASE_URL}}/v1/messages/schedule \
--header "X-API-Key: {{API_KEY}}" \
--header "Content-Type: application/json" \
--data '{
  "device_id": "{{DEVICE_ID}}",
  "to": ["+905551112233"],
  "text": "Randevunuz yarın saat 14:00",
  "scheduled_at": "2026-04-12T09:00:00Z",
  "group_name": "Randevu Hatırlatma"
}'

Yanıt

JSON

{
"data": {
  "id": "00f38f5f-f907-4f65-92ed-ef1e5db11e3d",
  "group_id": "cb9d52d9-1781-462e-a9a5-a6de96d17e18",
  "group_name": "Randevu Hatırlatma",
  "to": "+905551112233",
  "status": "pending",
  "scheduled_at": "2026-04-12T09:00:00Z",
  "created_at": "2026-04-01T10:00:00Z"
}
}

POST/v1/messages/otp

X-API-Key200 OK

OTP mesajı gönder

Doğrulama kodu gibi kısa ömürlü transaction mesajları için optimize edilmiş OTP akışını kullanır.

ttl dakika cinsindendir ve mesaj metninde son kullanma süresini belirtmek için kullanılabilir.

OTP çağrısı kısa metinli, hızlı teslim edilmesi beklenen tekli doğrulama mesajları için tasarlanmıştır.

İstek

curl --request POST \
--url {{BASE_URL}}/v1/messages/otp \
--header "X-API-Key: {{API_KEY}}" \
--header "Content-Type: application/json" \
--data '{
  "device_id": "{{DEVICE_ID}}",
  "phone": "+905551112233",
  "code": "918221",
  "ttl": 5
}'

Yanıt

JSON

{
"data": {
  "id": "6f4c7081-387d-4784-a1a6-d9fda3d73a3a",
  "to": "+905551112233",
  "status": "sent"
}
}

Diğer kullanılabilir uçlar

Metot	Yol	Amaç
`GET`	`/v1/messages/:message_id`	Tek mesajın özet görünümünü döner
`POST`	`/v1/messages/:message_id/resend`	Aynı payload ile mesajı yeniden gönderir
`GET`	`/v1/messages/scheduled`	Bekleyen planlı kayıtları listeler
`POST`	`/v1/messages/:message_id/cancel`	Bekleyen tekli kayıtları iptal eder
`GET`	`/v1/messages/scheduled/group/:group_id`	Planlı grup detayını döner
`DELETE`	`/v1/messages/scheduled/group/:group_id`	Grup içindeki pending kayıtları iptal eder
`POST`	`/v1/messages/scheduled/group/cancel-selective`	Grup içindeki seçili numaraları iptal eder

Doküman dışında bırakılan mesaj uçları

/v1/messages/stats/summary public müşteri dokümanının parçası değildir. Genel istatistik ve dashboard özeti ürün içinde dashboard tarafında kalır.