Treceți la conținutul principal

Documentația Bulk Template Message API

Acest API vă permite să trimiteți mesaje șablon către mai mulți destinatari simultan, prin canalul WhatsApp.

Livrarea mesajelor este procesată asincron; cererea API returnează imediat un bulkMessageId, iar mesajele sunt puse în coadă și procesate în fundal.

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

Funcționalități principale​

  • Trimiteți mesaje șablon în masă către 1–5.000 de destinatari într-o singură cerere
  • Variabile personalizate pentru fiecare destinatar (HEADER, BODY, BUTTONS, CAROUSEL)
  • defaultPayload comun pentru toți destinatarii, cu îmbinarea payload-ului specific fiecărui destinatar (isMerge)
  • Livrare programată (scheduleAt)
  • Indicați destinatarii prin username (număr de telefon), userId sau sessionId
  • Trimiteți mai multe mesaje aceluiași utilizator în cadrul unei singure cereri în masă
  • referenceId opțional pentru urmărirea înregistrărilor în sisteme externe
  • Atribuiți automat conversațiile unui utilizator sau unui grup de lucru după trimitere (action)
avertisment

Acest API poate trimite doar șabloane aprobate de Meta.

Numele șablonului și codul de limbă trebuie să corespundă exact șablonului înregistrat în Meta Business Manager.

Parametrii cererii​

Parametri de nivel superior​

ParametruTipObligatoriuDescriere
channelUsernamestringDaNumărul canalului WhatsApp folosit pentru trimiterea mesajului (de exemplu "908506669933")
connectorBrandstringDaBrandul conectorului de canal. Valoare acceptată în prezent: "whatsapp"
titlestringNuTitlul campaniei. Folosit pentru afișare în dashboard. Implicit: "-"
scheduleAtstring (ISO 8601)NuData și ora livrării programate (de exemplu "2026-06-10T10:00:00.000Z"). Dacă este omis, mesajele se trimit imediat.
defaultPayloadobjectCondiționat*Payload-ul implicit al șablonului, aplicat tuturor destinatarilor. Obligatoriu dacă un destinatar nu furnizează propriul payload.
recipientsarrayDaLista destinatarilor. Minimum 1, maximum 5.000 de destinatari.
actionobjectNuAcțiune aplicată conversației după trimitere. assign-to-user sau assign-to-workgroup.

*Dacă fiecare destinatar furnizează propriul payload, defaultPayload este opțional.

Structura destinatarului​

Pentru fiecare destinatar trebuie furnizat exact unul dintre username, userId sau sessionId. Mai mulți identificatori nu pot fi folosiți împreună, iar omiterea tuturor duce la o eroare.

Pentru a trimite mai multe mesaje aceluiași utilizator într-o singură cerere în masă, adăugați același identificator în lista de destinatari de mai multe ori.

CâmpTipDescriere
usernamestringNumărul de telefon al destinatarului (de exemplu "905554443322"). Dacă utilizatorul nu există în sistem, este creat automat.
userIdstringID-ul unui utilizator existent în sistem.
sessionIdstringID-ul unei sesiuni de conversație existente în sistem.
referenceIdstringID de referință opțional (maximum 256 de caractere) pentru asocierea cu înregistrările din sisteme externe (CRM, comandă, tichet etc.). Dacă este furnizat, trebuie să fie unic în cadrul mesajului în masă.
payloadobjectPayload-ul șablonului specific destinatarului (opțional). Dacă isMerge: true, este îmbinat cu defaultPayload.
isMergebooleanSuprascrie comportamentul de îmbinare pentru acest destinatar (opțional). Dacă este omis, se folosește defaultPayload.isMerge.

Structura acțiunii​

CâmpTipDescriere
action.keystring"assign-to-user" atribuie conversația unui anumit agent; "assign-to-workgroup" o atribuie unui grup de lucru.
action.valuestringID-ul utilizatorului sau al grupului de lucru țintă.

