API și MCP ale propriei centrale telefonice

Propria centrală telefonică Cenaly este deschisă pentru programele și asistenții dumneavoastră AI:

• CRM, sistem de evidență, propriul site — REST API: jurnal de apeluri, înregistrări și transcrieri, apel la un clic, posturi suplimentare, redirecționare, reguli de apelare;
• Claude Code, Claude Desktop, Cursor — server MCP la distanță prin cheie;
• ChatGPT, claude.ai, Perplexity, Cursor și VS Code — același server MCP fără cheie: vă autentificați în contul dumneavoastră și autorizați accesul (OAuth).

Totul funcționează în numele proprietarului contului și doar cu drepturile pe care acesta le-a acordat. Fiecare modificare este vizibilă în jurnalul de acțiuni al centralei telefonice, cu numele cheii sau al aplicației.

Adrese#

Cheia și drepturile#

Cheia este creată doar de proprietarul contului: Telefonie → API și MCP → Chei → Creează cheie. Un angajat cu rolul „Administrator al centralei telefonice” nu vede cheile — cheia acționează în numele proprietarului.

• Cheia de forma cpx_… este afișată o singură dată — imediat după creare, împreună cu fragmente gata de inserat pentru conectare. La noi se păstrează doar amprenta ei (SHA-256); cheia nu poate fi recuperată — doar emisă una nouă.
• Cheia poate fi limitată la puncte de lucru (altfel — toate punctele de lucru, inclusiv cele viitoare) și la un termen (30, 90, 365 de zile sau nelimitat).
• „Drepturi” modifică în timp real drepturile și punctele de lucru ale cheii: integrarea continuă să funcționeze, iar noile drepturi se aplică de la următoarea cerere.
• „Revocă” — imediat și definitiv: următoarea cerere cu această cheie va primi 401.
• Chei și conexiuni active — până la 20 per cont.

Drepturile se aleg printr-un set gata pregătit sau prin bife:

Drepturile care modifică ceva sau consumă minute sunt marcate cu chihlimbar în fereastră. Ultimele trei drepturi nu fac parte din niciun set, nici măcar din „Tot” — ele pot fi acordate doar în cunoștință de cauză, cu o bifă separată.

ChatGPT, claude.ai, Perplexity, Cursor, VS Code: conectare fără cheie#

Asistenții cloud nu pot insera o cheie în antet — ei conectează serverul MCP prin OAuth. Nu este nevoie să creați o cheie.

claude.ai: Setări → Conectori → Adaugă propriul conector → inserați https://api.cenaly.com/pbx-api/mcp → Conectare.

ChatGPT: Setări → Aplicații și conectori → Avansat → activați modul dezvoltator → Creează → inserați https://api.cenaly.com/pbx-api/mcp, autentificare — OAuth.

Perplexity: Setările contului → Conectori → „+ Conector propriu” → La distanță → inserați https://api.cenaly.com/pbx-api/mcp, autentificare — OAuth.

Cursor și VS Code: adăugați un server MCP la distanță (HTTP) cu adresa https://api.cenaly.com/pbx-api/mcp fără antet cu cheie — fereastra de autentificare se va deschide în browser. În Cursor: .cursor/mcp.json → {"mcpServers": {"cenaly-pbx": {"url": "https://api.cenaly.com/pbx-api/mcp"}}}; în VS Code: comanda „MCP: Add Server” → HTTP.

Apoi asistentul va deschide fereastra de autentificare Cenaly. După autentificare veți vedea:

• cine solicită accesul — aplicația este denumită după adresa către care va reveni răspunsul: „Conector verificat · chatgpt.com” (la fel — claude.ai, perplexity.ai, vscode.dev, Cursor), „Program de pe acest computer” sau avertismentul „Adresă necunoscută”. Numele trimis de aplicație este afișat cu caractere mici — oricine îl poate scrie;
• drepturile — sunt bifate cele solicitate de aplicație (dacă aceasta solicită „tot ce se poate”, este bifat setul „Asistent AI”); drepturile „doar cu bifă separată” nu sunt niciodată bifate în prealabil;
• punctele de lucru — toate sau cele selectate.

