بلک ٹیمپلیٹ میسج 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

جواب کا فارمیٹ

اس دستاویز کا ہر اینڈ پوائنٹ ایک کسٹم فنکشن (custom function) ہے۔ 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	سسٹم میں موجود صارف کی ID۔
`sessionId`	string	سسٹم میں موجود گفتگو کے سیشن کی ID۔
`referenceId`	string	بیرونی سسٹم کے ریکارڈز (CRM، آرڈر، ٹکٹ وغیرہ) سے ملانے کے لیے اختیاری حوالہ ID (زیادہ سے زیادہ 256 حروف)۔ اگر دی جائے تو بلک کے اندر منفرد ہونی چاہیے۔
`payload`	object	وصول کنندہ کے لیے مخصوص ٹیمپلیٹ پے لوڈ (اختیاری)۔ اگر `isMerge: true` ہو تو اسے `defaultPayload` کے ساتھ ضم کیا جاتا ہے۔
`isMerge`	boolean	اس وصول کنندہ کے لیے انضمام کا رویہ تبدیل کرتا ہے (اختیاری)۔ اگر نہ دیا جائے تو `defaultPayload.isMerge` استعمال ہوتا ہے۔

ایکشن کی ساخت

فیلڈ	قسم	تفصیل
`action.key`	string	`"assign-to-user"` گفتگو کو کسی مخصوص ایجنٹ کو تفویض کرتا ہے؛ `"assign-to-workgroup"` اسے ورک گروپ کو تفویض کرتا ہے۔
`action.value`	string	ہدف صارف یا ورک گروپ کی ID۔

ٹیمپلیٹ پے لوڈ کی ساخت

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 فراہم کرے تو گہرا انضمام (deep merge) لاگو ہوتا ہے۔
گہرے انضمام میں وصول کنندہ صرف variables دے سکتا ہے؛ templateName اور languageCode ڈیفالٹ پے لوڈ سے حاصل ہو جاتے ہیں۔
وصول کنندہ کا isMerge فیلڈ defaultPayload.isMerge کو اووررائیڈ کرتا ہے۔
اگر وصول کنندہ payload نہ دے تو ہمیشہ defaultPayload استعمال ہوتا ہے۔

ویری ایبلز کی ساخت

variables ارے کا ہر آئٹم ٹیمپلیٹ کے ایک جزو سے مطابقت رکھتا ہے۔ جزو کی قسم (type) ارے میں صرف ایک بار آ سکتی ہے۔

type	تفصیل	parameters	cards
`"HEADER"`	ٹیمپلیٹ ہیڈر کا جزو۔ ٹیکسٹ ویری ایبل یا میڈیا URL (تصویر، ویڈیو، دستاویز)	ہاں	—
`"BODY"`	ٹیمپلیٹ باڈی ٹیکسٹ کے ویری ایبلز	ہاں	—
`"BUTTONS"`	بٹنوں کے لیے ڈائنامک URL لاحقے کے ویری ایبلز	ہاں	—
`"CAROUSEL"`	کیروسل ٹیمپلیٹس کے کارڈ اجزا	—	ہاں

پیرامیٹر کے فارمیٹس

parameters فیلڈ تین مختلف فارمیٹس میں دیا جا سکتا ہے:

// 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" }

کون سا فارمیٹ استعمال کروں؟

اگر آپ کا Meta ٹیمپلیٹ {{1}}، {{2}} جیسے پلیس ہولڈرز استعمال کرتا ہے تو ارے فارمیٹ یا عددی کلیدوں والا آبجیکٹ فارمیٹ استعمال کریں۔
اگر آپ کا ٹیمپلیٹ {{firstName}} یا {{orderTotal}} جیسے نام والے پلیس ہولڈرز استعمال کرتا ہے تو نام والی کلیدوں کا آبجیکٹ فارمیٹ استعمال کریں۔
ارے استعمال کرتے وقت ترتیب اہم ہے: پہلا عنصر {{1}} سے، دوسرا {{2}} سے، اور اسی طرح آگے مطابقت رکھتا ہے۔

HEADER جزو

جب ٹیمپلیٹ ہیڈر میں میڈیا (تصویر، ویڈیو، دستاویز) یا ڈائنامک ٹیکسٹ ہو تو HEADER جزو استعمال کریں۔

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

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

BODY جزو

ٹیمپلیٹ باڈی کے اندر ڈائنامک ٹیکسٹ ویری ایبلز کے لیے استعمال ہوتا ہے۔

// 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"
  }
}

BUTTONS جزو