Structura payload-ului șablonului​

defaultPayload și payload-ul specific destinatarului au aceeași structură. Pentru mesajele șablon trebuie indicat type: "template".

{
  "type": "template",
  "template": {
    "templateName": "order_confirmation",
    "languageCode": "tr-TR",
    "variables": []
  },
  "isMerge": true
}
CâmpTipObligatoriuDescriere
typestringDaTipul payload-ului. Pentru mesaje șablon: "template"
template.templateNamestringDa*Numele șablonului înregistrat în Meta. Opțional în payload-urile destinatarilor când se folosește isMerge: true (se moștenește din cel implicit).
template.languageCodestringNuCodul de limbă al șablonului (de exemplu "tr", "en", "tr-TR", "en-US"). Trebuie să corespundă exact limbii înregistrate în Meta.
template.variablesarrayNuLista variabilelor aplicate componentelor șablonului. Detalii mai jos.
isMergebooleanNutrue: payload-ul destinatarului este îmbinat în profunzime cu defaultPayload. false sau omis: payload-ul destinatarului înlocuiește complet defaultPayload.
Comportamentul isMerge
  • Dacă defaultPayload.isMerge: true și destinatarul furnizează propriul payload, se aplică o îmbinare în profunzime.
  • Cu îmbinarea în profunzime, destinatarul poate furniza doar variables; templateName și languageCode sunt moștenite din payload-ul implicit.
  • Câmpul isMerge al destinatarului îl suprascrie pe defaultPayload.isMerge.
  • Dacă un destinatar nu furnizează un payload, se folosește întotdeauna defaultPayload.

Structura variabilelor​

Fiecare element din array-ul variables corespunde unei componente a șablonului. Un tip de componentă (type) poate apărea o singură dată în array.

typeDescriereparameterscards
"HEADER"Componenta de antet a șablonului. Variabilă de text sau URL media (imagine, videoclip, document)Da—
"BODY"Variabilele de text din corpul șablonuluiDa—
"BUTTONS"Variabile pentru sufixul URL dinamic al butoanelorDa—
"CAROUSEL"Componentele cardurilor pentru șabloanele de tip carusel—Da

Formate pentru parametri​

Câmpul parameters poate fi furnizat în trei formate diferite:

// Formatul 1: array (pe bază de index) — pentru substituenți precum {{1}}, {{2}}, {{3}}
"parameters": ["value1", "value2", "value3"]

// Formatul 2: obiect (chei numerice) — reprezentare alternativă pentru {{1}}, {{2}}
"parameters": { "1": "value1", "2": "value2" }

// Formatul 3: obiect (chei denumite) — pentru substituenți precum {{name}}, {{amount}}
"parameters": { "name": "John", "amount": "150 USD" }
Ce format ar trebui să folosesc?
  • Dacă șablonul dvs. Meta folosește substituenți precum {{1}}, {{2}}, folosiți fie formatul array, fie formatul obiect cu chei numerice.
  • Dacă șablonul dvs. folosește substituenți cu nume, precum {{firstName}} sau {{orderTotal}}, folosiți formatul obiect cu chei denumite.
  • Când folosiți array-uri, ordinea contează: primul element corespunde lui {{1}}, al doilea lui {{2}} și așa mai departe.

Componenta HEADER​

Folosiți componenta HEADER când antetul șablonului conține media (imagine, videoclip, document) sau text dinamic.

// Antet media (URL de imagine)
{
  "type": "HEADER",
  "parameters": ["https://example.com/product-image.jpg"]
}

// Variabilă de text în antet
{
  "type": "HEADER",
  "parameters": ["Special Campaign"]
}

Componenta BODY​

Se folosește pentru variabilele de text dinamic din corpul șablonului.

// Format array — când șablonul folosește {{1}}, {{2}}, {{3}}
{
  "type": "BODY",
  "parameters": ["John", "ORD-12345", "150.00 USD"]
}

