Toplu Şablon Mesaj API Dokümantasyonu — v2

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 bulkOperationId 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/v2/bulk-operation/send.js

Yanıt formatı

Bu dokümandaki her endpoint bir custom function'dır. HTTP yanıt gövdesinde fonksiyonun kendi alanları (_id, title, pathString…) bulunur, endpoint'in asıl yanıtı result altında gelir. Bu dokümandaki yanıt örnekleri result'ın içeriğini gösterir:

{
  "_id": "function_id",
  "title": "Show",
  "pathString": "/bulk-message-api-app/api/v2/bulk-operation/show.js",
  "result": {
    "bulkOperation": { "_id": "abc123xyz789", "status": "running" }
  }
}

v1'den Geçiş

v2, v1 ile yan yana çalışır; geçişi kendi takviminizle yapabilirsiniz. v1 uçları (/api/bulk-message/…, /api/bulk-message-records/…) kullanımdan kalkacaktır, yeni entegrasyonlar v2'yi kullanmalıdır.

Endpoint yollarını v2'ye taşıyın: …/api/bulk-message/… → …/api/v2/bulk-operation/…, …/api/bulk-message-records/… → …/api/v2/bulk-operation-items/…. send isteğinin gövdesi değişmez; tek istekte 5.000 yerine 100.000 alıcıya kadar gönderebilirsiniz.
İsteklerde bulkMessageId yerine bulkOperationId gönderin.
stats.js yerine show.js kullanın.
Yanıtları aşağıdaki tablodaki yeni alan adlarıyla okuyun.

v2 uçları yalnızca v2 send ile oluşturulan bulk operation'ları tanır. Geçişten önce v1 ile oluşturduğunuz bir bulk mesajı takip etmek için v1 uçlarını kullanmaya devam edin.

Endpointler

v1	v2	Yanıtta değişen
`bulk-message/send.js`	`v2/bulk-operation/send.js`	`{ bulkMessageId }` yerine `{ bulkOperationId }`
`bulk-message/stats.js`	`v2/bulk-operation/show.js`	`{ bulkMessage, stats }` yerine `{ bulkOperation }`
`bulk-message/message-stats.js`	`v2/bulk-operation/message-stats.js`	Sayaçlar `messageStats` altında değil, yanıtın kökünde
`bulk-message/stop.js`	`v2/bulk-operation/stop.js`	Değişmedi
`bulk-message-records/list.js`	`v2/bulk-operation-items/list.js`	`bulkMessageRecords` yerine `bulkOperationItems`
`bulk-message-records/list-with-messages.js`	`v2/bulk-operation-items/list-with-messages.js`	`list` ile aynı; ek olarak her item'da `session`

Alan adları

