API και MCP του δικού σας τηλεφωνικού κέντρου

Το δικό σας τηλεφωνικό κέντρο Cenaly είναι ανοιχτό στα προγράμματά σας και στους βοηθούς AI:

• CRM, λογιστικό σύστημα, δικός σας ιστότοπος — REST API: αρχείο κλήσεων, καταγραφές και απομαγνητοφωνήσεις, κλήση με ένα κλικ, εσωτερικά, προώθηση, κανόνες κλήσεων;
• Claude Code, Claude Desktop, Cursor — απομακρυσμένος διακομιστής MCP με κλειδί;
• ChatGPT, claude.ai, Perplexity, Cursor και VS Code — ο ίδιος διακομιστής MCP χωρίς κλειδί: συνδέεστε στον λογαριασμό σας και παραχωρείτε πρόσβαση (OAuth).

Όλα λειτουργούν για λογαριασμό του κατόχου του λογαριασμού και μόνο με τα δικαιώματα που έχει παραχωρήσει. Κάθε αλλαγή είναι ορατή στο αρχείο ενεργειών του τηλεφωνικού κέντρου με το όνομα του κλειδιού ή της εφαρμογής.

Διευθύνσεις#

Κλειδί και δικαιώματα#

Το κλειδί το δημιουργεί μόνο ο κάτοχος του λογαριασμού: Τηλεφωνία → API και MCP → Κλειδιά → Δημιουργία κλειδιού. Ο υπάλληλος με ρόλο «Διαχειριστής τηλεφωνικού κέντρου» δεν βλέπει κλειδιά — το κλειδί ενεργεί για λογαριασμό του κατόχου.

• Το κλειδί της μορφής cpx_… εμφανίζεται μία φορά — αμέσως μετά τη δημιουργία, μαζί με έτοιμα αποσπάσματα για σύνδεση. Από εμάς αποθηκεύεται μόνο το αποτύπωμά του (SHA-256), το κλειδί δεν μπορεί να ανακτηθεί — μόνο να εκδοθεί νέο.
• Το κλειδί μπορεί να περιοριστεί σε καταστήματα (διαφορετικά — όλα τα καταστήματα, συμπεριλαμβανομένων των μελλοντικών) και σε διάρκεια (30, 90, 365 ημέρες ή αόριστα).
• Τα «Δικαιώματα» αλλάζουν τα δικαιώματα και τα καταστήματα του κλειδιού άμεσα: η ενσωμάτωση συνεχίζει να λειτουργεί, τα νέα δικαιώματα ισχύουν από το επόμενο αίτημα.
• «Ανάκληση» — αμέσως και οριστικά: το επόμενο αίτημα με αυτό το κλειδί θα λάβει 401.
• Ενεργά κλειδιά και συνδέσεις — έως 20 ανά λογαριασμό.

Τα δικαιώματα επιλέγονται με έτοιμο σύνολο ή με πλαίσια επιλογής:

Τα δικαιώματα που αλλάζουν κάτι ή καταναλώνουν λεπτά επισημαίνονται στο παράθυρο με πορτοκαλί χρώμα. Τα τρία τελευταία δικαιώματα δεν ανήκουν σε κανένα σύνολο, ούτε στο «Όλα» — μπορούν να δοθούν μόνο συνειδητά, με ξεχωριστό πλαίσιο επιλογής.

ChatGPT, claude.ai, Perplexity, Cursor, VS Code: σύνδεση χωρίς κλειδί#

Οι βοηθοί cloud δεν μπορούν να εισάγουν κλειδί στην κεφαλίδα — συνδέουν τον διακομιστή MCP μέσω OAuth. Δεν χρειάζεται να δημιουργήσετε κλειδί.

claude.ai: Ρυθμίσεις → Σύνδεσμοι → Προσθήκη δικού σας συνδέσμου → επικολλήστε https://api.cenaly.com/pbx-api/mcp → Σύνδεση.