ڈائنامک URL لاحقے والے بٹنوں کے لیے استعمال ہوتا ہے۔ اگر ٹیمپلیٹ میں متعدد URL بٹن ہوں تو صرف ویری ایبلز والے بٹنوں کو ترتیب وار انڈیکس کیا جاتا ہے (ویری ایبلز کے بغیر بٹن یا FLOW بٹن نظر انداز کیے جاتے ہیں)۔

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

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	ہاں	ٹریک کیے جانے والے بلک آپریشن کی ID (`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 ہو سکتا ہے جبکہ پیغام ابھی پہنچا یا پڑھا نہ گیا ہو

ریفرنس ID

referenceId ایک اختیاری فیلڈ ہے جسے آپ ٹریکنگ کے لیے ترسیلی آئٹمز کو اپنے سسٹم کی ID (مثلاً آرڈر نمبر، ٹکٹ ID) سے ملانے کے لیے استعمال کر سکتے ہیں۔ یہ ہر آئٹم پر 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	ہاں	جس بلک آپریشن کی معلومات چاہییں اس کی ID

{
  "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) سے بھی فلٹر کر سکتے ہیں۔

// Filter by item status
{
  "options": {
    "filtering": {
      "status": "succeeded"
    }
  }
}

// Filter by referenceId
{
  "options": {
    "filtering": {
      "payload.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"]
      }
    }
  }
}

// List items that have no message (only list-with-messages)
{
  "options": {
    "filtering": {
      "message": {
        "$exists": false
      }
    }
  }
}

ترتیب کی ساخت

ترتیب MongoDB کے sort فارمیٹ میں ہوتی ہے۔ 1 کا مطلب صعودی اور -1 کا مطلب نزولی ہے۔ position درخواست کی recipients array میں وصول کنندہ کا ترتیبی نمبر ہے (0 سے شروع)۔

// Sort in the order the recipients were sent in the request
{
  "options": {
    "sorting": {
      "position": 1
    }
  }
}

// Sort by multiple fields
{
  "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 array کی ایک اندراج کی نمائندگی کرتا ہے۔

List — آئٹمز کی فہرست

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

درخواست کے پیرامیٹرز

پیرامیٹر	قسم	لازمی	تفصیل
`bulkOperationId`	string	ہاں	جس بلک آپریشن کی فہرست چاہیے اس کی ID
`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	آئٹم کی ID
`bulkOperationId`	string	اس بلک آپریشن کی ID جس سے یہ آئٹم تعلق رکھتا ہے
`position`	number	درخواست کی `recipients` array میں وصول کنندہ کا ترتیبی نمبر، `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	وصول کنندہ صارف کی ID
`result.sessionId`	string	گفتگو کے سیشن کی ID
`result.messageId`	string	بھیجے گئے پیغام کی ID (اگر کوئی پیغام نہیں بھیجا گیا تو موجود نہیں)
`completedAt`	string	آئٹم کب پراسیس ہوا
`message`	object	پیغام کی تفصیلات (صرف list-with-messages میں)
`session`	object	گفتگو کی تفصیلات (صرف list-with-messages میں)

List بمقابلہ List-With-Messages کا موازنہ

خصوصیت	list	list-with-messages
صفحہ بندی	ہاں	ہاں
فلٹرنگ	ہاں (صرف آئٹم کے فیلڈز)	ہاں (آئٹم + پیغام کے فیلڈز)
پیغام / سیشن	نہیں	ہاں (اگر موجود ہوں)
کارکردگی	تیز	درمیانی (JOIN کرتا ہے)
message.status فلٹر	دستیاب نہیں	دستیاب

استعمال کے منظرنامے

list: تمام آئٹمز کی فوری فہرست، referenceId سے فلٹر، آئٹم کی حالتیں چیک کرنا
list-with-messages: WhatsApp پیغامات کی حالتیں (delivered, read) دیکھنا، پیغام کے پے لوڈ کا معائنہ کرنا
فلٹرنگ کی مثالیں:
- {"status": "failed"} — ناکام ترسیلی آئٹمز
- {"payload.referenceId": "ORDER-123"} — مخصوص ریفرنس ID
- {"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	ہاں	روکے جانے والے بلک آپریشن کی ID

{
  "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 کے ذریعے بنائے گئے بلک آپریشنز روکے جا سکتے ہیں
ترسیل روکنے کے بعد آپ show اینڈ پوائنٹ سے منسوخ شدہ آئٹمز کی تعداد (bulkOperation.progress.cancelled) کی تصدیق کر سکتے ہیں
اگر بلک آپریشن نہ ملے تو API یہ خرابی واپس کرتی ہے: Bulk operation not found.

v1 سے منتقلی​

اینڈ پوائنٹس​

فیلڈ نام​

اہم خصوصیات​

درخواست کے پیرامیٹرز​

اعلیٰ سطح کے پیرامیٹرز​

وصول کنندہ کی ساخت​

ایکشن کی ساخت​

ٹیمپلیٹ پے لوڈ کی ساخت​

ویری ایبلز کی ساخت​

پیرامیٹر کے فارمیٹس​

HEADER جزو​

BODY جزو​

BUTTONS جزو​

CAROUSEL جزو​

مثالیں​

1. سادہ ٹیمپلیٹ — کوئی ویری ایبل نہیں، تمام وصول کنندگان کے لیے ایک جیسا مواد​

2. مشترکہ باڈی ویری ایبلز والا ٹیمپلیٹ​

3. حسبِ ضرورت ٹیمپلیٹ — isMerge کے ساتھ ہر وصول کنندہ کے ویری ایبلز​

4. URL بٹن ویری ایبل​

5. طے شدہ وقت پر ترسیل​

جواب​

خرابی کے جوابات​

Show — بلک آپریشن کی حالت اور اعداد و شمار​

درخواست کے پیرامیٹرز​

جواب​

Show کے فیلڈز​

ریفرنس ID​

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 کے فیلڈز

ریفرنس ID

Message Stats — WhatsApp پیغام کی حالت

درخواست کے پیرامیٹرز

جواب

Message Stats کے فیلڈز

Options کی ساخت — صفحہ بندی، فلٹرنگ اور ترتیب

Options کے فیلڈز

صفحہ بندی کی ساخت

فلٹرنگ کی ساخت

ترتیب کی ساخت

مشترکہ استعمال کی مثال

Items — آئٹم کی تفصیلات اور فہرست

List — آئٹمز کی فہرست

درخواست کے پیرامیٹرز

درخواست — بنیادی استعمال

درخواست — مخصوص حالت کے مطابق فلٹر

جواب

List With Messages — پیغام کی تفصیلات کے ساتھ فہرست

درخواست — بنیادی استعمال

درخواست — پیغام کی حالت کے مطابق فلٹر

درخواست — ناکام پیغامات کی فہرست

جواب

آئٹم کے فیلڈز

List بمقابلہ List-With-Messages کا موازنہ

Stop — ترسیل منسوخ کریں

درخواست کے پیرامیٹرز

جواب