Dokumentasi Bulk Template Message API

API ini memungkinkan Anda mengirim pesan template ke banyak penerima sekaligus melalui saluran WhatsApp.

Pengiriman pesan diproses secara asinkron; permintaan API langsung mengembalikan bulkMessageId, sementara pesan diantrekan dan diproses di latar belakang.

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

Fitur utama

Kirim pesan template massal ke 1–5.000 penerima dalam satu permintaan
Variabel yang dipersonalisasi untuk setiap penerima (HEADER, BODY, BUTTONS, CAROUSEL)
defaultPayload bersama untuk semua penerima dengan penggabungan payload khusus penerima (isMerge)
Pengiriman terjadwal (scheduleAt)
Tentukan penerima menggunakan username (nomor telepon), userId, atau sessionId
Kirim beberapa pesan ke pengguna yang sama dalam satu permintaan massal
referenceId opsional untuk melacak catatan dengan sistem eksternal
Tugaskan percakapan secara otomatis ke pengguna atau grup kerja setelah pengiriman (action)

peringatan

API ini hanya dapat mengirim template yang telah disetujui Meta.

Nama template dan kode bahasa harus persis sama dengan template yang terdaftar di Meta Business Manager.

Parameter permintaan

Parameter tingkat atas

Parameter	Tipe	Wajib	Deskripsi
`channelUsername`	string	Ya	Nomor saluran WhatsApp yang digunakan untuk mengirim pesan (misalnya `"908506669933"`)
`connectorBrand`	string	Ya	Merek konektor saluran. Nilai yang saat ini didukung: `"whatsapp"`
`title`	string	Tidak	Judul kampanye. Digunakan untuk tampilan di dasbor. Default: `"-"`
`scheduleAt`	string (ISO 8601)	Tidak	Tanggal dan waktu pengiriman terjadwal (misalnya `"2026-06-10T10:00:00.000Z"`). Jika dihilangkan, pesan dikirim segera.
`defaultPayload`	object	Bersyarat*	Payload template default yang berlaku untuk semua penerima. Wajib jika penerima tidak menyediakan `payload` sendiri.
`recipients`	array	Ya	Daftar penerima. Minimum 1, maksimum 5.000 penerima.
`action`	object	Tidak	Tindakan yang diterapkan pada percakapan setelah pengiriman. `assign-to-user` atau `assign-to-workgroup`.

*Jika setiap penerima menyediakan payload sendiri, defaultPayload bersifat opsional.

Struktur penerima

Untuk setiap penerima, tepat satu dari username, userId, atau sessionId harus diberikan. Beberapa pengenal tidak dapat digunakan bersamaan, dan jika semuanya dihilangkan akan terjadi error.

Untuk mengirim beberapa pesan ke pengguna yang sama dalam satu permintaan massal, tambahkan pengenal yang sama ke daftar penerima beberapa kali.

Kolom	Tipe	Deskripsi
`username`	string	Nomor telepon penerima (misalnya `"905554443322"`). Jika pengguna belum ada di sistem, pengguna dibuat otomatis.
`userId`	string	ID pengguna yang sudah ada di sistem.
`sessionId`	string	ID sesi percakapan yang sudah ada di sistem.
`referenceId`	string	Reference ID opsional (maks. 256 karakter) untuk mencocokkan dengan catatan sistem eksternal (CRM, pesanan, tiket, dll.). Harus unik di dalam satu pesan massal jika diberikan.
`payload`	object	Payload template khusus penerima (opsional). Jika `isMerge: true`, payload digabungkan dengan `defaultPayload`.
`isMerge`	boolean	Menggantikan perilaku penggabungan untuk penerima ini (opsional). Jika dihilangkan, `defaultPayload.isMerge` digunakan.

Struktur action

Kolom	Tipe	Deskripsi
`action.key`	string	`"assign-to-user"` menugaskan percakapan ke agen tertentu; `"assign-to-workgroup"` menugaskannya ke grup kerja.
`action.value`	string	ID pengguna atau grup kerja tujuan.

Struktur payload template

