API dhe MCP i centralit tuaj telefonik

Centrali tuaj telefonik Cenaly është i hapur për programet tuaja dhe asistentët AI:

• CRM, sistemi i kontabilitetit, faqja tuaj — REST API: regjistri i telefonatave, regjistrimet dhe transkriptimet, telefonata me një klik, numrat e brendshëm, devijimi i telefonatave, rregullat e telefonatave;
• Claude Code, Claude Desktop, Cursor — server MCP në distancë me çelës;
• ChatGPT, claude.ai, Perplexity, Cursor dhe VS Code — i njëjti server MCP pa çelës: ju hyni në llogarinë tuaj dhe autorizoni aksesin (OAuth).

Gjithçka funksionon në emër të pronarit të llogarisë dhe vetëm me të drejtat që ai ka dhënë. Çdo ndryshim shihet në regjistrin e veprimeve të centralit telefonik me emrin e çelësit ose të aplikacionit.

Adresat#

Çelësi dhe të drejtat#

Çelësin e krijon vetëm pronari i llogarisë: Telefonia → API dhe MCP → Çelësat → Krijo çelës. Punonjësi me rolin «Administrator i centralit telefonik» nuk i sheh çelësat — çelësi vepron në emër të pronarit.

• Çelësi i formës cpx_… shfaqet vetëm një herë — menjëherë pas krijimit, bashkë me copëzat e gatshme për t'u futur për lidhjen. Tek ne ruhet vetëm gjurma e tij (SHA-256), çelësi nuk mund të rikthehet — vetëm të lëshohet një i ri.
• Çelësi mund të kufizohet me njësi (përndryshe — të gjitha njësitë, përfshirë ato të ardhshme) dhe me afat (30, 90, 365 ditë ose pa afat).
• «Të drejtat» ndryshojnë të drejtat dhe njësitë e çelësit në çast: integrimi vazhdon të funksionojë, të drejtat e reja hyjnë në fuqi nga kërkesa e radhës.
• «Anulo» — menjëherë dhe përgjithmonë: kërkesa e radhës me këtë çelës merr 401.
• Çelësat dhe lidhjet aktive — deri në 20 për llogari.

Të drejtat zgjidhen me një grup të gatshëm ose me shenja:

Të drejtat që ndryshojnë diçka ose harxhojnë minuta, në dritare shënohen me ngjyrë qelibari. Tri të drejtat e fundit nuk bëjnë pjesë në asnjë grup, as në «Të gjitha» — ato mund të jepen vetëm me vetëdije, me shenjë të veçantë.

ChatGPT, claude.ai, Perplexity, Cursor, VS Code: lidhje pa çelës#

Asistentët në re nuk dinë të fusin çelësin në kokë — ata lidhin serverin MCP me OAuth. Nuk është e nevojshme të krijohet çelës.

claude.ai: Cilësimet → Konektorët → Shto konektorin tënd → futeni https://api.cenaly.com/pbx-api/mcp → Lidh.

ChatGPT: Cilësimet → Aplikacionet dhe konektorët → Të avancuara → aktivizoni modalitetin e zhvilluesit → Krijo → futeni https://api.cenaly.com/pbx-api/mcp, vërtetimi — OAuth.

Perplexity: Cilësimet e llogarisë → Konektorët → «+ Konektori yt» → Në distancë → futeni https://api.cenaly.com/pbx-api/mcp, vërtetimi — OAuth.

Cursor dhe VS Code: shtoni një server MCP në distancë (HTTP) me adresën https://api.cenaly.com/pbx-api/mcp pa kokë me çelës — dritarja e hyrjes hapet në shfletues. Në Cursor: .cursor/mcp.json → {"mcpServers": {"cenaly-pbx": {"url": "https://api.cenaly.com/pbx-api/mcp"}}}; në VS Code: komanda «MCP: Add Server» → HTTP.

Më pas asistenti hap dritaren e hyrjes së Cenaly. Pas hyrjes do të shihni:

• kush kërkon akses — aplikacioni emërtohet sipas adresës ku do të kthehet përgjigja: «Konektor i verifikuar · chatgpt.com» (po ashtu — claude.ai, perplexity.ai, vscode.dev, Cursor), «Program në këtë kompjuter» ose paralajmërimin «Adresë e panjohur». Emri që ka dërguar aplikacioni shfaqet i vogël — atë mund ta shkruajë kushdo;
• të drejtat — shënohet ajo që kërkon aplikacioni (nëse kërkon «gjithçka radhazi», shënohet grupi «Asistenti AI»); të drejtat «vetëm me shenjë të veçantë» nuk shënohen kurrë paraprakisht;
• njësitë — të gjitha ose të zgjedhurat.

