Μετάβαση στο κύριο περιεχόμενο

Τεκμηρίωση Bulk Template Message API — v2

Αυτό το API σάς επιτρέπει να στέλνετε μηνύματα προτύπων σε πολλούς παραλήπτες ταυτόχρονα μέσω του καναλιού WhatsApp.

Η παράδοση των μηνυμάτων γίνεται ασύγχρονα· το αίτημα API επιστρέφει αμέσως ένα bulkOperationId, ενώ τα μηνύματα μπαίνουν σε ουρά και επεξεργάζονται στο παρασκήνιο.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation/send.js
Μορφή απόκρισης

Κάθε endpoint σε αυτό το έγγραφο είναι μια προσαρμοσμένη συνάρτηση (custom function). Το σώμα της απόκρισης HTTP περιέχει τα δικά της πεδία της συνάρτησης (_id, title, pathString…) και την πραγματική απόκριση του endpoint κάτω από το result. Τα παραδείγματα αποκρίσεων σε αυτό το έγγραφο δείχνουν το περιεχόμενο του result:

{
"_id": "function_id",
"title": "Show",
"pathString": "/bulk-message-api-app/api/v2/bulk-operation/show.js",
"result": {
"bulkOperation": { "_id": "abc123xyz789", "status": "running" }
}
}

Μετάβαση από το v1​

Το v2 λειτουργεί παράλληλα με το v1, ώστε να μπορείτε να κάνετε τη μετάβαση με τον δικό σας ρυθμό. Τα endpoints του v1 (/api/bulk-message/…, /api/bulk-message-records/…) θα καταργηθούν· οι νέες ενσωματώσεις πρέπει να χρησιμοποιούν το v2.

  1. Μεταφέρετε τις διαδρομές των endpoints στο v2: το …/api/bulk-message/… γίνεται …/api/v2/bulk-operation/… και το …/api/bulk-message-records/… γίνεται …/api/v2/bulk-operation-items/…. Το σώμα του αιτήματος send δεν αλλάζει· ένα μεμονωμένο αίτημα δέχεται πλέον έως 100.000 παραλήπτες αντί για 5.000.
  2. Στέλνετε bulkOperationId αντί για bulkMessageId στα αιτήματα.
  3. Αντικαταστήστε το stats.js με το show.js.
  4. Διαβάζετε τις αποκρίσεις με τα νέα ονόματα πεδίων που φαίνονται στον παρακάτω πίνακα.

Τα endpoints του v2 γνωρίζουν μόνο τις μαζικές λειτουργίες που δημιουργήθηκαν με το send του v2. Για να παρακολουθήσετε ένα μαζικό μήνυμα που δημιουργήθηκε με το v1 πριν κάνετε τη μετάβαση, συνεχίστε να χρησιμοποιείτε γι' αυτό τα endpoints του v1.

Endpoints​

v1v2Τι αλλάζει στην απόκριση
bulk-message/send.jsv2/bulk-operation/send.jsΤο { bulkMessageId } γίνεται { bulkOperationId }
bulk-message/stats.jsv2/bulk-operation/show.jsΤο { bulkMessage, stats } γίνεται { bulkOperation }
bulk-message/message-stats.jsv2/bulk-operation/message-stats.jsΟι μετρητές βρίσκονται στη ρίζα αντί κάτω από το messageStats
bulk-message/stop.jsv2/bulk-operation/stop.jsΤίποτα
bulk-message-records/list.jsv2/bulk-operation-items/list.jsΤο bulkMessageRecords γίνεται bulkOperationItems
bulk-message-records/list-with-messages.jsv2/bulk-operation-items/list-with-messages.jsΌπως το list, και κάθε στοιχείο φέρει επιπλέον το session

Ονόματα πεδίων​

v1v2
stats.successbulkOperation.progress.succeeded
stats.pending, stats.failed, stats.cancelled, stats.totalbulkOperation.progress.pending, .failed, .cancelled, .total
—bulkOperation.progress.unknown, bulkOperation.status, bulkOperation.result.outcome
bulkMessage (μαζικό μήνυμα)bulkOperation (μαζική λειτουργία)
bulkMessageRecord (εγγραφή)bulkOperationItem (στοιχείο)
bulkMessageId στα αιτήματα, στην απόκριση του send και στις εγγραφέςbulkOperationId
username / userId / sessionId της εγγραφής όπως στάλθηκανpayload.username / payload.userId / payload.sessionId
referenceId της εγγραφήςpayload.referenceId
payload της εγγραφής (το payload προτύπου του παραλήπτη)payload.payload
userId, sessionId, messageId της εγγραφής μετά την αποστολήresult.userId, result.sessionId, result.messageId
κατάσταση εγγραφής successsucceeded
errorMessage της εγγραφής στις αποτυχημένες εγγραφέςerror.message, δίπλα στα error.code και error.retryable
—position (ο δείκτης του παραλήπτη στο recipients)
φίλτρο {"status": "success"}{"status": "succeeded"}
φίλτρο {"referenceId": "…"}{"payload.referenceId": "…"}
σφάλματα του send schema-error, invalidRequestzod-schema-error, με τη διαδρομή του μη έγκυρου πεδίου στο μήνυμα