// Format cu nume — când șablonul folosește {{name}}, {{orderAmount}}
{
  "type": "BODY",
  "parameters": {
    "name": "John",
    "orderAmount": "150.00 USD"
  }
}

Componenta BUTTONS​

Se folosește pentru butoanele cu sufixe URL dinamice. Dacă șablonul conține mai multe butoane URL, doar butoanele cu variabile sunt indexate secvențial (butoanele fără variabile sau butoanele FLOW sunt ignorate).

// Variabilă pentru sufixul unui singur buton URL
{
  "type": "BUTTONS",
  "parameters": ["tracking/ORD-12345"]
}

// Variabile pentru sufixele mai multor butoane URL (primul buton URL, al doilea buton URL)
{
  "type": "BUTTONS",
  "parameters": ["tracking/ORD-12345", "cancel/ORD-12345"]
}

Pentru șabloanele de tip carusel, variabilele componentelor se definesc separat pentru fiecare card.

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

Lungimea array-ului cards trebuie să corespundă exact numărului de carduri definite în șablon.

Exemple​

1. Șablon simplu — fără variabile, același conținut pentru toți destinatarii​

Aceasta este cea mai simplă modalitate de a trimite un șablon static, fără variabile, către mai mulți destinatari.

{
  "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" }
  ]
}'
sfat
  • Destinatarii indicați prin username sunt creați automat dacă nu există încă în sistem
  • Toți destinatarii folosesc același defaultPayload; nu sunt necesare date specifice destinatarului
  • Când isMerge nu este specificat, fiecare destinatar folosește direct defaultPayload

2. Șablon cu variabile de corp comune​

Același șablon este trimis tuturor destinatarilor, cu aceleași valori ale variabilelor. Șablonul conține substituenți precum {{1}} și {{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" }]
}
sfat
  • În acest exemplu, corpul șablonului ar putea conține un text de genul: „Beneficiați de o reducere de {{1}} în campania noastră! Ofertă valabilă până la {{2}}.”
  • parameters[0] înlocuiește {{1}}, iar parameters[1] înlocuiește {{2}}

3. Șablon personalizat — variabile pentru fiecare destinatar, cu isMerge​

Pentru fiecare destinatar se folosesc valori diferite ale variabilelor. Dacă setați isMerge: true în defaultPayload, destinatarii trebuie să furnizeze doar variables; templateName și languageCode sunt moștenite din payload-ul implicit.

În acest exemplu, șablonul include atât un antet media, cât și variabile de corp personalizate.

{
  "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"]
            }
          ]
        }
      }
    }
  ]
}
sfat
  • Datorită isMerge: true, templateName nu trebuie repetat în payload-ul fiecărui destinatar
  • Array-ul variables al fiecărui destinatar este complet independent
  • URL-ul media din antet trebuie să fie accesibil public
  • Dacă type este omis în payload-ul destinatarului, se moștenește defaultPayload.type

4. Variabilă pentru butonul URL​

Folosiți componenta BUTTONS când șablonul conține un buton cu sufix URL dinamic. De exemplu, un număr de urmărire adăugat la URL-ul de bază 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"]
            }
          ]
        }
      }
    }
  ]
}
sfat
  • Parametrii BUTTONS sunt asociați în ordinea butoanelor care conțin variabile
  • Butoanele FLOW și butoanele fără variabile sunt ignorate; indexarea se aplică doar butoanelor URL dinamice
  • Dacă URL-ul butonului din șablon este https://example.com/track/{{1}}, atunci parameters[0] înlocuiește {{1}}

5. Livrare programată​

Programați trimiterea unui mesaj la o dată și o oră viitoare. scheduleAt trebuie furnizat ca timestamp UTC în format ISO 8601.

