Toplu Şablon Mesaj API Dokümantasyonu

Bu API, WhatsApp kanalı üzerinden birden fazla alıcıya aynı anda şablon mesajı (template message) göndermenizi sağlar. Gönderim işlemi asenkron olarak gerçekleşir; API isteği anında bir bulkMessageId döner ve mesajlar arka planda kuyruğa alınarak işlenir.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/send.js

Temel Özellikler

Tek istek ile 1–5.000 alıcıya toplu şablon mesajı gönderimi
Her alıcı için kişiselleştirilmiş değişkenler (HEADER, BODY, BUTTONS, CAROUSEL)
Tüm alıcılar için ortak defaultPayload + kişiye özel payload birleştirme (isMerge)
Zamanlanmış gönderim (scheduleAt)
Alıcıları username (telefon numarası), userId veya sessionId ile belirtme
Aynı kullanıcıya aynı bulk içinde birden fazla mesaj gönderimi
İsteğe bağlı referenceId ile dış sistem kayıtlarını takip etme
Gönderim sonrası konuşmaları otomatik kullanıcı veya çalışma grubuna atama (action)

uyarı

Bu API yalnızca Meta tarafından onaylanmış şablonları gönderebilir. Şablon adı ve dil kodu, Meta Business Manager'daki şablon kaydı ile tam olarak eşleşmelidir.

İstek Parametreleri

Üst Seviye Parametreler

Parametre	Tip	Zorunlu	Açıklama
`channelUsername`	string	Evet	Mesajın gönderileceği WhatsApp kanal numarası (örn. `"908506669933"`)
`connectorBrand`	string	Evet	Kanal bağlayıcı markası. Şu an desteklenen değer: `"whatsapp"`
`title`	string	Hayır	Kampanya başlığı. Dashboard'da görüntüleme için kullanılır. Varsayılan: `"-"`
`scheduleAt`	string (ISO 8601)	Hayır	Zamanlanmış gönderim tarihi ve saati (örn. `"2026-06-10T10:00:00.000Z"`). Belirtilmezse hemen gönderilir.
`defaultPayload`	object	Koşullu*	Tüm alıcılara uygulanacak varsayılan şablon payload'ı. Kendi `payload`'u olmayan alıcılar için zorunludur.
`recipients`	array	Evet	Alıcı listesi. Minimum 1, maksimum 5.000 alıcı.
`action`	object	Hayır	Gönderim sonrası konuşmaya uygulanacak aksiyon. `assign-to-user` veya `assign-to-workgroup`

*Her alıcının kendi payload'u varsa defaultPayload opsiyoneldir.

Alıcı (Recipient) Yapısı

Her alıcı için username, userId ve sessionId alanlarından yalnızca biri verilmelidir. Birden fazlası aynı anda kullanılamaz; hiçbiri verilmezse istek hata döner.

Aynı kullanıcıya aynı bulk içinde birden fazla mesaj göndermek için alıcı listesine aynı tanımlayıcıyı birden fazla kez ekleyebilirsiniz.

Alan	Tip	Açıklama
`username`	string	Alıcının telefon numarası (örn. `"905554443322"`). Kullanıcı sistemde yoksa otomatik oluşturulur.
`userId`	string	Sistemdeki mevcut kullanıcının ID'si
`sessionId`	string	Sistemdeki mevcut konuşma oturumunun ID'si
`referenceId`	string	İsteğe bağlı referans ID (max 256 karakter). Dış sistemdeki kayıtlarla (CRM, sipariş, ticket vb.) eşleştirme ve takip için kullanılır. Verilirse bulk içinde benzersiz olmalıdır.
`payload`	object	Bu alıcıya özel şablon payload'ı (opsiyonel). `isMerge: true` ise `defaultPayload` ile birleştirilir.
`isMerge`	boolean	Bu alıcı için birleştirme davranışını geçersiz kılar (opsiyonel). Belirtilmezse `defaultPayload.isMerge` değeri kullanılır.

Action Yapısı

Alan	Tip	Açıklama
`action.key`	string	`"assign-to-user"` — konuşmayı belirli bir agent'a atar; `"assign-to-workgroup"` — konuşmayı çalışma grubuna atar
`action.value`	string	Atanacak kullanıcı veya çalışma grubunun ID'si

Template Payload Yapısı

defaultPayload ve alıcıya özel payload aynı yapıyı paylaşır. Template türü için type: "template" belirtilmelidir.