Βασικά χαρακτηριστικά​

  • Αποστολή μαζικών μηνυμάτων προτύπων σε 1–100.000 παραλήπτες με ένα μόνο αίτημα
  • Εξατομικευμένες μεταβλητές για κάθε παραλήπτη (HEADER, BODY, BUTTONS, CAROUSEL)
  • Κοινό defaultPayload για όλους τους παραλήπτες με συγχώνευση του payload ανά παραλήπτη (isMerge)
  • Προγραμματισμένη παράδοση (scheduleAt)
  • Προσδιορισμός παραληπτών με username (αριθμός τηλεφώνου), userId ή sessionId
  • Αποστολή πολλών μηνυμάτων στον ίδιο χρήστη μέσα σε ένα μεμονωμένο μαζικό αίτημα
  • Προαιρετικό referenceId για την παρακολούθηση εγγραφών με εξωτερικά συστήματα
  • Αυτόματη ανάθεση των συνομιλιών σε χρήστη ή ομάδα εργασίας μετά την αποστολή (action)
προειδοποίηση

Αυτό το API μπορεί να στείλει μόνο πρότυπα που έχουν εγκριθεί από το Meta.

Το όνομα του προτύπου και ο κωδικός γλώσσας πρέπει να ταιριάζουν ακριβώς με το πρότυπο που είναι καταχωρισμένο στο Meta Business Manager.

Παράμετροι αιτήματος​

Παράμετροι ανώτατου επιπέδου​

ΠαράμετροςΤύποςΥποχρεωτικήΠεριγραφή
channelUsernamestringΝαιΑριθμός καναλιού WhatsApp που χρησιμοποιείται για την αποστολή του μηνύματος (π.χ. "908506669933")
connectorBrandstringΝαιΜάρκα του connector του καναλιού. Τρέχουσα υποστηριζόμενη τιμή: "whatsapp"
titlestringΌχιΤίτλος καμπάνιας. Χρησιμοποιείται για εμφάνιση στον πίνακα ελέγχου. Προεπιλογή: "-"
scheduleAtstring (ISO 8601)ΌχιΠρογραμματισμένη ημερομηνία και ώρα παράδοσης (π.χ. "2026-06-10T10:00:00.000Z"). Αν παραλειφθεί, τα μηνύματα στέλνονται αμέσως.
defaultPayloadobjectΥπό προϋποθέσεις*Προεπιλεγμένο payload προτύπου που εφαρμόζεται σε όλους τους παραλήπτες. Απαιτείται αν ένας παραλήπτης δεν παρέχει δικό του payload.
recipientsarrayΝαιΛίστα παραληπτών. Ελάχιστο 1, μέγιστο 100.000 παραλήπτες.
actionobjectΌχιΕνέργεια που εφαρμόζεται στη συνομιλία μετά την αποστολή. assign-to-user ή assign-to-workgroup.

*Αν κάθε παραλήπτης παρέχει δικό του payload, το defaultPayload είναι προαιρετικό.

Δομή παραλήπτη​

Για κάθε παραλήπτη πρέπει να δίνεται ακριβώς ένα από τα username, userId ή sessionId. Δεν μπορούν να χρησιμοποιηθούν μαζί πολλά αναγνωριστικά και η παράλειψη όλων θα προκαλέσει σφάλμα.

Για να στείλετε πολλά μηνύματα στον ίδιο χρήστη μέσα σε ένα μεμονωμένο μαζικό αίτημα, προσθέστε το ίδιο αναγνωριστικό στη λίστα παραληπτών πολλές φορές.

ΠεδίοΤύποςΠεριγραφή
usernamestringΑριθμός τηλεφώνου του παραλήπτη (π.χ. "905554443322"). Αν ο χρήστης δεν υπάρχει στο σύστημα, δημιουργείται αυτόματα.
userIdstringΑναγνωριστικό ενός υπάρχοντος χρήστη στο σύστημα.
sessionIdstringΑναγνωριστικό μιας υπάρχουσας συνεδρίας συνομιλίας στο σύστημα.
referenceIdstringΠροαιρετικό αναγνωριστικό αναφοράς (έως 256 χαρακτήρες) για αντιστοίχιση με εγγραφές εξωτερικών συστημάτων (CRM, παραγγελία, tickets κ.λπ.). Πρέπει να είναι μοναδικό μέσα στη μαζική αποστολή, αν δοθεί.
payloadobjectPayload προτύπου ειδικό για τον παραλήπτη (προαιρετικό). Αν isMerge: true, συγχωνεύεται με το defaultPayload.
isMergebooleanΠαρακάμπτει τη συμπεριφορά συγχώνευσης για αυτόν τον παραλήπτη (προαιρετικό). Αν παραλειφθεί, χρησιμοποιείται το defaultPayload.isMerge.

Δομή ενέργειας​