ChatGPT: Ρυθμίσεις → Εφαρμογές και σύνδεσμοι → Για προχωρημένους → ενεργοποιήστε τη λειτουργία προγραμματιστή → Δημιουργία → επικολλήστε https://api.cenaly.com/pbx-api/mcp, έλεγχος ταυτότητας — OAuth.

Perplexity: Ρυθμίσεις λογαριασμού → Σύνδεσμοι → «+ Δικός σας σύνδεσμος» → Απομακρυσμένος → επικολλήστε https://api.cenaly.com/pbx-api/mcp, έλεγχος ταυτότητας — OAuth.

Cursor και VS Code: προσθέστε απομακρυσμένο (HTTP) διακομιστή MCP με διεύθυνση https://api.cenaly.com/pbx-api/mcp χωρίς κεφαλίδα με κλειδί — το παράθυρο σύνδεσης θα ανοίξει στο πρόγραμμα περιήγησης. Στο Cursor: .cursor/mcp.json → {"mcpServers": {"cenaly-pbx": {"url": "https://api.cenaly.com/pbx-api/mcp"}}}; στο VS Code: εντολή «MCP: Add Server» → HTTP.

Στη συνέχεια ο βοηθός θα ανοίξει το παράθυρο σύνδεσης του Cenaly. Μετά τη σύνδεση θα δείτε:

• ποιος ζητά πρόσβαση — η εφαρμογή ονομάζεται από τη διεύθυνση στην οποία θα επιστραφεί η απάντηση: «Επαληθευμένος σύνδεσμος · chatgpt.com» (το ίδιο — claude.ai, perplexity.ai, vscode.dev, Cursor), «Πρόγραμμα σε αυτόν τον υπολογιστή» ή προειδοποίηση «Άγνωστη διεύθυνση». Το όνομα που έστειλε η εφαρμογή εμφανίζεται με μικρά γράμματα — μπορεί να το γράψει οποιοσδήποτε;
• δικαιώματα — σημειώνεται αυτό που ζητά η εφαρμογή (αν ζητά «τα πάντα», σημειώνεται το σύνολο «Βοηθός AI»); τα δικαιώματα «μόνο με ξεχωριστό πλαίσιο επιλογής» δεν σημειώνονται ποτέ εκ των προτέρων;
• καταστήματα — όλα ή επιλεγμένα.

Το «Αποδοχή» σας επιστρέφει στον βοηθό και αυτός βλέπει αμέσως τα εργαλεία του τηλεφωνικού κέντρου. Η σύνδεση εμφανίζεται στο Τηλεφωνία → API και MCP → Κλειδιά ως γραμμή με ένδειξη OAuth και τη διεύθυνση της εφαρμογής — εκεί αλλάζουν και τα δικαιώματα και ανακαλείται η πρόσβαση. Η εκ νέου σύνδεση της ίδιας εφαρμογής ενημερώνει τα δικαιώματά της και δεν δημιουργεί δεύτερη σύνδεση.

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

Claude Code, Claude Desktop, Cursor: σύνδεση με κλειδί#

Claude Code — με μία εντολή:

claude mcp add --transport http telephony https://api.cenaly.com/pbx-api/mcp --header "Authorization: Bearer cpx_…"

Claude Desktop, Cursor (.cursor/mcp.json) και άλλοι πελάτες με αρχείο ρυθμίσεων:

{
  "mcpServers": {
    "telephony": {
      "type": "http",
      "url": "https://api.cenaly.com/pbx-api/mcp",
      "headers": { "Authorization": "Bearer cpx_…" }
    }
  }
}

Έτοιμα αποσπάσματα με το κλειδί σας εμφανίζονται αμέσως μετά τη δημιουργία του κλειδιού. Ο Βοηθός AI βλέπει μόνο τα εργαλεία που επιτρέπει το κλειδί και μπορεί να απαντήσει σε «ποιος τηλεφώνησε σήμερα και δεν απαντήθηκε», «κάλεσε πίσω αυτόν τον επισκέπτη από το τηλέφωνο της Άννας», «ενεργοποίησέ μου την προώθηση στο κινητό».

