بلک ٹیمپلیٹ میسج API دستاویز

یہ API آپ کو WhatsApp چینل کے ذریعے بیک وقت متعدد وصول کنندگان کو ٹیمپلیٹ پیغامات بھیجنے کی سہولت دیتی ہے۔

پیغامات کی ترسیل غیر متزامن طور پر ہوتی ہے؛ API درخواست فوراً ایک bulkMessageId واپس کرتی ہے، جبکہ پیغامات قطار میں لگ کر پسِ منظر میں پراسیس ہوتے ہیں۔

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

اہم خصوصیات

• ایک ہی درخواست میں 1 سے 5,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، زیادہ سے زیادہ 5,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/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" }
  ]
}'

ٹپ

• 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 کے ساتھ، پیغام کی ترسیل سے بننے والی گفتگو خودکار طور پر مخصوص ورک گروپ کو تفویض ہو جاتی ہے

---

جواب

کامیاب درخواست ایک bulkMessageId واپس کرتی ہے، جس سے ترسیل کے عمل کو ٹریک کیا جا سکتا ہے:

{
  "bulkMessageId": "abc123xyz789"
}

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

اسٹیٹس	تفصیل
Channel not found	channelUsername اور connectorBrand سے مطابقت رکھنے والا کوئی تصدیق شدہ چینل نہیں ملا
Channel is not verified	مطابقت رکھنے والا چینل موجود ہے مگر ابھی تصدیق شدہ نہیں
invalidRequest	کسی وصول کنندہ کے لیے متعدد شناخت کنندگان دیے گئے یا مطلوبہ پے لوڈ غائب ہے
channelNotFound	فراہم کردہ channelId سے مطابقت رکھنے والا کوئی فعال چینل نہیں ملا
schema-error	درخواست کی باڈی کا کوئی فیلڈ اسکیما کی توثیق میں ناکام ہو گیا (لازمی فیلڈ غائب، غلط قسم، یا غیر معاون قدر)

واپس ملنے والی bulkMessageId کو نیچے دیے گئے اینڈ پوائنٹس کے ساتھ ترسیل کے اعداد و شمار دیکھنے اور ترسیل روکنے کے لیے استعمال کیا جا سکتا ہے۔

---

Stats — ترسیل کے اعداد و شمار

بلک پیغام کی موجودہ ترسیلی حالت حاصل کرتا ہے۔ زیرِ التوا، کامیاب، ناکام اور منسوخ ریکارڈز کی تعداد واپس کرتا ہے۔

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

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

پیرامیٹر	قسم	لازمی	تفصیل
bulkMessageId	string	ہاں	ٹریک کیے جانے والے بلک پیغام کی ID (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"
}'

جواب

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

Stats کے فیلڈز

فیلڈ	قسم	تفصیل
stats.pending	number	قطار میں انتظار کرنے والے ریکارڈز کی تعداد
stats.success	number	ترسیل کے لیے کامیابی سے پراسیس ہونے والے ریکارڈز کی تعداد
stats.failed	number	ترسیل میں خرابی کا سامنا کرنے والے ریکارڈز کی تعداد
stats.cancelled	number	منسوخ شدہ ریکارڈز کی تعداد
stats.total	number	ریکارڈز کی کل تعداد (pending + success + failed + cancelled)

نوٹ

stats.success ظاہر کرتا ہے کہ پیغام سسٹم کی جانب سے کامیابی سے آگے بھیج دیا گیا۔ یہ اس بات کی ضمانت نہیں ہے کہ Meta نے پیغام وصول کنندہ تک پہنچا دیا ہے۔ Meta کی جانب سے بعد میں آنے والی اسٹیٹس اپ ڈیٹس (جیسے delivered، read یا failed) اس کاؤنٹر پر اثر انداز نہیں ہوتیں اور یہاں ظاہر نہیں ہوتیں۔

Stats بمقابلہ Message Stats

• stats اینڈ پوائنٹ: ترسیلی جاب کی حالت دکھاتا ہے (pending, success, failed, cancelled)
• message-stats اینڈ پوائنٹ: پیغام کی اصل حالت دکھاتا ہے (pending, sending, sent, delivered, read, error وغیرہ)
• ممکن ہے جاب کامیاب ہو، مگر پیغام ابھی تک ڈیلیور یا پڑھا نہ گیا ہو

---

ریفرنس ID