ΠεδίοΤύποςΠεριγραφή
action.keystringΤο "assign-to-user" αναθέτει τη συνομιλία σε συγκεκριμένο εκπρόσωπο· το "assign-to-workgroup" την αναθέτει σε ομάδα εργασίας.
action.valuestringΑναγνωριστικό του χρήστη ή της ομάδας εργασίας προορισμού.

Δομή payload προτύπου​

Το defaultPayload και το payload ειδικό για κάθε παραλήπτη έχουν την ίδια δομή. Για μηνύματα προτύπων πρέπει να οριστεί type: "template".

{
"type": "template",
"template": {
"templateName": "order_confirmation",
"languageCode": "tr-TR",
"variables": []
},
"isMerge": true
}
ΠεδίοΤύποςΥποχρεωτικόΠεριγραφή
typestringΝαιΤύπος payload. Για μηνύματα προτύπων: "template"
template.templateNamestringΝαι*Όνομα προτύπου καταχωρισμένο στο Meta. Προαιρετικό στα payloads των παραληπτών όταν χρησιμοποιείται isMerge: true (κληρονομείται από το προεπιλεγμένο).
template.languageCodestringΌχιΚωδικός γλώσσας του προτύπου (π.χ. "tr", "en", "tr-TR", "en-US"). Πρέπει να ταιριάζει ακριβώς με τη γλώσσα που είναι καταχωρισμένη στο Meta.
template.variablesarrayΌχιΛίστα μεταβλητών που εφαρμόζονται στα στοιχεία του προτύπου. Αναλύεται παρακάτω.
isMergebooleanΌχιtrue: το payload του παραλήπτη συγχωνεύεται σε βάθος (deep merge) με το defaultPayload. false ή παράλειψη: το payload του παραλήπτη αντικαθιστά εντελώς το defaultPayload.
Συμπεριφορά του isMerge
  • Αν defaultPayload.isMerge: true και ο παραλήπτης παρέχει δικό του payload, εφαρμόζεται deep merge.
  • Με το deep merge, ο παραλήπτης μπορεί να δώσει μόνο variables· τα templateName και languageCode κληρονομούνται από το προεπιλεγμένο payload.
  • Το πεδίο isMerge του παραλήπτη παρακάμπτει το defaultPayload.isMerge.
  • Αν ένας παραλήπτης δεν παρέχει payload, χρησιμοποιείται πάντα το defaultPayload.

Δομή μεταβλητών​

Κάθε στοιχείο του πίνακα variables αντιστοιχεί σε ένα στοιχείο (component) του προτύπου. Ένας τύπος στοιχείου (type) μπορεί να εμφανίζεται μόνο μία φορά στον πίνακα.

typeΠεριγραφήparameterscards
"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 χρησιμοποιεί placeholders όπως {{1}}, {{2}}, χρησιμοποιήστε είτε τη μορφή πίνακα είτε τη μορφή αντικειμένου με αριθμητικά κλειδιά.
  • Αν το πρότυπό σας χρησιμοποιεί placeholders με όνομα, όπως {{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"]
}

Για πρότυπα καρουζέλ, οι μεταβλητές των στοιχείων ορίζονται ξεχωριστά για κάθε κάρτα.

{
"type": "CAROUSEL",
"cards": [
{
"components": [
{
"type": "HEADER",
"parameters": ["https://example.com/card1.jpg"]
},
{
"type": "BODY",
"parameters": ["Product A", "99.00 USD"]
}
]
},
{
"components": [
{
"type": "HEADER",
"parameters": ["https://example.com/card2.jpg"]
},
{
"type": "BODY",
"parameters": ["Product B", "149.00 USD"]
}
]
}
]
}
προειδοποίηση

Το μήκος του πίνακα cards πρέπει να ταιριάζει ακριβώς με τον αριθμό των καρτών που ορίζονται στο πρότυπο.

Παραδείγματα​

1. Απλό πρότυπο — Χωρίς μεταβλητές, ίδιο περιεχόμενο για όλους τους παραλήπτες​

Αυτός είναι ο απλούστερος τρόπος για να στείλετε ένα στατικό πρότυπο χωρίς μεταβλητές σε πολλούς παραλήπτες.

{
"channelUsername": "908506669933",
"connectorBrand": "whatsapp",
"title": "General Announcement",
"defaultPayload": {
"type": "template",
"template": {
"templateName": "hello_world",
"languageCode": "tr-TR"
}
},
"recipients": [{ "username": "905554443301" }, { "username": "905554443302" }, { "username": "905554443303" }]
}
curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation/send.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
"channelUsername": "908506669933",
"connectorBrand": "whatsapp",
"title": "General Announcement",
"defaultPayload": {
"type": "template",
"template": {
"templateName": "hello_world",
"languageCode": "tr-TR"
}
},
"recipients": [
{ "username": "905554443301" },
{ "username": "905554443302" },
{ "username": "905554443303" }
]
}'
συμβουλή
  • Οι παραλήπτες που προσδιορίζονται με username δημιουργούνται αυτόματα αν δεν υπάρχουν ήδη στο σύστημα
  • Όλοι οι παραλήπτες χρησιμοποιούν το ίδιο defaultPayload· δεν απαιτούνται δεδομένα ειδικά για τον παραλήπτη
  • Όταν δεν έχει οριστεί το isMerge, κάθε παραλήπτης χρησιμοποιεί απευθείας το defaultPayload

