Bulk Template Message 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	सिस्टम में मौजूद किसी उपयोगकर्ता की आईडी।
`sessionId`	string	सिस्टम में मौजूद किसी बातचीत सेशन की आईडी।
`referenceId`	string	बाहरी सिस्टम के रिकॉर्ड (CRM, ऑर्डर, टिकट आदि) से मिलान के लिए वैकल्पिक रेफ़रेंस आईडी (अधिकतम 256 वर्ण)। दिए जाने पर बल्क के भीतर यूनिक होनी चाहिए।
`payload`	object	प्राप्तकर्ता-विशिष्ट टेम्पलेट पेलोड (वैकल्पिक)। अगर `isMerge: true` है, तो इसे `defaultPayload` के साथ मर्ज किया जाता है।
`isMerge`	boolean	इस प्राप्तकर्ता के लिए मर्ज व्यवहार को बदलता है (वैकल्पिक)। छोड़ने पर `defaultPayload.isMerge` इस्तेमाल होता है।

Action की संरचना

फ़ील्ड	प्रकार	विवरण
`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 फ़ील्ड तीन अलग फ़ॉर्मैट में दिया जा सकता है:

// 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	हाँ	ट्रैक किए जाने वाले बल्क संदेश की आईडी (`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 आदि)
कोई जॉब सफल हो सकता है, लेकिन हो सकता है कि संदेश अभी डिलीवर या पढ़ा न गया हो

रेफ़रेंस आईडी

referenceId एक वैकल्पिक फ़ील्ड है, जिससे आप ट्रैकिंग के लिए डिलीवरी रिकॉर्ड का मिलान अपने सिस्टम की किसी आईडी (जैसे ऑर्डर नंबर, टिकट आईडी) से कर सकते हैं।

दिए जाने पर यह बल्क के भीतर यूनिक होना चाहिए (अधिकतम 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	हाँ	जिस बल्क संदेश के बारे में पूछना है उसकी आईडी

{
  "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 की गिनती से कैंपेन के एंगेजमेंट को मापा जा सकता है
रीयल-टाइम ट्रैकिंग के लिए आप इस एंडपॉइंट को समय-समय पर पोल कर सकते हैं

Options की संरचना — पेजिनेशन, फ़िल्टरिंग और सॉर्टिंग

list और list-with-messages एंडपॉइंट में इस्तेमाल होने वाला options पैरामीटर पेजिनेशन, फ़िल्टरिंग और सॉर्टिंग के लिए एक मानक संरचना देता है।

Options फ़ील्ड

फ़ील्ड	प्रकार	ज़रूरी	विवरण
`pagination`	object	नहीं	पेजिनेशन सेटिंग
`filtering`	object	नहीं	फ़िल्टरिंग मानदंड
`sorting`	object	नहीं	सॉर्टिंग सेटिंग (जैसे `{"createdAt": -1}`)

Pagination की संरचना

फ़ील्ड	प्रकार	डिफ़ॉल्ट	विवरण
`currentPage`	number	1	जो पेज नंबर पाना है
`pageItems`	number	50	प्रति पेज रिकॉर्ड की संख्या (अधिकतम: 50)

Filtering की संरचना

फ़िल्टरिंग 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"]
      }
    }
  }
}

Sorting की संरचना