defaultPayload dan payload khusus penerima memiliki struktur yang sama. Untuk pesan template, type: "template" harus ditentukan.

{
  "type": "template",
  "template": {
    "templateName": "order_confirmation",
    "languageCode": "tr-TR",
    "variables": []
  },
  "isMerge": true
}

Kolom	Tipe	Wajib	Deskripsi
`type`	string	Ya	Tipe payload. Untuk pesan template: `"template"`
`template.templateName`	string	Ya*	Nama template yang terdaftar di Meta. Opsional pada payload penerima saat `isMerge: true` digunakan (diwarisi dari default).
`template.languageCode`	string	Tidak	Kode bahasa template (misalnya `"tr"`, `"en"`, `"tr-TR"`, `"en-US"`). Harus persis sama dengan bahasa yang terdaftar di Meta.
`template.variables`	array	Tidak	Daftar variabel yang diterapkan pada komponen template. Dijelaskan di bawah.
`isMerge`	boolean	Tidak	`true`: payload penerima digabungkan secara mendalam dengan `defaultPayload`. `false` atau dihilangkan: payload penerima sepenuhnya menggantikan `defaultPayload`.

Perilaku isMerge

Jika defaultPayload.isMerge: true dan penerima menyediakan payload sendiri, penggabungan mendalam (deep merge) diterapkan.
Dengan deep merge, penerima cukup menyediakan variables; templateName dan languageCode diwarisi dari payload default.
Kolom isMerge penerima menggantikan defaultPayload.isMerge.
Jika penerima tidak menyediakan payload, defaultPayload selalu digunakan.

Struktur variabel

Setiap item dalam array variables sesuai dengan satu komponen template. Satu jenis komponen (type) hanya boleh muncul sekali dalam array.

type	Deskripsi	parameters	cards
`"HEADER"`	Komponen header template. Variabel teks atau URL media (gambar, video, dokumen)	Ya	—
`"BODY"`	Variabel teks body template	Ya	—
`"BUTTONS"`	Variabel akhiran URL dinamis untuk tombol	Ya	—
`"CAROUSEL"`	Komponen kartu untuk template carousel	—	Ya

Format parameter

Kolom parameters dapat diberikan dalam tiga format berbeda:

// Format 1: Array (index-based) — for placeholders like {{1}}, {{2}}, {{3}}
"parameters": ["value1", "value2", "value3"]

// Format 2: Object (numeric keys) — alternative representation for {{1}}, {{2}}
"parameters": { "1": "value1", "2": "value2" }

// Format 3: Object (named keys) — for placeholders like {{name}}, {{amount}}
"parameters": { "name": "John", "amount": "150 USD" }

Format mana yang sebaiknya saya pakai?

Jika template Meta Anda menggunakan placeholder seperti {{1}}, {{2}}, gunakan format array atau format objek dengan kunci numerik.
Jika template Anda menggunakan placeholder bernama seperti {{firstName}} atau {{orderTotal}}, gunakan format objek dengan kunci bernama.
Saat menggunakan array, urutan berpengaruh: elemen pertama untuk {{1}}, elemen kedua untuk {{2}}, dan seterusnya.

Komponen HEADER

Gunakan komponen HEADER saat header template berisi media (gambar, video, dokumen) atau teks dinamis.

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

// Text header variable
{
  "type": "HEADER",
  "parameters": ["Special Campaign"]
}

Komponen BODY

Digunakan untuk variabel teks dinamis di dalam body template.

// Array format — when the template uses {{1}}, {{2}}, {{3}}
{
  "type": "BODY",
  "parameters": ["John", "ORD-12345", "150.00 USD"]
}

// Named format — when the template uses {{name}}, {{orderAmount}}
{
  "type": "BODY",
  "parameters": {
    "name": "John",
    "orderAmount": "150.00 USD"
  }
}

Komponen BUTTONS

Digunakan untuk tombol dengan akhiran URL dinamis. Jika template berisi beberapa tombol URL, hanya tombol yang memiliki variabel yang diindeks secara berurutan (tombol tanpa variabel atau tombol FLOW diabaikan).