2. Πρότυπο με κοινές μεταβλητές σώματος​

Το ίδιο πρότυπο στέλνεται σε όλους τους παραλήπτες με τις ίδιες τιμές μεταβλητών. Το πρότυπο περιέχει placeholders όπως {{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​

Για κάθε παραλήπτη χρησιμοποιούνται διαφορετικές τιμές μεταβλητών. Ορίζοντας isMerge: true στο defaultPayload, οι παραλήπτες χρειάζεται να δώσουν μόνο 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 των πολυμέσων της κεφαλίδας πρέπει να είναι δημόσια προσβάσιμο
  • Αν το type παραλειφθεί στο payload του παραλήπτη, κληρονομείται το defaultPayload.type

4. Μεταβλητή κουμπιού URL​

Χρησιμοποιήστε το στοιχείο BUTTONS όταν το πρότυπο περιέχει ένα κουμπί με δυναμικό επίθεμα URL. Για παράδειγμα, ένας αριθμός παρακολούθησης που προστίθεται στο βασικό 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 πρέπει να δίνεται ως χρονοσφραγίδα UTC 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" }
}
]
}
}
}
]
}
συμβουλή
  • Το scheduleAt πρέπει να δίνεται στη ζώνη ώρας UTC (π.χ. για τις 10:00 π.μ. ώρα Τουρκίας, χρησιμοποιήστε 07:00:00.000Z)
  • Αυτό το παράδειγμα χρησιμοποιεί τη μορφή παραμέτρων με όνομα· το πρότυπο πρέπει να περιέχει placeholders όπως {{name}} και {{discountRate}}
  • Με το action, οι συνομιλίες που δημιουργούνται από την αποστολή του μηνύματος ανατίθενται αυτόματα στην καθορισμένη ομάδα εργασίας

Απόκριση​

Ένα επιτυχές αίτημα επιστρέφει ένα bulkOperationId, που μπορεί να χρησιμοποιηθεί για την παρακολούθηση της διαδικασίας παράδοσης:

{
"bulkOperationId": "abc123xyz789"
}

Αποκρίσεις σφάλματος​

ΚατάστασηΠεριγραφή
recipients field is requiredΤο πεδίο recipients δεν στάλθηκε
Channel not foundΔεν βρέθηκε επαληθευμένο κανάλι που να ταιριάζει με τα channelUsername και connectorBrand
Channel is not verifiedΤο κανάλι που αντιστοιχίστηκε υπάρχει αλλά δεν έχει ακόμη επαληθευτεί
zod-schema-errorΈνα πεδίο του σώματος του αιτήματος απέτυχε στον έλεγχο σχήματος (λείπει υποχρεωτικό πεδίο, λάθος τύπος, μη υποστηριζόμενη τιμή, περισσότερα από ένα αναγνωριστικά σε έναν παραλήπτη ή λείπει το payload). Το μήνυμα κατονομάζει το πεδίο, π.χ. recipients.0.referenceId: referenceId must be unique

Το bulkOperationId που επιστρέφεται μπορεί να χρησιμοποιηθεί με τα παρακάτω endpoints για την αναζήτηση στατιστικών παράδοσης και τη διακοπή της διαδικασίας παράδοσης.


Show — Κατάσταση και στατιστικά μαζικής λειτουργίας​

Ανακτά τη μαζική λειτουργία με την τρέχουσα κατάστασή της και τους μετρητές παράδοσης των στοιχείων της, κάτω από το κλειδί bulkOperation.

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

Παράμετροι αιτήματος​

ΠαράμετροςΤύποςΥποχρεωτικήΠεριγραφή
bulkOperationIdstringΝαιΑναγνωριστικό της μαζικής λειτουργίας που παρακολουθείτε (επιστρέφεται από το send)
{
"bulkOperationId": "abc123xyz789"
}
curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation/show.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
"bulkOperationId": "abc123xyz789"
}'

Απόκριση​

{
"bulkOperation": {
"_id": "abc123xyz789",
"type": "send-bulk-message",
"slug": "my-workspace",
"userId": "agent_user_id",
"payload": {
"title": "Campaign Title",
"channelUsername": "908506669933",
"connectorBrand": "whatsapp",
"connectorSlug": "om2WabVegaCloud",
"defaultLanguageCode": "tr-TR",
"sentUser": { "firstname": "John", "lastname": "Doe" },
"defaultPayload": {
"type": "template",
"template": { "templateName": "order_confirmation", "languageCode": "tr-TR" },
"isMerge": true
},
"source": { "type": "recipients", "bulkOperationInputGroupId": "group_id" }
},
"status": "running",
"result": { "outcome": "unknown", "hasErrors": false },
"progress": {
"total": 100,
"pending": 45,
"succeeded": 42,
"failed": 3,
"cancelled": 10,
"unknown": 0
},
"scheduleAt": "2026-06-10T07:00:00.000Z",
"createdAt": "2026-06-08T10:00:00.000Z",
"updatedAt": "2026-06-10T07:00:30.000Z",
"startedAt": "2026-06-10T07:00:05.000Z"
}
}