{
  "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" }
            }
          ]
        }
      }
    }
  ]
}
sfat
  • scheduleAt trebuie furnizat în fusul orar UTC (de exemplu, pentru ora 10:00 AM a Turciei, folosiți 07:00:00.000Z)
  • Acest exemplu folosește formatul cu parametri denumiți; șablonul trebuie să conțină substituenți precum {{name}} și {{discountRate}}
  • Cu action, conversațiile create prin livrarea mesajului sunt atribuite automat grupului de lucru indicat

Răspuns​

O cerere reușită returnează un bulkMessageId, care poate fi folosit pentru a urmări procesul de livrare:

{
  "bulkMessageId": "abc123xyz789"
}

Răspunsuri de eroare​

StareDescriere
Channel not foundNu a fost găsit niciun canal verificat care să corespundă channelUsername și connectorBrand
Channel is not verifiedCanalul găsit există, dar nu a fost încă verificat
invalidRequestAu fost furnizați mai mulți identificatori pentru un destinatar sau lipsește un payload obligatoriu
channelNotFoundNu a fost găsit niciun canal activ care să corespundă channelId furnizat
schema-errorUn câmp din corpul cererii nu a trecut validarea schemei (câmp obligatoriu lipsă, tip incorect sau valoare neacceptată)

bulkMessageId-ul returnat poate fi folosit cu endpoint-urile de mai jos pentru a interoga statisticile de livrare și pentru a opri procesul de livrare.

Stats — statistici de livrare​

Returnează starea curentă a livrării unui mesaj în masă. Oferă numărul de înregistrări în așteptare, reușite, eșuate și anulate.

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

Parametrii cererii​

ParametruTipObligatoriuDescriere
bulkMessageIdstringDaID-ul mesajului în masă de urmărit (returnat de 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"
}'

Răspuns​

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

Câmpurile Stats​

CâmpTipDescriere
stats.pendingnumberNumărul de înregistrări aflate încă în coadă
stats.successnumberNumărul de înregistrări procesate cu succes pentru livrare
stats.failednumberNumărul de înregistrări care au întâmpinat o eroare de livrare
stats.cancellednumberNumărul de înregistrări anulate
stats.totalnumberNumărul total de înregistrări (pending + success + failed + cancelled)
notă

stats.success indică faptul că mesajul a fost predat cu succes de sistem. Nu garantează că Meta a livrat mesajul destinatarului. Actualizările de stare ulterioare generate de Meta (precum delivered, read sau failed) nu afectează acest contor și nu sunt reflectate aici.

Stats față de Message Stats
  • endpoint-ul stats: arată starea job-ului de livrare (pending, success, failed, cancelled)
  • endpoint-ul message-stats: arată starea reală a mesajului (pending, sending, sent, delivered, read, error etc.)
  • Un job poate fi reușit, dar mesajul poate să nu fie încă livrat sau citit

ID de referință​

referenceId este un câmp opțional pe care îl puteți folosi pentru a asocia înregistrările de livrare cu un ID din propriul sistem, în scopuri de urmărire (de exemplu, numărul comenzii sau ID-ul tichetului).

Dacă este furnizat, trebuie să fie unic în cadrul mesajului în masă (maximum 256 de caractere).

Important
  • Nu este obligatoriu
  • Nu poate fi duplicat în cadrul aceluiași mesaj în masă
  • Poate fi refolosit în mesaje în masă diferite

Message Stats — starea mesajelor WhatsApp​

Returnează statisticile de stare a mesajelor pentru un mesaj în masă. Spre deosebire de endpoint-ul stats, acesta arată message.status real pentru fiecare înregistrare, în loc de starea job-ului.

Stări posibile ale mesajului: 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

Parametrii cererii​

ParametruTipObligatoriuDescriere
bulkMessageIdstringDaID-ul mesajului în masă de interogat
{
  "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"
}'

Răspuns​

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

Câmpurile Message Stats​