v1	v2
`stats.success`	`bulkOperation.progress.succeeded`
`stats.pending`, `stats.failed`, `stats.cancelled`, `stats.total`	`bulkOperation.progress.pending`, `.failed`, `.cancelled`, `.total`
—	`bulkOperation.progress.unknown`, `bulkOperation.status`, `bulkOperation.result.outcome`
`bulkMessage` (bulk mesaj)	`bulkOperation` (bulk operation)
`bulkMessageRecord` (kayıt)	`bulkOperationItem` (item)
istekte, `send` yanıtında ve kayıtta `bulkMessageId`	`bulkOperationId`
kayıtta gönderilen `username` / `userId` / `sessionId`	`payload.username` / `payload.userId` / `payload.sessionId`
kayıtta `referenceId`	`payload.referenceId`
kayıtta `payload` (alıcıya özel şablon payload'ı)	`payload.payload`
gönderim sonrası `userId`, `sessionId`, `messageId`	`result.userId`, `result.sessionId`, `result.messageId`
kayıt durumu `success`	`succeeded`
başarısız kayıtta `errorMessage`	`error.message`; yanında `error.code` ve `error.retryable`
—	`position` (alıcının `recipients` içindeki sırası)
filtre `{"status": "success"}`	`{"status": "succeeded"}`
filtre `{"referenceId": "…"}`	`{"payload.referenceId": "…"}`
`send` hataları `schema-error`, `invalidRequest`	`zod-schema-error`, mesajda hatalı alanın yolu ile

Temel Özellikler

Tek istek ile 1–100.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 100.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ı) — {{name}}, {{amount}} gibi adlandırılmış placeholder'lar için
"parameters": { "name": "Ahmet", "amount": "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 {{name}}, {{orderAmount}} kullanıldıysa
{
  "type": "BODY",
  "parameters": {
    "name": "Ahmet",
    "orderAmount": "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/v2/bulk-operation/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": { "name": "Ahmet", "discountRate": "25" }
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "BODY",
              "parameters": { "name": "Zeynep", "discountRate": "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 {{name}} ve {{discountRate}} 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 bulkOperationId'yi döner:

{
  "bulkOperationId": "abc123xyz789"
}

Hata Yanıtları

Durum	Açıklama
`recipients field is required`	`recipients` alanı gönderilmedi
`Channel not found`	`channelUsername` ve `connectorBrand` ile eşleşen doğrulanmış kanal bulunamadı
`Channel is not verified`	Bulunan kanal henüz doğrulanmamış
`zod-schema-error`	İstek gövdesindeki bir alan şema doğrulamasından geçemedi (zorunlu alan eksik, yanlış tip, izin verilmeyen değer, bir alıcıda birden fazla tanımlayıcı veya eksik `payload`). Mesaj alanın yolunu içerir, örn. `recipients.0.referenceId: referenceId must be unique`

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

Show — Bulk Operation Durumu ve İstatistikleri

Bulk operation'ı anlık durumu ve item'larının gönderim sayaçlarıyla birlikte bulkOperation anahtarı altında döner.

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

İstek Parametreleri

Parametre	Tip	Zorunlu	Açıklama
`bulkOperationId`	string	Evet	Takip edilecek bulk operation'ın ID'si (`send`'den dönen değer)

{
  "bulkOperationId": "abc123xyz789"
}

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

Response

{
  "bulkOperation": {
    "_id": "abc123xyz789",
    "type": "send-bulk-message",
    "slug": "my-workspace",
    "userId": "agent_user_id",
    "payload": {
      "title": "Kampanya Başlığı",
      "channelUsername": "908506669933",
      "connectorBrand": "whatsapp",
      "connectorSlug": "om2WabVegaCloud",
      "defaultLanguageCode": "tr-TR",
      "sentUser": { "firstname": "Ahmet", "lastname": "Yılmaz" },
      "defaultPayload": {
        "type": "template",
        "template": { "templateName": "order_confirmation", "languageCode": "tr-TR" },
        "isMerge": true
      },
      "source": { "type": "recipients", "bulkOperationInputGroupId": "group_id" }
    },
    "status": "running",
    "result": { "outcome": "unknown", "hasErrors": false },
    "progress": {
      "total": 100,
      "pending": 45,
      "succeeded": 42,
      "failed": 3,
      "cancelled": 10,
      "unknown": 0
    },
    "scheduleAt": "2026-06-10T07:00:00.000Z",
    "createdAt": "2026-06-08T10:00:00.000Z",
    "updatedAt": "2026-06-10T07:00:30.000Z",
    "startedAt": "2026-06-10T07:00:05.000Z"
  }
}

Show Alanları

Alanlar bulkOperation altındadır.

Alan	Tip	Açıklama
`status`	string	Bulk operation durumu: `preparing`, `scheduled`, `pending`, `running`, `stopping`, `stopped`, `completed`, `failed`
`progress.total`	number	Toplam item sayısı
`progress.pending`	number	Henüz işlenmemiş, kuyruktaki item sayısı
`progress.succeeded`	number	Gönderim işlemi başarıyla tamamlanmış item sayısı
`progress.failed`	number	Gönderim hatası alan item sayısı
`progress.cancelled`	number	`stop` ile iptal edilmiş item sayısı
`progress.unknown`	number	Sonucu belirlenemeyen item sayısı
`result.outcome`	string	Bulk operation bittiğinde genel sonuç: `success`, `partial`, `all-failed`, `cancelled`, `unknown`
`result.hasErrors`	boolean	En az bir item başarısız olduysa `true`
`scheduleAt`	string	Planlanan gönderim zamanı (yalnızca planlı bulk operation'larda)
`startedAt`, `completedAt`	string	Gönderimin başladığı ve bittiği zaman

not

progress.succeeded, 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.

Show vs Message Stats

show endpoint'i: Item'ların gönderim durumunu gösterir (pending, succeeded, failed, cancelled, unknown)
message-stats endpoint'i: Mesajların gerçek durumunu gösterir (pending, sending, sent, delivered, read, error vb.)
Item succeeded olsa bile mesaj henüz delivered/read olmamış olabilir

Reference ID

referenceId opsiyonel bir alandır. Gönderim item'ını kendi sisteminizdeki bir ID ile eşleştirmek ve sonradan takip etmek için kullanabilirsiniz (örn. sipariş numarası, ticket ID). Her item'da payload.referenceId olarak döner.

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 operation'larda aynı değer tekrar kullanılabilir

Message Stats — WhatsApp Mesaj Durumları

Bulk operation'ın mesaj durumu istatistiklerini döner. show endpointinden farklı olarak item'ın değil, gönderilen mesajın gerçek message.status değerini sayar.

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/v2/bulk-operation/message-stats.js

İstek Parametreleri

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

{
  "bulkOperationId": "abc123xyz789"
}

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

Response

{
  "pending": 5,
  "sending": 2,
  "sent": 10,
  "delivered": 45,
  "read": 30,
  "deleted": 2,
  "warning": 1,
  "error": 3,
  "unknown": 0,
  "not-sended": 2,
  "no-message": 20,
  "total": 120
}

Message Stats Alanları

Alan	Tip	Açıklama
`pending`	number	Henüz gönderilmemiş mesajlar
`sending`	number	Gönderilmekte olan mesajlar
`sent`	number	WhatsApp'a iletilmiş, henüz teslim edilmemiş mesajlar
`delivered`	number	Alıcının telefonuna teslim edilmiş mesajlar
`read`	number	Alıcı tarafından okunmuş mesajlar
`deleted`	number	Silinmiş mesajlar
`warning`	number	Uyarı almış mesajlar
`error`	number	Hata almış mesajlar
`unknown`	number	Durumu bilinmeyen mesajlar
`not-sended`	number	Gönderilemeyen mesajlar
`no-message`	number	Mesajı olmayan item'lar (kuyrukta bekleyen, başarısız veya iptal edilen)
`total`	number	Toplam item sayısı

Kullanım İpuçları

Bulk operation running durumundayken yüksek no-message sayısı gönderimin sürdüğünü gösterir
delivered sayısı başarılı teslimatları gösterir
read sayısı kampanya etkileşimini ölçmek için kullanılabilir
Anlık takip için bu endpoint'i periyodik olarak sorgulayabilirsiniz

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

list ve list-with-messages endpointlerinde 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. `{"position": 1}`)

Pagination Yapısı

pagination gönderilmezse ilk sayfa en fazla 50 item ile döner. Gönderilirse currentPage zorunludur.

Alan	Tip	Varsayılan	Açıklama
`currentPage`	number	—	Getirilecek sayfa numarası (`pagination` gönderildiğinde zorunlu)
`pageItems`	number	50	Sayfa başına item sayısı (maksimum: 50)

Filtering Yapısı

Filtreleme MongoDB sorgu formatıyla, item alanlarının yanıtta göründüğü adlarıyla yapılır (örn. status, payload.referenceId, result.messageId). list-with-messages endpointinde mesaj alanlarına göre de filtreleme yapabilirsiniz (örn. message.status).

// Item durumuna göre filtreleme
{
  "options": {
    "filtering": {
      "status": "succeeded"
    }
  }
}

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

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

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

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

// Mesajı olmayan item'lar (sadece list-with-messages)
{
  "options": {
    "filtering": {
      "message": {
        "$exists": false
      }
    }
  }
}

Sorting Yapısı

Sıralama MongoDB sort formatıyla yapılır. 1 artan, -1 azalan sıralama anlamına gelir. position, alıcının istekteki recipients dizisindeki sırasıdır (0'dan başlar).

// Alıcıların istekte gönderildiği sırayla
{
  "options": {
    "sorting": {
      "position": 1
    }
  }
}

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

Kombine Kullanım Örneği

{
  "bulkOperationId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 2,
      "pageItems": 50
    },
    "filtering": {
      "message.status": "delivered"
    },
    "sorting": {
      "position": 1
    }
  }
}

Bu örnek teslim edilmiş mesajların ikinci sayfasını alıcı sırasıyla listeler.

Pratik İpuçları

Hedefli sorgular için filtering ve pagination'ı birlikte kullanın
Yanıt, gezinme için options.pagination.totalCount ve options.pagination.totalPages içerir
message.status filtresi sadece list-with-messages endpointinde çalışır

Items — Item Detayları ve Listeleme

Bir bulk operation'ın tüm gönderim item'larını listeler. Her item, recipients dizisindeki bir elemana karşılık gelir.

List — Item Listesi

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

İstek Parametreleri

Parametre	Tip	Zorunlu	Açıklama
`bulkOperationId`	string	Evet	Listelenecek bulk operation'ı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

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

Request — Belirli Duruma Göre Filtreleme

{
  "bulkOperationId": "abc123xyz789",
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50
    },
    "filtering": {
      "status": "failed"
    }
  }
}

Sadece başarısız gönderim item'larını, hata nedeni error alanında olacak şekilde listeler.

Response

{
  "bulkOperationItems": [
    {
      "_id": "item_1",
      "bulkOperationId": "abc123xyz789",
      "bulkOperationBatchId": "batch_1",
      "slug": "my-workspace",
      "position": 0,
      "payload": {
        "username": "905554443301",
        "referenceId": "ORDER-12345",
        "payload": {
          "template": {
            "variables": [{ "type": "BODY", "parameters": ["Ahmet", "ORD-001"] }]
          }
        }
      },
      "status": "succeeded",
      "attempt": 1,
      "result": {
        "userId": "user_123",
        "sessionId": "session_456",
        "messageId": "msg_789"
      },
      "createdAt": "2026-06-10T10:00:00.000Z",
      "updatedAt": "2026-06-10T10:00:01.000Z",
      "completedAt": "2026-06-10T10:00:01.000Z"
    },
    {
      "_id": "item_2",
      "bulkOperationId": "abc123xyz789",
      "bulkOperationBatchId": "batch_1",
      "slug": "my-workspace",
      "position": 1,
      "payload": { "username": "905554443302", "referenceId": "ORDER-12346" },
      "status": "failed",
      "attempt": 1,
      "error": { "code": "error", "message": "Variable missing", "retryable": false },
      "result": { "userId": "user_124", "sessionId": "session_457" },
      "createdAt": "2026-06-10T10:00:00.000Z",
      "updatedAt": "2026-06-10T10:00:01.000Z",
      "completedAt": "2026-06-10T10:00:01.000Z"
    }
  ],
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50,
      "totalCount": 150,
      "totalPages": 3
    },
    "sorting": {},
    "filtering": {},
    "searching": {}
  }
}