{
  "type": "template",
  "template": {
    "templateName": "order_confirmation",   // zorunlu (defaultPayload'da)
    "languageCode": "tr-TR",                // opsiyonel — örn. "tr", "en", "tr-TR", "en-US"
    "variables": [ ... ]                    // opsiyonel
  },
  "isMerge": true                           // opsiyonel
}

Alan	Tip	Zorunlu	Açıklama
`type`	string	Evet	Payload türü. Template için: `"template"`
`template.templateName`	string	Evet*	Meta'da kayıtlı şablon adı. `isMerge: true` kullanılıyorsa alıcı payload'unda opsiyoneldir (default'tan devralınır).
`template.languageCode`	string	Hayır	Şablon dil kodu (örn. `"tr"`, `"en"`, `"tr-TR"`, `"en-US"`). Şablonun Meta'da kayıtlı dil kodu ile tam olarak eşleşmelidir.
`template.variables`	array	Hayır	Şablon bileşenlerine uygulanacak değişken listesi. Aşağıda detaylı açıklanmaktadır.
`isMerge`	boolean	Hayır	`true`: Alıcı payload'u `defaultPayload` ile derin birleştirme (deep merge) yapılır. `false`/belirtilmezse: Alıcı payload'u `defaultPayload`'un yerine tamamen geçer.

isMerge Davranışı

defaultPayload.isMerge: true + alıcının kendi payload'u varsa → deep merge uygulanır
Deep merge ile alıcı yalnızca variables sağlayabilir, templateName ve languageCode default'tan gelir
Alıcının isMerge alanı, defaultPayload.isMerge değerini geçersiz kılar
Alıcının kendi payload'u yoksa her zaman defaultPayload kullanılır

Variables Yapısı

variables dizisinin her elemanı bir şablon bileşenine karşılık gelir. Bir bileşen türü (type) dizide yalnızca bir kez yer almalıdır.

type	Açıklama	parameters	cards
`"HEADER"`	Şablon başlık bileşeni. Metin değişkeni veya medya URL'si (resim, video, doküman)	Evet	—
`"BODY"`	Şablon gövde metni değişkenleri	Evet	—
`"BUTTONS"`	Dinamik URL suffix içeren buton değişkenleri	Evet	—
`"CAROUSEL"`	Carousel şablonu kart bileşenleri	—	Evet

Parameters Formatları

parameters alanı üç farklı formatta verilebilir:

// Format 1: Dizi (index tabanlı) — {{1}}, {{2}}, {{3}} gibi placeholder'lar için
"parameters": ["değer1", "değer2", "değer3"]

// Format 2: Nesne (sayısal anahtar) — {{1}}, {{2}} için alternatif gösterim
"parameters": { "1": "değer1", "2": "değer2" }

// Format 3: Nesne (isim tabanlı) — {{ad}}, {{tutar}} gibi adlandırılmış placeholder'lar için
"parameters": { "ad": "Ahmet", "tutar": "150 TL" }

Hangi format ne zaman kullanılır?

Meta şablon editöründe {{1}}, {{2}} gibi placeholder oluşturduysa → dizi veya sayısal nesne formatı kullanın
Şablonda {{firstName}}, {{orderTotal}} gibi isimli placeholder'lar varsa → isim tabanlı nesne formatı kullanın
Dizi kullanıldığında sıralama önemlidir: ilk eleman {{1}}'e, ikinci eleman {{2}}'ye karşılık gelir

HEADER Bileşeni

Şablon başlığında medya (resim, video, doküman) veya dinamik metin varsa HEADER bileşeni kullanılır.

// Medya header (resim URL)
{
  "type": "HEADER",
  "parameters": ["https://example.com/product-image.jpg"]
}

// Metin header değişkeni
{
  "type": "HEADER",
  "parameters": ["Özel Kampanya"]
}

BODY Bileşeni

Şablon gövdesindeki dinamik metin değişkenleri için kullanılır.

// Dizi formatı — şablonda {{1}}, {{2}}, {{3}} kullanıldıysa
{
  "type": "BODY",
  "parameters": ["Ahmet", "ORD-12345", "150,00 TL"]
}

// İsim tabanlı — şablonda {{ad}}, {{siparisTutari}} kullanıldıysa
{
  "type": "BODY",
  "parameters": {
    "ad": "Ahmet",
    "siparisTutari": "150,00 TL"
  }
}

BUTTONS Bileşeni

Dinamik URL suffix içeren butonlar için kullanılır. Şablonda birden fazla URL butonu varsa, değişkeni olan butonlar sırasıyla indekslenir (değişkeni olmayan veya FLOW tipi butonlar sayılmaz).

// Tek URL buton suffix değişkeni
{
  "type": "BUTTONS",
  "parameters": ["takip/ORD-12345"]
}

// Birden fazla URL buton suffix değişkeni (sırayla ilk, ikinci URL butonu)
{
  "type": "BUTTONS",
  "parameters": ["takip/ORD-12345", "iptal/ORD-12345"]
}

CAROUSEL Bileşeni

Carousel şablonlarında her kart için ayrı bileşen değişkenleri tanımlanır.

{
  "type": "CAROUSEL",
  "cards": [
    {
      "components": [
        {
          "type": "HEADER",
          "parameters": ["https://example.com/card1.jpg"]
        },
        {
          "type": "BODY",
          "parameters": ["Ürün A", "99,00 TL"]
        }
      ]
    },
    {
      "components": [
        {
          "type": "HEADER",
          "parameters": ["https://example.com/card2.jpg"]
        },
        {
          "type": "BODY",
          "parameters": ["Ürün B", "149,00 TL"]
        }
      ]
    }
  ]
}

uyarı

cards dizisinin uzunluğu şablondaki kart sayısıyla tam olarak eşleşmelidir.

Örnekler

1. Basit Şablon — Değişkensiz, Tüm Alıcılara Aynı

Değişken içermeyen, sabit içerikli bir şablonu birden fazla kişiye göndermek için en sade kullanım şeklidir.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Genel Duyuru",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "hello_world",
      "languageCode": "tr-TR"
    }
  },
  "recipients": [{ "username": "905554443301" }, { "username": "905554443302" }, { "username": "905554443303" }]
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/send.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Genel Duyuru",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "hello_world",
      "languageCode": "tr-TR"
    }
  },
  "recipients": [
    { "username": "905554443301" },
    { "username": "905554443302" },
    { "username": "905554443303" }
  ]
}'