CâmpTipDescriere
pendingnumberMesaje netrimise încă
sendingnumberMesaje în curs de trimitere
sentnumberMesaje predate către WhatsApp, încă nelivrate
deliverednumberMesaje livrate pe telefonul destinatarului
readnumberMesaje citite de destinatar
deletednumberMesaje șterse
warningnumberMesaje cu avertismente
errornumberMesaje cu erori
unknownnumberMesaje cu stare necunoscută
not-sendednumberMesaje care nu au putut fi trimise
no-messagenumberÎnregistrări fără mesaj încă (în coadă)
totalnumberNumărul total de înregistrări
Sfaturi de utilizare
  • Un număr mare de no-message indică faptul că livrarea este încă în curs
  • Numărul delivered arată câte mesaje au fost livrate cu succes
  • Numărul read poate fi folosit pentru a măsura implicarea în campanie
  • Puteți interoga periodic acest endpoint pentru urmărire în timp real

Structura options — paginare, filtrare și sortare​

Parametrul options folosit în endpoint-urile list și list-with-messages oferă o structură standard pentru paginare, filtrare și sortare.

Câmpurile options​

CâmpTipObligatoriuDescriere
paginationobjectNuSetări de paginare
filteringobjectNuCriterii de filtrare
sortingobjectNuSetări de sortare (de exemplu {"createdAt": -1})

Structura paginării​

CâmpTipImplicitDescriere
currentPagenumber1Numărul paginii de preluat
pageItemsnumber50Numărul de înregistrări pe pagină (maximum: 50)

Structura filtrării​

Filtrarea se face în formatul de interogare MongoDB. Puteți filtra după câmpurile înregistrării. În endpoint-ul list-with-messages puteți filtra și după câmpurile mesajului (de exemplu, message.status).

// Filtrare după starea înregistrării
{
  "options": {
    "filtering": {
      "status": "success"
    }
  }
}

// Filtrare după referenceId
{
  "options": {
    "filtering": {
      "referenceId": "ORDER-12345"
    }
  }
}

// Filtrare după starea mesajului (doar list-with-messages)
{
  "options": {
    "filtering": {
      "message.status": "delivered"
    }
  }
}

// Filtrare după mai multe stări cu $in (operator MongoDB)
{
  "options": {
    "filtering": {
      "message.status": {
        "$in": ["delivered", "read"]
      }
    }
  }
}

// Excluderea unor stări cu $nin (operator MongoDB)
{
  "options": {
    "filtering": {
      "message.status": {
        "$nin": ["error", "not-sended"]
      }
    }
  }
}

Structura sortării​

Sortarea se face în formatul de sortare MongoDB. 1 înseamnă crescător, -1 înseamnă descrescător.

// Sortare după data creării, descrescător (cele mai noi primele)
{
  "options": {
    "sorting": {
      "createdAt": -1
    }
  }
}

// Sortare după mai multe câmpuri
{
  "options": {
    "sorting": {
      "status": 1,
      "createdAt": -1
    }
  }
}

Exemplu de utilizare combinată​

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

Acest exemplu sortează mesajele livrate de la cele mai noi la cele mai vechi.

Sfaturi practice
  • Combinați filtering și pagination pentru interogări țintite
  • Răspunsul include options.pagination.totalCount și options.pagination.totalPages pentru navigare
  • Filtrul message.status funcționează doar în endpoint-ul list-with-messages

Records — detalii și listarea înregistrărilor​

Listează toate înregistrările de livrare ale unui mesaj în masă. Fiecare înregistrare reprezintă un singur mesaj trimis unui destinatar.

List — lista înregistrărilor​

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

Parametrii cererii​

ParametruTipObligatoriuDescriere
bulkMessageIdstringDaID-ul mesajului în masă de listat
optionsobjectNuOpțiuni de paginare, filtrare și sortare. Consultați Structura options pentru detalii.

Cerere — utilizare de bază​

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

Cerere — filtrare după o anumită stare​

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

Listează doar înregistrările de livrare reușite (record.status = "success").

Răspuns​

