Το API του Entagl επιτρέπει στο δικό σας λογισμικό να δουλεύει με ένα workspace του Entagl: επαφές, συνομιλίες, μηνύματα, κρατήσεις, υπενθυμίσεις, παραγγελίες, προϊόντα, κλήσεις AI και καμπάνιες. Τα webhooks ειδοποιούν τα συστήματά σας τη στιγμή που συμβαίνει κάτι. Είναι το ίδιο API που χρησιμοποιεί η εφαρμογή Entagl για το Make.

Τα αιτήματα και οι αποκρίσεις είναι JSON μέσω HTTPS. Τα ονόματα των πεδίων είναι σε snake_case. Τα ID είναι ακέραιοι αριθμοί, εκτός αν ένα endpoint ορίζει κάτι άλλο. Οι ώρες είναι strings ISO 8601 και οι αποκρίσεις χρησιμοποιούν UTC.

Στείλτε ένα token με κάθε αίτημα στο header Authorization: Authorization: Bearer <token>. Λειτουργούν δύο είδη token:

Ένα header που λείπει απαντά 401 unauthenticated. Ένα λάθος ή ανακλημένο κλειδί απαντά 401 invalid_api_key. Ένα ληγμένο OAuth token απαντά 401 invalid_token: ανανεώστε το και δοκιμάστε ξανά.

Κάθε αίτημα δουλεύει σε ακριβώς ένα workspace. Ένα API key χρησιμοποιεί πάντα το δικό του workspace. Μια σύνδεση OAuth μπορεί να ανήκει σε περισσότερα workspaces (δικά σας ή όπου συμμετέχετε ως μέλος της ομάδας): στείλτε το header X-Entagl-Workspace με το ID του workspace για να διαλέξετε ένα. Με ένα μόνο workspace το header είναι προαιρετικό. Το GET /me λειτουργεί χωρίς το header και δείχνει κάθε workspace που μπορεί να χρησιμοποιήσει η σύνδεση.

Χωρίς το header σε σύνδεση με πολλά workspaces παίρνετε 400 workspace_required. Ένα workspace στο οποίο η σύνδεση δεν έχει πρόσβαση απαντά 403 workspace_forbidden. Ένα ID που ανήκει σε άλλο workspace απαντά πάντα 404 not_found, ποτέ 403.

Κάθε endpoint παρακάτω δείχνει το δικαίωμα που χρειάζεται. Οι ιδιοκτήτες, οι admins και τα API keys περνούν κάθε έλεγχο. Τα μέλη της ομάδας περνούν όταν ο ρόλος τους έχει αυτό το δικαίωμα τικαρισμένο στις ρυθμίσεις ομάδας: contacts, inbox, calendar, orders, business_pages, call_agent, campaigns ή integrations. Χωρίς αυτό, το API απαντά 403 insufficient_permissions.

Στείλτε τα σώματα ως JSON με Content-Type: application/json. Τα περισσότερα endpoints απορρίπτουν με 422 τα άγνωστα πεδία του σώματος, ώστε ένα τυπογραφικό λάθος να μην περνά ποτέ απαρατήρητο. Κάθε σφάλμα έχει την ίδια μορφή: ένα σταθερό code για να διακλαδώνετε τον κώδικά σας, ένα ευανάγνωστο message και, στα σφάλματα επικύρωσης, μια λίστα details που δείχνει κάθε λάθος πεδίο.

Οι διαδρομές με την ένδειξη Παλαιά μορφή απόκρισης προηγούνται αυτών των συμβάσεων: επιστρέφουν απλά αντικείμενα ή πίνακες JSON και απαντούν στα περισσότερα σφάλματα ως { "message": "…" }.

Τα endpoints που φέρουν την ένδειξη Με σελιδοποίηση επιστρέφουν πρώτα τα νεότερα στοιχεία, σε ένα αντικείμενο λίστας. Ζητήστε έως 100 στοιχεία με limit (προεπιλογή 25). Όταν το has_more είναι true, περάστε το next_cursor ως starting_after για να πάρετε την επόμενη σελίδα. Οι άλλες λίστες επιστρέφουν τα πάντα με μία κλήση, με has_more: false.

Κάθε POST endpoint στη βασική μορφή δέχεται την κεφαλίδα Idempotency-Key (έως 200 χαρακτήρες). Χρησιμοποιήστε μια μοναδική τιμή ανά ενέργεια, για παράδειγμα ένα UUID. Το Entagl κρατά την πρώτη απάντηση για 24 ώρες: μια επανάληψη με το ίδιο κλειδί και το ίδιο σώμα παίρνει πίσω αυτή την απάντηση με Idempotent-Replayed: true, και τίποτα δεν εκτελείται δύο φορές. Οι διαδρομές με την ένδειξη Παλαιά μορφή απόκρισης λειτουργούν διαφορετικά, δείτε παρακάτω.

• Το ίδιο κλειδί με διαφορετικό σώμα απαντά 409 idempotency_key_reused.
• Όσο το πρώτο αίτημα εκτελείται ακόμη, ή αν δεν ολοκληρώθηκε ποτέ, μια νέα προσπάθεια απαντά 409 request_in_progress. Ελέγξτε το αποτέλεσμα και δοκιμάστε ξανά με νέο κλειδί.
• Κάθε αποτέλεσμα αποθηκεύεται, και τα σφάλματα μαζί. Για να ξαναδοκιμάσετε ένα αίτημα που απέτυχε, χρησιμοποιήστε νέο κλειδί.
• Τα κλειδιά ισχύουν ανά workspace και ανά διαπιστευτήριο.

Παλαιές διαδρομές. Το POST /messages δέχεται επίσης Idempotency-Key (ή ένα message_id στο σώμα): η επανάληψη ενός μηνύματος που έχει ήδη γίνει δεκτό απαντά 202 με το ίδιο conversationId και δεν επεξεργάζεται δύο φορές, ενώ το ίδιο κλειδί με διαφορετικό σώμα απαντά 409. Το POST /chat δεν έχει προστασία από επαναλήψεις: μια επανάληψη τρέχει ξανά την AI, οπότε ελέγξτε το αποτέλεσμα πριν δοκιμάσετε ξανά.

Κάθε workspace μπορεί να κάνει 120 αιτήματα ανά λεπτό, κοινά για όλα τα API keys και τις συνδέσεις του. Οι αποκρίσεις περιέχουν RateLimit-Limit, RateLimit-Remaining και RateLimit-Reset (δευτερόλεπτα μέχρι να μηδενιστεί το παράθυρο). Αν ξεπεράσετε το όριο, παίρνετε 429 rate_limited με header Retry-After: περιμένετε τόσα δευτερόλεπτα και δοκιμάστε ξανά. Οι παλαιές διαδρομές του καναλιού API δεν προσμετρώνται σε αυτό το όριο.