Τεκμηρίωση 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.
Παράμετροι αιτήματος
Παράμετροι ανώτατου επιπέδου
| Παράμετρος | Τύπος | Υποχρεωτική | Περιγραφή |
|---|---|---|---|
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, μέγιστα 5.000 παραλήπτες. |
action | object | Όχι | Ενέργεια που εφαρμόζεται στη συνομιλία μετά την αποστολή. assign-to-user ή assign-to-workgroup. |
*Αν κάθε παραλήπτης παρέχει δικό του payload, το defaultPayload είναι προαιρετικό.
Δομή παραλήπτη
Για κάθε παραλήπτη πρέπει να δοθεί ακριβώς ένα από τα username, userId ή sessionId. Δεν μπορούν να χρησιμοποιηθούν μαζί πολλά αναγνωριστικά και η παράλειψη όλων θα προκαλέσει σφάλμα.
Για να στείλετε πολλά μηνύματα στον ίδιο χρήστη μέσα σε ένα μαζικό αίτημα, προσθέστε το ίδιο αναγνωριστικό πολλές φορές στη λίστα παραληπτών.
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
username | string | Ο αριθμός τηλεφώνου του παραλήπτη (π.χ. "905554443322"). Αν ο χρήστης δεν υπάρχει στο σύστημα, δημιουργείται αυτόματα. |
userId | string | Το ID ενός υπάρχοντος χρήστη στο σύστημα. |
sessionId | string | Το ID μιας υπάρχο υσας συνεδρίας συνομιλίας στο σύστημα. |
referenceId | string | Προαιρετικό ID αναφοράς (έως 256 χαρακτήρες) για αντιστοίχιση με εγγραφές εξωτερικών συστημάτων (CRM, παραγγελία, αίτημα κ.λπ.). Πρέπει να είναι μοναδικό μέσα στο μαζικό αίτημα, αν δοθεί. |
payload | object | Payload προτύπου ειδικά για τον παραλήπτη (προαιρετικό). Αν isMerge: true, συγχωνεύεται με το defaultPayload. |
isMerge | boolean | Παρακάμπτει τη συμπεριφορά συγχώνευσης για αυτόν τον παραλήπτη (προαιρετικό). Αν παραλειφθεί, χρησιμοποιείται το defaultPayload.isMerge. |
Δομή ενέργειας
| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
action.key | string | Το "assign-to-user" αναθέτει τη συνομιλία σε συγκεκριμένο εκπρόσωπο· το "assign-to-workgroup" την αναθέτει σε ομάδα εργασίας. |
action.value | string | Το ID του χρήστη ή της ομάδας εργασίας-στόχου. |
Δομή payload προτύπου
Το defaultPayload και το payload ανά παραλήπτη έχουν την ίδια δομή. Για μηνύματα προτύπου πρέπει να οριστεί type: "template".
{
"type": "template",
"template": {
"templateName": "order_confirmation",
"languageCode": "tr-TR",
"variables": []
},
"isMerge": true
}
| Πεδίο | Τύπος | Υποχρεωτικό | Περιγραφή |
|---|---|---|---|
type | string | Ναι | Τύπος payload. Για μηνύματα προτύπου: "template" |
template.templateName | string | Ναι* | Όνομα προτύπου καταχωρισμένο στο Meta. Προαιρετικό στα payload των παραληπτών όταν χρησιμοποιείται isMerge: true (κληρονομείται από το προεπιλεγμένο). |
template.languageCode | string | Όχι | Κωδικός γλώσσας του προτύπου (π.χ. "tr", "en", "tr-TR", "en-US"). Πρέπει να ταυτίζεται ακριβώς με τη γλώσσα που είναι καταχωρισμένη στο Meta. |
template.variables | array | Όχι | Λίστα μεταβλητών που εφαρμόζονται στα συστατικά του προτύπου. Αναλύεται παρακάτω. |
isMerge | boolean | Όχι | true: το payload του παραλήπτη συγχωνεύεται σε βάθος με το defaultPayload. false ή παράλειψη: το payload του παραλήπτη αντικαθιστά πλήρως το defaultPayload. |
- Αν
defaultPayload.isMerge: trueκαι ο παραλήπτης παρέχει δικό τουpayload, εφαρμόζεται συγχώνευση σε βάθος. - Με τη συγχώνευση σε βάθος, ο παραλήπτης μπορεί να δώσει μόνο
variables· ταtemplateNameκαιlanguageCodeκληρονομούνται από το προεπιλεγμένο payload. - Το πεδίο
isMergeτου παραλήπτη παρακάμπτει τοdefaultPayload.isMerge. - Αν ένας παραλήπτης δεν παρέχει
payload, χρησιμοποιείται πάντα τοdefaultPayload.
Δομή μεταβλητών
Κάθε στοιχείο του πίνακα variables αντιστοιχεί σε ένα συστατικό του προτύπου. Ένας τύπος συστατικού (type) μπορεί να εμφανίζεται μόνο μία φορά στον πίνακα.
| type | Περιγραφή | parameters | cards |
|---|---|---|---|
"HEADER" | Συστατικό κεφαλίδας του προτύπου. Μεταβλητή κειμένου ή URL πολυμέσου (εικόνα, βίντεο, έγγραφο) | Ναι | — |
"BODY" | Μεταβλητές κειμένου του σώματος του προτύπου | Ναι | — |
"BUTTONS" | Μεταβλητές επιθήματος δυναμικού URL για κουμπιά | Ναι | — |
"CAROUSEL" | Συστατικά καρτών για πρότυπα καρουσέλ | — | Ναι |
Μορφές παραμέτρων
Το πεδίο parameters μπορεί να δοθεί σε τρεις διαφορετικές μορφές:
// Format 1: Array (index-based) — for placeholders like {{1}}, {{2}}, {{3}}
"parameters": ["value1", "value2", "value3"]
// Format 2: Object (numeric keys) — alternative representation for {{1}}, {{2}}
"parameters": { "1": "value1", "2": "value2" }
// Format 3: Object (named keys) — for placeholders like {{name}}, {{amount}}
"parameters": { "name": "John", "amount": "150 USD" }
- Αν το πρότυπό σας στο Meta χρησιμοποιεί πεδία όπως
{{1}},{{2}}, χρησιμοποιήστε είτε τη μορφή πίνακα είτε τη μορφή αντικειμένου με αριθμητικά κλειδιά. - Αν το πρότυπό σας χρησιμοποιεί πεδία με όνομα, όπως
{{firstName}}ή{{orderTotal}}, χρησιμοποιήστε τη μορφή αντικειμένου με κλειδιά ονομάτων. - Όταν χρησιμοποιείτε πίνακες, η σειρά έχει σημασία: το πρώτο στοιχείο αντιστοιχεί στο
{{1}}, το δεύτερο στο{{2}}κ.ο.κ.
Συστατικό HEADER
Χρησιμοποιήστε το συστατικό HEADER όταν η κεφαλίδα του προτύπου περιέχει πολυμέσα (εικόνα, βίντεο, έγγραφο) ή δυναμικό κείμενο. Για έγγραφο, δώστε επίσης 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"]
}
Συστατικό CAROUSEL
Στα πρότυπα καρουσέλ, οι μεταβλητές των συστατικών ορίζονται χωριστά για κάθε κάρτα.
{
"type": "CAROUSEL",
"cards": [
{
"components": [
{
"type": "HEADER",
"parameters": ["https://example.com/card1.jpg"]
},
{
"type": "BODY",
"parameters": ["Product A", "99.00 USD"]
}
]
},
{
"components": [
{
"type": "HEADER",
"parameters": ["https://example.com/card2.jpg"]
},
{
"type": "BODY",
"parameters": ["Product B", "149.00 USD"]
}
]
}
]
}
Το μήκος του πίνακα cards πρέπει να ταυτίζεται ακριβώς με τον αριθμό καρτών που ορίζονται στο πρότυπο.
Παραδείγματα
1. Απλό πρότυπο — χωρίς μεταβλητές, ίδιο περιεχόμενο για όλους τους παραλήπτες
Αυτός είναι ο απλούστερος τρόπος να στείλετε ένα στατικό πρότυπο χωρίς μεταβλητές σε πολλούς π αραλήπτες.
{
"channelUsername": "908506669933",
"connectorBrand": "whatsapp",
"title": "General Announcement",
"defaultPayload": {
"type": "template",
"template": {
"templateName": "hello_world",
"languageCode": "tr-TR"
}
},
"recipients": [{ "username": "905554443301" }, { "username": "905554443302" }, { "username": "905554443303" }]
}
curl --location 'https://app.monochat.ai/api/:slug/custom-functions/bulk-message-api-app/api/bulk-message/send.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN' \
--data '{
"channelUsername": "908506669933",
"connectorBrand": "whatsapp",
"title": "General Announcement",
"defaultPayload": {
"type": "template",
"template": {
"templateName": "hello_world",
"languageCode": "tr-TR"
}
},
"recipients": [
{ "username": "905554443301" },
{ "username": "905554443302" },
{ "username": "905554443303" }
]
}'
- Οι παραλήπτες που ορίζονται μέσω
usernameδημιουργούνται αυτόματα αν δεν υπάρχουν ήδη στο σύστημα - Όλοι οι παραλήπτες χρησιμοποιούν το ίδιο
defaultPayload· δεν απαιτούνται δεδομένα ειδικά για παραλήπτη - Όταν δεν ορίζεται
isMerge, κάθε παραλήπτης χρησιμοποιεί απευθείας τοdefaultPayload
2. Πρότυπο με κοινές μεταβλητές σώματος
Το ίδιο πρότυπο αποστέλλεται σε όλους τους παραλήπτες με πανομοιότυπες τιμές μεταβλητών. Το πρότυπο περιέχει πεδία όπως {{1}} και {{2}}.
{
"channelUsername": "908506669933",
"connectorBrand": "whatsapp",
"title": "Summer Campaign",
"defaultPayload": {
"type": "template",
"template": {
"templateName": "promo_notification",
"languageCode": "tr-TR",
"variables": [
{
"type": "BODY",
"parameters": ["30%", "July 31, 2026"]
}
]
}
},
"recipients": [{ "username": "905554443301" }, { "username": "905554443302" }]
}
- Σε αυτό το παράδειγμα, το σώμα του προτύπου θα μπορούσε να περιέχει κείμενο όπως: «Απολαύστε έκπτωση
{{1}}στην καμπάνια μας! Η προσφορά ισχύει έως{{2}}.» - Το
parameters[0]αντικαθιστά το{{1}}, ενώ τοparameters[1]αντικαθιστά το{{2}}
3. Εξατομικευμένο πρότυπο — μεταβλητές ανά παραλήπτη με isMerge
Για κάθε παραλήπτη χρησιμοποιούνται διαφορετικές τιμές μεταβλητών. Ορίζοντας 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