د 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 چې پر ټولو ترلاسه کوونکو پلي کیږي. اړین دی که یو ترلاسه کوونکی خپل `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	اختیاري حواله ID (تر 256 حروفو) د بهرني سیستم ریکارډونو (CRM، فرمایش، ټیکټ او نور) سره د سمون لپاره. که ورکړل شي، باید په ډله‌ییز پیغام کې ځانګړی وي.
`payload`	object	د ترلاسه کوونکي ځانګړی د ټیمپلېټ payload (اختیاري). که `isMerge: true` وي، له `defaultPayload` سره یوځای کیږي.
`isMerge`	boolean	د دې ترلاسه کوونکي لپاره د یوځای کولو چلند بدلوي (اختیاري). که ونه لیکل شي، `defaultPayload.isMerge` کارول کیږي.

د عمل جوړښت

ساحه	ډول	توضیح
`action.key`	string	`"assign-to-user"` خبرې اترې یو ټاکلي اجنټ ته سپاري؛ `"assign-to-workgroup"` یې یوې کاري ډلې ته سپاري.
`action.value`	string	د هدف کارن یا کاري ډلې ID.

د ټیمپلېټ payload جوړښت

defaultPayload او د ترلاسه کوونکي ځانګړی payload ورته جوړښت لري. د ټیمپلېټ پیغامونو لپاره باید type: "template" وټاکل شي.

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

ساحه	ډول	اړین	توضیح
`type`	string	هو	د payload ډول. د ټیمپلېټ پیغامونو لپاره: `"template"`
`template.templateName`	string	هو*	په Meta کې ثبت شوی د ټیمپلېټ نوم. د ترلاسه کوونکي په payload کې اختیاري دی کله چې `isMerge: true` وکارول شي (له ډیفالټ څخه میراث کیږي).
`template.languageCode`	string	نه	د ټیمپلېټ د ژبې کوډ (د بیلګې په توګه `"tr"`، `"en"`، `"tr-TR"`، `"en-US"`). باید په Meta کې د ثبت شوې ژبې سره دقیقاً سمون ولري.
`template.variables`	array	نه	د متغیرونو لیست چې پر ټیمپلېټ برخو پلي کیږي. لاندې په تفصیل سره.
`isMerge`	boolean	نه	`true`: د ترلاسه کوونکي payload له `defaultPayload` سره ژور یوځای کیږي. `false` یا نه لیکل شوی: د ترلاسه کوونکي payload `defaultPayload` په بشپړه توګه بدلوي.

د isMerge چلند

که defaultPayload.isMerge: true وي او ترلاسه کوونکی خپل payload ورکړي، ژور یوځای کول پلي کیږي.
په ژور یوځای کولو کې، ترلاسه کوونکی کولی شي یوازې variables ورکړي؛ templateName او languageCode له ډیفالټ payload څخه میراث کیږي.
د ترلاسه کوونکي 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 له ډیفالټ payload څخه میراث کیږي.

په دې بیلګه کې، ټیمپلېټ دواړه د رسنۍ سرلیک او شخصي شوي متن متغیرونه لري.

{
  "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 اړتیا نلري چې د هر ترلاسه کوونکي په payload کې تکرار شي
د هر ترلاسه کوونکي variables لړۍ بشپړه خپلواکه ده
د سرلیک د رسنۍ URL باید عامه رسېدونکی وي
که د ترلاسه کوونکي په payload کې 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`	د یو ترلاسه کوونکي لپاره څو پیژندونکي ورکړل شوي یا یو اړین payload نشته
`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 شمېر د کمپاین د ګډون د اندازه کولو لپاره کارول کیدی شي
تاسو کولی شئ دا اینډپوینټ په منظمو وختونو پوښتل څو په ریښتینې وخت کې تعقیب شي

د Options جوړښت — پاڼه‌بندي، فلټر کول او ترتیب

د options پارامېټر چې د list او list-with-messages اینډپوینټونو کې کارول کیږي، د پاڼه‌بندۍ، فلټر کولو او ترتیب لپاره یو معیاري جوړښت وړاندې کوي.

د 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 د ترتیب بڼې په کارولو سره کیږي. 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 او نور) او payload په یوې پوښتنې کې وګورئ.

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
پاڼه‌بندي	هو	هو
فلټر کول	هو (یوازې د ریکارډ ساحې)	هو (د ریکارډ + پیغام ساحې)
د پیغام اوبجیکټ	نه	هو (که messageId شته وي)
فعالیت	چټک	منځنی (JOIN ترسره کوي)
د message.status فلټر	شته نه دی	شته دی

د کارونې سناریوګانې

list: ټول ریکارډونه په چټکۍ لیست کړئ، د referenceId له مخې فلټر کړئ، د ریکارډ حالتونه وګورئ
list-with-messages: د WhatsApp د پیغام حالتونه (delivered، read) وګورئ، د پیغام payload وڅېړئ
د فلټر کولو بیلګې:
- {"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 وي، null message اوبجیکټونه به ولري

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

مهمې ځانګړتیاوې​

د غوښتنې پارامېټرونه​

پورتنۍ کچې پارامېټرونه​

د ترلاسه کوونکي جوړښت​

د عمل جوړښت​

د ټیمپلېټ payload جوړښت​

د متغیرونو جوړښت​

د پارامېټرونو بڼې​

د HEADER برخه​

د BODY برخه​

د BUTTONS برخه​

د CAROUSEL برخه​

بیلګې​

1. ساده ټیمپلېټ — پرته له متغیرونو، د ټولو ترلاسه کوونکو لپاره ورته منځپانګه​

2. ټیمپلېټ د ګډو متن متغیرونو سره​

3. شخصي شوی ټیمپلېټ — د هر ترلاسه کوونکي متغیرونه د isMerge سره​

4. د URL تڼۍ متغیر​

5. مهالویش شوی رسول​

ځواب​

د تېروتنې ځوابونه​

Stats — د رسولو احصایې​

د غوښتنې پارامېټرونه​

ځواب​

د Stats ساحې​

حواله ID​

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

د غوښتنې پارامېټرونه​

ځواب​

د Message Stats ساحې​

د Options جوړښت — پاڼه‌بندي، فلټر کول او ترتیب​

د Options ساحې​

د پاڼه‌بندۍ جوړښت​

د فلټر کولو جوړښت​

د ترتیب جوړښت​

د ګډ کارونې بیلګه​

Records — د ریکارډ توضیحات او لیست​

List — د ریکارډونو لیست​

د غوښتنې پارامېټرونه​

غوښتنه — بنسټیزه کارونه​

غوښتنه — د ځانګړي حالت له مخې فلټر​

ځواب​

List With Messages — د پیغام توضیحاتو سره لیست​

غوښتنه — بنسټیزه کارونه​

غوښتنه — د پیغام د حالت له مخې فلټر​

غوښتنه — ناکام پیغامونه لیست کړئ​

ځواب​

د ریکارډ ساحې​

د List او List-With-Messages پرتله​

Stop — رسول لغوه کړئ​

د غوښتنې پارامېټرونه​

ځواب​

مهمې ځانګړتیاوې

د غوښتنې پارامېټرونه

پورتنۍ کچې پارامېټرونه

د ترلاسه کوونکي جوړښت

د عمل جوړښت

د ټیمپلېټ payload جوړښت

د متغیرونو جوړښت

د پارامېټرونو بڼې

د HEADER برخه

د BODY برخه

د BUTTONS برخه

د CAROUSEL برخه

بیلګې

1. ساده ټیمپلېټ — پرته له متغیرونو، د ټولو ترلاسه کوونکو لپاره ورته منځپانګه

2. ټیمپلېټ د ګډو متن متغیرونو سره

3. شخصي شوی ټیمپلېټ — د هر ترلاسه کوونکي متغیرونه د isMerge سره

4. د URL تڼۍ متغیر

5. مهالویش شوی رسول

ځواب

د تېروتنې ځوابونه

Stats — د رسولو احصایې

د غوښتنې پارامېټرونه

ځواب

د Stats ساحې

حواله ID

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

د غوښتنې پارامېټرونه

ځواب

د Message Stats ساحې

د Options جوړښت — پاڼه‌بندي، فلټر کول او ترتیب

د Options ساحې

د پاڼه‌بندۍ جوړښت

د فلټر کولو جوړښت

د ترتیب جوړښت

د ګډ کارونې بیلګه

Records — د ریکارډ توضیحات او لیست

List — د ریکارډونو لیست

د غوښتنې پارامېټرونه

غوښتنه — بنسټیزه کارونه

غوښتنه — د ځانګړي حالت له مخې فلټر

ځواب

List With Messages — د پیغام توضیحاتو سره لیست

غوښتنه — بنسټیزه کارونه

غوښتنه — د پیغام د حالت له مخې فلټر

غوښتنه — ناکام پیغامونه لیست کړئ

ځواب

د ریکارډ ساحې

د List او List-With-Messages پرتله

Stop — رسول لغوه کړئ

د غوښتنې پارامېټرونه

ځواب