„Permite” vă readuce în asistent, iar acesta vede imediat instrumentele centralei telefonice. Conexiunea apare în Telefonie → API și MCP → Chei ca un rând cu eticheta OAuth și adresa aplicației — tot acolo se modifică drepturile și se revocă accesul. Reconectarea aceleiași aplicații îi actualizează drepturile, nu creează o a doua conexiune.

Doar proprietarul contului poate autoriza conexiuni.

Claude Code, Claude Desktop, Cursor: conectare prin cheie#

Claude Code — cu o singură comandă:

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

Claude Desktop, Cursor (.cursor/mcp.json) și alți clienți cu fișier de configurare:

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

Blocurile gata de inserat cu cheia dumneavoastră sunt afișate imediat după crearea cheii. Asistentul AI vede doar instrumentele permise de cheie și poate răspunde la „cine a sunat astăzi și nu a reușit să ajungă”, „sună-l înapoi pe acest client de pe telefonul Annei”, „activează-mi redirecționarea către mobil”.

REST API#

Cheia — în antetul Authorization: Bearer <cheie> (sau X-Api-Key). Dacă cheia are un singur punct de lucru, parametrul location poate fi omis; dacă are mai multe — răspunsul 400 location_required le va enumera.

Descrierea completă a câmpurilor — pe pagina documentației și în OpenAPI.

Cine a sunat astăzi și nu a reușit să ajungă:

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

Reapelarea unui client de pe telefonul postului suplimentar 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"

Metricile pentru septembrie cu comparație față de august și septembrie anul trecut — pentru propria panou 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"

În răspuns, metrics — aceleași cifre ca pe ecranul Telefonie → Jurnal apeluri → Analitică: apeluri primite, preluate și pierdute, nivelul de servire (pragul și ținta — din setările cozii), așteptarea medie și maximă, ponderea abandonate fără scurte, AHT, FCR, ponderea transferurilor și a botului, CSAT. compare.prev și compare.year — aceleași câmpuri pentru perioada anterioară și pentru aceeași perioadă de acum un an. Comparația cu anul trecut se calculează pentru perioade de până la 400 de zile.

Activarea redirecționării către mobil, dacă angajatul nu a răspuns în 15 secunde:

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"

Instrumente MCP#

Aceleași operațiuni ca la REST. Clientul vede doar instrumentele permise de cheie sau de conexiune:

Serverul funcționează fără sesiuni (streamable HTTP, JSON-RPC 2.0): initialize, tools/list, tools/call.

OAuth pentru dezvoltatorii propriilor conectori#

Serverul de autorizare respectă specificația de autorizare MCP — este potrivit orice client care o acceptă:

1. O cerere către MCP fără token primește 401 cu antetul WWW-Authenticate: Bearer resource_metadata="https://api.cenaly.com/.well-known/oauth-protected-resource/pbx-api/mcp".
2. Metadatele resursei (RFC 9728) indică serverul de autorizare — https://api.cenaly.com/pbx-api; metadatele acestuia (RFC 8414) sunt la adresa https://api.cenaly.com/.well-known/oauth-authorization-server/pbx-api (și …/pbx-api/.well-known/openid-configuration).
3. Înregistrare dinamică a clientului (RFC 7591): POST /pbx-api/oauth/register. Adresa de returnare — doar localhost / 127.0.0.1 (orice port) sau adresa unui conector cunoscut (claude.ai, claude.com, chatgpt.com, chat.openai.com, vscode.dev, www.perplexity.ai, enterprise.perplexity.ai; la Cursor — în plus exact cursor://anysphere.cursor-mcp/oauth/callback). Metoda de autentificare a clientului — none (client public), client_secret_post sau client_secret_basic.
4. Cod de autorizare cu PKCE (doar S256): GET /pbx-api/oauth/authorize → fereastra de autentificare și de consimțământ a proprietarului → revenire la adresa dumneavoastră cu code, state și iss. Parametrul resource — adresa serverului MCP.
5. Tokenuri: POST /pbx-api/oauth/token. Codul este de unică folosință și este valabil 2 minute (un code_verifier incorect îl anulează); tokenul de acces — 1 oră; tokenul de reînnoire — 90 de zile, la fiecare reînnoire se emite unul nou, iar cel vechi încetează să funcționeze.
6. Revocare: POST /pbx-api/oauth/revoke (RFC 7009) anulează conexiunea în întregime — ca „Revocare” în fereastra „API și MCP”.

Tokenul de acces este acceptat oriunde cheia: atât în MCP, cât și în REST, cu drepturile și punctele de lucru permise de proprietar.

Limite și erori#

• Per cheie sau conexiune: 120 de cereri pe minut și 20 000 pe zi (REST și MCP împreună).
• Apel în clic — separat: 10 pe minut și 300 pe zi.
• Jurnalul — până la 100 de apeluri per cerere; în jurnalul PBX al punctului de lucru — ultimele 400 de apeluri din 90 de zile.

Evenimente apel#

În timp real — webhook-uri ale centralei telefonice: Telefonie → API și MCP → Webhook-uri sau POST /v1/webhooks cu o cheie cu dreptul webhooks:write. La adresa dumneavoastră https ajunge în câteva secunde un POST pentru fiecare eveniment: call.started (a început: direcție, cine, către cine, linie), call.ringing (la cine sună — câte unul pentru fiecare telefon), call.answered (cine a răspuns), call.transferred (cine și către cine a transferat), call.ended (rezultat, durată, conversație, cine a răspuns). Webhook-ul poate fi limitat la puncte de lucru și tipuri de evenimente.

{ "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": "Анна" } } }