// Single URL button suffix variable
{
  "type": "BUTTONS",
  "parameters": ["tracking/ORD-12345"]
}

// Multiple URL button suffix variables (first URL button, second URL button)
{
  "type": "BUTTONS",
  "parameters": ["tracking/ORD-12345", "cancel/ORD-12345"]
}

Komponen CAROUSEL

Untuk template carousel, variabel komponen ditentukan secara terpisah untuk setiap kartu.

{
  "type": "CAROUSEL",
  "cards": [
    {
      "components": [
        {
          "type": "HEADER",
          "parameters": ["https://example.com/card1.jpg"]
        },
        {
          "type": "BODY",
          "parameters": ["Product A", "99.00 USD"]
        }
      ]
    },
    {
      "components": [
        {
          "type": "HEADER",
          "parameters": ["https://example.com/card2.jpg"]
        },
        {
          "type": "BODY",
          "parameters": ["Product B", "149.00 USD"]
        }
      ]
    }
  ]
}

peringatan

Panjang array cards harus persis sama dengan jumlah kartu yang ditentukan di template.

Contoh

1. Template sederhana — tanpa variabel, isi sama untuk semua penerima

Ini cara paling sederhana untuk mengirim template statis tanpa variabel ke banyak penerima.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "General Announcement",
  "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": "General Announcement",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "hello_world",
      "languageCode": "tr-TR"
    }
  },
  "recipients": [
    { "username": "905554443301" },
    { "username": "905554443302" },
    { "username": "905554443303" }
  ]
}'

tips

Penerima yang ditentukan lewat username dibuat otomatis jika belum ada di sistem
Semua penerima menggunakan defaultPayload yang sama; tidak diperlukan data khusus penerima
Jika isMerge tidak ditentukan, setiap penerima langsung menggunakan defaultPayload

2. Template dengan variabel body bersama

Template yang sama dikirim ke semua penerima dengan nilai variabel yang identik. Template berisi placeholder seperti {{1}} dan {{2}}.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Summer Campaign",
  "defaultPayload": {
    "type": "template",
    "template": {
      "templateName": "promo_notification",
      "languageCode": "tr-TR",
      "variables": [
        {
          "type": "BODY",
          "parameters": ["30%", "July 31, 2026"]
        }
      ]
    }
  },
  "recipients": [{ "username": "905554443301" }, { "username": "905554443302" }]
}

tips

Pada contoh ini, body template dapat berisi teks seperti: "Nikmati diskon {{1}} di kampanye kami! Penawaran berlaku hingga {{2}}."
parameters[0] menggantikan {{1}}, sedangkan parameters[1] menggantikan {{2}}

3. Template yang dipersonalisasi — variabel per penerima dengan isMerge

Nilai variabel yang berbeda digunakan untuk setiap penerima. Dengan menetapkan isMerge: true pada defaultPayload, penerima hanya perlu menyediakan variables; templateName dan languageCode diwarisi dari payload default.

Pada contoh ini, template memiliki header media sekaligus variabel body yang dipersonalisasi.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Personal Order Notification",
  "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 TRY"]
            }
          ]
        }
      }
    },
    {
      "username": "905554443302",
      "payload": {
        "template": {
          "variables": [
            {
              "type": "HEADER",
              "parameters": ["https://s3.example.com/product-b.jpg"]
            },
            {
              "type": "BODY",
              "parameters": ["Fatma", "ORD-002", "289.00 TRY"]
            }
          ]
        }
      }
    }
  ]
}

tips

Berkat isMerge: true, templateName tidak perlu diulang di setiap payload penerima
Array variables setiap penerima sepenuhnya independen
URL media header harus dapat diakses publik
Jika type dihilangkan pada payload penerima, defaultPayload.type diwarisi

4. Variabel tombol URL

Gunakan komponen BUTTONS saat template berisi tombol dengan akhiran URL dinamis. Misalnya, nomor pelacakan yang ditambahkan ke URL dasar https://example.com/track/.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Shipment Tracking Notification",
  "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"]
            }
          ]
        }
      }
    }
  ]
}

tips