Πεδία του Show​

Τα πεδία βρίσκονται κάτω από το bulkOperation.

ΠεδίοΤύποςΠεριγραφή
statusstringΚατάσταση της μαζικής λειτουργίας: preparing, scheduled, pending, running, stopping, stopped, completed, failed
progress.totalnumberΣυνολικός αριθμός στοιχείων
progress.pendingnumberΣτοιχεία που περιμένουν ακόμη στην ουρά
progress.succeedednumberΣτοιχεία που επεξεργάστηκαν με επιτυχία για παράδοση
progress.failednumberΣτοιχεία που αντιμετώπισαν σφάλμα παράδοσης
progress.cancellednumberΣτοιχεία που ακυρώθηκαν με το stop
progress.unknownnumberΣτοιχεία των οποίων το αποτέλεσμα δεν μπόρεσε να προσδιοριστεί
result.outcomestringΤελικό αποτέλεσμα όταν η μαζική λειτουργία έχει ολοκληρωθεί: success, partial, all-failed, cancelled, unknown
result.hasErrorsbooleantrue αν τουλάχιστον ένα στοιχείο απέτυχε
scheduleAtstringΠρογραμματισμένη ώρα παράδοσης (μόνο για προγραμματισμένες μαζικές λειτουργίες)
startedAt, completedAtstringΠότε ξεκίνησε και πότε ολοκληρώθηκε η παράδοση
σημείωση

Το progress.succeeded δείχνει ότι το μήνυμα παραδόθηκε με επιτυχία από το σύστημα. Δεν εγγυάται ότι το Meta παρέδωσε το μήνυμα στον παραλήπτη. Οι επόμενες ενημερώσεις κατάστασης που παράγονται από το Meta (όπως delivered, read ή failed) δεν επηρεάζουν αυτόν τον μετρητή και δεν αντικατοπτρίζονται εδώ.

Show έναντι Message Stats
  • Endpoint show: Δείχνει την κατάσταση παράδοσης των στοιχείων (pending, succeeded, failed, cancelled, unknown)
  • Endpoint message-stats: Δείχνει την πραγματική κατάσταση του μηνύματος (pending, sending, sent, delivered, read, error κ.λπ.)
  • Ένα στοιχείο μπορεί να είναι succeeded, αλλά το μήνυμα να μην έχει ακόμη παραδοθεί/αναγνωστεί

Αναγνωριστικό αναφοράς​

Το referenceId είναι ένα προαιρετικό πεδίο που μπορείτε να χρησιμοποιήσετε για να αντιστοιχίσετε στοιχεία παράδοσης με ένα αναγνωριστικό από το δικό σας σύστημα, για λόγους παρακολούθησης (π.χ. αριθμός παραγγελίας, αναγνωριστικό ticket). Επιστρέφεται σε κάθε στοιχείο ως payload.referenceId.

Αν δοθεί, πρέπει να είναι μοναδικό μέσα στη μαζική αποστολή (έως 256 χαρακτήρες).

Σημαντικό
  • Δεν είναι υποχρεωτικό
  • Δεν μπορεί να επαναληφθεί μέσα στην ίδια μαζική λειτουργία
  • Μπορεί να επαναχρησιμοποιηθεί σε διαφορετικές μαζικές λειτουργίες

Message Stats — Κατάσταση μηνυμάτων WhatsApp​

Ανακτά τα στατιστικά κατάστασης μηνυμάτων για μια μαζική λειτουργία. Σε αντίθεση με το endpoint show, εδώ εμφανίζεται η πραγματική message.status των μηνυμάτων που στάλθηκαν αντί για την κατάσταση του στοιχείου.

Πιθανές καταστάσεις μηνυμάτων: pending, sending, sent, delivered, read, deleted, warning, error, unknown, not-sended

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

Παράμετροι αιτήματος​

ΠαράμετροςΤύποςΥποχρεωτικήΠεριγραφή
bulkOperationIdstringΝαιΑναγνωριστικό της μαζικής λειτουργίας που ερωτάτε
{
"bulkOperationId": "abc123xyz789"
}
curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation/message-stats.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
"bulkOperationId": "abc123xyz789"
}'

Απόκριση​

{
"pending": 5,
"sending": 2,
"sent": 10,
"delivered": 45,
"read": 30,
"deleted": 2,
"warning": 1,
"error": 3,
"unknown": 0,
"not-sended": 2,
"no-message": 20,
"total": 120
}

Πεδία του Message Stats​