ipucu

username ile belirtilen alıcılar sistemde yoksa otomatik olarak oluşturulur
Tüm alıcılar aynı defaultPayload'u kullanır, alıcıya özel ek veri gerekmez
isMerge belirtilmediğinde her alıcı doğrudan defaultPayload'u kullanır

2. Ortak Body Değişkenli Şablon

Tüm alıcılara aynı değişken değerleriyle bir şablon gönderilir. Şablonda {{1}}, {{2}} gibi placeholder'lar bulunmaktadır.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Yaz Kampanyası",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "promo_notification",
      "languageCode": "tr-TR",
      "variables": [
        {
          "type": "BODY",
          "parameters": ["30", "31 Temmuz 2026"]
        }
      ]
    }
  },
  "recipients": [{ "username": "905554443301" }, { "username": "905554443302" }]
}

ipucu

Bu örnekte şablon body'si şu içeriğe sahip olabilir: "Kampanyamızda {{1}} indirim fırsatı sizi bekliyor! Son tarih: {{2}}"
parameters[0] → {{1}} yerine, parameters[1] → {{2}} yerine geçer

3. Kişiselleştirilmiş Şablon — isMerge ile Per-Recipient Değişkenler

Her alıcı için farklı değişkenler kullanılır. defaultPayload'da isMerge: true ayarlanarak alıcıların yalnızca variables sağlaması yeterli olur; templateName ve languageCode default'tan devralınır.

Bu örnekte şablonun hem medya header'ı hem de kişiselleştirilmiş body değişkenleri bulunmaktadır.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Kişisel Sipariş Bildirimi",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "order_confirmation",
      "languageCode": "tr-TR"
    },
    "isMerge": true
  },
  "recipients": [
    {
      "username": "905554443301",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "HEADER",
              "parameters": ["https://s3.example.com/product-a.jpg"]
            },
            {
              "type": "BODY",
              "parameters": ["Ahmet", "ORD-001", "150,00 TL"]
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "HEADER",
              "parameters": ["https://s3.example.com/product-b.jpg"]
            },
            {
              "type": "BODY",
              "parameters": ["Fatma", "ORD-002", "289,00 TL"]
            }
          ]
        }
      }
    }
  ]
}

