API μηνυμάτων

Στείλτε ένα μεμονωμένο μήνυμα, διαχειριστείτε τα πρότυπα WhatsApp από τα οποία στέλνετε, και διαβάστε τι απαντούν οι άνθρωποι.

Αυτό δεν είναι το API καμπανιών. Μια καμπάνια στοχεύει ένα κοινό και μετριέται ως καμπάνια· αυτές οι διαδρομές στέλνουν ένα μήνυμα σε ένα άτομο, για τις περιπτώσεις που δεν περιγράφονται από κοινό - μια ενημέρωση παραγγελίας, μια απάντηση υποστήριξης, μια επιβεβαίωση που αποφάσισε να στείλει το δικό σας σύστημα.

Όλα τα endpoints αυτής της σελίδας είναι σχετικά με το βασικό URL: https://api-eu1.joryio.com/api - δείτε την Επισκόπηση API.

Έλεγχος ταυτότητας

Authorization: Bearer your_api_key_or_jwt
Content-Type: application/json

Αποστολή WhatsApp

Αποστολή μηνύματος προτύπου

POST /whatsapp/send/template

Το μόνο που μπορείτε να στείλετε σε κάποιον εκτός ανοιχτού 24ωρου παραθύρου συνομιλίας. Το πρότυπο πρέπει να είναι ήδη εγκεκριμένο από τη Meta.

{
  "to": "+306912345678",
  "templateName": "order_shipped",
  "language": "en",
  "variables": { "1": "Alex", "2": "GR-40921" }
}

Αποστολή μηνύματος συνεδρίας

POST /whatsapp/send/text

Ελεύθερο κείμενο, επιτρέπεται μόνο όσο το 24ωρο παράθυρο είναι ανοιχτό - δηλαδή εντός 24 ωρών από το τελευταίο εισερχόμενο μήνυμα εκείνου του ατόμου. Εκτός αυτού επιστρέφεται 409 και πρέπει να στείλετε πρότυπο. Το WhatsApp δεν επιτρέπει να ξεκινήσετε συνομιλία με ελεύθερο κείμενο· αν δεν είστε βέβαιοι, στείλτε πρότυπο.

{ "to": "+306912345678", "text": "Your order is out for delivery." }

Πρότυπα

GET /whatsapp/templates
POST /whatsapp/templates

Όλα τα πρότυπα με την κατάσταση έγκρισής τους. Μόνο τα APPROVED μπορούν να σταλούν. Η δημιουργία υποβάλλει το πρότυπο στη Meta για έγκριση - η έγκριση δεν είναι άμεση και μπορεί να απορριφθεί.

{
  "templates": [
    { "name": "order_shipped", "language": "en", "status": "APPROVED",
      "category": "UTILITY", "variables": 2 }
  ]
}

Πρότυπα SMS (μόνο Delivyr)

Μόνο Delivyr. Αυτές οι διαδρομές λειτουργούν μόνο σε χώρο εργασίας του οποίου ο αριθμός SMS συνδέεται με λογαριασμό Delivyr. Η Delivyr στέλνει μόνο πρότυπα που έχει εγκρίνει, σε αριθμούς ΗΠΑ και Καναδά. Σε κάθε άλλο χώρο εργασίας, όλες οι διαδρομές εκτός από το GET /sms/templates/accounts απαντούν 403 με code: "delivyr_account_required":

{ "statusCode": 403, "code": "delivyr_account_required",
  "message": "SMS templates are available only to workspaces that send SMS through a Delivyr account. Connect one under Integrations > Delivyr." }

Η ανάγνωση απαιτεί templates:read. Η δημιουργία, η ανανέωση και η διαγραφή απαιτούν templates:write.

Λογαριασμοί Delivyr του χώρου εργασίας

Επιστρέφει [] όταν δεν υπάρχει λογαριασμός, ώστε ένας πελάτης να ελέγξει πριν από οποιαδήποτε άλλη κλήση. Το key είναι το accountKey που δέχονται οι άλλες διαδρομές.

GET /sms/templates/accounts

[
  { "key": "6f1c2a9e-3b4d-4e5f-8a7b-9c0d1e2f3a4b", "smsAccountId": "6f1c2a9e-3b4d-4e5f-8a7b-9c0d1e2f3a4b",
    "provider": "delivyr", "name": "Delivyr US" }
]

Λίστα προτύπων

Προαιρετικά φίλτρα: status (pending, approved, rejected, system) και accountKey. Μπορούν να σταλούν μόνο πρότυπα approved και system. Τα mappableVariables είναι οι μεταβλητές που συμπληρώνετε για κάθε επαφή· τις υπόλοιπες (account_dba) τις συμπληρώνει η ίδια η Delivyr.

GET /sms/templates?status=approved