ΠεδίοΤύποςΠεριγραφή
pendingnumberΜηνύματα που δεν έχουν σταλεί ακόμη
sendingnumberΜηνύματα που αποστέλλονται αυτή τη στιγμή
sentnumberΜηνύματα που παραδόθηκαν στο WhatsApp, αλλά δεν έχουν παραδοθεί ακόμη
deliverednumberΜηνύματα που παραδόθηκαν στο τηλέφωνο του παραλήπτη
readnumberΜηνύματα που διαβάστηκαν από τον παραλήπτη
deletednumberΔιαγραμμένα μηνύματα
warningnumberΜηνύματα με προειδοποιήσεις
errornumberΜηνύματα με σφάλματα
unknownnumberΜηνύματα με άγνωστη κατάσταση
not-sendednumberΜηνύματα που δεν μπόρεσαν να σταλούν
no-messagenumberΣτοιχεία χωρίς μήνυμα (ακόμη σε ουρά, αποτυχημένα ή ακυρωμένα)
totalnumberΣυνολικός αριθμός στοιχείων
Usage Tips
  • Ένας υψηλός αριθμός no-message ενώ η μαζική λειτουργία είναι running δείχνει ότι η παράδοση βρίσκεται ακόμη σε εξέλιξη
  • Ο αριθμός delivered δείχνει την επιτυχή παράδοση μηνυμάτων
  • Ο αριθμός read μπορεί να χρησιμοποιηθεί για τη μέτρηση της αλληλεπίδρασης με την καμπάνια
  • Μπορείτε να κάνετε περιοδικά poll σε αυτό το endpoint για παρακολούθηση σε πραγματικό χρόνο

Δομή Options — Σελιδοποίηση, φιλτράρισμα και ταξινόμηση​

Η παράμετρος options που χρησιμοποιείται στα endpoints list και list-with-messages παρέχει μια τυπική δομή για σελιδοποίηση, φιλτράρισμα και ταξινόμηση.

Πεδία Options​

ΠεδίοΤύποςΥποχρεωτικόΠεριγραφή
paginationobjectΌχιΡυθμίσεις σελιδοποίησης
filteringobjectΌχιΚριτήρια φιλτραρίσματος
sortingobjectΌχιΡυθμίσεις ταξινόμησης (π.χ. {"position": 1})

Δομή σελιδοποίησης​

Αν δεν σταλεί pagination, επιστρέφεται η πρώτη σελίδα με έως 50 στοιχεία. Αν σταλεί, το currentPage είναι υποχρεωτικό.

ΠεδίοΤύποςΠροεπιλογήΠεριγραφή
currentPagenumber—Αριθμός σελίδας προς ανάκτηση (υποχρεωτικό όταν σταλεί το pagination)
pageItemsnumber50Αριθμός στοιχείων ανά σελίδα (μέγιστο: 50)

Δομή φιλτραρίσματος​

Το φιλτράρισμα γίνεται με τη μορφή ερωτήματος MongoDB στα πεδία των στοιχείων, χρησιμοποιώντας τα ονόματα των πεδίων ακριβώς όπως εμφανίζονται στην απόκριση (π.χ. status, payload.referenceId, result.messageId). Στο endpoint list-with-messages μπορείτε επίσης να φιλτράρετε με πεδία του μηνύματος (π.χ. message.status).

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

// Filter by referenceId
{
"options": {
"filtering": {
"payload.referenceId": "ORDER-12345"
}
}
}

// Filter by message status (only list-with-messages)
{
"options": {
"filtering": {
"message.status": "delivered"
}
}
}

// Filter by multiple statuses using $in (MongoDB operator)
{
"options": {
"filtering": {
"message.status": {
"$in": ["delivered", "read"]
}
}
}
}

// Exclude specific statuses using $nin (MongoDB operator)
{
"options": {
"filtering": {
"message.status": {
"$nin": ["error", "not-sended"]
}
}
}
}

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

Δομή ταξινόμησης​

Η ταξινόμηση γίνεται με τη μορφή ταξινόμησης MongoDB. Το 1 σημαίνει αύξουσα και το -1 φθίνουσα. Το position είναι η σειρά του παραλήπτη στον πίνακα recipients του αιτήματος (ξεκινώντας από το 0).

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

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

Παράδειγμα συνδυασμένης χρήσης​

{
"bulkOperationId": "abc123xyz789",
"options": {
"pagination": {
"currentPage": 2,
"pageItems": 50
},
"filtering": {
"message.status": "delivered"
},
"sorting": {
"position": 1
}
}
}

Αυτό το παράδειγμα εμφανίζει τη δεύτερη σελίδα των παραδοθέντων μηνυμάτων με τη σειρά των παραληπτών.

Πρακτικές συμβουλές
  • Συνδυάστε τα filtering και pagination για στοχευμένα ερωτήματα
  • Η απόκριση περιλαμβάνει τα options.pagination.totalCount και options.pagination.totalPages για πλοήγηση
  • Το φίλτρο message.status λειτουργεί μόνο στο endpoint list-with-messages

Items — Λεπτομέρειες και λίστα στοιχείων​