{
  "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 — listare cu detaliile mesajelor​

Are aceleași funcționalități ca endpoint-ul list (paginare, filtrare, sortare). Singura diferență: dacă o înregistrare are un messageId, este returnat și obiectul message asociat. Astfel puteți vedea starea mesajului (delivered, read, error etc.) și payload-ul într-o singură interogare.

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

Cerere — utilizare de bază​

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

Cerere — filtrare după starea mesajului​

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

Acest exemplu preia doar mesajele cu starea „delivered”.

Cerere — listarea mesajelor eșuate​

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

Se folosește pentru a verifica mesajele care au întâmpinat erori de livrare.

Răspuns​

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

Câmpurile înregistrării​

CâmpTipDescriere
_idstringID-ul înregistrării
bulkMessageIdstringID-ul mesajului în masă căruia îi aparține această înregistrare
userIdstringID-ul utilizatorului destinatar
sessionIdstringID-ul sesiunii de conversație
messageIdstringID-ul mesajului trimis (null dacă nu a fost trimis încă)
referenceIdstringID de referință opțional (dacă este furnizat)
statusstringStarea înregistrării: pending, success, failed, cancelled
messageobjectDetaliile mesajului (doar în list-with-messages)

Comparație între List și List-With-Messages​

Funcționalitatelistlist-with-messages
PaginareDaDa
FiltrareDa (doar câmpurile înregistrării)Da (câmpuri de înregistrare și de mesaj)
Obiect mesajNuDa (dacă există messageId)
PerformanțăRapidMediu (execută JOIN)
Filtru message.statusIndisponibilDisponibil
Scenarii de utilizare
  • list: listați rapid toate înregistrările, filtrați după referenceId, verificați stările înregistrărilor
  • list-with-messages: vedeți stările mesajelor WhatsApp (delivered, read), inspectați payload-urile mesajelor
  • Exemple de filtrare:
    • {"status": "failed"} — înregistrări cu livrare eșuată
    • {"referenceId": "ORDER-123"} — un anumit ID de referință
    • {"message.status": "delivered"} — mesaje livrate (doar list-with-messages)
    • {"message.status": "read"} — mesaje citite (doar list-with-messages)
    • {"message.status": "error"} — mesaje cu erori (doar list-with-messages)
    • {"message.status": {"$in": ["delivered", "read"]}} — mesaje livrate sau citite (doar list-with-messages)
    • {"message.status": {"$nin": ["error", "not-sended"]}} — mesaje, fără cele cu erori și cele netrimise (doar list-with-messages)
    • {"status": {"$in": ["success", "pending"]}} — înregistrări reușite sau în așteptare
Note privind performanța și utilizarea
  • Endpoint-ul list este mai rapid; preferați-l pentru verificările generale de stare
  • Folosiți list-with-messages când aveți nevoie de detaliile mesajelor
  • Numărul maxim de înregistrări pe pagină (pageItems) este 50; implicit este 50 dacă nu este specificat
  • Filtrul message.status funcționează doar în list-with-messages
  • Înregistrările cu messageId nul vor avea obiecte message nule

Stop — anularea livrării​

Oprește o livrare în masă aflată în desfășurare. Job-ul din coadă este anulat, iar toate înregistrările pending trec în starea cancelled. Înregistrările deja procesate ca success sau failed nu sunt afectate.

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

Această acțiune nu poate fi anulată. O livrare oprită nu poate fi reluată.

Parametrii cererii​

ParametruTipObligatoriuDescriere
bulkMessageIdstringDaID-ul mesajului în masă de oprit
{
  "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"
}'

Răspuns​

Pentru o cerere reușită, corpul răspunsului este gol. Un status HTTP 200 indică faptul că operațiunea s-a încheiat cu succes.

{}
sfat
  • Pot fi oprite doar mesajele în masă create prin acest API
  • După oprirea unei livrări, puteți folosi endpoint-ul stats pentru a verifica numărul de înregistrări anulate
  • Dacă mesajul în masă nu este găsit, API-ul returnează eroarea: bulkMessageNotFound