Parameter BUTTONS dicocokkan menurut urutan tombol yang memiliki variabel
Tombol FLOW dan tombol tanpa variabel diabaikan; pengindeksan hanya berlaku untuk tombol URL dinamis
Jika URL tombol template adalah https://example.com/track/{{1}}, maka parameters[0] menggantikan {{1}}

5. Pengiriman terjadwal

Jadwalkan pesan untuk dikirim pada tanggal dan waktu mendatang. scheduleAt harus diberikan sebagai stempel waktu UTC ISO 8601.

{
  "channelUsername": "908506669933",
  "connectorBrand": "whatsapp",
  "title": "Morning Campaign Message",
  "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" }
            }
          ]
        }
      }
    }
  ]
}

tips

scheduleAt harus diberikan dalam zona waktu UTC (misalnya, untuk pukul 10.00 waktu Turki, gunakan 07:00:00.000Z)
Contoh ini menggunakan format parameter bernama; template harus berisi placeholder seperti {{name}} dan {{discountRate}}
Dengan action, percakapan yang dibuat oleh pengiriman pesan otomatis ditugaskan ke grup kerja yang ditentukan

Respons

Permintaan yang berhasil mengembalikan bulkMessageId, yang dapat digunakan untuk melacak proses pengiriman:

{
  "bulkMessageId": "abc123xyz789"
}

Respons error

Status	Deskripsi
`Channel not found`	Tidak ditemukan saluran terverifikasi yang cocok dengan `channelUsername` dan `connectorBrand`
`Channel is not verified`	Saluran yang cocok ada tetapi belum terverifikasi
`invalidRequest`	Beberapa pengenal diberikan untuk satu penerima atau payload yang wajib tidak ada
`channelNotFound`	Tidak ditemukan saluran aktif yang cocok dengan `channelId` yang diberikan
`schema-error`	Sebuah kolom di isi permintaan gagal validasi skema (kolom wajib tidak ada, tipe salah, atau nilai tidak didukung)

bulkMessageId yang dikembalikan dapat digunakan dengan endpoint di bawah ini untuk melihat statistik pengiriman dan menghentikan proses pengiriman.

Stats — Statistik pengiriman

Mengambil status pengiriman terkini dari sebuah pesan massal. Mengembalikan jumlah catatan yang tertunda, berhasil, gagal, dan dibatalkan.

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

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`bulkMessageId`	string	Ya	ID pesan massal yang dilacak (dikembalikan dari `createBulkPerRecipient`)

{
  "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"
}'

Respons

{
  "bulkMessage": {
    "_id": "abc123xyz789",
    "slug": "my-workspace",
    "title": "Campaign Title",
    "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
  }
}

Kolom stats

Kolom	Tipe	Deskripsi
`stats.pending`	number	Jumlah catatan yang masih menunggu dalam antrean
`stats.success`	number	Jumlah catatan yang berhasil diproses untuk pengiriman
`stats.failed`	number	Jumlah catatan yang mengalami error pengiriman
`stats.cancelled`	number	Jumlah catatan yang dibatalkan
`stats.total`	number	Jumlah total catatan (`pending + success + failed + cancelled`)

catatan

stats.success menunjukkan bahwa pesan berhasil diserahkan oleh sistem. Ini tidak menjamin bahwa Meta menyampaikan pesan ke penerima. Pembaruan status berikutnya dari Meta (seperti delivered, read, atau failed) tidak memengaruhi penghitung ini dan tidak tercermin di sini.

Stats vs Message Stats

Endpoint stats: Menampilkan status pekerjaan pengiriman (pending, success, failed, cancelled)
Endpoint message-stats: Menampilkan status pesan sebenarnya (pending, sending, sent, delivered, read, error, dll.)
Sebuah pekerjaan bisa berhasil, tetapi pesannya mungkin belum terkirim/terbaca

Reference ID

referenceId adalah kolom opsional yang dapat Anda gunakan untuk mencocokkan catatan pengiriman dengan ID dari sistem Anda sendiri untuk keperluan pelacakan (misalnya nomor pesanan, ID tiket).