Εμφανίζει όλα τα στοιχεία παράδοσης μιας μαζικής λειτουργίας. Κάθε στοιχείο αντιπροσωπεύει μία καταχώριση του πίνακα recipients.

List — Λίστα στοιχείων​

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

Παράμετροι αιτήματος​

ΠαράμετροςΤύποςΥποχρεωτικήΠεριγραφή
bulkOperationIdstringΝαιΑναγνωριστικό της μαζικής λειτουργίας προς εμφάνιση
optionsobjectΌχιΕπιλογές σελιδοποίησης, φιλτραρίσματος, ταξινόμησης. Δείτε τη Δομή Options για λεπτομέρειες.

Αίτημα — Βασική χρήση​

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

Αίτημα — Φιλτράρισμα με συγκεκριμένη κατάσταση​

{
"bulkOperationId": "abc123xyz789",
"options": {
"pagination": {
"currentPage": 1,
"pageItems": 50
},
"filtering": {
"status": "failed"
}
}
}

Εμφανίζει μόνο τα αποτυχημένα στοιχεία παράδοσης, με τον λόγο στο error.

Απόκριση​

{
"bulkOperationItems": [
{
"_id": "item_1",
"bulkOperationId": "abc123xyz789",
"bulkOperationBatchId": "batch_1",
"slug": "my-workspace",
"position": 0,
"payload": {
"username": "905554443301",
"referenceId": "ORDER-12345",
"payload": {
"template": {
"variables": [{ "type": "BODY", "parameters": ["Ahmet", "ORD-001"] }]
}
}
},
"status": "succeeded",
"attempt": 1,
"result": {
"userId": "user_123",
"sessionId": "session_456",
"messageId": "msg_789"
},
"createdAt": "2026-06-10T10:00:00.000Z",
"updatedAt": "2026-06-10T10:00:01.000Z",
"completedAt": "2026-06-10T10:00:01.000Z"
},
{
"_id": "item_2",
"bulkOperationId": "abc123xyz789",
"bulkOperationBatchId": "batch_1",
"slug": "my-workspace",
"position": 1,
"payload": { "username": "905554443302", "referenceId": "ORDER-12346" },
"status": "failed",
"attempt": 1,
"error": { "code": "error", "message": "Variable missing", "retryable": false },
"result": { "userId": "user_124", "sessionId": "session_457" },
"createdAt": "2026-06-10T10:00:00.000Z",
"updatedAt": "2026-06-10T10:00:01.000Z",
"completedAt": "2026-06-10T10:00:01.000Z"
}
],
"options": {
"pagination": {
"currentPage": 1,
"pageItems": 50,
"totalCount": 150,
"totalPages": 3
},
"sorting": {},
"filtering": {},
"searching": {}
}
}

List With Messages — Λίστα με λεπτομέρειες μηνυμάτων​

Έχει τα ίδια χαρακτηριστικά με το endpoint list (σελιδοποίηση, φιλτράρισμα, ταξινόμηση). Η διαφορά: κάθε στοιχείο φέρει επιπλέον τα σχετικά αντικείμενα message και session όταν υπάρχουν. Έτσι μπορείτε να δείτε την κατάσταση του μηνύματος (delivered, read, error κ.λπ.) και το payload με ένα μόνο ερώτημα.

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

Αίτημα — Βασική χρήση​

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

Αίτημα — Φιλτράρισμα με κατάσταση μηνύματος​

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

Αυτό το παράδειγμα ανακτά μόνο μηνύματα με κατάσταση "delivered".

Αίτημα — Λίστα αποτυχημένων μηνυμάτων​

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

Χρησιμοποιείται για τον έλεγχο μηνυμάτων που αντιμετώπισαν σφάλματα παράδοσης.

Απόκριση​

{
"bulkOperationItems": [
{
"_id": "item_1",
"bulkOperationId": "abc123xyz789",
"position": 0,
"payload": { "username": "905554443301", "referenceId": "ORDER-12345" },
"status": "succeeded",
"result": {
"userId": "user_123",
"sessionId": "session_456",
"messageId": "msg_789"
},
"message": {
"_id": "msg_789",
"type": "template",
"status": "delivered",
"payload": {
"template": {
"name": "order_notification"
}
},
"createdAt": "2026-06-10T10:01:00.000Z"
},
"session": {
"_id": "session_456",
"status": "opened"
}
}
],
"options": {
"pagination": {
"currentPage": 1,
"pageItems": 50,
"totalCount": 150,
"totalPages": 3
},
"sorting": {},
"filtering": {},
"searching": {}
}
}

Πεδία στοιχείου​

