Bulk Template Message API ডকুমেন্টেশন — v2

এই API দিয়ে আপনি WhatsApp চ্যানেলের মাধ্যমে একসঙ্গে একাধিক প্রাপকের কাছে টেমপ্লেট মেসেজ পাঠাতে পারেন।

মেসেজ ডেলিভারি অ্যাসিনক্রোনাসভাবে প্রসেস হয়; API অনুরোধ সঙ্গে সঙ্গে একটি bulkOperationId ফেরত দেয়, আর মেসেজগুলো কিউতে রেখে ব্যাকগ্রাউন্ডে প্রসেস করা হয়।

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

রেসপন্সের ফরম্যাট

এই ডকুমেন্টের প্রতিটি এন্ডপয়েন্ট একটি কাস্টম ফাংশন। HTTP রেসপন্স বডিতে ফাংশনের নিজস্ব ফিল্ড (_id, title, pathString…) থাকে, আর এন্ডপয়েন্টের আসল রেসপন্স থাকে result-এর ভেতরে। এই ডকুমেন্টের রেসপন্স উদাহরণগুলো result-এর বিষয়বস্তু দেখায়:

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

v1 থেকে মাইগ্রেশন

v2, v1-এর পাশাপাশি চলে, তাই আপনি নিজের সুবিধামতো সময়ে মাইগ্রেট করতে পারেন। v1 এন্ডপয়েন্টগুলো (/api/bulk-message/…, /api/bulk-message-records/…) বন্ধ করে দেওয়া হবে; নতুন ইন্টিগ্রেশনে v2 ব্যবহার করা উচিত।

এন্ডপয়েন্টের পাথ v2-তে সরান: …/api/bulk-message/… হয়ে যায় …/api/v2/bulk-operation/…, আর …/api/bulk-message-records/… হয়ে যায় …/api/v2/bulk-operation-items/…। send অনুরোধের বডি বদলায় না; একটি অনুরোধে এখন 5,000-এর বদলে সর্বোচ্চ 100,000 প্রাপক দেওয়া যায়।
অনুরোধে bulkMessageId-এর বদলে bulkOperationId পাঠান।
stats.js-এর বদলে show.js ব্যবহার করুন।
নিচের টেবিলের নতুন ফিল্ড নাম অনুযায়ী রেসপন্স পড়ুন।

v2 এন্ডপয়েন্টগুলো শুধু v2 send দিয়ে তৈরি বাল্ক অপারেশন চেনে। স্যুইচ করার আগে v1 দিয়ে তৈরি কোনো বাল্ক মেসেজ ট্র্যাক করতে হলে সেটির জন্য v1 এন্ডপয়েন্টই ব্যবহার করতে থাকুন।

এন্ডপয়েন্ট

v1	v2	রেসপন্সে কী বদলায়
`bulk-message/send.js`	`v2/bulk-operation/send.js`	`{ bulkMessageId }` হয়ে যায় `{ bulkOperationId }`
`bulk-message/stats.js`	`v2/bulk-operation/show.js`	`{ bulkMessage, stats }` হয়ে যায় `{ bulkOperation }`
`bulk-message/message-stats.js`	`v2/bulk-operation/message-stats.js`	কাউন্টারগুলো `messageStats`-এর ভেতরে না থেকে রুটে থাকে
`bulk-message/stop.js`	`v2/bulk-operation/stop.js`	কিছুই না
`bulk-message-records/list.js`	`v2/bulk-operation-items/list.js`	`bulkMessageRecords` হয়ে যায় `bulkOperationItems`
`bulk-message-records/list-with-messages.js`	`v2/bulk-operation-items/list-with-messages.js`	`list`-এর মতোই, আর প্রতিটি আইটেমে `session`-ও থাকে