«Autorizo» ju kthen te asistenti, dhe ai menjëherë sheh instrumentet e centralit telefonik. Lidhja shfaqet në Telefonia → API dhe MCP → Çelësat si një rresht me etiketën OAuth dhe adresën e aplikacionit — aty ndryshohen edhe të drejtat dhe anulohet aksesi. Lidhja e përsëritur e të njëjtit aplikacion përditëson të drejtat e tij, nuk krijon një lidhje të dytë.

Lidhjet mund t'i autorizojë vetëm pronari i llogarisë.

Claude Code, Claude Desktop, Cursor: lidhja me çelës#

Claude Code — me një komandë:

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

Claude Desktop, Cursor (.cursor/mcp.json) dhe klientë të tjerë me skedar cilësimesh:

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

Fragmente të gatshme me çelësin tuaj shfaqen menjëherë pas krijimit të çelësit. Asistenti AI sheh vetëm mjetet e lejuara nga çelësi dhe mund t'u përgjigjet pyetjeve si "kush ka telefonuar sot dhe nuk është përgjigjur", "telefonoji përsëri këtij klienti nga telefoni i Anës", "më aktivizo devijimin në celular".

REST API#

Çelësi — në titullin Authorization: Bearer <ключ> (ose X-Api-Key). Nëse çelësi ka një njësi, parametri location mund të mos dërgohet; nëse ka disa — përgjigja 400 location_required do t'i listojë ato.

Përshkrimi i plotë i fushave — në faqen e dokumentacionit dhe në OpenAPI.

Kush ka telefonuar sot dhe nuk është përgjigjur:

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

Telefonoji përsëri klientit nga telefoni i numrit të brendshëm 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"

Metrikat për shtatorin me krahasim me gushtin dhe shtatorin e vitit të kaluar — për panelin tuaj 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ë përgjigjen metrics — të njëjtat shifra si në ekranin Telefonia → Regjistri i telefonatave → Analitika: hyrjet, të pranuara dhe të humbura, niveli i shërbimit (pragu dhe objektivi — nga cilësimet e radhës), pritja mesatare dhe maksimale, përqindja e braktisjeve pa bisedë të shkurtër, AHT, FCR, përqindja e transferimeve dhe e botit, CSAT. compare.prev dhe compare.year — të njëjtat fusha për periudhën e kaluar dhe për të njëjtën periudhë një vit më parë. Krahasimi me vitin e kaluar llogaritet për periudha deri në 400 ditë.

Aktivizo devijimin në celular, nëse punonjësi nuk përgjigjet brenda 15 sekondave:

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"

Mjetet MCP#

Të njëjtat veprime si në REST. Klienti shikon vetëm mjetet e lejuara nga çelësi ose lidhja:

Serveri punon pa sesione (streamable HTTP, JSON-RPC 2.0): initialize, tools/list, tools/call.

OAuth për zhvilluesit e konnektorëve të vet#

Serveri i autorizimit ndjek specifikimin e autorizimit MCP — përshtatet çdo klient që e mbështet atë:

1. Kërkesa drejt MCP pa token merr 401 me kokën WWW-Authenticate: Bearer resource_metadata="https://api.cenaly.com/.well-known/oauth-protected-resource/pbx-api/mcp".
2. Metadhanat e burimit (RFC 9728) tregojnë serverin e autorizimit — https://api.cenaly.com/pbx-api; metadhanat e tij (RFC 8414) — në adresën https://api.cenaly.com/.well-known/oauth-authorization-server/pbx-api (dhe …/pbx-api/.well-known/openid-configuration).
3. Regjistrim dinamik i klientit (RFC 7591): POST /pbx-api/oauth/register. Adresa e kthimit — vetëm localhost / 127.0.0.1 (çdo port) ose adresa e një konnektori të njohur (claude.ai, claude.com, chatgpt.com, chat.openai.com, vscode.dev, www.perplexity.ai, enterprise.perplexity.ai; për Cursor — gjithashtu saktësisht cursor://anysphere.cursor-mcp/oauth/callback). Mënyra e hyrjes së klientit — none (klient publik), client_secret_post ose client_secret_basic.
4. Kodi i autorizimit me PKCE (vetëm S256): GET /pbx-api/oauth/authorize → dritarja e hyrjes dhe e pëlqimit të pronarit → kthim në adresën tuaj me code, state dhe iss. Parametri resource — adresa e serverit MCP.
5. Tokenët: POST /pbx-api/oauth/token. Kodi është njëpërdorimësh dhe zgjat 2 minuta (code_verifier i gabuar e fik atë); tokeni i hyrjes — 1 orë; tokeni i rifreskimit — 90 ditë, në çdo rifreskim lëshohet një i ri, i mëparshmi pushon së punuari.
6. Anulimi: POST /pbx-api/oauth/revoke (RFC 7009) fik lidhjen tërësisht — si «Anulo» në dritaren «API dhe MCP».

Tokeni i hyrjes pranohet kudo ku pranohet çelësi: si në MCP, ashtu edhe në REST, me të drejtat dhe njësitë që lejoi pronari.

Kufizimet dhe gabimet#

• Për çelës ose lidhje: 120 kërkesa në minutë dhe 20 000 në ditë (REST dhe MCP bashkë).
• Thirrja me një klik — veçmas: 10 në minutë dhe 300 në ditë.
• Regjistri — deri në 100 thirrje për kërkesë; në regjistrin e centralit të njësisë — 400 thirrjet e fundit gjatë 90 ditëve.

Ngjarjet e thirrjeve#

Në kohë reale — webhook-et e centralit telefonik: Telefonia → API dhe MCP → Webhook-et ose POST /v1/webhooks me një çelës me të drejtën webhooks:write. Në adresën tuaj https vjen brenda sekondash një POST për çdo ngjarje: call.started (filloi: drejtimi, kush, ku, linja), call.ringing (tek kush po zile — nga një për çdo telefon), call.answered (kush u përgjigj), call.transferred (kush dhe kujt e transferoi), call.ended (rezultati, kohëzgjatja, biseda, kush u përgjigj). Webhook-u mund të kufizohet sipas njësive dhe llojeve të ngjarjeve.

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

Nënshkrimi — kreu X-Cenaly-Signature: t=<koha unix>,v1=<HMAC-SHA256 nga "t.trupi" me sekretin e webhook-ut>. Rillogaritni, krahasoni në kohë konstante dhe refuzoni t më të vjetër se 5 minuta. Sekreti whsec_… shfaqet një herë; «Sekret i ri» e shuan menjëherë atë të mëparshmin.

Dërgimi — përgjigjuni 2xx brenda 10 sekondave. Përndryshe ripërpiqemi me pauza 10 s, 30 s, 2, 5, 10, 15 dhe 15 minuta (8 përpjekje, rreth një orë); ripërpjekja mban të njëjtin id — sipas tij hidhni dublikatat. Regjistri i dërgimeve (kodi i përgjigjes, koha, përpjekja) — në dritaren e webhook-ut dhe GET /v1/webhooks/{id}/deliveries; «Kontrollo» dërgon webhook.ping të shërbimit. Adresa nuk pranoi asnjë dërgim për 3 ditë rresht — webhook-u fiket vetë: pronarit i vjen një email, në dritaren «Webhook-et» — shënimi «Fikur automatikisht» dhe butoni «Aktivizo» (ose PATCH /v1/webhooks/{id} me { "enabled": true }).

Pa serverin tuaj — i njëjti fluks me anketim: GET /v1/events?since=<id e ngjarjes së fundit> ose mjeti MCP get_call_events (ngjarjet e njësisë për 7 ditët e fundit, deri në 2000; për përgjigje — deri në 500, more: true — vazhdoni më tej me të njëjtin since).

Pas përpunimit të regjistrimit — thirrja me transkriptim dhe analizë vjen me webhook nga burimi «Webhook» në seksionin «Thirrjet».

«Hapur / mbyllur» — PUT /v1/open-closed me { "closed": true } mbyll njësinë deri në fund të ditës (si *28 nga telefoni: thirrjet shkojnë me rregullat «jashtë orarit»), false — e hap; GET tregon nëse është e mbyllur dhe nga kush. Me "until" — e mbyllur deri në atë moment (jo më shumë se 30 ditë), pastaj hapet vetë: koha pa zhvendosje (2026-10-05T09:00) lexohet në zonën e njësisë; false e heq edhe atë. Kërkohet kutia e shënuar «Mbyll me kodin *28» në rrugëtim (përndryshe 409).

Siguria#

• Çelësi shfaqet një herë dhe ruhet te ne vetëm si gjurmë; një çelës i rrjedhur revokohet me një buton.
• Lidhjen OAuth e autorizon vetëm pronari, dhe shihet se në cilën adresë shkon aksesi; lidhja e autorizuar mund të kufizohet sipas të drejtave dhe njësive dhe të revokohet në çdo moment.
• Numrat e telefonit janë të dhëna personale të klientëve tuaj: jepni të drejta për regjistrin dhe regjistrimet vetëm atyre integrimeve që i kanë vërtet të nevojshme.
• Të gjitha ndryshimet me çelës ose lidhje — në regjistrin e veprimeve të centralit telefonik me emrin e çelësit ose të aplikacionit.