List With Messages — Mesaj Detaylı Liste

list endpointiyle aynı özelliklere sahiptir (sayfalama, filtreleme, sıralama). Farkı: her item, varsa ilgili message ve session nesneleriyle birlikte döner. Böylece mesaj durumunu (delivered, read, error vb.) ve içeriğini tek sorguda görebilirsiniz.

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

Request — Temel Kullanım

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

Request — Mesaj Durumuna Göre Filtreleme

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

Bu örnek sadece "delivered" durumundaki mesajları getirir.

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

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

Gönderimde hata alan mesajları incelemek için kullanılır.

Response

{
  "bulkOperationItems": [
    {
      "_id": "item_1",
      "bulkOperationId": "abc123xyz789",
      "position": 0,
      "payload": { "username": "905554443301", "referenceId": "ORDER-12345" },
      "status": "succeeded",
      "result": {
        "userId": "user_123",
        "sessionId": "session_456",
        "messageId": "msg_789"
      },
      "message": {
        "_id": "msg_789",
        "type": "template",
        "status": "delivered",
        "payload": {
          "template": {
            "name": "order_notification"
          }
        },
        "createdAt": "2026-06-10T10:01:00.000Z"
      },
      "session": {
        "_id": "session_456",
        "status": "opened"
      }
    }
  ],
  "options": {
    "pagination": {
      "currentPage": 1,
      "pageItems": 50,
      "totalCount": 150,
      "totalPages": 3
    },
    "sorting": {},
    "filtering": {},
    "searching": {}
  }
}

