Τεκμηρίωση 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.
- Μεταφέρετε τις διαδρομές των endpoints στο v2: το
…/api/bulk-message/…γίνεται…/api/v2/bulk-operation/…και το…/api/bulk-message-records/…γίνεται…/api/v2/bulk-operation-items/…. Το σώμα του αιτήματοςsendδεν αλλάζει· ένα μεμονωμένο αίτημα δέχεται πλέον έως 100.000 παραλήπτες αντί για 5.000. - Στέλνετε
bulkOperationIdαντί γιαbulkMessageIdστα αιτήματα. - Αντικαταστήστε το
stats.jsμε τοshow.js. - Διαβάζετε τις αποκρίσεις με τα νέα ονόματα πεδίων που φαίνονται στον παρακάτω πίνακα.
Τα endpoints του v2 γνωρίζουν μόνο τις μαζικές λειτουργίες που δημιουργήθηκαν με το send του v2. Για να παρακολουθήσετε ένα μαζικό μήνυμα που δημιουργήθηκε με το v1 πριν κάνετε τη μετάβαση, συνεχίστε να χρησιμοποιείτε γι' αυτό τα endpoints του v1.
Endpoints
| v1 | v2 | Τι αλλάζει στην απόκριση |
|---|---|---|
bulk-message/send.js | v2/bulk-operation/send.js | Το { bulkMessageId } γίνεται { bulkOperationId } |
bulk-message/stats.js | v2/bulk-operation/show.js | Το { bulkMessage, stats } γίνεται { bulkOperation } |
bulk-message/message-stats.js | v2/bulk-operation/message-stats.js | Οι μετρητές βρίσκονται στη ρίζα αντί κάτω από το messageStats |
bulk-message/stop.js | v2/bulk-operation/stop.js | Τίποτα |
bulk-message-records/list.js | v2/bulk-operation-items/list.js | Το bulkMessageRecords γίνεται bulkOperationItems |
bulk-message-records/list-with-messages.js | v2/bulk-operation-items/list-with-messages.js | Όπως το list, και κάθε στοιχείο φέρει επιπλέον το session |
Ονόματα πεδίων
| v1 | v2 |
|---|---|
stats.success | bulkOperation.progress.succeeded |
stats.pending, stats.failed, stats.cancelled, stats.total | bulkOperation.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 |
κατάσταση εγγραφής success | succeeded |
errorMessage της εγγραφής στις αποτυχημένες εγγραφές | error.message, δίπλα στα error.code και error.retryable |
| — | position (ο δείκτης του παραλήπτη στο recipients) |
φίλτρο {"status": "success"} | {"status": "succeeded"} |
φίλτρο {"referenceId": "…"} | {"payload.referenceId": "…"} |
σφάλματα του send schema-error, invalidRequest | zod-schema-error, με τη διαδρομή του μη έγκυρου πεδίου στο μήνυμα |
Βασικά χαρακτηριστικά
- Αποστολή μαζικών μηνυμάτων προτύπων σε 1–100.000 παραλήπτες με ένα μόνο αίτημα
- Εξατομικευμένες μεταβλητές για κάθε παραλήπτη (HEADER, BODY, BUTTONS, CAROUSEL)
- Κοινό
defaultPayloadγια όλους τους παραλήπτες με συγχώνευση τουpayloadανά παραλήπτη (isMerge) - Προγραμματισμένη παράδοση (
scheduleAt) - Προσδιορισμός παραληπτών με
username(αριθμός τηλεφώνου),userIdήsessionId - Αποστολή πολλών μηνυμάτων στον ίδιο χρήστη μέσα σε ένα μεμονωμένο μαζικό αίτημα
- Προαιρετικό
referenceIdγια την παρακολούθηση εγγραφών με εξωτερικά συστήματα - Αυτόματη ανάθεση των συνομιλιών σε χρήστη ή ομάδα εργασίας μετά την αποστολή (
action)
Αυτό το API μπορεί να στείλει μόνο πρότυπα που έχουν εγκριθεί από το Meta.
Το όνομα του προτύπου και ο κωδικός γλώσσας πρέπει να ταιριάζουν ακριβώς με το πρότυπο που είναι καταχωρισμένο στο Meta Business Manager.
Παράμετροι αιτήματος
Παράμετροι ανώτατου επιπέδου
| Παράμετρος | Τύπος | Υποχρεωτική | Περιγραφή |
|---|---|---|---|
channelUsername | string | Ναι | Αριθμός καναλιού WhatsApp που χρησιμοποιείται για την αποστολή του μηνύματος (π.χ. "908506669933") |
connectorBrand | string | Ναι | Μάρκα του connector του καναλιού. Τρέχουσα υποστηριζόμενη τιμή: "whatsapp" |
title | string | Όχι | Τίτλος καμπάνιας. Χρησιμοποιείται για εμφάνιση στον πίνακα ελέγχου. Προεπιλογή: "-" |
scheduleAt | string (ISO 8601) | Όχι | Προγραμματισμένη ημερομηνία και ώρα παράδοσης (π.χ. "2026-06-10T10:00:00.000Z"). Αν παραλειφθεί, τα μηνύματα στέλνονται αμέσως. |
defaultPayload | object | Υπό προϋποθέσεις* | Προεπιλεγμένο payload προτύπου που εφαρμόζεται σε όλους τους παραλήπτες. Απαιτείται αν ένας παραλήπτης δεν παρέχει δικό του payload. |
recipients | array | Ναι | Λίστα παραληπτών. Ελάχιστο 1, μέγιστο 100.000 παραλήπτες. |
action | object | Όχι | Ενέργεια που εφαρμόζεται στη συνομιλία μετά την αποστολή. assign-to-user ή assign-to-workgroup. |
*Αν κάθε παραλήπτης παρέχει δικό του payload, το defaultPayload είναι προαιρετικό.
Δομή παραλήπτη
Για κάθε παραλήπτη πρέπει να δίνεται ακριβώς ένα από τα username, userId ή sessionId. Δεν μπορούν να χρησιμοποιηθούν μαζί πολλά αναγνωριστικά και η παράλειψη όλων θα προκαλέσει σφάλμα.
Για να στείλετ ε πολλά μηνύματα στον ίδιο χρήστη μέσα σε ένα μεμονωμένο μαζικό αίτημα, προσθέστε το ίδιο αναγνωριστικό στη λίστα παραληπτών πολλές φορές.
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
username | string | Αριθμός τηλεφώνου του παραλήπτη (π.χ. "905554443322"). Αν ο χρήστης δεν υπάρχει στο σύστημα, δημιουργείται αυτόματα. |
userId | string | Αναγνωριστικό ενός υπάρχοντος χρήστη στο σύστημα. |
sessionId | string | Αναγνωριστικό μιας υπάρχουσας συνεδρίας συνομιλίας στο σύστημα. |
referenceId | string | Προαιρετικό αναγνωριστικό αναφοράς (έως 256 χαρακτήρες) για αντιστοίχιση με εγγραφές εξωτερικών συστημάτων (CRM, παραγγελία, tickets κ.λπ.). Πρέπει να είναι μοναδικό μέσα στη μαζική αποστολή, αν δοθεί. |
payload | object | Payload προτύπου ειδικό για τον παραλήπτη (προαιρετικό). Αν isMerge: true, συγχωνεύεται με το defaultPayload. |
isMerge | boolean | Παρακάμπτει τη συμπεριφορά συγχώνευσης για αυτόν τον παραλήπτη (προαιρετικό). Αν παραλειφθεί, χρησιμοποιείται το defaultPayload.isMerge. |
Δομή ενέργειας
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
action.key | string | Το "assign-to-user" αναθέτει τη συνομιλία σε συγκεκριμένο εκπρόσωπο· το "assign-to-workgroup" την αναθέτει σε ομάδα εργασίας. |
action.value | string | Αναγνωριστικό του χρήστη ή της ομάδας εργασίας προορισμού. |
Δομή payload προτύπου
Το defaultPayload και το payload ειδικό για κάθε παραλήπτη έχουν την ίδια δομή. Για μηνύματα προτύπων πρέπει να οριστεί type: "template".
{
"type": "template",
"template": {
"templateName": "order_confirmation",
"languageCode": "tr-TR",
"variables": []
},
"isMerge": true
}
| Πεδίο | Τύπος | Υποχρεωτικό | Περιγραφή |
|---|---|---|---|
type | string | Ναι | Τύπος payload. Για μηνύματα προτύπων: "template" |
template.templateName | string | Ναι* | Όνομα προτύπου καταχωρισμένο στο Meta. Προαιρετικό στα payloads των παραληπτών όταν χρησιμοποιείται isMerge: true (κληρονομείται από το προεπιλεγμένο). |
template.languageCode | string | Όχι | Κωδικός γλώσσας του προτύπου (π.χ. "tr", "en", "tr-TR", "en-US"). Πρέπει να ταιριάζει ακριβώς με τη γλώσσα που είναι καταχωρισμένη στο Meta. |
template.variables | array | Όχι | Λίστα μεταβλητών που εφαρμόζονται στα στοιχεία του προτύπου. Αν αλύεται παρακάτω. |
isMerge | boolean | Όχι | true: το payload του παραλήπτη συγχωνεύεται σε βάθος (deep merge) με το defaultPayload. false ή παράλειψη: το payload του παραλήπτη αντικαθιστά εντελώς το defaultPayload. |
- Αν
defaultPayload.isMerge: trueκαι ο παραλήπτης παρέχει δικό τουpayload, εφαρμόζεται deep merge. - Με το deep merge, ο παραλήπτης μπορεί να δώσει μόνο
variables· ταtemplateNameκαιlanguageCodeκληρονομούνται από το προεπιλεγμένο payload. - Το πεδίο
isMergeτου παραλήπτη παρακάμπτει τοdefaultPayload.isMerge. - Αν ένας παραλήπτης δεν παρέχει
payload, χρησιμοποιείται πάντα τοdefaultPayload.
Δομή μεταβλητών
Κάθε στοιχείο του πίνακα variables αντιστοιχεί σε ένα στοιχείο (component) του προτύπου. Ένας τύπος στοιχείου (type) μπορεί να εμφανίζεται μόνο μία φορά στον πίνακα.
| type | Περιγραφή | parameters | cards |
|---|---|---|---|
"HEADER" | Στοιχείο κεφαλίδας του προτύπου. Μεταβλητή κειμένου ή URL πολυμέσων (εικόνα, βίντεο, έγγραφο) | Ναι | — |
"BODY" | Μεταβλητές κειμένου του σώματος του προτύπου | Ναι | — |
"BUTTONS" | Μεταβλητές δυναμικού επιθέματος URL για κουμπιά | Ναι | — |
"CAROUSEL" | Στοιχεία καρτών για πρότυπα καρουζέλ | — | Ναι |
Μορφές παραμέτρων
Το πεδίο parameters μπορεί να δοθεί σε τρεις διαφορετικές μορφές:
// Format 1: Array (index-based) — for placeholders like {{1}}, {{2}}, {{3}}
"parameters": ["value1", "value2", "value3"]
// Format 2: Object (numeric keys) — alternative representation for {{1}}, {{2}}
"parameters": { "1": "value1", "2": "value2" }
// Format 3: Object (named keys) — for placeholders like {{name}}, {{amount}}
"parameters": { "name": "John", "amount": "150 USD" }
- Αν το πρότυπό σας στο Meta χρησιμοποιεί placeholders όπως
{{1}},{{2}}, χρησιμοποιήστε είτε τη μορφή πίνακα είτε τη μορφή αντικειμένου με αριθμητικά κλειδιά. - Αν το πρότυπό σας χρησιμοποιεί placeholders με όνομα, όπως
{{firstName}}ή{{orderTotal}}, χρησιμοποιήστε τη μορφή αντικειμένου με ονομασμένα κλειδιά. - Όταν χρησιμοποιείτε πίνακες, η σειρά έχει σημασία: το πρώτο στοιχείο αντιστοιχεί στο
{{1}}, το δεύτερο στο{{2}}κ.ο.κ.