ipucu

isMerge: true sayesinde alıcı payload'unda templateName tekrar yazılmak zorunda değildir
Her alıcının variables dizisi birbirinden tamamen bağımsızdır
Header medya URL'si herkese açık (publicly accessible) bir URL olmalıdır
Alıcı payload'unda type belirtilmediğinde defaultPayload.type devralınır

4. URL Buton Değişkeni

Şablonda dinamik URL suffix içeren bir buton varsa BUTTONS bileşeni kullanılır. Örneğin https://example.com/track/ base URL'sine eklenen sipariş takip numarası.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Kargo Takip Bildirimi",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "shipment_tracking",
      "languageCode": "tr-TR"
    },
    "isMerge": true
  },
  "recipients": [
    {
      "username": "905554443301",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": ["Ahmet", "TK-98765"]
            },
            {
              "type": "BUTTONS",
              "parameters": ["TK-98765"]
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": ["Recep", "TK-12345"]
            },
            {
              "type": "BUTTONS",
              "parameters": ["TK-12345"]
            }
          ]
        }
      }
    }
  ]
}

ipucu

BUTTONS parametreleri, değişkeni olan butonların sırasına göre eşleştirilir
FLOW tipi butonlar ve değişkeni olmayan butonlar sayılmaz; sıralama yalnızca dinamik URL butonlarını kapsar
Şablon butonu https://example.com/track/{{1}} ise, parameters[0] → {{1}} yerine geçer

5. Zamanlanmış Gönderim

İleri bir tarih ve saat için gönderim planlanır. scheduleAt ISO 8601 formatında UTC zaman damgasıdır.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Sabah Kampanya Mesajı",
  "scheduleAt": "2026-06-10T07:00:00.000Z",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "morning_campaign",
      "languageCode": "en-US"
    },
    "isMerge": true
  },
  "action": {
    "key": "assign-to-workgroup",
    "value": "WORKGROUP_ID"
  },
  "recipients": [
    {
      "username": "905554443301",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": { "ad": "Ahmet", "indirimOrani": "25" }
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": { "ad": "Zeynep", "indirimOrani": "40" }
            }
          ]
        }
      }
    }
  ]
}

ipucu

scheduleAt UTC zaman diliminde verilmelidir (örn. Türkiye saati 10:00 için 07:00:00.000Z)
Bu örnekte isim tabanlı parametre formatı kullanılmıştır: şablonda {{ad}} ve {{indirimOrani}} gibi placeholder'lar olmalıdır
action ile mesaj gönderilen konuşmalar belirlenen çalışma grubuna otomatik atanır

Yanıt (Response)

Başarılı bir istek, gönderim sürecini takip etmek için kullanılacak bulkMessageId'yi döner:

{
  "bulkMessageId": "abc123xyz789"
}

Hata Yanıtları

Durum	Açıklama
`Channel not found`	`channelUsername` ve `connectorBrand` ile eşleşen doğrulanmış kanal bulunamadı
`Channel is not verified`	Bulunan kanal henüz doğrulanmamış
`invalidRequest`	Alıcı için birden fazla tanımlayıcı verildi veya payload eksik
`channelNotFound`	Verilen `channelId` ile eşleşen aktif kanal bulunamadı
`schema-error`	İstek gövdesindeki bir alan şema doğrulamasından geçemedi (zorunlu alan eksik, yanlış tip veya izin verilmeyen değer)

Dönen bulkMessageId, gönderim istatistiklerini sorgulamak ve gönderimi durdurmak için aşağıdaki endpointlerde kullanılabilir.

Stats — Gönderim İstatistikleri

Bir bulk mesajın anlık gönderim durumunu sorgular. Bekleyen, başarılı, başarısız ve iptal edilen kayıt sayılarını döner.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/stats.js

İstek Parametreleri

Parametre	Tip	Zorunlu	Açıklama
`bulkMessageId`	string	Evet	Takip edilecek bulk mesajın ID'si (`createBulkPerRecipient`'ten dönen değer)

{
  "bulkMessageId": "abc123xyz789"
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/stats.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "bulkMessageId": "abc123xyz789"
}'

Response