Jika diberikan, nilainya harus unik di dalam satu pesan massal (maksimal 256 karakter).

Penting

Tidak wajib digunakan
Tidak boleh duplikat dalam pesan massal yang sama
Dapat dipakai ulang di pesan massal yang berbeda

Message Stats — Status pesan WhatsApp

Mengambil statistik status pesan dari sebuah pesan massal. Berbeda dengan endpoint stats, endpoint ini menampilkan message.status sebenarnya untuk setiap catatan, bukan status pekerjaan.

Status pesan yang mungkin: 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

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`bulkMessageId`	string	Ya	ID pesan massal yang di-query

{
  "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"
}'

Respons

{
  "bulkMessage": {
    "_id": "abc123xyz789",
    "slug": "my-workspace",
    "type": "perRecipient",
    "title": "Campaign Title"
  },
  "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
  }
}

Kolom message stats

Kolom	Tipe	Deskripsi
`pending`	number	Pesan yang belum dikirim
`sending`	number	Pesan yang sedang dikirim
`sent`	number	Pesan yang sudah diserahkan ke WhatsApp, belum terkirim
`delivered`	number	Pesan yang terkirim ke ponsel penerima
`read`	number	Pesan yang dibaca penerima
`deleted`	number	Pesan yang dihapus
`warning`	number	Pesan dengan peringatan
`error`	number	Pesan dengan error
`unknown`	number	Pesan dengan status tidak diketahui
`not-sended`	number	Pesan yang tidak dapat dikirim
`no-message`	number	Catatan yang belum memiliki pesan (masih dalam antrean)
`total`	number	Jumlah total catatan

Tips penggunaan

Jumlah no-message yang tinggi menunjukkan pengiriman masih berlangsung
Jumlah delivered menunjukkan pesan berhasil terkirim
Jumlah read dapat digunakan untuk mengukur keterlibatan kampanye
Anda dapat memanggil endpoint ini secara berkala untuk pelacakan real-time

Struktur options — penomoran halaman, pemfilteran, dan pengurutan

Parameter options yang digunakan pada endpoint list dan list-with-messages menyediakan struktur standar untuk penomoran halaman, pemfilteran, dan pengurutan.

Kolom options

Kolom	Tipe	Wajib	Deskripsi
`pagination`	object	Tidak	Pengaturan penomoran halaman
`filtering`	object	Tidak	Kriteria pemfilteran
`sorting`	object	Tidak	Pengaturan pengurutan (misalnya `{"createdAt": -1}`)

Struktur pagination

Kolom	Tipe	Default	Deskripsi
`currentPage`	number	1	Nomor halaman yang diambil
`pageItems`	number	50	Jumlah catatan per halaman (maksimum: 50)

Struktur filtering

Pemfilteran menggunakan format query MongoDB. Anda dapat memfilter berdasarkan kolom catatan. Pada endpoint list-with-messages, Anda juga dapat memfilter berdasarkan kolom pesan (misalnya message.status).

// Filter by record status
{
  "options": {
    "filtering": {
      "status": "success"
    }
  }
}

// Filter by referenceId
{
  "options": {
    "filtering": {
      "referenceId": "ORDER-12345"
    }
  }
}

// Filter by message status (only list-with-messages)
{
  "options": {
    "filtering": {
      "message.status": "delivered"
    }
  }
}

// Filter by multiple statuses using $in (MongoDB operator)
{
  "options": {
    "filtering": {
      "message.status": {
        "$in": ["delivered", "read"]
      }
    }
  }
}

// Exclude specific statuses using $nin (MongoDB operator)
{
  "options": {
    "filtering": {
      "message.status": {
        "$nin": ["error", "not-sended"]
      }
    }
  }
}

Struktur sorting

Pengurutan menggunakan format sort MongoDB. 1 berarti menaik, -1 berarti menurun.

// Sort by creation date descending (newest first)
{
  "options": {
    "sorting": {
      "createdAt": -1
    }
  }
}

// Sort by multiple fields
{
  "options": {
    "sorting": {
      "status": 1,
      "createdAt": -1
    }
  }
}

