API και webhooks του Call για developers: κλειδιά, scopes, events
Πρακτική περιήγηση στο REST API του Call: κλειδιά API και scopes, όρια ρυθμού, χειρισμός σφαλμάτων, υπογεγραμμένα webhooks και η σελίδα Developers για τα endpoints.
Αργά ή γρήγορα ένα τηλεφωνικό σύστημα πρέπει να επικοινωνήσει με κάτι άλλο: ένα CRM που πρέπει να δείχνει μια κλήση μόλις τελειώσει, ένα εργαλείο χρέωσης που θέλει να ξέρει ποιος κάλεσε, ένα script που κάνει κλήση όταν υποβάλλεται μια φόρμα. Το Call έχει REST API και εξερχόμενα webhooks ακριβώς γι’ αυτό. Ο οδηγός αυτός εξηγεί πώς ταιριάζουν τα κομμάτια, τι να ζητήσετε πριν γράψετε κώδικα και τα λάθη που συνήθως κοστίζουν σε έναν developer ένα απόγευμα.

Αν ο στόχος σας είναι απλώς να μεταφέρετε επαφές μαζικά, διαβάστε πρώτα τον οδηγό Εισαγωγή επαφών σε CRM τηλεφωνικής ομάδας· μια εισαγωγή είναι συχνά ευκολότερη από μια ενσωμάτωση.
Από πού να ξεκινήσετε: η τεκμηρίωση και η σελίδα Developers
Υπάρχουν δύο σημεία που πρέπει να γνωρίζετε. Η Τεκμηρίωση API βρίσκεται στις Ρυθμίσεις, καθώς και στο μενού Πόροι της αρχικής σελίδας. Διαβάζεται χωρίς σύνδεση, κάτι βολικό όταν εκτιμάτε μια δουλειά για έναν πελάτη. Η σελίδα Developers, επίσης στις Ρυθμίσεις, αφορά τον δικό σας χώρο εργασίας: δείχνει τα αναγνωριστικά του οργανισμού και των εκπροσώπων σας, τα endpoints webhook και μια λίστα μόνο για ανάγνωση με τα κλειδιά σας.
Τι σας δίνει κάθε σημείο
- Ξεκινήστε εδώΒασικό URL και συμβάσεις, έλεγχος ταυτότητας με πίνακα scopes και σφάλματα με κωδικούς status.
- EndpointsΚάθε κάρτα endpoint δείχνει το scope, τις παραμέτρους, το σώμα αιτήματος, την απόκριση και τα σφάλματα, με έτοιμα αιτήματα σε curl, JavaScript και Python.
- ΑναζήτησηΠατήστε / για να πάτε στην Αναζήτηση endpoints και να φιλτράρετε κατά μέθοδο, διαδρομή, scope ή περίληψη.
- OpenAPI JSONΚατεβάζει όλη την προδιαγραφή ως ένα αρχείο για τα δικά σας εργαλεία.
- Agent ID / APIΤο ID και το slug του οργανισμού σας, τη λειτουργία API (Sandbox ή Live) και το ID του εκπροσώπου AI που επιλέγετε, καθένα με κουμπί Αντιγραφή.
- WebhooksΤα endpoints σας, τα συμβάντα που λαμβάνει το καθένα, το τελευταίο HTTP status και τυχόν αποτυχημένες παραδόσεις.
Διαβάστε τις ενότητες για τα όρια ρυθμού και τα εξερχόμενα webhooks πριν ξεκινήσετε την παραγωγική λειτουργία, όχι μετά. Περιγράφουν συμπεριφορές που εύκολα ξεφεύγουν σε μια γρήγορη δοκιμή.
Κλειδιά API και scopes
Κάθε αίτημα φέρει ένα κλειδί σε κεφαλίδα Authorization ως bearer token. Τα κλειδιά δεν δημιουργούνται μέσα στην εφαρμογή: ο φορέας λειτουργίας του χώρου εργασίας σας τα εκδίδει και σας λέει ποια scopes έχουν. Το πλήρες κλειδί εμφανίζεται μία φορά, τη στιγμή της έκδοσης, και μετά φαίνονται μόνο οι πρώτοι χαρακτήρες του, οπότε αποθηκεύστε το αμέσως στο δικό σας χώρο φύλαξης μυστικών.
| Scope | Τι επιτρέπει |
|---|---|
| read | Ανάγνωση επαφών, κλήσεων, ουρών, μελών ομάδας, αναφορών και της λίστας μη κλήσης. |
| write | Δημιουργία και ενημέρωση επαφών, καταγραφή αποτελεσμάτων κλήσεων, προσθήκη αριθμών στη λίστα μη κλήσης. |
| calls | Πραγματοποίηση και τερματισμός κλήσεων. |
| admin | Διαχείριση webhooks· μπορεί επίσης να καλεί κάθε άλλο endpoint. |
Ζητήστε το μικρότερο σύνολο που κάνει τη δουλειά. Ένα script αναφορών χρειάζεται μόνο read· ένα κουμπί click-to-call χρειάζεται calls. Αν ένα αίτημα επιστρέψει 403 με κωδικό insufficient_scope, στο κλειδί λείπει το scope που φαίνεται στην κάρτα του endpoint.
Sandbox και live
Τα κλειδιά μπορούν να εκδοθούν για sandbox, που χρησιμοποιεί προσομοιωτή και δεν κάνει πραγματικές κλήσεις, ή για πραγματική χρήση. Αντιμετωπίστε το πρόθεμα ενός κλειδιού μόνο ως ετικέτα: ένα κλειδί με ετικέτα δοκιμής λειτουργεί στα ίδια δεδομένα και στην ίδια τηλεφωνική σύνδεση με ένα live, οπότε μη βασίζεστε στο πρόθεμα για να κρατάτε τα πειράματα μακριά από πραγματικούς πελάτες. Χρησιμοποιήστε τη λειτουργία API που δείχνει η σελίδα Developers για να ξέρετε πού βρίσκεστε.
Πραγματοποίηση κλήσεων μέσω του API
Τα δημόσια endpoints καλύπτουν τα βασικά: έλεγχο λειτουργίας, λίστα κλήσεων, ανάγνωση μίας κλήσης, πραγματοποίηση κλήσης, τερματισμό, διαχείριση webhooks και συνομιλία με εκπρόσωπο AI. Μια εξερχόμενη κλήση μέσω του API περνά τον ίδιο έλεγχο συμμόρφωσης με μια κλήση από την κονσόλα, οπότε ένας αριθμός στη λίστα μη κλήσης ή εκτός των επιτρεπόμενων ωρών απορρίπτεται, ακριβώς όπως θα συνέβαινε για έναν εκπρόσωπο. Σχεδιάστε τον κώδικά σας ώστε να χειρίζεται αυτή την απόρριψη ως κανονικό αποτέλεσμα, όχι ως σφάλμα.
Αυτό έχει σημασία για τον σχεδιασμό. Μη γράφετε βρόχο που ξαναδοκιμάζει μια απορριφθείσα κλήση μέχρι να πετύχει. Διαβάστε τον λόγο, καταγράψτε τον και προχωρήστε. Για τους κανόνες πίσω από αυτές τις απορρίψεις, δείτε τους οδηγούς Προστασία ωρών κλήσεων στο Call και Η λίστα μη κλήσης στο Call.
Όρια ρυθμού και σφάλματα
Κάθε κλειδί έχει το δικό του όριο αιτημάτων ανά λεπτό, που ορίζεται κατά την έκδοση· η προεπιλογή είναι 120. Όταν ένα κλειδί εξαντλήσει το λεπτό, το API απαντά 429 με κωδικό rate_limited και λέει πόσο να περιμένετε στην κεφαλίδα X-RateLimit-Reset. Περιμένετε τόσο και μετά συνεχίστε. Ένας ευγενικός client επιβραδύνει μόνος του πριν φτάσει στο όριο.
- 429 rate_limited: περιμένετε για το διάστημα της κεφαλίδας reset και κατανείμετε τη μαζική δουλειά στον χρόνο.
- 403 insufficient_scope: στο κλειδί λείπει το scope της κάρτας του endpoint· ζητήστε κλειδί που το έχει.
- Άλλα σφάλματα: ενεργείτε με βάση τον κωδικό σφάλματος, όχι το μήνυμα. Οι κωδικοί δεν αλλάζουν· η διατύπωση μπορεί να αλλάξει.
Χειρισμός αποτυχημένου αιτήματος
- Διαβάστε το statusΕίναι σφάλμα client που μπορείτε να διορθώσετε ή σφάλμα server που αξίζει νέα προσπάθεια;
- Διαβάστε τον κωδικόΔιακλαδώστε με βάση τον κωδικό, ποτέ με βάση το κείμενο του μηνύματος.
- ΠεριμένετεΓια 429, περιμένετε όσο λέει η κεφαλίδα reset· για σφάλματα server, ξαναδοκιμάστε λίγες φορές με αυξανόμενες καθυστερήσεις.
- Καταγράψτε τις λεπτομέρειεςΚρατήστε το endpoint, τον κωδικό και την ώρα, ώστε η υποστήριξη να μπορεί να το εντοπίσει.
- Σταματήστε στις απορρίψειςΜια απόρριψη συμμόρφωσης είναι απόφαση, όχι δυσλειτουργία· μην την ξαναδοκιμάζετε σε βρόχο.
Webhooks: λήψη συμβάντων
Αντί να ρωτάτε ξανά και ξανά το API αν συνέβη κάτι, αφήστε το Call να σας ενημερώσει. Στη σελίδα Developers, πατήστε Προσθήκη endpoint, εισαγάγετε μια δημόσια διεύθυνση https και τσεκάρετε τα συμβάντα που θέλετε· αν δεν τσεκάρετε κανένα, λαμβάνετε όλα τα συμβάντα. Το μυστικό υπογραφής εμφανίζεται μία φορά, όταν προστίθεται το endpoint. Αντιγράψτε το τότε. Αν χαθεί, διαγράψτε το endpoint και προσθέστε το ξανά για να πάρετε νέο.
Κάθε παράδοση είναι υπογεγραμμένη. Η κεφαλίδα υπογραφής περιέχει ένα HMAC-SHA256 της χρονοσφραγίδας και του σώματος ενωμένων με τελεία, υπολογισμένο με το μυστικό υπογραφής σας, και μια ξεχωριστή κεφαλίδα φέρει τη χρονοσφραγίδα. Υπολογίστε το ξανά από τη μεριά σας και συγκρίνετε πριν εμπιστευτείτε το περιεχόμενο. Η τεκμηρίωση του API περιλαμβάνει παραδείγματα κώδικα για αυτό σε Node.js και Python, και η απόρριψη παλιών χρονοσφραγίδων σας προστατεύει από επαναλαμβανόμενα αιτήματα.
Καλός και κακός δέκτης webhook
| Καλός | Κακός | |
|---|---|---|
| Υπογραφή | Επαληθεύεται σε κάθε αίτημα | Γίνεται αποδεκτή χωρίς έλεγχο |
| Απάντηση | 2xx μέσα σε δευτερόλεπτα, η δουλειά μπαίνει σε ουρά για αργότερα | Αργή επεξεργασία πριν από την απάντηση |
| Διπλότυπα | Ασφαλής λήψη του ίδιου συμβάντος δύο φορές | Δημιουργούνται δύο εγγραφές |
| Αποτυχίες | Ειδοποίηση όταν αποτυγχάνουν παραδόσεις | Σιωπή μέχρι να το προσέξει κάποιος |
Το endpoint σας πρέπει να απαντά με status 2xx μέσα σε 10 δευτερόλεπτα. Μια αποτυχημένη παράδοση επαναλαμβάνεται, έως έξι προσπάθειες συνολικά, και ένα endpoint που αποτυγχάνει 50 συνεχόμενες φορές απενεργοποιείται. Κάθε γραμμή στη σελίδα Developers δείχνει το τελευταίο HTTP status και πόσες παραδόσεις απέτυχαν, και το Αποστολή δοκιμής στέλνει ένα υπογεγραμμένο δοκιμαστικό συμβάν ώστε να δείτε τι απαντά ο server σας.
Λίστα ελέγχου πριν από την έναρξη
Πριν ενεργοποιήσετε μια ενσωμάτωση
- Ξέρετε ποια scopes έχει το κλειδί, και δεν έχει περισσότερα από όσα χρειάζονται
- Το κλειδί είναι αποθηκευμένο σε χώρο φύλαξης μυστικών, όχι στον πηγαίο κώδικα
- Οι υπογραφές webhook επαληθεύονται και οι παλιές χρονοσφραγίδες απορρίπτονται
- Ο δέκτης απαντά γρήγορα και χειρίζεται διπλά συμβάντα
- Οι αποκρίσεις ορίου ρυθμού και απόρριψης αντιμετωπίζονται χωρίς σφιχτούς βρόχους επανάληψης
- Δοκιμάσατε σε λειτουργία sandbox και πατήσατε Αποστολή δοκιμής στο endpoint
- Έχει οριστεί κάποιος που θα λαμβάνει ειδοποίηση αν αρχίσουν να αποτυγχάνουν οι παραδόσεις
Πώς γίνεται στο Call
Στο Call, ανοίξτε τις Ρυθμίσεις και μετά την Τεκμηρίωση API για να μελετήσετε τα endpoints, και τις Ρυθμίσεις και μετά το Developers για να αντιγράψετε το ID του οργανισμού σας, να ελέγξετε τα κλειδιά σας και να προσθέσετε webhook. Κάτοχοι, διαχειριστές και υπεύθυνοι μπορούν να προσθέτουν, να δοκιμάζουν και να διαγράφουν endpoints· όλοι οι άλλοι βλέπουν τη λίστα. Αν χρησιμοποιείτε και τις λειτουργίες εκπροσώπου AI, το ID εκπροσώπου στην ίδια σελίδα τροφοδοτεί το endpoint συνομιλίας. Για τη φωνητική πλευρά του προϊόντος, δείτε τον οδηγό Ρύθμιση εκπροσώπου AI στο Call.
Συχνές ερωτήσεις
Πώς αποκτώ κλειδί API;
Τα κλειδιά εκδίδονται από τον φορέα λειτουργίας του χώρου εργασίας σας· δεν δημιουργούνται μέσα στην εφαρμογή. Ζητήστε ένα και πείτε ποια scopes χρειάζεται. Το πλήρες κλειδί εμφανίζεται μία φορά κατά την έκδοση.
Τι σημαίνει μια απόκριση 429;
Το κλειδί έχει εξαντλήσει τα αιτήματά του για το τρέχον λεπτό. Περιμένετε όσα δευτερόλεπτα δείχνει η κεφαλίδα X-RateLimit-Reset, δοκιμάστε ξανά και κατανείμετε τη μαζική δουλειά σε μεγαλύτερο διάστημα.
Πώς ελέγχω ότι ένα webhook προήλθε πράγματι από το Call;
Υπολογίστε ένα HMAC-SHA256 της χρονοσφραγίδας και του σώματος με το μυστικό υπογραφής σας και συγκρίνετέ το με την κεφαλίδα υπογραφής. Η τεκμηρίωση του API δείχνει παραδείγματα σε Node.js και Python.
Μπορώ να στέλνω webhooks σε τοπικό server ανάπτυξης;
Όχι απευθείας. Τα endpoints πρέπει να είναι δημόσιες διευθύνσεις https, οπότε χρησιμοποιήστε ένα εργαλείο tunneling που εκθέτει τον τοπικό σας server σε μία τέτοια.
Γιατί απορρίφθηκε η κλήση που έκανα μέσω του API;
Οι κλήσεις μέσω του API περνούν τον ίδιο έλεγχο συμμόρφωσης με τις κλήσεις από την κονσόλα. Ένας αριθμός στη λίστα μη κλήσης ή εκτός ωρών κλήσεων απορρίπτεται.
Ποιος μπορεί να βλέπει και να αλλάζει τα webhooks;
Όλοι μπορούν να διαβάζουν τη λίστα, αλλά μόνο κάτοχοι, διαχειριστές και υπεύθυνοι μπορούν να προσθέτουν, να δοκιμάζουν ή να διαγράφουν endpoints.