{
  "bulkMessage": {
    "_id": "abc123xyz789",
    "slug": "my-workspace",
    "title": "Kampanya Başlığı",
    "channelUsername": "908506669933",
    "connectorBrand": "whatsapp",
    "connectorSlug": "whatsapp-cloud",
    "payload": {
      "recipientCount": 100,
      "defaultPayloadType": "template",
      "jobId": "job_abc123"
    },
    "schedule": {
      "date": "2026-06-10T07:00:00.000Z",
      "type": "later"
    },
    "createdAt": "2026-06-08T10:00:00.000Z",
    "updatedAt": "2026-06-08T10:30:00.000Z"
  },
  "stats": {
    "pending": 45,
    "success": 42,
    "failed": 3,
    "cancelled": 10,
    "total": 100
  }
}

Stats Alanları

Alan	Tip	Açıklama
`stats.pending`	number	Henüz işlenmemiş, kuyruktaki kayıt sayısı
`stats.success`	number	Gönderim işlemi başarıyla tamamlanmış kayıt sayısı
`stats.failed`	number	Gönderim hatası alan kayıt sayısı
`stats.cancelled`	number	İptal edilmiş kayıt sayısı
`stats.total`	number	Toplam kayıt sayısı (`pending + success + failed + cancelled`)

not

stats.success, mesajın sisteme başarıyla iletildiğini gösterir; Meta'nın mesajı alıcıya ulaştırdığını garanti etmez. Meta'nın sonraki aşamalarda ürettiği durum bildirimleri (delivered, read, failed vb.) bu sayacı etkilemez ve burada yansıtılmaz.

Stats vs Message Stats

stats endpoint'i: Gönderim job'unun durumunu gösterir (pending, success, failed, cancelled)
message-stats endpoint'i: Mesajların gerçek durumunu gösterir (pending, sending, sent, delivered, read, error vb.)
Job başarılı (success) olsa bile mesaj henüz delivered/read olmamış olabilir

Reference ID

referenceId opsiyonel bir alandır. Gönderim kaydını kendi sisteminizdeki bir ID ile eşleştirmek ve sonradan takip etmek için kullanabilirsiniz (örn. sipariş numarası, ticket ID).

Verilirse bulk içinde benzersiz olmalıdır (max 256 karakter).

Önemli

Kullanım zorunlu değildir
Bulk içinde aynı referenceId tekrar edemez
Farklı bulk mesajlarda aynı değer tekrar kullanılabilir

Message Stats — WhatsApp Mesaj Durumları

Bir bulk mesajın mesaj durumlarını sorgular. stats endpoint'inden farkı: Job durumu yerine her mesajın message.status değerine göre sayımları gösterir.

Olası mesaj durumları: pending, sending, sent, delivered, read, deleted, warning, error, unknown, not-sended

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/message-stats.js

İstek Parametreleri

Parametre	Tip	Zorunlu	Açıklama
`bulkMessageId`	string	Evet	Sorgulanacak bulk mesajın ID'si

{
  "bulkMessageId": "abc123xyz789"
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/message-stats.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "bulkMessageId": "abc123xyz789"
}'

Response

{
  "bulkMessage": {
    "_id": "abc123xyz789",
    "slug": "my-workspace",
    "type": "perRecipient",
    "title": "Kampanya Başlığı"
  },
  "messageStats": {
    "pending": 5,
    "sending": 2,
    "sent": 10,
    "delivered": 45,
    "read": 30,
    "deleted": 2,
    "warning": 1,
    "error": 3,
    "unknown": 0,
    "not-sended": 2,
    "no-message": 10,
    "total": 120
  }
}

messageStats Alanları

Alan	Tip	Açıklama
`pending`	number	Henüz gönderilmemiş mesajlar
`sending`	number	Gönderim işlemi devam eden mesajlar
`sent`	number	WhatsApp'a iletilmiş, henüz teslim edilmemiş mesajlar
`delivered`	number	Alıcının telefonuna ulaşmış mesajlar
`read`	number	Alıcı tarafından okunmuş mesajlar
`deleted`	number	Silinmiş mesajlar
`warning`	number	Uyarı durumundaki mesajlar
`error`	number	Hata alan mesajlar
`unknown`	number	Bilinmeyen durumdaki mesajlar
`not-sended`	number	Gönderilememiş mesajlar
`no-message`	number	Henüz mesaj oluşturulmamış kayıtlar (kuyrukta bekliyor)
`total`	number	Toplam kayıt sayısı

Kullanım İpuçları