referenceId ایک اختیاری فیلڈ ہے جسے آپ ٹریکنگ کے لیے ترسیلی ریکارڈز کو اپنے سسٹم کی ID (مثلاً آرڈر نمبر، ٹکٹ ID) سے ملانے کے لیے استعمال کر سکتے ہیں۔

اگر دی جائے تو بلک کے اندر منفرد ہونی چاہیے (زیادہ سے زیادہ 256 حروف)۔

اہم

• استعمال کے لیے لازمی نہیں
• ایک ہی بلک پیغام میں دہرائی نہیں جا سکتی
• مختلف بلک پیغامات میں دوبارہ استعمال کی جا سکتی ہے

---

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

بلک پیغام کے پیغامات کی حالت کے اعداد و شمار حاصل کرتا ہے۔ stats اینڈ پوائنٹ کے برعکس، یہ جاب کی حالت کے بجائے ہر ریکارڈ کا اصل 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/bulk-message/message-stats.js

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

پیرامیٹر	قسم	لازمی	تفصیل
bulkMessageId	string	ہاں	جس بلک پیغام کی معلومات درکار ہوں اس کی ID

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

جواب

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

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	ریکارڈز کی کل تعداد

استعمال کے مشورے

• no-message کی زیادہ تعداد ظاہر کرتی ہے کہ ترسیل ابھی جاری ہے
• delivered کی تعداد پیغام کی کامیاب ترسیل ظاہر کرتی ہے
• read کی تعداد سے مہم کی مشغولیت (engagement) ناپی جا سکتی ہے
• حقیقی وقت میں ٹریکنگ کے لیے آپ اس اینڈ پوائنٹ کو وقفے وقفے سے پول کر سکتے ہیں

---

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

list اور list-with-messages اینڈ پوائنٹس میں استعمال ہونے والا options پیرامیٹر صفحہ بندی، فلٹرنگ اور ترتیب کے لیے ایک معیاری ساخت فراہم کرتا ہے۔

Options کے فیلڈز

فیلڈ	قسم	لازمی	تفصیل
pagination	object	نہیں	صفحہ بندی کی ترتیبات
filtering	object	نہیں	فلٹر کے معیارات
sorting	object	نہیں	ترتیب کی سیٹنگز (مثلاً {"createdAt": -1})

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

فیلڈ	قسم	ڈیفالٹ	تفصیل
currentPage	number	1	حاصل کیے جانے والے صفحے کا نمبر
pageItems	number	50	فی صفحہ ریکارڈز کی تعداد (زیادہ سے زیادہ: 50)

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

فلٹرنگ MongoDB کوئری فارمیٹ میں کی جاتی ہے۔ آپ ریکارڈ کے فیلڈز کے مطابق فلٹر کر سکتے ہیں۔ list-with-messages اینڈ پوائنٹ میں آپ پیغام کے فیلڈز (مثلاً 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"]
      }
    }
  }
}

ترتیب کی ساخت

ترتیب MongoDB sort فارمیٹ میں کی جاتی ہے۔ 1 کا مطلب بڑھتی ترتیب اور -1 کا مطلب گھٹتی ترتیب ہے۔

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

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

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

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

یہ مثال ڈیلیور شدہ پیغامات کو نئے سے پرانے کی ترتیب میں رکھتی ہے۔

عملی مشورے

• ہدف شدہ کوئریز کے لیے filtering اور pagination کو ملا کر استعمال کریں
• جواب میں نیویگیشن کے لیے options.pagination.totalCount اور options.pagination.totalPages شامل ہوتے ہیں
• message.status فلٹر صرف list-with-messages اینڈ پوائنٹ میں کام کرتا ہے

---

Records — ریکارڈ کی تفصیلات اور فہرست

بلک پیغام کے تمام ترسیلی ریکارڈز کی فہرست دیتا ہے۔ ہر ریکارڈ وصول کنندہ کو بھیجے گئے ایک پیغام کی نمائندگی کرتا ہے۔

List — ریکارڈ کی فہرست

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

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

پیرامیٹر	قسم	لازمی	تفصیل
bulkMessageId	string	ہاں	جس بلک پیغام کی فہرست درکار ہو اس کی ID
options	object	نہیں	صفحہ بندی، فلٹرنگ اور ترتیب کے اختیارات۔ تفصیل کے لیے Options کی ساخت دیکھیں۔

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

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

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

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