Semnătura — antetul X-Cenaly-Signature: t=<timp unix>,v1=<HMAC-SHA256 din "t.corp" cu secretul webhook-ului>. Recalculați, comparați în timp constant și respingeți t mai vechi de 5 minute. Secretul whsec_… este afișat o singură dată; „Secret nou” îl anulează imediat pe cel anterior.

Livrarea — răspundeți 2xx în 10 secunde. Altfel reluăm cu pauze de 10 s, 30 s, 2, 5, 10, 15 și 15 minute (8 încercări, circa o oră); reluarea poartă același id — după el eliminați duplicatele. Jurnalul livrărilor (codul răspunsului, ora, încercarea) — în fereastra webhook-ului și GET /v1/webhooks/{id}/deliveries; „Verifică” trimite un webhook.ping de serviciu. Adresa timp de 3 zile consecutive nu a acceptat nicio livrare — webhook-ul se dezactivează singur: proprietarul primește un e-mail, în fereastra „Webhook-uri” apare mențiunea „Dezactivat automat” și butonul „Activează” (sau PATCH /v1/webhooks/{id} cu { "enabled": true }).

Fără server propriu — aceeași listă prin interogare: GET /v1/events?since=<id-ul ultimului eveniment> sau instrumentul MCP get_call_events (evenimentele punctului de lucru din ultimele 7 zile, până la 2000; per răspuns — până la 500, more: true — continuați cu același since).

După procesarea înregistrării — apelul cu transcriere și analiză ajunge prin webhook-ul sursei „Webhook” în secțiunea „Apeluri”.

„Deschis / închis” — PUT /v1/open-closed cu { "closed": true } închide punctul de lucru până la sfârșitul zilei (ca *28 de la telefon: apelurile merg după regulile „în afara orelor”), false — îl deschide; GET arată dacă este închis și de către cine. Cu "until" — închis până la acel moment (nu mai mult de 30 de zile), apoi se deschide singur: ora fără decalaj (2026-10-05T09:00) este citită în fusul punctului de lucru; false îl anulează și pe acesta. Este nevoie de bifa activată „Închidere cu codul *28” în rutare (altfel 409).

Securitate#

• Cheia este afișată o singură dată și este păstrată la noi doar ca amprentă; o cheie compromisă se revocă printr-un singur buton.
• Conexiunea OAuth este permisă doar de proprietar și se vede către ce adresă pleacă accesul; o conexiune permisă poate fi limitată la drepturi și puncte de lucru și revocată în orice moment.
• Numerele de telefon sunt date personale ale clienților dumneavoastră: acordați drepturi asupra jurnalului și înregistrărilor doar acelor integrări care le necesită cu adevărat.
• Toate modificările prin cheie sau conexiune — în jurnalul de acțiuni al centralei telefonice, cu numele cheii sau al aplicației.