[
  { "id": "1d2e3f40-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "accountKey": "6f1c2a9e-3b4d-4e5f-8a7b-9c0d1e2f3a4b",
    "provider": "delivyr", "providerTemplateId": "NMPNWAS6", "title": "We Miss You",
    "body": "Hi {{first_name}}, we miss you: {{link}}", "status": "approved", "source": "portal",
    "variables": ["first_name", "link"], "mappableVariables": ["first_name", "link"] }
]

Ανανέωση από τη Delivyr

Φέρνει τώρα τα πρότυπα του λογαριασμού από τη Delivyr, μαζί με όσα δημιουργήθηκαν στην πύλη της Delivyr, και ενημερώνει την κατάσταση ελέγχου τους. Το Joryio ανανεώνει επίσης κάθε 30 λεπτά. Προαιρετικό σώμα: { "accountKey": "..." }.

POST /sms/templates/sync

{ "results": [ { "accountKey": "6f1c2a9e-3b4d-4e5f-8a7b-9c0d1e2f3a4b", "added": 2, "updated": 5, "removed": 0, "total": 7 } ] }

Δημιουργία προτύπου

Υποβάλλει το πρότυπο για έλεγχο στη Delivyr. Ξεκινά ως pending και η κατάσταση αλλάζει μετά τον έλεγχο. Χρησιμοποιήστε μεταβλητές {{name}}. Βάλτε {{link}} όπου πρέπει να μπει σύνδεσμος, και το Joryio το συμπληρώνει κατά την αποστολή με δικό του σύντομο σύνδεσμο με παρακολούθηση. Το accountKey χρειάζεται μόνο όταν ο χώρος εργασίας στέλνει μέσω περισσότερων από έναν λογαριασμούς Delivyr. Το εγκεκριμένο κείμενο δεν αλλάζει: για νέα διατύπωση, δημιουργήστε νέο πρότυπο.

POST /sms/templates

{
  "title": "Weekend offer",
  "body": "Hi {{first_name}}, your weekend offer is ready: {{link}} Reply STOP to opt out.",
  "tags": ["promo"]
}

Ανάκτηση ή διαγραφή προτύπου

Η διαγραφή διαγράφει το πρότυπο και στη Delivyr. Τα πρότυπα συστήματος της Delivyr δεν διαγράφονται.

GET /sms/templates/:id
DELETE /sms/templates/:id

Χρήση και όρια

GET /whatsapp/usage?period=monthly&startDate=2026-08-01&endDate=2026-08-31
GET /whatsapp/usage/limits?wabaId=waba_120363

Το WhatsApp χρεώνει ανά 24ωρη συνομιλία και όχι ανά μήνυμα, οπότε το πλήθος μηνυμάτων δεν προβλέπει το κόστος. Η διαδρομή χρήσης επιστρέφει τις αποθηκευμένες γραμμές χρήσης των λογαριασμών του χώρου εργασίας - μία γραμμή ανά λογαριασμό και περίοδο, με τη νεότερη περίοδο πρώτη. Παράμετροι (όλες προαιρετικές): wabaId (ένας λογαριασμός), period (daily ή monthly), startDate / endDate (ημερομηνίες ISO· γραμμές των οποίων η περίοδος αρχίζει από το startDate και τελειώνει έως το endDate). Κάθε γραμμή φέρει επίσης organizationId, workspaceId, createdAt και updatedAt.

[
  {
    "id": "usage_9f2c", "wabaId": "waba_120363", "period": "monthly",
    "periodStart": "2026-08-01", "periodEnd": "2026-08-31",
    "conversations": { "marketing": 4120, "utility": 8802, "authentication": 310, "service": 1904, "total": 15136 },
    "messages": { "sent": 31204, "delivered": 30877, "read": 22410, "failed": 327, "received": 4810 },
    "estimatedCost": 812.4,
    "currency": "USD"
  }
]

Η διαδρομή ορίων δείχνει τη βαθμίδα που επιτρέπει η Meta για τον αριθμό σας και πόσο έχει χρησιμοποιηθεί - η εξάντλησή της αποτυγχάνει τις αποστολές, δεν τις βάζει σε ουρά. Το wabaId είναι προαιρετικό - χωρίς αυτό τα όρια είναι του προεπιλεγμένου λογαριασμού και οι τρεις τιμές χρήσης επιστρέφουν 0, γιατί η χρήση αναζητείται μόνο για ονομαστικά δηλωμένο λογαριασμό.

{
  "tier": "TIER_10K",
  "dailyLimit": 10000,
  "dailyConversations": 3410,
  "monthlyConversations": 41200,
  "monthlyEstimatedCost": 812.4,
  "qualityRating": "GREEN"
}

Τα μηνύματα μιας επαφής

GET /messages?userId=665f1e2a9b3c4d5e6f7a8b9c&direction=outbound&channel=email&limit=50&offset=0

Ό,τι στείλατε σε μια επαφή και ό,τι σας έστειλε, από το νεότερο: κάθε message.sent από καμπάνια ή διαδρομή (email, SMS, WhatsApp, push, Viber - όχι κόμβοι webhook) και οι απαντήσεις που επιστρέφει το GET /messages/inbound. Είναι η καρτέλα Μηνύματα στο προφίλ της επαφής.