Item Alanları

Alan	Tip	Açıklama
`_id`	string	Item ID'si
`bulkOperationId`	string	Item'ın ait olduğu bulk operation ID'si
`position`	number	Alıcının istekteki `recipients` dizisindeki sırası (`0`'dan başlar)
`payload`	object	İstekte gönderildiği haliyle alıcı (`username` / `userId` / `sessionId`, `referenceId`, `payload`, `isMerge`)
`status`	string	Item durumu: `pending`, `succeeded`, `failed`, `cancelled`, `unknown`
`error`	object	Sadece `failed` item'larda: `code`, `message` ve `retryable`
`result.userId`	string	Alıcı kullanıcı ID'si
`result.sessionId`	string	Konuşma (session) ID'si
`result.messageId`	string	Gönderilen mesajın ID'si (mesaj gönderilmediyse yoktur)
`completedAt`	string	Item'ın işlendiği zaman
`message`	object	Mesaj detayları (sadece list-with-messages)
`session`	object	Konuşma detayları (sadece list-with-messages)

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

Özellik	list	list-with-messages
Sayfalama	Var	Var
Filtreleme	Var (sadece item alanları)	Var (item + mesaj alanları)
Mesaj / Session	Yok	Var (varsa)
Performans	Hızlı	Orta (JOIN yapar)
message.status Filtresi	Yok	Var

Kullanım Senaryoları

list: Tüm item'ları hızlıca listeleme, referenceId ile filtreleme, item durumlarını kontrol etme
list-with-messages: WhatsApp mesaj durumlarını (delivered, read) görme, mesaj içeriklerini inceleme
Filtreleme örnekleri:
- {"status": "failed"} — Başarısız gönderim item'ları
- {"payload.referenceId": "ORDER-123"} — Belirli bir reference ID
- {"message.status": "delivered"} — Teslim edilmiş mesajlar (sadece list-with-messages)
- {"message.status": "read"} — Okunmuş mesajlar (sadece list-with-messages)
- {"message.status": "error"} — Hata almış 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önderilemeyenler hariç mesajlar (sadece list-with-messages)
- {"message": {"$exists": false}} — Mesajı olmayan item'lar (sadece list-with-messages)
- {"status": {"$in": ["succeeded", "pending"]}} — Başarılı veya bekleyen item'lar

Performans ve Kullanım Notları

list endpointi daha hızlıdır; genel durum kontrolleri için onu tercih edin
Mesaj detayı gerektiğinde list-with-messages kullanın
Sayfa başına maksimum item (pageItems) 50'dir; belirtilmezse 50 kullanılır
message.status filtresi sadece list-with-messages'da çalışır
result.messageId olmayan item'larda message nesnesi yoktur

Stop — Gönderimi Durdur

Devam eden bir bulk operation gönderimini durdurur. Tüm pending item'lar cancelled statüsüne çekilir ve bulk operation stopped olur. Halihazırda işlenmiş (succeeded) veya hata almış (failed) item'lar etkilenmez. Planlı bir bulk operation scheduleAt zamanından önce de durdurulabilir.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation/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
`bulkOperationId`	string	Evet	Durdurulacak bulk operation'ın ID'si

{
  "bulkOperationId": "abc123xyz789"
}

curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation/stop.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
  "bulkOperationId": "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 operation'lar durdurulabilir
Gönderimi durdurduktan sonra show endpointi ile iptal edilen item sayısını (bulkOperation.progress.cancelled) doğrulayabilirsiniz
Bulk operation bulunamazsa hata döner: Bulk operation not found.

v1'den Geçiş​

Endpointler​

Alan adları​

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ı​

Show — Bulk Operation Durumu ve İstatistikleri​

İstek Parametreleri​

Response​

Show Alanları​

Reference ID​

Message Stats — WhatsApp Mesaj Durumları​

İstek Parametreleri​

Response​

Message Stats 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​

Items — Item Detayları ve Listeleme​

List — Item 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​

Item Alanları​

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

Stop — Gönderimi Durdur​

İstek Parametreleri​

Response​

v1'den Geçiş

Endpointler

Alan adları

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ı

Show — Bulk Operation Durumu ve İstatistikleri

İstek Parametreleri

Response

Show Alanları

Reference ID

Message Stats — WhatsApp Mesaj Durumları

İstek Parametreleri

Response

Message Stats 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

Items — Item Detayları ve Listeleme

List — Item 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

Item Alanları

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

Stop — Gönderimi Durdur

İstek Parametreleri

Response