Contoh penggunaan gabungan

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

Contoh ini mengurutkan pesan terkirim dari yang terbaru ke yang terlama.

Tips praktis

Gabungkan filtering dan pagination untuk query yang terarah
Respons menyertakan options.pagination.totalCount dan options.pagination.totalPages untuk navigasi
Filter message.status hanya berfungsi pada endpoint list-with-messages

Records — Detail dan daftar catatan

Menampilkan semua catatan pengiriman dari sebuah pesan massal. Setiap catatan mewakili satu pesan yang dikirim ke satu penerima.

List — Daftar catatan

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

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`bulkMessageId`	string	Ya	ID pesan massal yang ditampilkan
`options`	object	Tidak	Opsi penomoran halaman, pemfilteran, dan pengurutan. Lihat Struktur options untuk detailnya.

Permintaan — penggunaan dasar

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

Permintaan — filter berdasarkan status tertentu

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

Hanya menampilkan catatan pengiriman yang berhasil (record.status = "success").

Respons

{
  "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 — Daftar dengan detail pesan

Memiliki fitur yang sama dengan endpoint list (penomoran halaman, pemfilteran, pengurutan). Satu-satunya perbedaan: jika sebuah catatan memiliki messageId, objek message terkait juga dikembalikan. Dengan begitu Anda dapat melihat status pesan (delivered, read, error, dll.) dan payload dalam satu query.

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

Permintaan — penggunaan dasar

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

Permintaan — filter berdasarkan status pesan

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

Contoh ini hanya mengambil pesan dengan status "delivered".

Permintaan — daftar pesan yang gagal

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

Digunakan untuk meninjau pesan yang mengalami error pengiriman.

Respons

{
  "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": {}
  }
}

Kolom catatan

Kolom	Tipe	Deskripsi
`_id`	string	ID catatan
`bulkMessageId`	string	ID pesan massal pemilik catatan ini
`userId`	string	ID pengguna penerima
`sessionId`	string	ID sesi percakapan
`messageId`	string	ID pesan terkirim (null jika belum dikirim)
`referenceId`	string	Reference ID opsional (jika diberikan)
`status`	string	Status catatan: `pending`, `success`, `failed`, `cancelled`
`message`	object	Detail pesan (hanya di list-with-messages)

Perbandingan List dan List-With-Messages

Fitur	list	list-with-messages
Penomoran halaman	Ya	Ya
Pemfilteran	Ya (hanya kolom catatan)	Ya (kolom catatan + pesan)
Objek pesan	Tidak	Ya (jika messageId ada)
Kinerja	Cepat	Sedang (melakukan JOIN)
Filter message.status	Tidak tersedia	Tersedia

Skenario penggunaan

list: Menampilkan semua catatan dengan cepat, memfilter berdasarkan referenceId, memeriksa status catatan
list-with-messages: Melihat status pesan WhatsApp (delivered, read), memeriksa payload pesan
Contoh pemfilteran:
- {"status": "failed"} — Catatan pengiriman yang gagal
- {"referenceId": "ORDER-123"} — Reference ID tertentu
- {"message.status": "delivered"} — Pesan terkirim (hanya list-with-messages)
- {"message.status": "read"} — Pesan terbaca (hanya list-with-messages)
- {"message.status": "error"} — Pesan dengan error (hanya list-with-messages)
- {"message.status": {"$in": ["delivered", "read"]}} — Pesan yang terkirim atau terbaca (hanya list-with-messages)
- {"message.status": {"$nin": ["error", "not-sended"]}} — Pesan tanpa yang error dan tidak terkirim (hanya list-with-messages)
- {"status": {"$in": ["success", "pending"]}} — Catatan yang berhasil atau tertunda

Catatan kinerja dan penggunaan

Endpoint list lebih cepat; pilih endpoint ini untuk pemeriksaan status umum
Gunakan list-with-messages saat detail pesan dibutuhkan
Jumlah catatan maksimum per halaman (pageItems) adalah 50; default 50 jika tidak ditentukan
Filter message.status hanya berfungsi pada list-with-messages
Catatan dengan messageId null akan memiliki objek message null