Παράμετρος	Περιγραφή
userId	Υποχρεωτικό. Το id της επαφής στο Joryio ή το externalId της. Άγνωστη επαφή επιστρέφει κενή σελίδα.
direction	Προαιρετικό. outbound (αποστολές) ή inbound (απαντήσεις)· χωρίς αυτό, και τα δύο.
channel	Προαιρετικό. Ένα κανάλι, π.χ. email, sms, whatsapp, push.
limit	Προαιρετικό. Προεπιλογή 50, περιορίζεται σε 1-200.
offset	Προαιρετικό. Γραμμές που παραλείπονται, προεπιλογή 0, το πολύ 5000.

Response:

{
  "data": [
    { "direction": "outbound", "channel": "email", "eventName": "message.sent",
      "timestamp": "2026-10-28 10:00:00.000", "subject": "Your cart is still here",
      "messageId": "0100019a2b3c", "status": "opened",
      "source": { "kind": "journey", "id": "8f0c2d1e-5b7a-4c3e-9f1a-2d3e4f5a6b7c", "name": "Cart recovery" },
      "body": null, "from": null, "toNumber": null, "account": null, "messageType": null },
    { "direction": "inbound", "channel": "sms", "eventName": "sms.message.received",
      "timestamp": "2026-10-27 18:02:00.000", "body": "thanks!", "from": "+306912345678",
      "toNumber": "+302101234567", "account": "Support line", "messageType": "text",
      "subject": null, "messageId": null, "source": null, "status": null }
  ],
  "total": 2
}

Μια αποστολή δηλώνει στο source τι την έστειλε (kind είναι journey ή campaign, name είναι null όταν δεν εντοπίζεται πια), το subject του email και το status - το πιο προχωρημένο αποτέλεσμα που καταγράφηκε για το μήνυμα: sent, delivered, opened, clicked ή failed / bounced, που υπερισχύουν. Μια απάντηση έχει from, toNumber, account και body όπως στο /messages/inbound. Η διαδρομή διαβάζει τους τελευταίους 12 μήνες· το total είναι το μέγεθος της σελίδας, οπότε σελιδοποιήστε με offset μέχρι μια σελίδα να επιστρέψει μικρότερη από το limit.

Εισερχόμενα μηνύματα

GET /messages/inbound?userId=665f1e2a9b3c4d5e6f7a8b9c&channel=whatsapp&limit=50&offset=0
GET /sms/messages?userId=665f1e2a9b3c4d5e6f7a8b9c&limit=50

Ό,τι σας έστειλε μία επαφή, σε WhatsApp και SMS - οι γραμμές προέρχονται από τα συμβάντα <channel>.message.received της επαφής. Το userId (το αναγνωριστικό Joryio της επαφής, το id που επιστρέφει το Users API) είναι υποχρεωτικό - χωρίς αυτό η διαδρομή επιστρέφει κενή σελίδα. Το channel φιλτράρει σε ένα κανάλι (sms ή whatsapp)· το limit έχει προεπιλογή 50 και περιορίζεται σε 1-200· το offset έχει προεπιλογή 0. Το total είναι το μέγεθος της σελίδας που επιστράφηκε, όχι συνολικό πλήθος - σελιδοποιήστε με offset μέχρι μια σελίδα να επιστρέψει λιγότερες γραμμές από το limit. Δεν υπάρχει δρομέας since σε αυτή τη διαδρομή. Το toNumber είναι ο αριθμός στον οποίο έφτασε το μήνυμα και το account η ετικέτα του λογαριασμού που το έλαβε· και τα δύο είναι null για μηνύματα που καταγράφηκαν πριν αρχίσουν να σημειώνονται.

{
  "data": [
    { "channel": "whatsapp", "from": "+306912345678", "toNumber": "+302101234567",
      "account": "Support line", "body": "when will it arrive?", "messageType": "text",
      "eventName": "whatsapp.message.received", "timestamp": "2026-08-27T09:41:00Z" }
  ],
  "total": 1
}

Το GET /sms/messages επιστρέφει τα SMS μιας επαφής (το χρονολόγιο του προφίλ), νεότερα πρώτα, ως πίνακα JSON. Το userId είναι υποχρεωτικό - χωρίς αυτό η διαδρομή επιστρέφει []· το limit έχει προεπιλογή 50 και περιορίζεται σε 1-200. Το direction είναι inbound ή outbound. Δεν υπάρχει κατάσταση παράδοσης από τον πάροχο σε αυτή τη διαδρομή - παράδοση και αποτυχία είναι συμβάντα στο χρονολόγιο της επαφής (GET /users/:id/events).

[
  { "id": "sms_411", "body": "STOP", "phoneNumber": "+306912345678",
    "direction": "inbound", "messageType": "text", "accountId": "acct_7a1",
    "createdAt": "2026-08-26T18:02:00Z" }
]