no-message sayısı yüksekse gönderim hala devam ediyor demektir
delivered sayısı mesajın başarıyla ulaştığını gösterir
read sayısı kampanya etkileşimini ölçmek için kullanılabilir
Gerçek zamanlı takip için bu endpoint'i periyodik olarak çağırabilirsiniz

Options Yapısı — Sayfalama, Filtreleme ve Sıralama

list ve list-with-messages endpoint'lerinde kullanılan options parametresi, sayfalama, filtreleme ve sıralama için standart bir yapı sunar.

Options Alanları

Alan	Tip	Zorunlu	Açıklama
`pagination`	object	Hayır	Sayfalama ayarları
`filtering`	object	Hayır	Filtreleme kriterleri
`sorting`	object	Hayır	Sıralama ayarları (örn: `{"createdAt": -1}`)

Pagination Yapısı

Alan	Tip	Varsayılan	Açıklama
`currentPage`	number	1	Getirilecek sayfa numarası
`pageItems`	number	50	Sayfa başı kayıt sayısı (maksimum: 50)

Filtering Yapısı

Filtreleme MongoDB query formatında yapılır. Kayıt alanlarına göre filtreleme yapabilirsiniz. list-with-messages endpoint'inde mesaj alanlarına da (örn: message.status) filtreleme uygulanabilir.

// Kayıt durumuna göre filtreleme
{
  "options": {
    "filtering": {
      "status": "success"
    }
  }
}

// referenceId'ye göre filtreleme
{
  "options": {
    "filtering": {
      "referenceId": "ORDER-12345"
    }
  }
}

// Mesaj durumuna göre filtreleme (sadece list-with-messages)
{
  "options": {
    "filtering": {
      "message.status": "delivered"
    }
  }
}

// Birden fazla duruma göre filtreleme - $in operatörü (MongoDB)
{
  "options": {
    "filtering": {
      "message.status": {
        "$in": ["delivered", "read"]
      }
    }
  }
}

// Belirli durumları hariç tutma - $nin operatörü (MongoDB)
{
  "options": {
    "filtering": {
      "message.status": {
        "$nin": ["error", "not-sended"]
      }
    }
  }
}

Sorting Yapısı

Sıralama MongoDB sort formatında yapılır. 1 artan, -1 azalan sıralama anlamına gelir.

// Oluşturulma tarihine göre azalan (en yeni önce)
{
  "options": {
    "sorting": {
      "createdAt": -1
    }
  }
}

// Birden fazla alana göre sıralama
{
  "options": {
    "sorting": {
      "status": 1,
      "createdAt": -1
    }
  }
}

Kombine Kullanım Örneği

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 2,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "delivered"
    },
    "sorting": {
      "createdAt": -1
    }
  }
}

Bu örnek: Delivered durumundaki mesajları en yeniden eskiye sıralar.

Pratik İpuçları

filtering ve pagination birlikte kullanılarak hedefli sorgular yapılabilir
Response'da options.pagination.totalCount ve options.pagination.totalPages bilgileri döner, sayfalama için kullanabilirsiniz
message.status filtresi sadece list-with-messages endpoint'inde çalışır

Records — Kayıt Detayları ve Listeleme

Bir bulk mesaja ait tüm gönderim kayıtlarını listeler. Her kayıt bir alıcıya gönderilen tek bir mesajı temsil eder.

List — Kayıt Listesi

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message-records/list.js

İstek Parametreleri

Parametre	Tip	Zorunlu	Açıklama
`bulkMessageId`	string	Evet	Listelenecek bulk mesajın ID'si
`options`	object	Hayır	Sayfalama, filtreleme, sıralama seçenekleri. Detaylı bilgi için Options Yapısı bölümüne bakın.

Request — Temel Kullanım

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    }
  }
}

Request — Belirli Duruma Göre Filtreleme

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "status": "success"
    }
  }
}

Sadece başarılı gönderim kayıtlarını listeler (record.status = "success").

Response

{
  "bulkMessageRecords": [
    {
      "_id": "record_1",
      "bulkMessageId": "abc123xyz789",
      "slug": "my-workspace",
      "userId": "user_123",
      "sessionId": "session_456",
      "messageId": "msg_789",
      "referenceId": "ORDER-12345",
      "status": "success",
      "createdAt": "2026-06-10T10:00:00.000Z"
    }
  ],
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50,
      "totalCount": 150,
      "totalPages": 3
    },
    "sorting": {},
    "filtering": {}
  }
}

