Τοπικό REST API
Το AI Softphone διαθέτει ένα REST API για ενοποίηση CTI: ένα πρόγραμμα στον ίδιο υπολογιστή μπορεί να κάνει και να ελέγχει κλήσεις, να διαβάζει επαφές, ιστορικό κλήσεων και λογαριασμούς SIP, και να παρακολουθεί τις κλήσεις σε εξέλιξη. Χωρίς SDK, χωρίς ενδιάμεσο στο cloud και χωρίς ακροατή εκτεθειμένο στο δίκτυο. Τα αιτήματα και οι απαντήσεις είναι JSON, οπότε αρκεί το curl ή οποιοσδήποτε πελάτης HTTP.
Το API είναι ανενεργό μετά την εγκατάσταση· τίποτα δεν ακούει μέχρι να το ενεργοποιήσετε. Τότε ακούει μόνο στη διεπαφή loopback — μια μικρή διαδικτυακή διεπαφή που απαντά μόνο σε αυτόν τον υπολογιστή — και δεν είναι προσβάσιμο από το δίκτυο του γραφείου, από VPN ή από άλλο μηχάνημα.
Χρησιμοποιήστε το API όταν το πρόγραμμά σας χρειάζεται δεδομένα από το τηλέφωνο ή πρέπει να ελέγξει μια κλήση. Χρησιμοποιήστε τα webhooks όταν πρέπει να αντιδρά στις κλήσεις τη στιγμή που συμβαίνουν, χωρίς επαναλαμβανόμενα ερωτήματα. Οι περισσότερες ενοποιήσεις χρησιμοποιούν και τα δύο· είναι ανεξάρτητα μεταξύ τους.
Ενεργοποίηση
Ανοίξτε τις Ρυθμίσεις → Ενσωμάτωση και πηγαίνετε στον Τοπικό έλεγχο.
- Ενεργοποιήστε το Επίτρεψε σε άλλα προγράμματα αυτού του υπολογιστή να χειρίζονται το τηλέφωνο. Ο διακομιστής ξεκινά αμέσως.
- Κρατήστε την προεπιλεγμένη Θύρα,
8377, εκτός αν τη χρησιμοποιεί ήδη άλλο πρόγραμμα. - Προαιρετικά ορίστε ένα Διακριτικό. Μόλις αποθηκευτεί, το πεδίο δείχνει Αποθηκευμένο — πληκτρολογήστε για αντικατάσταση.
- Στην Πρόσβαση, επιλέξτε τις ομάδες που θα ανοίξουν: Επαφές, Ιστορικό κλήσεων, Κλήσεις και ο χειρισμός τους, Λογαριασμοί, Ρυθμίσεις, Μετρητές (οι μετρικές). Μια ανενεργή ομάδα δεν φιλτράρεται απλώς, αλλά δεν εξυπηρετείται καθόλου.
- Δοκιμάστε το:
curl http://127.0.0.1:8377/accounts. Αν η απάντηση είναι JSON, το API λειτουργεί.
Δεν εγκαθίσταται ξεχωριστή υπηρεσία και δεν χρειάζεται επανεκκίνηση. Το μέρος του προγράμματος που το κάνει αυτό μπορεί να απενεργοποιηθεί στις Μονάδες (Ενσωμάτωση).
Η σελίδα του API
Το Άνοιγμα της σελίδας του API ανοίγει το http://127.0.0.1:8377 σε έναν φυλλομετρητή. Η διεύθυνση απαντά με μια λίστα όλων όσων εξυπηρετεί, στα αγγλικά· οι διευθύνσεις που διαβάζουν κάτι είναι σύνδεσμοι που μπορείτε να ακολουθήσετε.
Πρόσβαση και διακριτικό
Τι μπορεί να κάνει ένα πρόγραμμα εξαρτάται από το αν αλλάζει αποθηκευμένα δεδομένα, όχι από το αν διαβάζει:
- Χωρίς διακριτικό, οποιοδήποτε πρόγραμμα στον υπολογιστή μπορεί να διαβάζει τα πάντα στις ενεργές ομάδες και να ελέγχει κλήσεις: να κάνει κλήση, να απαντά, να τερματίζει, να βάζει σε αναμονή, να συνεχίζει, να μεταφέρει και να στέλνει DTMF.
- Με το διακριτικό στην κεφαλίδα
Authorization, μπορεί επιπλέον να χρησιμοποιεί τα σημεία πρόσβασης που αλλάζουν όσα είναι αποθηκευμένα. Χωρίς το διακριτικό, αυτά τα σημεία πρόσβασης δεν αναφέρονται στη σελίδα του API και απαντούν401. Αν δεν έχει οριστεί καθόλου διακριτικό, τίποτα δεν μπορεί να αλλάξει όσα είναι αποθηκευμένα.
Το διακριτικό φυλάσσεται στη θυρίδα κλειδιών του υπολογιστή, όχι στο αρχείο ρυθμίσεων, και δεν επιστρέφεται ποτέ από το /settings.
Χωρίς διακριτικό, οποιοδήποτε πρόγραμμα τρέχει σε αυτόν τον υπολογιστή μπορεί να ελέγχει το τηλέφωνο, μαζί και την απάντηση κλήσεων. Σε έναν προσωπικό σταθμό εργασίας αυτό είναι συνήθως αποδεκτό. Σε έναν κοινόχρηστο ή διαχειριζόμενο υπολογιστή, ορίστε διακριτικό και χειριστείτε το όπως κάθε άλλον κωδικό πρόσβασης. Το διακριτικό προστατεύει μόνο τα αιτήματα που αλλάζουν αποθηκευμένα δεδομένα, όχι τις κλήσεις: για να κρατήσετε άλλα προγράμματα μακριά από τις κλήσεις, απενεργοποιήστε την ομάδα Κλήσεις και ο χειρισμός τους στην Πρόσβαση.
Σημεία πρόσβασης
Η βασική διεύθυνση είναι http://127.0.0.1:8377. Τα παρακάτω σημεία πρόσβασης δεν χρειάζονται διακριτικό.
| Μέθοδος | Διαδρομή | Τι κάνει |
|---|---|---|
| GET | /metrics | Οι μετρητές, σε μορφή Prometheus. |
| GET | /ui | Η λίστα των εγγραφών, ως σελίδα HTML. |
| GET | /ui/recordings/{id} | Μια εγγραφή με την απομαγνητοφώνησή της, ως σελίδα HTML. |
| GET | /ui/recordings/{id}/audio | Ο ήχος για την παραπάνω σελίδα. |
| GET | /contacts | Οι επαφές. |
| GET | /contacts/{id} | Μία επαφή. |
| GET | /history | Το αρχείο κλήσεων, με τις νεότερες πρώτες. Δέχεται ?limit=, ?missed=true και ?declined=true. |
| GET | /calls | Οι κλήσεις σε εξέλιξη. |
| POST | /calls | Κάνει μια κλήση: {"number": "...", "account_id": "..."}. |
| POST | /calls/{id}/answer | Απαντά σε μια κλήση. |
| POST | /calls/{id}/hangup | Τερματίζει μια κλήση. |
| POST | /calls/{id}/hold | Βάζει μια κλήση σε αναμονή. |
| POST | /calls/{id}/resume | Τη βγάζει από την αναμονή. |
| POST | /calls/{id}/dtmf | Στέλνει τόνους: {"digits": "..."}. |
| POST | /calls/{id}/transfer | Μεταφέρει την κλήση: {"target": "..."}. |
| GET | /accounts | Οι λογαριασμοί SIP και η κατάσταση καταχώρισής τους. Ποτέ κωδικός. |
| GET | /settings | Ολόκληρη η διαμόρφωση, χωρίς τα μυστικά. |
| GET | /taxonomy | Κατηγορίες, ετικέτες και ενδείξεις προσοχής, με τους κωδικούς τους. |
Σημεία πρόσβασης που χρειάζονται το διακριτικό
Αλλάζουν όσα είναι αποθηκευμένα, γι' αυτό κάθε αίτημα πρέπει να φέρει το διακριτικό στην κεφαλίδα Authorization. Η σελίδα του API τα δείχνει μόνο σε αίτημα που το φέρει.
| Μέθοδος | Διαδρομή | Τι κάνει |
|---|---|---|
| POST | /contacts | Προσθέτει μια επαφή: {"name": "...", "number": "...", "account_id": "..."}· το account_id είναι προαιρετικό. |
| PUT | /contacts/{id} | Αντικαθιστά μια επαφή. |
| DELETE | /contacts/{id} | Αφαιρεί μια επαφή. |
| DELETE | /history/{id} | Ξεχνά μία κλήση του ιστορικού κλήσεων. |
| DELETE | /history | Ξεχνά όλο το ιστορικό κλήσεων. Δεν αναιρείται. |
| PUT | /accounts/{id} | Αντικαθιστά τις ρυθμίσεις ενός λογαριασμού. Ο κωδικός πρόσβασης δεν είναι ανάμεσά τους. |
| PUT | /settings | Αντικαθιστά τις ρυθμίσεις. |
Κάθε αναγνωριστικό είναι ένα UUID που εκδίδει το τηλέφωνο: το id μιας κλήσης προέρχεται από το /calls ή από την απάντηση στο POST /calls, το id ενός λογαριασμού από το /accounts.
Τα ονόματα πεδίων είναι σε snake_case και η κατάληξη δείχνει τον τύπο: _id είναι αναφορά σε UUID, _ts είναι μια στιγμή σε χιλιοστά του δευτερολέπτου Unix (UTC), _s είναι διάρκεια σε δευτερόλεπτα. Το ίδιο ισχύει για τα webhooks· μόνο το /settings κρατά δικά του ονόματα. Στο REST API αυτές οι τιμές είναι αριθμοί JSON, και μια στιγμή που δεν είναι γνωστή είναι null.
Παράδειγμα: πραγματοποίηση κλήσης
Το POST /calls κάνει μια εξερχόμενη κλήση. Το σώμα είναι JSON με τον number που θα κληθεί και, προαιρετικά, το account_id του λογαριασμού από τον οποίο θα γίνει η κλήση:
curl --location 'http://127.0.0.1:8377/calls' \
--header 'Content-Type: application/json' \
--data '{
"number": "1020",
"account_id": "0d7a4c52-6f2e-4a51-8f46-7d9a3e1b2c90"
}'
Η απάντηση είναι το αναγνωριστικό της νέας κλήσης:
{ "id": "9a3e5c71-2d48-4b6f-8e10-3c5f7a1b9d24" }
- Το
numberείναι υποχρεωτικό. Χωρίς αυτό η απάντηση είναι400 {"error":"a call needs a number"}και δεν καλείται τίποτα. - Ο αριθμός συμπληρώνεται στον επιλεγμένο λογαριασμό με τον ίδιο τρόπο που τον συμπληρώνει το πεδίο κλήσης: το
1020στέλνεται ωςsip:1020@pbx.example.com. ΤοPOST /calls/{id}/transferσυμπληρώνει τοtargetτου με τον ίδιο τρόπο· ένας προορισμός που έχει ήδη σχήμα ή@στέλνεται όπως είναι. - Το
account_idείναι προαιρετικό· πάρτε το από τοGET /accounts. Χωρίς αυτό η κλήση γίνεται από τον λογαριασμό που είναι επιλεγμένος στο κύριο παράθυρο. - Χρησιμοποιήστε το
idστα/calls/{id}/…:hangup,hold,resume,dtmfκαιtransfer. Τα webhooks αυτής της κλήσης φέρουν το ίδιοid.
Από μια ιστοσελίδα: κλήση με ένα κλικ
Μια σελίδα που καλεί το 127.0.0.1 φτάνει στον υπολογιστή στον οποίο τρέχει ο φυλλομετρητής — τον ίδιο στον οποίο τρέχει και το τηλέφωνο — οπότε ένα κουμπί κλήσης με ένα κλικ σε ένα CRM δεν χρειάζεται δικό του διακομιστή:
async function dial(number) {
const r = await fetch("http://127.0.0.1:8377/calls", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ number }),
});
if (!r.ok) console.warn("softphone:", (await r.json()).error);
}
Τι περιέχουν οι απαντήσεις
Κλήσεις σε εξέλιξη: GET /calls
Κάθε κλήση έχει τα id, seance_id, account_id, direction, state, number, name, uri, dialed, muted, event_ts, callstart_ts και callstate_ts.
- Η
stateείναιdialing,ringing-out,ringing-in,active,hold(σε αναμονή από αυτό το τηλέφωνο),onhold(σε αναμονή από τον συνομιλητή),conferenceήended. Όταν ισχύουν περισσότερες από μία, τοconferenceυπερισχύει τουholdκαι τοholdτουonhold. - Το
mutedλέει αν το μικρόφωνο είναι σε σίγαση στην κλήση· η σίγαση δεν αλλάζει τηνstate. - Το
seance_idείναι η συνομιλία: οι κλήσεις που συνδέονται μέσω μεταφοράς, διαβούλευσης ή διάσκεψης το μοιράζονται. - Το
event_tsείναι η στιγμή που δόθηκε η απάντηση. Συγκρίνετέ το με τοcallstate_tsγια να δείτε πόση ώρα βρίσκεται η κλήση στην κατάστασή της, χωρίς να βασίζεστε στο δικό σας ρολόι.
Λογαριασμοί: GET /accounts
Κάθε λογαριασμός έχει το id του (το account_id σε όλα τα άλλα σημεία), τις ρυθμίσεις του — transport (udp, tcp ή tls), port, registrar, outbound_proxy, expiry_s και άλλες —, αν είναι enabled, και την state του στο τηλεφωνικό κέντρο: registered όσο η γραμμή είναι ενεργή. Οι κωδικοί δεν περιλαμβάνονται ποτέ.
Ιστορικό κλήσεων: GET /history
Με τις νεότερες πρώτες, 100 καταχωρίσεις εκτός αν το ?limit= ορίζει κάτι άλλο. Το ?missed=true επιστρέφει μόνο τις αναπάντητες κλήσεις, το ?declined=true μόνο τις κλήσεις που απέρριψε αυτό το τηλέφωνο.
| Πεδίο | Σημασία |
|---|---|
id | Το δικό της αναγνωριστικό της καταχώρισης ιστορικού. Δεν είναι το id της κλήσης του /calls και των webhooks· το seance_id συνδέει τα δύο. |
outcome | Η κύρια κατάταξη: answered, missed, declined ή failed. |
answered | true ή false. |
duration_s | 0 για μια κλήση που δεν συνδέθηκε ποτέ. |
number, uri | Ο συνομιλητής, ως αριθμός και ως διεύθυνση SIP. |
name | Από τις Επαφές, αν ο αριθμός είναι γνωστός, διαφορετικά κενό. Κάντε την αντιστοίχιση με το number, όχι με αυτό. |
dialed | Τα ψηφία που πληκτρολογήθηκαν, για μια εξερχόμενη κλήση· κενό για μια εισερχόμενη. |
account, account_id | Η γραμμή στην οποία ήταν η κλήση. |
reason | Πώς τελείωσε: local-hangup, remote-hangup, cancelled… |
answered_by | no αν απάντησε άνθρωπος· διαφορετικά τι απάντησε στην κλήση. |
Επαφές: GET /contacts
Κάθε επαφή έχει τα id, name, number και τη γραμμή στην οποία ανήκει, account_id και account· ένα κενό account σημαίνει ότι η επαφή δεν είναι δεμένη με γραμμή.
Εγγραφές
Οι εγγραφές και οι απομαγνητοφωνήσεις δεν δίνονται ως JSON. Το API τις εξυπηρετεί ως σελίδες HTML, /ui και /ui/recordings/{id}: βάλτε συνδέσμους προς αυτές τις σελίδες από το CRM σας αντί να μετακινείτε ήχο. Ο σύνδεσμος ανοίγει στον υπολογιστή που κρατά την εγγραφή, και ο ήχος δεν φεύγει ποτέ από αυτόν.
Ταξινομία και ρυθμίσεις
Κάθε καταχώριση του /taxonomy έχει έναν σταθερό code, έναν title και μια description στη γλώσσα της διεπαφής, ένα kind (category, tag ή red_flag) και, για τις ενδείξεις προσοχής, ένα severity. Κάντε την αντιστοίχιση με το code, ποτέ με το title: οι τίτλοι έρχονται στη γλώσσα που έχει ρυθμιστεί στο τηλέφωνο. Μια καταχώριση με retired: true διατηρείται ώστε οι παλαιότερες κλήσεις να εξακολουθούν να αντιστοιχίζονται· δεν δίνεται πλέον σε νέες κλήσεις. Φορτώστε την ταξινομία μία φορά κατά την εκκίνηση για να αντιστοιχίσετε τις λέξεις του τηλεφώνου στα δικά σας πεδία.
Το /settings επιστρέφει τη διαμόρφωση εκτός από τα μυστικά: συσκευές ήχου και εντάσεις, προτεραιότητα κωδικοποιητών, εμφάνιση και γλώσσα, εκκίνηση, συντομεύσεις, το επίπεδο διαγνωστικών και την κατάσταση και των δύο ενοποιήσεων — χρήσιμο για ένα εργαλείο υποστήριξης που πρέπει να ελέγξει έναν σταθμό εργασίας χωρίς κοινή χρήση οθόνης. Το api.disabled παραθέτει τις ομάδες πρόσβασης που είναι ανενεργές και το webhooks.silenced τα συμβάντα που είναι ανενεργά· κενές λίστες σημαίνουν ότι όλα είναι ενεργά. Δεν περιλαμβάνει ποτέ τον κωδικό SIP, το διακριτικό του API ή την τιμή της κεφαλίδας του webhook.
Σφάλματα
Κάθε σφάλμα είναι JSON με ένα μόνο κλειδί error, που προορίζεται για ανθρώπους, όχι για ανάλυση από πρόγραμμα.
| Κατάσταση | Σώμα | Σημασία |
|---|---|---|
| 404 | {"error":"no such endpoint"} | Η διαδρομή δεν υπάρχει ή η ομάδα πρόσβασής της είναι ανενεργή· και οι δύο περιπτώσεις δίνουν σκόπιμα την ίδια απάντηση. |
| 405 | {"error":"that endpoint does not take this method"} | Η διαδρομή υπάρχει, αλλά δεν δέχεται αυτή τη μέθοδο: για παράδειγμα POST /settings αντί για PUT. |
| 401 | {"error":"writing needs a token, and none is configured"} | Σημείο πρόσβασης που αλλάζει όσα είναι αποθηκευμένα, σε τηλέφωνο όπου το πεδίο Διακριτικό είναι κενό. Συμπληρώστε το στην ενότητα Τοπικός έλεγχος. |
| 401 | {"error":"this endpoint needs the authorization token"} | Σημείο πρόσβασης που αλλάζει όσα είναι αποθηκευμένα, χωρίς το σωστό διακριτικό. |
| 404 | {"error":"no contact with that id"} | Η διαδρομή είναι σωστή, το αναγνωριστικό όχι. |
| 400 | {"error":"no call with that id"} | Η κλήση έχει τελειώσει ή δεν υπήρξε ποτέ. |
| 400 | {"error":"a call needs a number"} | POST /calls χωρίς αριθμό. Δεν κλήθηκε τίποτα. |
| 400 | {"error":"no digits to send"} | POST /calls/{id}/dtmf χωρίς ψηφία. |
| 400 | {"error":"a transfer needs a target"} | POST /calls/{id}/transfer χωρίς προορισμό. |
| 400 | {"error":"the account this call is on is no longer set up"} | Ο λογαριασμός της κλήσης αφαιρέθηκε κατά τη διάρκεια της κλήσης, οπότε ο προορισμός δεν μπορεί να συμπληρωθεί. Δεν στάλθηκε τίποτα στο τηλεφωνικό κέντρο. |
Τα αιτήματα που απορρίφθηκαν μετρώνται στο api_requests_refused_total, ώστε μια ενοποίηση που αποτυγχάνει σιωπηλά να φαίνεται στις μετρικές, όχι μόνο στα δικά σας αρχεία καταγραφής.
Μετρικές
Το GET /metrics επιστρέφει κάθε μετρητή του τηλεφώνου, τον καθένα με ένα κείμενο βοήθειας. Συλλέξτε τους με το Prometheus ή διαβάστε τους με το χέρι.
| Μετρητής | Μετρά |
|---|---|
calls_incoming_total | Τις εισερχόμενες κλήσεις που λήφθηκαν. |
calls_outgoing_total | Τις εξερχόμενες κλήσεις που έγιναν. |
calls_answered_total | Τις κλήσεις που απαντήθηκαν. |
calls_missed_total | Τις εισερχόμενες κλήσεις που δεν απαντήθηκαν. |
calls_declined_total | Τις κλήσεις που απορρίφθηκαν εδώ ή από την άλλη πλευρά. |
calls_failed_total | Τις κλήσεις που δεν μπόρεσαν να αποκατασταθούν. |
registrations_succeeded_total | Τις επιτυχείς καταχωρίσεις SIP. |
registrations_failed_total | Τις καταχωρίσεις SIP που απορρίφθηκαν ή έληξαν χωρίς απάντηση. |
webhooks_delivered_total | Τα webhooks που αποδέχτηκε ο παραλήπτης. |
webhooks_failed_total | Τα webhooks που απορρίφθηκαν ή δεν παραδόθηκαν. |
webhooks_dropped_total | Τα webhooks που πετάχτηκαν επειδή η ουρά ήταν γεμάτη. |
api_requests_total | Τα αιτήματα που διεκπεραίωσε το API. |
api_requests_refused_total | Τα αιτήματα που απορρίφθηκαν: λάθος διακριτικό, ανενεργή ομάδα ή άγνωστη διαδρομή. |
Ενημέρωση μιας παλαιότερης ενοποίησης
Οι προηγούμενες εκδόσεις χρησιμοποιούσαν ονόματα σε camelCase και σύντομα αναγνωριστικά. Το accountId είναι τώρα account_id, το startedAt είναι callstart_ts, το durationSeconds είναι duration_s, το answeredBy είναι answered_by, και το πεδίο webhook at είναι event_ts. Οι κλήσεις και οι λογαριασμοί ταυτοποιούνται μόνο με UUID: το runtimeId και αναγνωριστικά όπως call-3 ή account-2 δεν επιστρέφονται ούτε γίνονται δεκτά πια.
Όταν δεν λειτουργεί
| Σύμπτωμα | Τι να ελέγξετε |
|---|---|
Η σύνδεση απορρίπτεται στο 127.0.0.1:8377 | Ο τοπικός έλεγχος είναι ανενεργός, το τηλέφωνο δεν τρέχει ή η θύρα άλλαξε. |
404 {"error":"no such endpoint"} για μια διαδρομή αυτής της σελίδας | Η ομάδα πρόσβασής της είναι ανενεργή. |
Η ανάγνωση λειτουργεί, η εγγραφή απορρίπτεται με 401 | Τα σημεία πρόσβασης που αλλάζουν αποθηκευμένα δεδομένα χρειάζονται το διακριτικό στην κεφαλίδα Authorization, και στο τηλέφωνο πρέπει πρώτα να συμπληρωθεί το πεδίο Διακριτικό. |
| Οι τίτλοι των κατηγοριών δεν είναι στα αγγλικά | Οι τίτλοι ακολουθούν τη γλώσσα της διεπαφής. Κάντε την αντιστοίχιση με το code από το /taxonomy. |
Λείπουν τα accountId, startedAt ή at | Η ενοποίηση γράφτηκε για τα παλαιότερα ονόματα· δείτε παραπάνω. |
Για ένα πρόβλημα με την καταχώριση ή με την ίδια την κλήση, ανοίξτε τα Διαγνωστικά.