ΠεδίοΤύποςΠεριγραφή
_idstringΑναγνωριστικό στοιχείου
bulkOperationIdstringΑναγνωριστικό της μαζικής λειτουργίας στην οποία ανήκει το στοιχείο
positionnumberΣειρά του παραλήπτη στον πίνακα recipients του αιτήματος, ξεκινώντας από το 0
payloadobjectΟ παραλήπτης ακριβώς όπως στάλθηκε στο αίτημα (username / userId / sessionId, referenceId, payload, isMerge)
statusstringΚατάσταση στοιχείου: pending, succeeded, failed, cancelled, unknown
errorobjectΜόνο στα στοιχεία failed: code, message και retryable
result.userIdstringΑναγνωριστικό χρήστη του παραλήπτη
result.sessionIdstringΑναγνωριστικό συνεδρίας συνομιλίας
result.messageIdstringΑναγνωριστικό του μηνύματος που στάλθηκε (λείπει αν δεν στάλθηκε μήνυμα)
completedAtstringΠότε επεξεργάστηκε το στοιχείο
messageobjectΛεπτομέρειες μηνύματος (μόνο στο list-with-messages)
sessionobjectΛεπτομέρειες συνομιλίας (μόνο στο list-with-messages)

Σύγκριση List και List-With-Messages​

Χαρακτηριστικόlistlist-with-messages
ΣελιδοποίησηΝαιΝαι
ΦιλτράρισμαΝαι (μόνο πεδία στοιχείου)Ναι (πεδία στοιχείου + μηνύματος)
Μήνυμα / ΣυνεδρίαΌχιΝαι (αν υπάρχουν)
ΑπόδοσηΓρήγορηΜέτρια (εκτελεί JOIN)
Φίλτρο message.statusΜη διαθέσιμοΔιαθέσιμο
Σενάρια χρήσης
  • list: Γρήγορη λίστα όλων των στοιχείων, φιλτράρισμα με referenceId, έλεγχος καταστάσεων στοιχείων
  • list-with-messages: Προβολή καταστάσεων μηνυμάτων WhatsApp (delivered, read), έλεγχος payloads μηνυμάτων
  • Παραδείγματα φιλτραρίσματος:
    • {"status": "failed"} — Αποτυχημένα στοιχεία παράδοσης
    • {"payload.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"]}} — Μηνύματα που είναι είτε delivered είτε read (μόνο στο list-with-messages)
    • {"message.status": {"$nin": ["error", "not-sended"]}} — Μηνύματα εκτός από όσα έχουν σφάλμα και όσα δεν στάλθηκαν (μόνο στο list-with-messages)
    • {"message": {"$exists": false}} — Στοιχεία χωρίς μήνυμα (μόνο στο list-with-messages)
    • {"status": {"$in": ["succeeded", "pending"]}} — Στοιχεία που έχουν επιτύχει ή εκκρεμούν
Απόδοση και σημειώσεις χρήσης
  • Το endpoint list είναι ταχύτερο· προτιμήστε το για γενικούς ελέγχους κατάστασης
  • Χρησιμοποιήστε το list-with-messages όταν χρειάζονται λεπτομέρειες μηνυμάτων
  • Ο μέγιστος αριθμός στοιχείων ανά σελίδα (pageItems) είναι 50· αν δεν οριστεί, η προεπιλογή είναι 50
  • Το φίλτρο message.status λειτουργεί μόνο στο list-with-messages
  • Στοιχεία χωρίς result.messageId δεν έχουν αντικείμενο message

Stop — Ακύρωση παράδοσης​

Σταματά μια μαζική παράδοση που βρίσκεται σε εξέλιξη. Όλα τα στοιχεία pending μεταφέρονται στην κατάσταση cancelled και η μαζική λειτουργία γίνεται stopped. Τα στοιχεία που έχουν ήδη επεξεργαστεί ως succeeded ή failed δεν επηρεάζονται. Μια προγραμματισμένη μαζική λειτουργία μπορεί επίσης να σταματήσει πριν από την ώρα scheduleAt.

POST https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation/stop.js
προειδοποίηση

Αυτή η ενέργεια δεν μπορεί να αναιρεθεί. Μια παράδοση που έχει σταματήσει δεν μπορεί να συνεχιστεί.

Παράμετροι αιτήματος​

ΠαράμετροςΤύποςΥποχρεωτικήΠεριγραφή
bulkOperationIdstringΝαιΑναγνωριστικό της μαζικής λειτουργίας προς διακοπή
{
"bulkOperationId": "abc123xyz789"
}
curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/v2/bulk-operation/stop.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
"bulkOperationId": "abc123xyz789"
}'

Απόκριση​

Για ένα επιτυχές αίτημα, το σώμα της απόκρισης είναι κενό. Ένας κωδικός κατάστασης HTTP 200 δείχνει ότι η λειτουργία ολοκληρώθηκε με επιτυχία.

{}
συμβουλή
  • Μόνο οι μαζικές λειτουργίες που δημιουργήθηκαν μέσω αυτού του API μπορούν να σταματήσουν
  • Μετά τη διακοπή μιας παράδοσης, μπορείτε να χρησιμοποιήσετε το endpoint show για να επαληθεύσετε τον αριθμό των ακυρωμένων στοιχείων (bulkOperation.progress.cancelled)
  • Αν η μαζική λειτουργία δεν βρεθεί, το API επιστρέφει το σφάλμα: Bulk operation not found.