ফিল্ডের নাম

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` (বাল্ক মেসেজ)	`bulkOperation` (বাল্ক অপারেশন)
`bulkMessageRecord` (রেকর্ড)	`bulkOperationItem` (আইটেম)
অনুরোধে, `send` রেসপন্সে ও রেকর্ডে `bulkMessageId`	`bulkOperationId`
পাঠানো অবস্থায় রেকর্ডের `username` / `userId` / `sessionId`	`payload.username` / `payload.userId` / `payload.sessionId`
রেকর্ডের `referenceId`	`payload.referenceId`
রেকর্ডের `payload` (প্রাপকের টেমপ্লেট পেলোড)	`payload.payload`
পাঠানোর পর রেকর্ডের `userId`, `sessionId`, `messageId`	`result.userId`, `result.sessionId`, `result.messageId`
রেকর্ডের অবস্থা `success`	`succeeded`
ব্যর্থ রেকর্ডে রেকর্ডের `errorMessage`	`error.message`, সঙ্গে `error.code` ও `error.retryable`
—	`position` (`recipients`-এ প্রাপকের ইনডেক্স)
ফিল্টার `{"status": "success"}`	`{"status": "succeeded"}`
ফিল্টার `{"referenceId": "…"}`	`{"payload.referenceId": "…"}`
`send`-এর ত্রুটি `schema-error`, `invalidRequest`	`zod-schema-error`, মেসেজে অবৈধ ফিল্ডের পাথসহ

প্রধান ফিচার

একটি অনুরোধে 1–100,000 প্রাপকের কাছে বাল্ক টেমপ্লেট মেসেজ পাঠান
প্রতিটি প্রাপকের জন্য ব্যক্তিগতকৃত ভেরিয়েবল (HEADER, BODY, BUTTONS, CAROUSEL)
সব প্রাপকের জন্য একটি সাধারণ defaultPayload এবং প্রাপক-নির্দিষ্ট payload-এর সঙ্গে মার্জ (isMerge)
নির্ধারিত সময়ে ডেলিভারি (scheduleAt)
username (ফোন নম্বর), userId বা sessionId দিয়ে প্রাপক নির্দিষ্ট করুন
একটি বাল্ক অনুরোধের মধ্যেই একই ব্যবহারকারীকে একাধিক মেসেজ পাঠান
বাইরের সিস্টেমের রেকর্ডের সঙ্গে ট্র্যাক করতে ঐচ্ছিক referenceId
পাঠানোর পর কথোপকথন স্বয়ংক্রিয়ভাবে কোনো ব্যবহারকারী বা ওয়ার্কগ্রুপকে দায়িত্ব দিন (action)

সতর্কবার্তা

এই API শুধু সেই টেমপ্লেটগুলোই পাঠাতে পারে যেগুলো Meta কর্তৃক অনুমোদিত।

টেমপ্লেটের নাম ও ভাষার কোড Meta Business Manager-এ নিবন্ধিত টেমপ্লেটের সঙ্গে হুবহু মিলতে হবে।

অনুরোধের প্যারামিটার

শীর্ষ-স্তরের প্যারামিটার

প্যারামিটার	ধরন	আবশ্যক	বিবরণ
`channelUsername`	string	হ্যাঁ	মেসেজ পাঠাতে ব্যবহৃত WhatsApp চ্যানেল নম্বর (যেমন `"908506669933"`)
`connectorBrand`	string	হ্যাঁ	চ্যানেল কানেক্টর ব্র্যান্ড। বর্তমানে সমর্থিত মান: `"whatsapp"`
`title`	string	না	ক্যাম্পেইনের শিরোনাম। ড্যাশবোর্ডে দেখানোর জন্য ব্যবহৃত। ডিফল্ট: `"-"`
`scheduleAt`	string (ISO 8601)	না	নির্ধারিত ডেলিভারির তারিখ ও সময় (যেমন `"2026-06-10T10:00:00.000Z"`)। বাদ দিলে মেসেজ সঙ্গে সঙ্গে পাঠানো হয়।
`defaultPayload`	object	শর্তসাপেক্ষ*	সব প্রাপকের জন্য প্রযোজ্য ডিফল্ট টেমপ্লেট পেলোড। কোনো প্রাপক নিজের `payload` না দিলে এটি আবশ্যক।
`recipients`	array	হ্যাঁ	প্রাপকের তালিকা। সর্বনিম্ন 1, সর্বোচ্চ 100,000 প্রাপক।
`action`	object	না	পাঠানোর পর কথোপকথনে প্রযোজ্য অ্যাকশন। `assign-to-user` বা `assign-to-workgroup`।

*প্রতিটি প্রাপক নিজের payload দিলে defaultPayload ঐচ্ছিক।

প্রাপকের কাঠামো

প্রতিটি প্রাপকের জন্য username, userId বা sessionId-এর ঠিক একটি দিতে হবে। একাধিক শনাক্তকারী একসঙ্গে ব্যবহার করা যায় না, আর সবগুলো বাদ দিলে ত্রুটি হবে।

একটি বাল্ক অনুরোধের মধ্যে একই ব্যবহারকারীকে একাধিক মেসেজ পাঠাতে প্রাপক তালিকায় একই শনাক্তকারী একাধিকবার যোগ করুন।

ফিল্ড	ধরন	বিবরণ
`username`	string	প্রাপকের ফোন নম্বর (যেমন `"905554443322"`)। ব্যবহারকারী সিস্টেমে না থাকলে স্বয়ংক্রিয়ভাবে তৈরি হয়।
`userId`	string	সিস্টেমে বিদ্যমান ব্যবহারকারীর আইডি।
`sessionId`	string	সিস্টেমে বিদ্যমান কথোপকথন সেশনের আইডি।
`referenceId`	string	বাইরের সিস্টেমের রেকর্ডের (CRM, অর্ডার, টিকিট ইত্যাদি) সঙ্গে মেলানোর জন্য ঐচ্ছিক রেফারেন্স আইডি (সর্বোচ্চ 256 অক্ষর)। দিলে বাল্কের মধ্যে অনন্য হতে হবে।
`payload`	object	প্রাপক-নির্দিষ্ট টেমপ্লেট পেলোড (ঐচ্ছিক)। `isMerge: true` হলে এটি `defaultPayload`-এর সঙ্গে মার্জ হয়।
`isMerge`	boolean	এই প্রাপকের জন্য মার্জ আচরণ বদলায় (ঐচ্ছিক)। বাদ দিলে `defaultPayload.isMerge` ব্যবহৃত হয়।

অ্যাকশনের কাঠামো

ফিল্ড	ধরন	বিবরণ
`action.key`	string	`"assign-to-user"` কথোপকথনটি একজন নির্দিষ্ট এজেন্টকে দেয়; `"assign-to-workgroup"` একটি ওয়ার্কগ্রুপকে দেয়।
`action.value`	string	লক্ষ্য ব্যবহারকারী বা ওয়ার্কগ্রুপের আইডি।

টেমপ্লেট পেলোডের কাঠামো

defaultPayload এবং প্রাপক-নির্দিষ্ট payload-এর কাঠামো একই। টেমপ্লেট মেসেজের জন্য type: "template" উল্লেখ করতে হবে।

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

ফিল্ড	ধরন	আবশ্যক	বিবরণ
`type`	string	হ্যাঁ	পেলোডের ধরন। টেমপ্লেট মেসেজের জন্য: `"template"`
`template.templateName`	string	হ্যাঁ*	Meta-তে নিবন্ধিত টেমপ্লেটের নাম। `isMerge: true` ব্যবহার করলে প্রাপকের পেলোডে ঐচ্ছিক (ডিফল্ট থেকে নেওয়া হয়)।
`template.languageCode`	string	না	টেমপ্লেটের ভাষার কোড (যেমন `"tr"`, `"en"`, `"tr-TR"`, `"en-US"`)। Meta-তে নিবন্ধিত ভাষার সঙ্গে হুবহু মিলতে হবে।
`template.variables`	array	না	টেমপ্লেটের কম্পোনেন্টে প্রযোজ্য ভেরিয়েবলের তালিকা। বিস্তারিত নিচে।
`isMerge`	boolean	না	`true`: প্রাপকের পেলোড `defaultPayload`-এর সঙ্গে ডিপ-মার্জ হয়। `false` বা বাদ দিলে: প্রাপকের পেলোড `defaultPayload`-কে সম্পূর্ণ প্রতিস্থাপন করে।

isMerge-এর আচরণ

defaultPayload.isMerge: true হলে এবং প্রাপক নিজের payload দিলে ডিপ মার্জ প্রয়োগ হয়।
ডিপ মার্জে প্রাপক শুধু variables দিতে পারেন; templateName ও languageCode ডিফল্ট পেলোড থেকে নেওয়া হয়।
প্রাপকের isMerge ফিল্ড defaultPayload.isMerge-কে ওভাররাইড করে।
কোনো প্রাপক payload না দিলে সবসময় defaultPayload ব্যবহৃত হয়।

ভেরিয়েবলের কাঠামো

variables অ্যারের প্রতিটি আইটেম টেমপ্লেটের একটি কম্পোনেন্টের সঙ্গে মেলে। একটি কম্পোনেন্টের ধরন (type) অ্যারেতে শুধু একবারই আসতে পারে।

type	বিবরণ	parameters	cards
`"HEADER"`	টেমপ্লেটের হেডার কম্পোনেন্ট। টেক্সট ভেরিয়েবল বা মিডিয়া URL (ছবি, ভিডিও, ডকুমেন্ট)	হ্যাঁ	—
`"BODY"`	টেমপ্লেটের বডি টেক্সটের ভেরিয়েবল	হ্যাঁ	—
`"BUTTONS"`	বোতামের জন্য ডাইনামিক URL সাফিক্স ভেরিয়েবল	হ্যাঁ	—
`"CAROUSEL"`	ক্যারোসেল টেমপ্লেটের কার্ড কম্পোনেন্ট	—	হ্যাঁ

প্যারামিটারের ফরম্যাট

parameters ফিল্ড তিনটি ভিন্ন ফরম্যাটে দেওয়া যায়:

// ফরম্যাট 1: অ্যারে (ইনডেক্সভিত্তিক) — {{1}}, {{2}}, {{3}}-এর মতো প্লেসহোল্ডারের জন্য
"parameters": ["value1", "value2", "value3"]

// ফরম্যাট 2: অবজেক্ট (সংখ্যাসূচক কী) — {{1}}, {{2}}-এর বিকল্প রূপ
"parameters": { "1": "value1", "2": "value2" }

// ফরম্যাট 3: অবজেক্ট (নামযুক্ত কী) — {{name}}, {{amount}}-এর মতো প্লেসহোল্ডারের জন্য
"parameters": { "name": "John", "amount": "150 USD" }

কোন ফরম্যাট ব্যবহার করবেন?

আপনার Meta টেমপ্লেটে {{1}}, {{2}}-এর মতো প্লেসহোল্ডার থাকলে অ্যারে ফরম্যাট বা সংখ্যাসূচক-কী অবজেক্ট ফরম্যাট ব্যবহার করুন।
টেমপ্লেটে {{firstName}} বা {{orderTotal}}-এর মতো নামযুক্ত প্লেসহোল্ডার থাকলে নামযুক্ত-কী অবজেক্ট ফরম্যাট ব্যবহার করুন।
অ্যারে ব্যবহার করলে ক্রম গুরুত্বপূর্ণ: প্রথম উপাদান {{1}}-এর সঙ্গে, দ্বিতীয়টি {{2}}-এর সঙ্গে মেলে, এভাবে চলে।

HEADER কম্পোনেন্ট

টেমপ্লেটের হেডারে মিডিয়া (ছবি, ভিডিও, ডকুমেন্ট) বা ডাইনামিক টেক্সট থাকলে HEADER কম্পোনেন্ট ব্যবহার করুন।

// মিডিয়া হেডার (ছবির URL)
{
  "type": "HEADER",
  "parameters": ["https://example.com/product-image.jpg"]
}

// টেক্সট হেডার ভেরিয়েবল
{
  "type": "HEADER",
  "parameters": ["Special Campaign"]
}

BODY কম্পোনেন্ট

টেমপ্লেটের বডির ভেতরে ডাইনামিক টেক্সট ভেরিয়েবলের জন্য ব্যবহৃত হয়।

// অ্যারে ফরম্যাট — টেমপ্লেটে {{1}}, {{2}}, {{3}} থাকলে
{
  "type": "BODY",
  "parameters": ["John", "ORD-12345", "150.00 USD"]
}

// নামযুক্ত ফরম্যাট — টেমপ্লেটে {{name}}, {{orderAmount}} থাকলে
{
  "type": "BODY",
  "parameters": {
    "name": "John",
    "orderAmount": "150.00 USD"
  }
}

BUTTONS কম্পোনেন্ট

ডাইনামিক URL সাফিক্সসহ বোতামের জন্য ব্যবহৃত হয়। টেমপ্লেটে একাধিক URL বোতাম থাকলে শুধু ভেরিয়েবল আছে এমন বোতামগুলোই ক্রমানুসারে সূচিবদ্ধ হয় (ভেরিয়েবল ছাড়া বোতাম বা FLOW বোতাম উপেক্ষা করা হয়)।

// একটি URL বোতামের সাফিক্স ভেরিয়েবল
{
  "type": "BUTTONS",
  "parameters": ["tracking/ORD-12345"]
}

// একাধিক URL বোতামের সাফিক্স ভেরিয়েবল (প্রথম URL বোতাম, দ্বিতীয় URL বোতাম)
{
  "type": "BUTTONS",
  "parameters": ["tracking/ORD-12345", "cancel/ORD-12345"]
}

CAROUSEL কম্পোনেন্ট

ক্যারোসেল টেমপ্লেটে প্রতিটি কার্ডের জন্য কম্পোনেন্টের ভেরিয়েবল আলাদাভাবে নির্ধারণ করা হয়।

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

সতর্কবার্তা

cards অ্যারের দৈর্ঘ্য টেমপ্লেটে নির্ধারিত কার্ডের সংখ্যার সঙ্গে হুবহু মিলতে হবে।

উদাহরণ

1. সাধারণ টেমপ্লেট — ভেরিয়েবল নেই, সব প্রাপকের জন্য একই বিষয়বস্তু

ভেরিয়েবল ছাড়া একটি স্থির টেমপ্লেট একাধিক প্রাপকের কাছে পাঠানোর সবচেয়ে সহজ উপায় এটি।

{
  "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/v2/bulk-operation/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" }
  ]
}'

টিপ

username দিয়ে নির্দিষ্ট করা প্রাপক সিস্টেমে আগে থেকে না থাকলে স্বয়ংক্রিয়ভাবে তৈরি হয়
সব প্রাপক একই defaultPayload ব্যবহার করে; প্রাপক-নির্দিষ্ট কোনো ডেটা লাগে না
isMerge নির্দিষ্ট না করলে প্রতিটি প্রাপক সরাসরি defaultPayload ব্যবহার করে

2. সবার জন্য একই বডি ভেরিয়েবলসহ টেমপ্লেট

একই টেমপ্লেট একই ভেরিয়েবল মান দিয়ে সব প্রাপকের কাছে পাঠানো হয়। টেমপ্লেটে {{1}} ও {{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" }]
}

টিপ

এই উদাহরণে টেমপ্লেটের বডিতে এমন লেখা থাকতে পারে: "আমাদের ক্যাম্পেইনে {{1}} ছাড় উপভোগ করুন! অফারটি {{2}} পর্যন্ত বৈধ।"
parameters[0] {{1}}-কে প্রতিস্থাপন করে, আর parameters[1] {{2}}-কে

3. ব্যক্তিগতকৃত টেমপ্লেট — isMerge সহ প্রাপকভেদে ভেরিয়েবল

প্রতিটি প্রাপকের জন্য আলাদা ভেরিয়েবল মান ব্যবহার করা হয়। defaultPayload-এ isMerge: true দিলে প্রাপকদের শুধু variables দিতে হয়; templateName ও languageCode ডিফল্ট পেলোড থেকে নেওয়া হয়।

এই উদাহরণে টেমপ্লেটে একটি মিডিয়া হেডার এবং ব্যক্তিগতকৃত বডি ভেরিয়েবল দুটোই আছে।

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

টিপ

isMerge: true-এর কারণে প্রতিটি প্রাপকের পেলোডে templateName আবার লিখতে হয় না
প্রতিটি প্রাপকের variables অ্যারে সম্পূর্ণ স্বাধীন
হেডার মিডিয়া URL সর্বসাধারণের জন্য প্রবেশযোগ্য হতে হবে
প্রাপকের পেলোডে type বাদ দিলে defaultPayload.type নেওয়া হয়

4. URL বোতামের ভেরিয়েবল

টেমপ্লেটে ডাইনামিক URL সাফিক্সসহ বোতাম থাকলে BUTTONS কম্পোনেন্ট ব্যবহার করুন। উদাহরণস্বরূপ, বেস URL 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"]
            }
          ]
        }
      }
    }
  ]
}

টিপ

BUTTONS প্যারামিটার ভেরিয়েবল আছে এমন বোতামগুলোর ক্রম অনুযায়ী মেলানো হয়
FLOW বোতাম এবং ভেরিয়েবল ছাড়া বোতাম উপেক্ষা করা হয়; সূচি শুধু ডাইনামিক URL বোতামে প্রযোজ্য
টেমপ্লেট বোতামের URL https://example.com/track/{{1}} হলে parameters[0] {{1}}-কে প্রতিস্থাপন করে

5. নির্ধারিত সময়ে ডেলিভারি

ভবিষ্যতের কোনো তারিখ ও সময়ে মেসেজ পাঠানোর সময়সূচি দিন। scheduleAt ISO 8601 UTC টাইমস্ট্যাম্প হিসেবে দিতে হবে।

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

টিপ

scheduleAt UTC টাইম জোনে দিতে হবে (যেমন তুরস্কের সময় সকাল 10:00-এর জন্য 07:00:00.000Z ব্যবহার করুন)
এই উদাহরণে নামযুক্ত প্যারামিটার ফরম্যাট ব্যবহার করা হয়েছে; টেমপ্লেটে {{name}} ও {{discountRate}}-এর মতো প্লেসহোল্ডার থাকা উচিত
action দিলে মেসেজ ডেলিভারির ফলে তৈরি হওয়া কথোপকথন স্বয়ংক্রিয়ভাবে নির্দিষ্ট ওয়ার্কগ্রুপকে দায়িত্ব দেওয়া হয়

রেসপন্স

সফল অনুরোধ একটি bulkOperationId ফেরত দেয়, যা দিয়ে ডেলিভারির অগ্রগতি ট্র্যাক করা যায়:

{
  "bulkOperationId": "abc123xyz789"
}

ত্রুটির রেসপন্স

স্ট্যাটাস	বিবরণ
`recipients field is required`	`recipients` ফিল্ড পাঠানো হয়নি
`Channel not found`	`channelUsername` ও `connectorBrand`-এর সঙ্গে মেলে এমন কোনো যাচাইকৃত চ্যানেল পাওয়া যায়নি
`Channel is not verified`	মেলানো চ্যানেলটি আছে কিন্তু এখনো যাচাই করা হয়নি
`zod-schema-error`	অনুরোধের বডির একটি ফিল্ড স্কিমা যাচাইয়ে ব্যর্থ হয়েছে (আবশ্যক ফিল্ড নেই, ভুল ধরন, অসমর্থিত মান, কোনো প্রাপকে একাধিক শনাক্তকারী, অথবা `payload` নেই)। মেসেজে ফিল্ডের নাম থাকে, যেমন `recipients.0.referenceId: referenceId must be unique`

ফেরত আসা bulkOperationId নিচের এন্ডপয়েন্টগুলোর সঙ্গে ব্যবহার করে ডেলিভারির পরিসংখ্যান জানা এবং ডেলিভারি বন্ধ করা যায়।

Show — বাল্ক অপারেশনের অবস্থা ও পরিসংখ্যান

বাল্ক অপারেশনটিকে তার বর্তমান অবস্থা এবং এর আইটেমগুলোর ডেলিভারি কাউন্টারসহ bulkOperation কী-এর অধীনে আনে।

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

অনুরোধের প্যারামিটার

প্যারামিটার	ধরন	আবশ্যক	বিবরণ
`bulkOperationId`	string	হ্যাঁ	ট্র্যাক করার বাল্ক অপারেশনের আইডি (`send` থেকে ফেরত আসে)

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

রেসপন্স

{
  "bulkOperation": {
    "_id": "abc123xyz789",
    "type": "send-bulk-message",
    "slug": "my-workspace",
    "userId": "agent_user_id",
    "payload": {
      "title": "Campaign Title",
      "channelUsername": "908506669933",
      "connectorBrand": "whatsapp",
      "connectorSlug": "om2WabVegaCloud",
      "defaultLanguageCode": "tr-TR",
      "sentUser": { "firstname": "John", "lastname": "Doe" },
      "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 ফিল্ড

ফিল্ডগুলো bulkOperation-এর অধীনে থাকে।

ফিল্ড	ধরন	বিবরণ
`status`	string	বাল্ক অপারেশনের অবস্থা: `preparing`, `scheduled`, `pending`, `running`, `stopping`, `stopped`, `completed`, `failed`
`progress.total`	number	মোট আইটেমের সংখ্যা
`progress.pending`	number	এখনো কিউতে অপেক্ষমাণ আইটেম
`progress.succeeded`	number	ডেলিভারির জন্য সফলভাবে প্রসেস হওয়া আইটেম
`progress.failed`	number	ডেলিভারিতে ত্রুটি হওয়া আইটেম
`progress.cancelled`	number	`stop` দিয়ে বাতিল হওয়া আইটেম
`progress.unknown`	number	যেসব আইটেমের ফলাফল নির্ধারণ করা যায়নি
`result.outcome`	string	বাল্ক অপারেশন শেষ হওয়ার পর চূড়ান্ত ফলাফল: `success`, `partial`, `all-failed`, `cancelled`, `unknown`
`result.hasErrors`	boolean	অন্তত একটি আইটেম ব্যর্থ হলে `true`
`scheduleAt`	string	নির্ধারিত ডেলিভারির সময় (শুধু নির্ধারিত বাল্ক অপারেশনের জন্য)
`startedAt`, `completedAt`	string	ডেলিভারি কখন শুরু ও শেষ হয়েছে

নোট

progress.succeeded বোঝায় যে সিস্টেম মেসেজটি সফলভাবে হস্তান্তর করেছে। এটি নিশ্চিত করে না যে Meta মেসেজটি প্রাপকের কাছে পৌঁছে দিয়েছে। Meta-র পরবর্তী স্ট্যাটাস আপডেট (যেমন delivered, read বা failed) এই কাউন্টারকে প্রভাবিত করে না এবং এখানে প্রতিফলিত হয় না।

Show বনাম Message Stats

show এন্ডপয়েন্ট: আইটেমগুলোর ডেলিভারির অবস্থা দেখায় (pending, succeeded, failed, cancelled, unknown)
message-stats এন্ডপয়েন্ট: মেসেজের প্রকৃত অবস্থা দেখায় (pending, sending, sent, delivered, read, error ইত্যাদি)
একটি আইটেম succeeded হলেও মেসেজটি হয়তো এখনো ডেলিভার/পড়া হয়নি

রেফারেন্স আইডি

referenceId একটি ঐচ্ছিক ফিল্ড, যা দিয়ে আপনি ট্র্যাকিংয়ের জন্য ডেলিভারি আইটেমকে আপনার নিজের সিস্টেমের আইডির (যেমন অর্ডার নম্বর, টিকিট আইডি) সঙ্গে মেলাতে পারেন। এটি প্রতিটি আইটেমে payload.referenceId হিসেবে ফেরত আসে।

দিলে এটি বাল্কের মধ্যে অনন্য হতে হবে (সর্বোচ্চ 256 অক্ষর)।

গুরুত্বপূর্ণ

ব্যবহার করা বাধ্যতামূলক নয়
একই বাল্ক অপারেশনের মধ্যে পুনরাবৃত্তি করা যায় না
ভিন্ন বাল্ক অপারেশনে পুনরায় ব্যবহার করা যায়

Message Stats — WhatsApp মেসেজের অবস্থা

একটি বাল্ক অপারেশনের মেসেজ-অবস্থার পরিসংখ্যান আনে। show এন্ডপয়েন্টের মতো আইটেমের অবস্থা না দেখিয়ে এটি পাঠানো মেসেজগুলোর প্রকৃত message.status দেখায়।

সম্ভাব্য মেসেজ স্ট্যাটাস: 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

অনুরোধের প্যারামিটার

প্যারামিটার	ধরন	আবশ্যক	বিবরণ
`bulkOperationId`	string	হ্যাঁ	যে বাল্ক অপারেশন সম্পর্কে জানতে চান তার আইডি

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

রেসপন্স

{
  "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 ফিল্ড

ফিল্ড	ধরন	বিবরণ
`pending`	number	এখনো পাঠানো হয়নি এমন মেসেজ
`sending`	number	এই মুহূর্তে পাঠানো হচ্ছে এমন মেসেজ
`sent`	number	WhatsApp-কে হস্তান্তর করা হয়েছে, এখনো ডেলিভার হয়নি এমন মেসেজ
`delivered`	number	প্রাপকের ফোনে ডেলিভার হওয়া মেসেজ
`read`	number	প্রাপক পড়েছেন এমন মেসেজ
`deleted`	number	মুছে ফেলা মেসেজ
`warning`	number	সতর্কতাসহ মেসেজ
`error`	number	ত্রুটিসহ মেসেজ
`unknown`	number	অজানা অবস্থার মেসেজ
`not-sended`	number	পাঠানো যায়নি এমন মেসেজ
`no-message`	number	মেসেজ নেই এমন আইটেম (এখনো কিউতে, ব্যর্থ বা বাতিল)
`total`	number	মোট আইটেমের সংখ্যা

ব্যবহারের টিপস

বাল্ক অপারেশন running থাকা অবস্থায় no-message-এর সংখ্যা বেশি হলে বোঝায় ডেলিভারি এখনো চলছে
delivered-এর সংখ্যা সফল মেসেজ ডেলিভারি দেখায়
read-এর সংখ্যা দিয়ে ক্যাম্পেইনের এনগেজমেন্ট মাপা যায়
রিয়েল-টাইম ট্র্যাকিংয়ের জন্য আপনি এই এন্ডপয়েন্টে নিয়মিত বিরতিতে পোল করতে পারেন

Options কাঠামো — পেজিনেশন, ফিল্টারিং ও সর্টিং

list ও list-with-messages এন্ডপয়েন্টে ব্যবহৃত options প্যারামিটার পেজিনেশন, ফিল্টারিং ও সর্টিংয়ের জন্য একটি প্রমিত কাঠামো দেয়।

Options ফিল্ড

ফিল্ড	ধরন	আবশ্যক	বিবরণ
`pagination`	object	না	পেজিনেশন সেটিংস
`filtering`	object	না	ফিল্টারিংয়ের শর্ত
`sorting`	object	না	সর্টিং সেটিংস (যেমন `{"position": 1}`)

পেজিনেশনের কাঠামো

pagination পাঠানো না হলে প্রথম পেজটি সর্বোচ্চ 50টি আইটেমসহ ফেরত আসে। পাঠানো হলে currentPage আবশ্যক।

ফিল্ড	ধরন	ডিফল্ট	বিবরণ
`currentPage`	number	—	যে পেজ আনতে চান তার নম্বর (`pagination` পাঠালে আবশ্যক)
`pageItems`	number	50	প্রতি পেজে আইটেমের সংখ্যা (সর্বোচ্চ: 50)

ফিল্টারিংয়ের কাঠামো

ফিল্টারিং আইটেমের ফিল্ডের ওপর MongoDB কোয়েরি ফরম্যাটে করা হয়, ফিল্ডের নাম ঠিক যেমন রেসপন্সে দেখা যায় তেমনই ব্যবহার করে (যেমন status, payload.referenceId, result.messageId)। list-with-messages এন্ডপয়েন্টে মেসেজের ফিল্ড দিয়েও (যেমন message.status) ফিল্টার করা যায়।

// আইটেমের অবস্থা দিয়ে ফিল্টার
{
  "options": {
    "filtering": {
      "status": "succeeded"
    }
  }
}

// referenceId দিয়ে ফিল্টার
{
  "options": {
    "filtering": {
      "payload.referenceId": "ORDER-12345"
    }
  }
}

// মেসেজের অবস্থা দিয়ে ফিল্টার (শুধু list-with-messages)
{
  "options": {
    "filtering": {
      "message.status": "delivered"
    }
  }
}

// $in (MongoDB অপারেটর) দিয়ে একাধিক অবস্থায় ফিল্টার
{
  "options": {
    "filtering": {
      "message.status": {
        "$in": ["delivered", "read"]
      }
    }
  }
}

// $nin (MongoDB অপারেটর) দিয়ে নির্দিষ্ট অবস্থা বাদ দিন
{
  "options": {
    "filtering": {
      "message.status": {
        "$nin": ["error", "not-sended"]
      }
    }
  }
}

// মেসেজ নেই এমন আইটেমের তালিকা (শুধু list-with-messages)
{
  "options": {
    "filtering": {
      "message": {
        "$exists": false
      }
    }
  }
}

সর্টিংয়ের কাঠামো

সর্টিং MongoDB সর্ট ফরম্যাটে করা হয়। 1 মানে ঊর্ধ্বক্রম, -1 মানে অধঃক্রম। position হলো অনুরোধের recipients অ্যারেতে প্রাপকের ক্রম (0 থেকে শুরু)।

// অনুরোধে প্রাপকরা যে ক্রমে পাঠানো হয়েছে সেই ক্রমে সাজান
{
  "options": {
    "sorting": {
      "position": 1
    }
  }
}

// একাধিক ফিল্ড দিয়ে সাজান
{
  "options": {
    "sorting": {
      "status": 1,
      "position": 1
    }
  }
}

একত্রে ব্যবহারের উদাহরণ

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

এই উদাহরণ ডেলিভার হওয়া মেসেজের দ্বিতীয় পেজটি প্রাপকের ক্রম অনুযায়ী তালিকাভুক্ত করে।

বাস্তব টিপস

নির্দিষ্ট কোয়েরির জন্য filtering ও pagination একসঙ্গে ব্যবহার করুন
নেভিগেশনের জন্য রেসপন্সে options.pagination.totalCount ও options.pagination.totalPages থাকে
message.status ফিল্টার শুধু list-with-messages এন্ডপয়েন্টে কাজ করে

Items — আইটেমের বিবরণ ও তালিকা

একটি বাল্ক অপারেশনের সব ডেলিভারি আইটেমের তালিকা দেয়। প্রতিটি আইটেম recipients অ্যারের একটি এন্ট্রি বোঝায়।

List — আইটেমের তালিকা

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

অনুরোধের প্যারামিটার

প্যারামিটার	ধরন	আবশ্যক	বিবরণ
`bulkOperationId`	string	হ্যাঁ	যে বাল্ক অপারেশনের তালিকা চান তার আইডি
`options`	object	না	পেজিনেশন, ফিল্টারিং ও সর্টিংয়ের অপশন। বিস্তারিত জানতে দেখুন Options কাঠামো।

অনুরোধ — মৌলিক ব্যবহার

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

অনুরোধ — নির্দিষ্ট অবস্থা দিয়ে ফিল্টার

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

শুধু ব্যর্থ ডেলিভারি আইটেমের তালিকা দেয়, কারণসহ error-এ।

রেসপন্স

{
  "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 — মেসেজের বিবরণসহ তালিকা

list এন্ডপয়েন্টের মতোই একই সুবিধা আছে (পেজিনেশন, ফিল্টারিং, সর্টিং)। পার্থক্য: প্রতিটি আইটেমে সংশ্লিষ্ট message ও session অবজেক্টও থাকে, যদি সেগুলো থাকে। এতে একটি কোয়েরিতেই মেসেজের অবস্থা (delivered, read, error ইত্যাদি) ও পেলোড দেখা যায়।

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

অনুরোধ — মৌলিক ব্যবহার

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

অনুরোধ — মেসেজের অবস্থা দিয়ে ফিল্টার

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

এই উদাহরণ শুধু "delivered" অবস্থার মেসেজ আনে।

অনুরোধ — ব্যর্থ মেসেজের তালিকা

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

ডেলিভারিতে ত্রুটি হওয়া মেসেজ পর্যালোচনা করতে ব্যবহৃত হয়।

রেসপন্স

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

আইটেমের ফিল্ড

ফিল্ড	ধরন	বিবরণ
`_id`	string	আইটেম আইডি
`bulkOperationId`	string	এই আইটেম যে বাল্ক অপারেশনের অন্তর্গত তার আইডি
`position`	number	অনুরোধের `recipients` অ্যারেতে প্রাপকের ক্রম, `0` থেকে শুরু
`payload`	object	অনুরোধে ঠিক যেভাবে পাঠানো হয়েছে সেভাবেই প্রাপক (`username` / `userId` / `sessionId`, `referenceId`, `payload`, `isMerge`)
`status`	string	আইটেমের অবস্থা: `pending`, `succeeded`, `failed`, `cancelled`, `unknown`
`error`	object	শুধু `failed` আইটেমে: `code`, `message` ও `retryable`
`result.userId`	string	প্রাপক ব্যবহারকারীর আইডি
`result.sessionId`	string	কথোপকথন সেশনের আইডি
`result.messageId`	string	পাঠানো মেসেজের আইডি (কোনো মেসেজ পাঠানো না হলে থাকে না)
`completedAt`	string	আইটেমটি কখন প্রসেস হয়েছে
`message`	object	মেসেজের বিবরণ (শুধু list-with-messages-এ)
`session`	object	কথোপকথনের বিবরণ (শুধু list-with-messages-এ)

List বনাম List-With-Messages তুলনা

বৈশিষ্ট্য	list	list-with-messages
পেজিনেশন	হ্যাঁ	হ্যাঁ
ফিল্টারিং	হ্যাঁ (শুধু আইটেমের ফিল্ড)	হ্যাঁ (আইটেম ও মেসেজের ফিল্ড)
Message / Session	না	হ্যাঁ (যদি থাকে)
পারফরম্যান্স	দ্রুত	মাঝারি (JOIN করে)
message.status ফিল্টার	উপলব্ধ নয়	উপলব্ধ

ব্যবহারের পরিস্থিতি

list: দ্রুত সব আইটেমের তালিকা নিন, referenceId দিয়ে ফিল্টার করুন, আইটেমের অবস্থা দেখুন
list-with-messages: WhatsApp মেসেজের অবস্থা (delivered, read) দেখুন, মেসেজের পেলোড পরীক্ষা করুন
ফিল্টারিংয়ের উদাহরণ:
- {"status": "failed"} — ব্যর্থ ডেলিভারি আইটেম
- {"payload.referenceId": "ORDER-123"} — নির্দিষ্ট রেফারেন্স আইডি
- {"message.status": "delivered"} — ডেলিভার হওয়া মেসেজ (শুধু list-with-messages)
- {"message.status": "read"} — পড়া মেসেজ (শুধু list-with-messages)
- {"message.status": "error"} — ত্রুটিসহ মেসেজ (শুধু list-with-messages)
- {"message.status": {"$in": ["delivered", "read"]}} — ডেলিভার হয়েছে বা পড়া হয়েছে এমন মেসেজ (শুধু list-with-messages)
- {"message.status": {"$nin": ["error", "not-sended"]}} — ত্রুটি ও না-পাঠানো বাদে মেসেজ (শুধু list-with-messages)
- {"message": {"$exists": false}} — মেসেজ নেই এমন আইটেম (শুধু list-with-messages)
- {"status": {"$in": ["succeeded", "pending"]}} — সফল বা অপেক্ষমাণ আইটেম

পারফরম্যান্স ও ব্যবহারের নোট

list এন্ডপয়েন্ট দ্রুততর; সাধারণ অবস্থা যাচাইয়ে এটি বেছে নিন
মেসেজের বিবরণ দরকার হলে list-with-messages ব্যবহার করুন
প্রতি পেজে সর্বোচ্চ আইটেম (pageItems) 50; নির্দিষ্ট না করলে ডিফল্ট 50
message.status ফিল্টার শুধু list-with-messages-এ কাজ করে
result.messageId নেই এমন আইটেমে message অবজেক্ট থাকে না

Stop — ডেলিভারি বাতিল

চলমান বাল্ক অপারেশনের ডেলিভারি বন্ধ করে। সব pending আইটেম cancelled অবস্থায় চলে যায় এবং বাল্ক অপারেশনটি stopped হয়। যেসব আইটেম আগেই succeeded বা failed হিসেবে প্রসেস হয়ে গেছে সেগুলো প্রভাবিত হয় না। নির্ধারিত বাল্ক অপারেশনও তার scheduleAt সময়ের আগে বন্ধ করা যায়।

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

সতর্কবার্তা

এই কাজ ফেরানো যায় না। বন্ধ করা ডেলিভারি আর চালু করা যায় না।

অনুরোধের প্যারামিটার

প্যারামিটার	ধরন	আবশ্যক	বিবরণ
`bulkOperationId`	string	হ্যাঁ	যে বাল্ক অপারেশন বন্ধ করবেন তার আইডি

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

রেসপন্স

সফল অনুরোধের রেসপন্স বডি খালি থাকে। HTTP 200 স্ট্যাটাস বোঝায় যে অপারেশন সফলভাবে সম্পন্ন হয়েছে।

{}

টিপ

শুধু এই API দিয়ে তৈরি বাল্ক অপারেশনই বন্ধ করা যায়
ডেলিভারি বন্ধ করার পর বাতিল আইটেমের সংখ্যা (bulkOperation.progress.cancelled) যাচাই করতে show এন্ডপয়েন্ট ব্যবহার করতে পারেন
বাল্ক অপারেশনটি খুঁজে না পেলে API এই ত্রুটি দেয়: Bulk operation not found.

v1 থেকে মাইগ্রেশন​

এন্ডপয়েন্ট​

ফিল্ডের নাম​

প্রধান ফিচার​

অনুরোধের প্যারামিটার​

শীর্ষ-স্তরের প্যারামিটার​

প্রাপকের কাঠামো​

অ্যাকশনের কাঠামো​

টেমপ্লেট পেলোডের কাঠামো​

ভেরিয়েবলের কাঠামো​

প্যারামিটারের ফরম্যাট​

HEADER কম্পোনেন্ট​

BODY কম্পোনেন্ট​

BUTTONS কম্পোনেন্ট​

CAROUSEL কম্পোনেন্ট​

উদাহরণ​

1. সাধারণ টেমপ্লেট — ভেরিয়েবল নেই, সব প্রাপকের জন্য একই বিষয়বস্তু​

2. সবার জন্য একই বডি ভেরিয়েবলসহ টেমপ্লেট​

3. ব্যক্তিগতকৃত টেমপ্লেট — isMerge সহ প্রাপকভেদে ভেরিয়েবল​

4. URL বোতামের ভেরিয়েবল​

5. নির্ধারিত সময়ে ডেলিভারি​

রেসপন্স​

ত্রুটির রেসপন্স​

Show — বাল্ক অপারেশনের অবস্থা ও পরিসংখ্যান​

অনুরোধের প্যারামিটার​

রেসপন্স​

Show ফিল্ড​

রেফারেন্স আইডি​

Message Stats — WhatsApp মেসেজের অবস্থা​

অনুরোধের প্যারামিটার​

রেসপন্স​

Message Stats ফিল্ড​

Options কাঠামো — পেজিনেশন, ফিল্টারিং ও সর্টিং​

Options ফিল্ড​

পেজিনেশনের কাঠামো​

ফিল্টারিংয়ের কাঠামো​

সর্টিংয়ের কাঠামো​

একত্রে ব্যবহারের উদাহরণ​

Items — আইটেমের বিবরণ ও তালিকা​

List — আইটেমের তালিকা​

অনুরোধের প্যারামিটার​

অনুরোধ — মৌলিক ব্যবহার​

অনুরোধ — নির্দিষ্ট অবস্থা দিয়ে ফিল্টার​

রেসপন্স​

List With Messages — মেসেজের বিবরণসহ তালিকা​

অনুরোধ — মৌলিক ব্যবহার​

অনুরোধ — মেসেজের অবস্থা দিয়ে ফিল্টার​

অনুরোধ — ব্যর্থ মেসেজের তালিকা​

রেসপন্স​

আইটেমের ফিল্ড​

List বনাম List-With-Messages তুলনা​

Stop — ডেলিভারি বাতিল​

অনুরোধের প্যারামিটার​

রেসপন্স​

v1 থেকে মাইগ্রেশন

এন্ডপয়েন্ট

ফিল্ডের নাম

প্রধান ফিচার

অনুরোধের প্যারামিটার

শীর্ষ-স্তরের প্যারামিটার

প্রাপকের কাঠামো

অ্যাকশনের কাঠামো

টেমপ্লেট পেলোডের কাঠামো

ভেরিয়েবলের কাঠামো

প্যারামিটারের ফরম্যাট

HEADER কম্পোনেন্ট

BODY কম্পোনেন্ট

BUTTONS কম্পোনেন্ট

CAROUSEL কম্পোনেন্ট

উদাহরণ

1. সাধারণ টেমপ্লেট — ভেরিয়েবল নেই, সব প্রাপকের জন্য একই বিষয়বস্তু

2. সবার জন্য একই বডি ভেরিয়েবলসহ টেমপ্লেট

3. ব্যক্তিগতকৃত টেমপ্লেট — isMerge সহ প্রাপকভেদে ভেরিয়েবল

4. URL বোতামের ভেরিয়েবল

5. নির্ধারিত সময়ে ডেলিভারি

রেসপন্স

ত্রুটির রেসপন্স

Show — বাল্ক অপারেশনের অবস্থা ও পরিসংখ্যান

অনুরোধের প্যারামিটার

রেসপন্স

Show ফিল্ড

রেফারেন্স আইডি

Message Stats — WhatsApp মেসেজের অবস্থা

অনুরোধের প্যারামিটার

রেসপন্স

Message Stats ফিল্ড

Options কাঠামো — পেজিনেশন, ফিল্টারিং ও সর্টিং

Options ফিল্ড

পেজিনেশনের কাঠামো

ফিল্টারিংয়ের কাঠামো

সর্টিংয়ের কাঠামো

একত্রে ব্যবহারের উদাহরণ

Items — আইটেমের বিবরণ ও তালিকা

List — আইটেমের তালিকা

অনুরোধের প্যারামিটার

অনুরোধ — মৌলিক ব্যবহার

অনুরোধ — নির্দিষ্ট অবস্থা দিয়ে ফিল্টার

রেসপন্স

List With Messages — মেসেজের বিবরণসহ তালিকা

অনুরোধ — মৌলিক ব্যবহার

অনুরোধ — মেসেজের অবস্থা দিয়ে ফিল্টার

অনুরোধ — ব্যর্থ মেসেজের তালিকা

রেসপন্স

আইটেমের ফিল্ড

List বনাম List-With-Messages তুলনা

Stop — ডেলিভারি বাতিল

অনুরোধের প্যারামিটার

রেসপন্স