सॉर्टिंग MongoDB सॉर्ट फ़ॉर्मैट में होती है। 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	हाँ	जिस बल्क संदेश की सूची चाहिए उसकी आईडी
`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	रिकॉर्ड आईडी
`bulkMessageId`	string	वह बल्क संदेश आईडी जिससे यह रिकॉर्ड जुड़ा है
`userId`	string	प्राप्तकर्ता उपयोगकर्ता आईडी
`sessionId`	string	बातचीत सेशन आईडी
`messageId`	string	भेजे गए संदेश की आईडी (अभी न भेजा गया हो तो null)
`referenceId`	string	वैकल्पिक रेफ़रेंस आईडी (अगर दी गई हो)
`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"} — कोई ख़ास रेफ़रेंस आईडी
- {"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	हाँ	जिस बल्क संदेश को रोकना है उसकी आईडी

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

मुख्य विशेषताएँ​

अनुरोध पैरामीटर​

टॉप-लेवल पैरामीटर​

प्राप्तकर्ता की संरचना​

Action की संरचना​

टेम्पलेट पेलोड की संरचना​

वेरिएबल की संरचना​

पैरामीटर के फ़ॉर्मैट​

HEADER कंपोनेंट​

BODY कंपोनेंट​

BUTTONS कंपोनेंट​

CAROUSEL कंपोनेंट​

उदाहरण​

1. सरल टेम्पलेट — कोई वेरिएबल नहीं, सभी प्राप्तकर्ताओं के लिए एक जैसी सामग्री​

2. साझा बॉडी वेरिएबल वाला टेम्पलेट​

3. वैयक्तिकृत टेम्पलेट — isMerge के साथ हर प्राप्तकर्ता के लिए अलग वेरिएबल​

4. URL बटन वेरिएबल​

5. शेड्यूल्ड डिलीवरी​

जवाब​

एरर जवाब​

Stats — डिलीवरी के आँकड़े​

अनुरोध पैरामीटर​

जवाब​

Stats फ़ील्ड​

रेफ़रेंस आईडी​

Message Stats — WhatsApp संदेश की स्थिति​

अनुरोध पैरामीटर​

जवाब​

Message Stats फ़ील्ड​

Options की संरचना — पेजिनेशन, फ़िल्टरिंग और सॉर्टिंग​

Options फ़ील्ड​

Pagination की संरचना​

Filtering की संरचना​

Sorting की संरचना​

संयुक्त उपयोग का उदाहरण​

Records — रिकॉर्ड का विवरण और सूची​

List — रिकॉर्ड सूची​

अनुरोध पैरामीटर​

अनुरोध — बुनियादी उपयोग​

अनुरोध — किसी ख़ास स्थिति से फ़िल्टर करें​

जवाब​

List With Messages — संदेश विवरण के साथ सूची​

अनुरोध — बुनियादी उपयोग​

अनुरोध — संदेश की स्थिति से फ़िल्टर करें​

अनुरोध — असफल संदेश सूचीबद्ध करें​

जवाब​

रिकॉर्ड फ़ील्ड​

List बनाम List-With-Messages की तुलना​

Stop — डिलीवरी रद्द करें​

अनुरोध पैरामीटर​

जवाब​

मुख्य विशेषताएँ

अनुरोध पैरामीटर

टॉप-लेवल पैरामीटर

प्राप्तकर्ता की संरचना

Action की संरचना

टेम्पलेट पेलोड की संरचना

वेरिएबल की संरचना

पैरामीटर के फ़ॉर्मैट

HEADER कंपोनेंट

BODY कंपोनेंट

BUTTONS कंपोनेंट

CAROUSEL कंपोनेंट

उदाहरण

1. सरल टेम्पलेट — कोई वेरिएबल नहीं, सभी प्राप्तकर्ताओं के लिए एक जैसी सामग्री

2. साझा बॉडी वेरिएबल वाला टेम्पलेट

3. वैयक्तिकृत टेम्पलेट — isMerge के साथ हर प्राप्तकर्ता के लिए अलग वेरिएबल

4. URL बटन वेरिएबल

5. शेड्यूल्ड डिलीवरी

जवाब

एरर जवाब

Stats — डिलीवरी के आँकड़े

अनुरोध पैरामीटर

जवाब

Stats फ़ील्ड

रेफ़रेंस आईडी

Message Stats — WhatsApp संदेश की स्थिति

अनुरोध पैरामीटर

जवाब

Message Stats फ़ील्ड

Options की संरचना — पेजिनेशन, फ़िल्टरिंग और सॉर्टिंग

Options फ़ील्ड

Pagination की संरचना

Filtering की संरचना

Sorting की संरचना

संयुक्त उपयोग का उदाहरण

Records — रिकॉर्ड का विवरण और सूची

List — रिकॉर्ड सूची

अनुरोध पैरामीटर

अनुरोध — बुनियादी उपयोग

अनुरोध — किसी ख़ास स्थिति से फ़िल्टर करें

जवाब

List With Messages — संदेश विवरण के साथ सूची

अनुरोध — बुनियादी उपयोग

अनुरोध — संदेश की स्थिति से फ़िल्टर करें

अनुरोध — असफल संदेश सूचीबद्ध करें

जवाब

रिकॉर्ड फ़ील्ड

List बनाम List-With-Messages की तुलना

Stop — डिलीवरी रद्द करें

अनुरोध पैरामीटर

जवाब