Stop — Batalkan pengiriman

Menghentikan pengiriman pesan massal yang sedang berjalan. Pekerjaan dalam antrean dibatalkan, dan semua catatan pending dipindahkan ke status cancelled. Catatan yang sudah diproses sebagai success atau failed tidak terpengaruh.

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

peringatan

Tindakan ini tidak dapat dibatalkan. Pengiriman yang dihentikan tidak dapat dilanjutkan.

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`bulkMessageId`	string	Ya	ID pesan massal yang dihentikan

{
  "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"
}'

Respons

Untuk permintaan yang berhasil, isi respons kosong. Status HTTP 200 menunjukkan bahwa operasi selesai dengan berhasil.

{}

tips

Hanya pesan massal yang dibuat melalui API ini yang dapat dihentikan
Setelah menghentikan pengiriman, Anda dapat menggunakan endpoint stats untuk memeriksa jumlah catatan yang dibatalkan
Jika pesan massal tidak ditemukan, API mengembalikan error: bulkMessageNotFound

Fitur utama​

Parameter permintaan​

Parameter tingkat atas​

Struktur penerima​

Struktur action​

Struktur payload template​

Struktur variabel​

Format parameter​

Komponen HEADER​

Komponen BODY​

Komponen BUTTONS​

Komponen CAROUSEL​

Contoh​

1. Template sederhana — tanpa variabel, isi sama untuk semua penerima​

2. Template dengan variabel body bersama​

3. Template yang dipersonalisasi — variabel per penerima dengan isMerge​

4. Variabel tombol URL​

5. Pengiriman terjadwal​

Respons​

Respons error​

Stats — Statistik pengiriman​

Parameter permintaan​

Respons​

Kolom stats​

Reference ID​

Message Stats — Status pesan WhatsApp​

Parameter permintaan​

Respons​

Kolom message stats​

Struktur options — penomoran halaman, pemfilteran, dan pengurutan​

Kolom options​

Struktur pagination​

Struktur filtering​

Struktur sorting​

Contoh penggunaan gabungan​

Records — Detail dan daftar catatan​

List — Daftar catatan​

Parameter permintaan​

Permintaan — penggunaan dasar​

Permintaan — filter berdasarkan status tertentu​

Respons​

List With Messages — Daftar dengan detail pesan​

Permintaan — penggunaan dasar​

Permintaan — filter berdasarkan status pesan​

Permintaan — daftar pesan yang gagal​

Respons​

Kolom catatan​

Perbandingan List dan List-With-Messages​

Stop — Batalkan pengiriman​

Parameter permintaan​

Respons​

Fitur utama

Parameter permintaan

Parameter tingkat atas

Struktur penerima

Struktur action

Struktur payload template

Struktur variabel

Format parameter

Komponen HEADER

Komponen BODY

Komponen BUTTONS

Komponen CAROUSEL

Contoh

1. Template sederhana — tanpa variabel, isi sama untuk semua penerima

2. Template dengan variabel body bersama

3. Template yang dipersonalisasi — variabel per penerima dengan isMerge

4. Variabel tombol URL

5. Pengiriman terjadwal

Respons

Respons error

Stats — Statistik pengiriman

Parameter permintaan

Respons

Kolom stats

Reference ID

Message Stats — Status pesan WhatsApp

Parameter permintaan

Respons

Kolom message stats

Struktur options — penomoran halaman, pemfilteran, dan pengurutan

Kolom options

Struktur pagination

Struktur filtering

Struktur sorting

Contoh penggunaan gabungan

Records — Detail dan daftar catatan

List — Daftar catatan

Parameter permintaan

Permintaan — penggunaan dasar

Permintaan — filter berdasarkan status tertentu

Respons

List With Messages — Daftar dengan detail pesan

Permintaan — penggunaan dasar

Permintaan — filter berdasarkan status pesan

Permintaan — daftar pesan yang gagal

Respons

Kolom catatan

Perbandingan List dan List-With-Messages

Stop — Batalkan pengiriman

Parameter permintaan

Respons