List With Messages — Mesaj Detaylı Liste

list endpoint'i ile aynı özelliklere sahiptir (pagination, filtering, sorting). Tek farkı: Her kayıtta messageId varsa, ilgili message objesi de döner. Bu sayede mesaj durumunu (delivered, read, error vb.) ve payload'u tek sorguda görebilirsiniz.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message-records/list-with-messages.js

Request — Temel Kullanım

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    }
  }
}

Request — Mesaj Durumuna Göre Filtreleme

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "delivered"
    }
  }
}

Bu örnek yalnızca "delivered" durumundaki mesajları getirir.

Request — Başarısız Mesajları Listeleme

{
  "bulkMessageId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "error"
    }
  }
}

Gönderim hatası alan mesajları incelemek için kullanılır.

Response

{
  "bulkMessageRecords": [
    {
      "_id": "record_1",
      "bulkMessageId": "abc123xyz789",
      "userId": "user_123",
      "messageId": "msg_789",
      "referenceId": "ORDER-12345",
      "status": "success",
      "message": {
        "_id": "msg_789",
        "status": "delivered",
        "payload": {
          "type": "template",
          "template": {
            "templateName": "order_notification"
          }
        },
        "createdAt": "2026-06-10T10:01:00.000Z",
        "deliveredAt": "2026-06-10T10:01:05.000Z"
      }
    }
  ],
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50,
      "totalCount": 150,
      "totalPages": 3
    },
    "sorting": {},
    "filtering": {}
  }
}

Kayıt (Record) Alanları