صرف کامیاب ترسیلی ریکارڈز کی فہرست دیتا ہے (record.status = "success")۔

جواب

{
  "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 — پیغام کی تفصیلات کے ساتھ فہرست

اس میں list اینڈ پوائنٹ جیسی ہی خصوصیات ہیں (صفحہ بندی، فلٹرنگ، ترتیب)۔ واحد فرق: اگر کسی ریکارڈ میں messageId ہو تو متعلقہ message آبجیکٹ بھی واپس کیا جاتا ہے۔ اس سے آپ پیغام کی حالت (delivered, read, error وغیرہ) اور پے لوڈ ایک ہی کوئری میں دیکھ سکتے ہیں۔

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

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

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

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

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

یہ مثال صرف "delivered" حالت والے پیغامات حاصل کرتی ہے۔

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

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

ان پیغامات کا جائزہ لینے کے لیے جنہیں ترسیل میں خرابی کا سامنا ہوا۔

جواب

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

ریکارڈ کے فیلڈز

فیلڈ	قسم	تفصیل
_id	string	ریکارڈ ID
bulkMessageId	string	وہ بلک پیغام ID جس سے یہ ریکارڈ تعلق رکھتا ہے
userId	string	وصول کنندہ صارف کی ID
sessionId	string	گفتگو کے سیشن کی ID
messageId	string	بھیجے گئے پیغام کی ID (اگر ابھی نہیں بھیجا گیا تو null)
referenceId	string	اختیاری حوالہ ID (اگر دی گئی ہو)
status	string	ریکارڈ کی حالت: pending, success, failed, cancelled
message	object	پیغام کی تفصیلات (صرف list-with-messages میں)

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

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

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

• list: تمام ریکارڈز کی فوری فہرست، referenceId سے فلٹر، ریکارڈ کی حالتیں چیک کرنا
• list-with-messages: WhatsApp پیغامات کی حالتیں (delivered, read) دیکھنا، پیغام کے پے لوڈ کا معائنہ کرنا
• فلٹرنگ کی مثالیں:
  • {"status": "failed"} — ناکام ترسیلی ریکارڈز
  • {"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)
  • {"status": {"$in": ["success", "pending"]}} — کامیاب یا زیرِ التوا ریکارڈز

کارکردگی اور استعمال کے نوٹس

• list اینڈ پوائنٹ زیادہ تیز ہے؛ عمومی حالت کی جانچ کے لیے اسے ترجیح دیں
• جب پیغام کی تفصیلات درکار ہوں تو list-with-messages استعمال کریں
• فی صفحہ زیادہ سے زیادہ ریکارڈز (pageItems) 50 ہیں؛ اگر متعین نہ ہوں تو ڈیفالٹ 50 ہے
• message.status فلٹر صرف list-with-messages میں کام کرتا ہے
• جن ریکارڈز کا messageId null ہو ان کے message آبجیکٹ بھی null ہوں گے

---

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

جاری بلک پیغام کی ترسیل روک دیتا ہے۔ قطار میں لگی جاب منسوخ ہو جاتی ہے، اور تمام pending ریکارڈز cancelled حالت میں منتقل ہو جاتے ہیں۔ جو ریکارڈز پہلے ہی success یا failed کے طور پر پراسیس ہو چکے ہیں ان پر کوئی اثر نہیں پڑتا۔

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

انتباہ

یہ عمل واپس نہیں ہو سکتا۔ روکی گئی ترسیل دوبارہ شروع نہیں کی جا سکتی۔

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

پیرامیٹر	قسم	لازمی	تفصیل
bulkMessageId	string	ہاں	روکے جانے والے بلک پیغام کی ID

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

جواب

کامیاب درخواست کی صورت میں جواب کی باڈی خالی ہوتی ہے۔ HTTP 200 اسٹیٹس ظاہر کرتا ہے کہ عمل کامیابی سے مکمل ہو گیا۔

{}

ٹپ

• صرف اسی API کے ذریعے بنائے گئے بلک پیغامات کو روکا جا سکتا ہے
• ترسیل روکنے کے بعد آپ stats اینڈ پوائنٹ سے منسوخ ریکارڈز کی تعداد کی تصدیق کر سکتے ہیں
• اگر بلک پیغام نہ ملے تو API یہ خرابی واپس کرتی ہے: bulkMessageNotFound