Μετάβαση στο κύριο περιεχόμενο

Τοπικό REST API

Το AI Softphone διαθέτει ένα REST API για ενοποίηση CTI: ένα πρόγραμμα στον ίδιο υπολογιστή μπορεί να κάνει και να ελέγχει κλήσεις, να διαβάζει επαφές, ιστορικό κλήσεων και λογαριασμούς SIP, και να παρακολουθεί τις κλήσεις σε εξέλιξη. Χωρίς SDK, χωρίς ενδιάμεσο στο cloud και χωρίς ακροατή εκτεθειμένο στο δίκτυο. Τα αιτήματα και οι απαντήσεις είναι JSON, οπότε αρκεί το curl ή οποιοσδήποτε πελάτης HTTP.

Το API είναι ανενεργό μετά την εγκατάσταση· τίποτα δεν ακούει μέχρι να το ενεργοποιήσετε. Τότε ακούει μόνο στη διεπαφή loopback — μια μικρή διαδικτυακή διεπαφή που απαντά μόνο σε αυτόν τον υπολογιστή — και δεν είναι προσβάσιμο από το δίκτυο του γραφείου, από VPN ή από άλλο μηχάνημα.

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

Ενεργοποίηση​

Ανοίξτε τις Ρυθμίσεις → Ενσωμάτωση και πηγαίνετε στον Τοπικό έλεγχο.

  1. Ενεργοποιήστε το Επίτρεψε σε άλλα προγράμματα αυτού του υπολογιστή να χειρίζονται το τηλέφωνο. Ο διακομιστής ξεκινά αμέσως.
  2. Κρατήστε την προεπιλεγμένη Θύρα, 8377, εκτός αν τη χρησιμοποιεί ήδη άλλο πρόγραμμα.
  3. Προαιρετικά ορίστε ένα Διακριτικό. Μόλις αποθηκευτεί, το πεδίο δείχνει Αποθηκευμένο — πληκτρολογήστε για αντικατάσταση.
  4. Στην Πρόσβαση, επιλέξτε τις ομάδες που θα ανοίξουν: Επαφές, Ιστορικό κλήσεων, Κλήσεις και ο χειρισμός τους, Λογαριασμοί, Ρυθμίσεις, Μετρητές (οι μετρικές). Μια ανενεργή ομάδα δεν φιλτράρεται απλώς, αλλά δεν εξυπηρετείται καθόλου.
  5. Δοκιμάστε το: 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.
answeredtrue ή false.
duration_s0 για μια κλήση που δεν συνδέθηκε ποτέ.
number, uriΟ συνομιλητής, ως αριθμός και ως διεύθυνση SIP.
nameΑπό τις Επαφές, αν ο αριθμός είναι γνωστός, διαφορετικά κενό. Κάντε την αντιστοίχιση με το number, όχι με αυτό.
dialedΤα ψηφία που πληκτρολογήθηκαν, για μια εξερχόμενη κλήση· κενό για μια εισερχόμενη.
account, account_idΗ γραμμή στην οποία ήταν η κλήση.
reasonΠώς τελείωσε: local-hangup, remote-hangup, cancelled…
answered_byno αν απάντησε άνθρωπος· διαφορετικά τι απάντησε στην κλήση.

Επαφές: 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Η ενοποίηση γράφτηκε για τα παλαιότερα ονόματα· δείτε παραπάνω.

Για ένα πρόβλημα με την καταχώριση ή με την ίδια την κλήση, ανοίξτε τα Διαγνωστικά.