Alan	Tip	Açıklama
`_id`	string	Kayıt ID'si
`bulkMessageId`	string	Ait olduğu bulk mesaj ID'si
`userId`	string	Alıcı kullanıcının ID'si
`sessionId`	string	Konuşma oturumu ID'si
`messageId`	string	Gönderilen mesajın ID'si (henüz gönderilmediyse null)
`referenceId`	string	İsteğe bağlı referans ID (varsa)
`status`	string	Kayıt durumu: `pending`, `success`, `failed`, `cancelled`
`message`	object	Mesaj detayları (yalnızca list-with-messages'da)

List vs List-With-Messages Karşılaştırması

Özellik	list	list-with-messages
Pagination	Var	Var
Filtering	Var (record alanlarına göre)	Var (record + message alanlarına göre)
Message Objesi	Yok	Var (messageId varsa)
Performans	Hızlı	Orta (JOIN yapar)
message.status Filtresi	Kullanılamaz	Kullanılabilir

Kullanım Senaryoları

list: Tüm kayıtları hızlıca listelemek, referenceId'ye göre filtreleme, record durumlarını kontrol
list-with-messages: WhatsApp mesaj durumlarını görmek (delivered, read), mesaj payload'larını incelemek
Filtering örnekleri:
- {"status": "failed"} — Başarısız gönderim kayıtları
- {"referenceId": "ORDER-123"} — Belirli referans ID
- {"message.status": "delivered"} — Teslim edilmiş mesajlar (sadece list-with-messages)
- {"message.status": "read"} — Okunmuş mesajlar (sadece list-with-messages)
- {"message.status": "error"} — Hata alan mesajlar (sadece list-with-messages)
- {"message.status": {"$in": ["delivered", "read"]}} — Teslim edilmiş veya okunmuş mesajlar (sadece list-with-messages)
- {"message.status": {"$nin": ["error", "not-sended"]}} — Hata ve gönderilememiş durumları hariç tutan mesajlar (sadece list-with-messages)
- {"status": {"$in": ["success", "pending"]}} — Başarılı veya beklemede olan kayıtlar

Performans ve Kullanım Notları

list endpoint'i daha hızlıdır, genel durum kontrolü için tercih edin
list-with-messages mesaj detayları gerektiğinde kullanın
Sayfa başı kayıt sayısı (pageItems) maksimum 50 olabilir, belirtilmezse otomatik 50 kullanılır
message.status filtresi sadece list-with-messages'da çalışır
messageId null olan kayıtlar için message objesi de null olur

Stop — Gönderimi Durdur

Devam eden bir bulk mesaj gönderimini durdurur. Kuyruktaki job iptal edilir ve tüm pending kayıtlar cancelled statüsüne çekilir. Halihazırda gönderilmiş (success) veya hata almış (failed) kayıtlar etkilenmez.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/stop.js

uyarı

Bu işlem geri alınamaz. Durdurulan gönderimi yeniden başlatmak mümkün değildir.

İstek Parametreleri

Parametre	Tip	Zorunlu	Açıklama
`bulkMessageId`	string	Evet	Durdurulacak bulk mesajın ID'si

{
  "bulkMessageId": "abc123xyz789"
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/stop.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "bulkMessageId": "abc123xyz789"
}'

Response

Başarılı durumda yanıt gövdesi boştur. HTTP 200 durumu işlemin başarıyla tamamlandığını gösterir.

{}

ipucu

Yalnızca bu API üzerinden oluşturulan bulk mesajlar durdurulabilir
Gönderimi durdurduktan sonra stats endpointi ile iptal edilen kayıt sayısını doğrulayabilirsiniz
Bulk mesaj bulunamazsa hata döner: bulkMessageNotFound

Temel Özellikler​

İstek Parametreleri​

Üst Seviye Parametreler​

Alıcı (Recipient) Yapısı​

Action Yapısı​

Template Payload Yapısı​

Variables Yapısı​

Parameters Formatları​

HEADER Bileşeni​

BODY Bileşeni​

BUTTONS Bileşeni​

CAROUSEL Bileşeni​

Örnekler​

1. Basit Şablon — Değişkensiz, Tüm Alıcılara Aynı​

2. Ortak Body Değişkenli Şablon​

3. Kişiselleştirilmiş Şablon — isMerge ile Per-Recipient Değişkenler​

4. URL Buton Değişkeni​

5. Zamanlanmış Gönderim​

Yanıt (Response)​

Hata Yanıtları​

Stats — Gönderim İstatistikleri​

İstek Parametreleri​

Response​

Stats Alanları​

Reference ID​

Message Stats — WhatsApp Mesaj Durumları​

İstek Parametreleri​

Response​

messageStats Alanları​

Options Yapısı — Sayfalama, Filtreleme ve Sıralama​

Options Alanları​

Pagination Yapısı​

Filtering Yapısı​

Sorting Yapısı​

Kombine Kullanım Örneği​

Records — Kayıt Detayları ve Listeleme​

List — Kayıt Listesi​

İstek Parametreleri​

Request — Temel Kullanım​

Request — Belirli Duruma Göre Filtreleme​

Response​

List With Messages — Mesaj Detaylı Liste​

Request — Temel Kullanım​

Request — Mesaj Durumuna Göre Filtreleme​

Request — Başarısız Mesajları Listeleme​

Response​

Kayıt (Record) Alanları​

List vs List-With-Messages Karşılaştırması​

Stop — Gönderimi Durdur​

İstek Parametreleri​

Response​

Temel Özellikler

İstek Parametreleri

Üst Seviye Parametreler

Alıcı (Recipient) Yapısı

Action Yapısı

Template Payload Yapısı

Variables Yapısı

Parameters Formatları

HEADER Bileşeni

BODY Bileşeni

BUTTONS Bileşeni

CAROUSEL Bileşeni

Örnekler

1. Basit Şablon — Değişkensiz, Tüm Alıcılara Aynı

2. Ortak Body Değişkenli Şablon

3. Kişiselleştirilmiş Şablon — isMerge ile Per-Recipient Değişkenler

4. URL Buton Değişkeni

5. Zamanlanmış Gönderim

Yanıt (Response)

Hata Yanıtları

Stats — Gönderim İstatistikleri

İstek Parametreleri

Response

Stats Alanları

Reference ID

Message Stats — WhatsApp Mesaj Durumları

İstek Parametreleri

Response

messageStats Alanları

Options Yapısı — Sayfalama, Filtreleme ve Sıralama

Options Alanları

Pagination Yapısı

Filtering Yapısı

Sorting Yapısı

Kombine Kullanım Örneği

Records — Kayıt Detayları ve Listeleme

List — Kayıt Listesi

İstek Parametreleri

Request — Temel Kullanım

Request — Belirli Duruma Göre Filtreleme

Response

List With Messages — Mesaj Detaylı Liste

Request — Temel Kullanım

Request — Mesaj Durumuna Göre Filtreleme

Request — Başarısız Mesajları Listeleme

Response

Kayıt (Record) Alanları

List vs List-With-Messages Karşılaştırması

Stop — Gönderimi Durdur

İstek Parametreleri

Response