REST API#

Το κλειδί — στην κεφαλίδα Authorization: Bearer <κλειδί> (ή X-Api-Key). Αν το κλειδί έχει ένα Κατάστημα, η παράμετρος location μπορεί να μη μεταδοθεί· αν έχει πολλά — η απάντηση 400 location_required θα τα απαριθμήσει.

Πλήρης περιγραφή πεδίων — στη σελίδα τεκμηρίωσης και στο OpenAPI.

Ποιος τηλεφώνησε σήμερα και δεν απαντήθηκε:

curl -H "Authorization: Bearer cpx_…" \
  "https://api.cenaly.com/pbx-api/v1/calls?status=missed&since=$(date -u +%Y-%m-%dT00:00:00Z)"

Επανάκληση πελάτη από το τηλέφωνο του εσωτερικού 101:

curl -X POST -H "Authorization: Bearer cpx_…" -H "Content-Type: application/json" \
  -d '{"extension":"101","number":"+995555123456"}' "https://api.cenaly.com/pbx-api/v1/dial"

Μετρικές για τον Σεπτέμβριο με σύγκριση με τον Αύγουστο και τον Σεπτέμβριο του προηγούμενου έτους — για το δικό σας πίνακα BI:

curl -H "Authorization: Bearer cpx_…" \
  "https://api.cenaly.com/pbx-api/v1/metrics?from=2026-09-01&to=2026-09-30&compare=prev,year"

Στην απάντηση metrics — τα ίδια νούμερα όπως στην οθόνη Τηλεφωνία → Αρχείο κλήσεων → Αναλυτικά: εισερχόμενες, απαντημένες και χαμένες, επίπεδο εξυπηρέτησης (όριο και στόχος — από τις ρυθμίσεις της ουράς), μέση και μέγιστη αναμονή, ποσοστό εγκαταλελειμμένων χωρίς σύντομες, AHT, FCR, ποσοστό μεταφορών και bot, CSAT. compare.prev και compare.year — τα ίδια πεδία για την προηγούμενη περίοδο και για την ίδια περίοδο πριν από ένα έτος. Η σύγκριση με το προηγούμενο έτος υπολογίζεται για περιόδους έως 400 ημέρες.

Ενεργοποίηση προώθησης στο κινητό, αν ο συνεργάτης δεν απαντήσει σε 15 δευτερόλεπτα:

curl -X PUT -H "Authorization: Bearer cpx_…" -H "Content-Type: application/json" \
  -d '{"forward":{"noAnswer":{"kind":"number","number":"+995599000111"},"noAnswerSec":15}}' \
  "https://api.cenaly.com/pbx-api/v1/extensions/101/forwarding"

Εργαλεία MCP#

Οι ίδιες λειτουργίες με το REST. Ο πελάτης βλέπει μόνο τα εργαλεία που επιτρέπονται από το κλειδί ή τη σύνδεση:

Ο διακομιστής λειτουργεί χωρίς συνεδρίες (streamable HTTP, JSON-RPC 2.0): initialize, tools/list, tools/call.

OAuth για προγραμματιστές δικών τους συνδέσμων#

Ο διακομιστής εξουσιοδότησης ακολουθεί την προδιαγραφή εξουσιοδότησης MCP — κάνει οποιοσδήποτε πελάτης την υποστηρίζει:

1. Αίτημα προς το MCP χωρίς token λαμβάνει 401 με κεφαλίδα WWW-Authenticate: Bearer resource_metadata="https://api.cenaly.com/.well-known/oauth-protected-resource/pbx-api/mcp".
2. Τα μεταδεδομένα πόρου (RFC 9728) ονομάζουν τον διακομιστή εξουσιοδότησης — https://api.cenaly.com/pbx-api; τα μεταδεδομένα του (RFC 8414) — στη διεύθυνση https://api.cenaly.com/.well-known/oauth-authorization-server/pbx-api (και …/pbx-api/.well-known/openid-configuration).
3. Δυναμική εγγραφή πελάτη (RFC 7591): POST /pbx-api/oauth/register. Διεύθυνση επιστροφής — μόνο localhost / 127.0.0.1 (οποιαδήποτε θύρα) ή διεύθυνση γνωστού συνδέσμου (claude.ai, claude.com, chatgpt.com, chat.openai.com, vscode.dev, www.perplexity.ai, enterprise.perplexity.ai; για το Cursor — επιπλέον ακριβώς cursor://anysphere.cursor-mcp/oauth/callback). Μέθοδος σύνδεσης πελάτη — none (δημόσιος πελάτης), client_secret_post ή client_secret_basic.
4. Κωδικός εξουσιοδότησης με PKCE (μόνο S256): GET /pbx-api/oauth/authorize → παράθυρο σύνδεσης και συγκατάθεσης του ιδιοκτήτη → επιστροφή στη διεύθυνσή σας με code, state και iss. Η παράμετρος resource — η διεύθυνση του διακομιστή MCP.
5. Tokens: POST /pbx-api/oauth/token. Ο κωδικός είναι μίας χρήσης και ισχύει 2 λεπτά (λάθος code_verifier τον ακυρώνει)· το token πρόσβασης — 1 ώρα· το token ανανέωσης — 90 ημέρες, σε κάθε ανανέωση εκδίδεται νέο, το προηγούμενο παύει να λειτουργεί.
6. Ανάκληση: POST /pbx-api/oauth/revoke (RFC 7009) ακυρώνει τη σύνδεση στο σύνολό της — όπως το «Ανάκληση» στο παράθυρο «API και MCP».

Το token πρόσβασης γίνεται δεκτό παντού όπου το κλειδί: και στο MCP και στο REST, με τα δικαιώματα και τα καταστήματα που επέτρεψε ο ιδιοκτήτης.

Όρια και σφάλματα#

• Ανά κλειδί ή σύνδεση: 120 αιτήματα το λεπτό και 20 000 την ημέρα (REST και MCP μαζί).
• Κλήση με ένα κλικ — ξεχωριστά: 10 το λεπτό και 300 την ημέρα.
• Το αρχείο καταγραφής — έως 100 κλήσεις ανά αίτημα· στο αρχείο καταγραφής του τηλεφωνικού κέντρου των καταστημάτων — οι τελευταίες 400 κλήσεις σε 90 ημέρες.

Συμβάντα κλήσεων#

Σε πραγματικό χρόνο — webhooks της τηλεφωνίας: Τηλεφωνία → API και MCP → Webhooks ή POST /v1/webhooks με κλειδί που έχει το δικαίωμα webhooks:write. Στη διεύθυνση https σας φτάνει μέσα σε δευτερόλεπτα ένα POST για κάθε συμβάν: call.started (ξεκίνησε: κατεύθυνση, ποιος, πού, γραμμή), call.ringing (σε ποιον χτυπάει — ένα ανά τηλέφωνο), call.answered (ποιος απάντησε), call.transferred (ποιος και σε ποιον έκανε προώθηση), call.ended (αποτέλεσμα, διάρκεια, συνομιλία, ποιος απάντησε). Το webhook μπορεί να περιοριστεί σε καταστήματα και τύπους συμβάντων.

{ "id": "1727771234.56:2", "type": "call.answered", "createdAt": "2026-10-01T10:00:05Z",
  "locationId": "…", "webhookId": "wh_…", "attempt": 1,
  "data": { "callId": "1727771234.56", "seq": 2, "direction": "inbound",
            "from": { "number": "+995555123456" }, "party": { "extension": "101", "name": "Άννα" } } }

Υπογραφή — κεφαλίδα X-Cenaly-Signature: t=<χρόνος unix>,v1=<HMAC-SHA256 του "t.σώμα" με το μυστικό του webhook>. Επανυπολογίστε, συγκρίνετε σε σταθερό χρόνο και απορρίψτε t παλαιότερο των 5 λεπτών. Το μυστικό whsec_… εμφανίζεται μία φορά· το «Νέο μυστικό» ακυρώνει αμέσως το προηγούμενο.

Παράδοση — απαντήστε 2xx εντός 10 δευτερολέπτων. Διαφορετικά επαναλαμβάνουμε με παύσεις 10 δευτ., 30 δευτ., 2, 5, 10, 15 και 15 λεπτών (8 προσπάθειες, περίπου μία ώρα)· η επανάληψη φέρει το ίδιο id — με αυτό απορρίπτετε τα διπλότυπα. Το αρχείο παραδόσεων (κωδικός απάντησης, χρόνος, προσπάθεια) — στο παράθυρο του webhook και στο GET /v1/webhooks/{id}/deliveries· το «Έλεγχος» στέλνει το υπηρεσιακό webhook.ping. Αν η διεύθυνση δεν δεχτεί καμία παράδοση για 3 συνεχόμενες ημέρες — το webhook απενεργοποιείται μόνο του: ο ιδιοκτήτης λαμβάνει email, στο παράθυρο «Webhooks» — η ένδειξη «Απενεργοποιήθηκε αυτόματα» και το κουμπί «Ενεργοποίηση» (ή PATCH /v1/webhooks/{id} με { "enabled": true }).

Χωρίς δικό σας διακομιστή — η ίδια ροή με polling: GET /v1/events?since=<id τελευταίου συμβάντος> ή το εργαλείο MCP get_call_events (συμβάντα καταστήματος των τελευταίων 7 ημερών, έως 2000· ανά απάντηση — έως 500, more: true — συνεχίστε με το ίδιο since).

Μετά την επεξεργασία της καταγραφής — η κλήση με απομαγνητοφώνηση και ανάλυση φτάνει με webhook της πηγής «Webhook» στην ενότητα «Κλήσεις».

«Ανοιχτό / κλειστό» — το PUT /v1/open-closed με { "closed": true } κλείνει το κατάστημα μέχρι το τέλος της ημέρας (όπως το *28 από το τηλέφωνο: οι κλήσεις ακολουθούν τους κανόνες «εκτός ωραρίου»), το false — το ανοίγει· το GET δείχνει αν είναι κλειστό και από ποιον. Με "until" — κλειστό μέχρι αυτή τη στιγμή (όχι πάνω από 30 ημέρες), μετά ανοίγει μόνο του: ο χρόνος χωρίς μετατόπιση (2026-10-05T09:00) διαβάζεται στη ζώνη ώρας του καταστήματος· το false το αίρει και αυτό. Απαιτείται ενεργοποιημένο το πλαίσιο «Κλείσιμο με κωδικό *28» στη δρομολόγηση (διαφορετικά 409).

Ασφάλεια#

• Το κλειδί εμφανίζεται μία φορά και αποθηκεύεται σε εμάς μόνο ως αποτύπωμα· ένα κλειδί που διέρρευσε ανακαλείται με ένα κουμπί.
• Τη σύνδεση OAuth την επιτρέπει μόνο ο ιδιοκτήτης, και φαίνεται σε ποια διεύθυνση πηγαίνει η πρόσβαση· μια εγκεκριμένη σύνδεση μπορεί να περιοριστεί σε δικαιώματα και καταστήματα και να ανακληθεί οποιαδήποτε στιγμή.
• Οι αριθμοί τηλεφώνου είναι προσωπικά δεδομένα των πελατών σας: δίνετε δικαιώματα στο αρχείο καταγραφής και στις καταγραφές μόνο στις ενσωματώσεις που τα χρειάζονται πραγματικά.
• Όλες οι αλλαγές μέσω κλειδιού ή σύνδεσης — στο αρχείο ενεργειών της τηλεφωνίας με το όνομα του κλειδιού ή της εφαρμογής.