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

Τεκμηρίωση API μηνυμάτων προτύπου μαζικής αποστολής — v1

Καταργείται

Αυτή η έκδοση (v1) θα καταργηθεί. Οι νέες ενσωματώσεις πρέπει να χρησιμοποιούν την v2, η οποία περιγράφει επίσης πώς να μεταβείτε από την v1.

Αυτό το 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Κάθε στοιχείο του πίνακα variables αντιστοιχεί σε ένα συστατικό του προτύπου. Ένας τύπος συστατικού (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 χρησιμοποιεί πεδία όπως {{1}}, {{2}}, χρησιμοποιήστε είτε τη μορφή πίνακα είτε τη μορφή αντικειμένου με αριθμητικά κλειδιά.
  • Αν το πρότυπό σας χρησιμοποιεί πεδία με όνομα, όπως {{firstName}} ή {{orderTotal}}, χρησιμοποιήστε τη μορφή αντικειμένου με κλειδιά ονομάτων.
  • Όταν χρησιμοποιείτε πίνακες, η σειρά έχει σημασία: το πρώτο στοιχείο αντιστοιχεί στο {{1}}, το δεύτερο στο {{2}} κ.ο.κ.

Συστατικό HEADER​

Χρησιμοποιήστε το συστατικό HEADER όταν η κεφαλίδα του προτύπου περιέχει πολυμέσα (εικόνα, βίντεο, έγγραφο) ή δυναμικό κείμενο. Για έγγραφο, δώστε επίσης filename: είναι το όνομα που εμφανίζει το WhatsApp για το αρχείο.

// Media header (image URL)
{
"type": "HEADER",
"parameters": ["https://example.com/product-image.jpg"]
}

// Document header with a file name
{
"type": "HEADER",
"parameters": ["https://example.com/offer.pdf"],
"filename": "Offer.pdf"
}

// 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/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​

Για κάθε παραλήπτη χρησιμοποιούνται διαφορετικές τιμές μεταβλητών. Ορίζοντας 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)
  • Αυτό το παράδειγμα χρησιμοποιεί τη μορφή παραμέτρων με όνομα· το πρότυπο πρέπει να περιέχει πεδία όπως {{name}} και {{discountRate}}
  • Με το action, οι συνομιλίες που δημιουργούνται από την παράδοση του μηνύματος ανατίθενται αυτόματα στην καθορισμένη ομάδα εργασίας

Απάντηση​

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

{
"bulkMessageId": "abc123xyz789"
}

Απαντήσεις σφάλματος​

ΚατάστασηΠεριγραφή
Channel not foundΔεν βρέθηκε επαληθευμένο κανάλι που να αντιστοιχεί στα channelUsername και connectorBrand
Channel is not verifiedΤο κανάλι που αντιστοιχίστηκε υπάρχει αλλά δεν έχει ακόμη επαληθευτεί
invalidRequestΔόθηκαν πολλά αναγνωριστικά για έναν παραλήπτη ή λείπει ένα απαιτούμενο payload
channelNotFoundΔεν βρέθηκε ενεργό κανάλι που να αντιστοιχεί στο channelId που δόθηκε
schema-errorΈνα πεδίο στο σώμα του αιτήματος απέτυχε στην επικύρωση σχήματος (λείπει υποχρεωτικό πεδίο, λάθος τύπος ή μη υποστηριζόμενη τιμή)

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


Stats — Στατιστικά παράδοσης​

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

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

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

ΠαράμετροςΤύποςΥποχρεωτικήΠεριγραφή
bulkMessageIdstringΝαιΤο 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.pendingnumberΠλήθος εγγραφών που περιμένουν ακόμη στην ουρά
stats.successnumberΠλήθος εγγραφών που επεξεργάστηκαν επιτυχώς για παράδοση
stats.failednumberΠλήθος εγγραφών που αντιμετώπισαν σφάλμα παράδοσης
stats.cancellednumberΠλήθος ακυρωμένων εγγραφών
stats.totalnumberΣυνολικό πλήθος εγγραφών (pending + success + failed + cancelled)
σημείωση

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

Stats έναντι Message Stats
  • Το endpoint stats: Εμφανίζει την κατάσταση της εργασίας παράδοσης (pending, success, failed, cancelled)
  • Το endpoint message-stats: Εμφανίζει την πραγματική κατάσταση των μηνυμάτων (pending, sending, sent, delivered, read, error κ.ά.)
  • Μια εργασία μπορεί να είναι επιτυχής, αλλά το μήνυμα να μην έχει παραδοθεί/διαβαστεί ακόμη

Reference ID​

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

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

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

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

Ανακτά τα στατιστικά κατάστασης μηνυμάτων ενός μαζικού μηνύματος. Σε αντίθεση με το endpoint 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

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

ΠαράμετροςΤύποςΥποχρεωτικήΠεριγραφή
bulkMessageIdstringΝαιΤο 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​

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

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

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

Πεδία Options​

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

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

ΠεδίοΤύποςΠροεπιλογήΠεριγραφή
currentPagenumber1Ο αριθμός σελίδας που θα ανακτηθεί
pageItemsnumber50Πλήθος εγγραφών ανά σελίδα (μέγιστο: 50)

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

Το φιλτράρισμα γίνεται με τη μορφή ερωτημάτων MongoDB. Μπορείτε να φιλτράρετε με βάση τα πεδία των εγγραφών. Στο endpoint 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 λειτουργεί μόνο στο endpoint list-with-messages

Records — Λεπτομέρειες και λίστα εγγραφών​

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

List — Λίστα εγγραφών​

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

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

ΠαράμετροςΤύποςΥποχρεωτικήΠεριγραφή
bulkMessageIdstringΝαιΤο ID του μαζικού μηνύματος που θα απαριθμηθεί
optionsobjectΌχιΕπιλογές σελιδοποίησης, φιλτραρίσματος και ταξινόμησης. Δείτε τη Δομή 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 — Λίστα με λεπτομέρειες μηνυμάτων​

Έχει τα ίδια χαρακτηριστικά με το endpoint 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": {}
}
}

Πεδία εγγραφής​

ΠεδίοΤύποςΠεριγραφή
_idstringID εγγραφής
bulkMessageIdstringID του μαζικού μηνύματος στο οποίο ανήκει η εγγραφή
userIdstringID χρήστη του παραλήπτη
sessionIdstringID συνεδρίας συνομιλίας
messageIdstringID του μηνύματος που στάλθηκε (null αν δεν έχει σταλεί ακόμη)
referenceIdstringΠροαιρετικό ID αναφοράς (αν δόθηκε)
statusstringΚατάσταση εγγραφής: pending, success, failed, cancelled
messageobjectΛεπτομέρειες μηνύματος (μόνο στο list-with-messages)

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

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

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

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

ΠαράμετροςΤύποςΥποχρεωτικήΠεριγραφή
bulkMessageIdstringΝαιΤο 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
  • Μετά τη διακοπή μιας παράδοσης, μπορείτε να χρησιμοποιήσετε το endpoint stats για να επαληθεύσετε το πλήθος των ακυρωμένων εγγραφών
  • Αν το μαζικό μήνυμα δεν βρεθεί, το API επιστρέφει το σφάλμα: bulkMessageNotFound