C cenaly.com
Тегін бастау

Жеке АТС-тің API және MCP қызметі

Кілттер мен құқықтар, REST API, Claude және Cursor үшін MCP-сервер, кілтсіз OAuth арқылы ChatGPT және claude.ai қосу, мысалдар, шектеулер және қателер

10 min read Админ-панельдің демо нұсқасы
On this page 10

Өз АТС-іңіздің API және MCP

Өз АТС Cenaly бағдарламаларыңыз бен AI-ассистенттеріңізге ашық:

  • CRM, есеп жүйесі, өз сайтыңыз — REST API: қоңыраулар журналы, жазбалар мен транскрипттер, бір басумен қоңырау шалу, қосымша нөмірлер, қайта бағыттау, қоңырау ережелері;
  • Claude Code, Claude Desktop, Cursor — кілт арқылы қашықтағы MCP-сервер;
  • ChatGPT, claude.ai, Perplexity, Cursor және VS Code — сол MCP-сервер кілтсіз: тіркелгіңізге кіріп, рұқсат бересіз (OAuth).

Барлығы тіркелгі иесінің атынан және ол берген құқықтармен ғана жұмыс істейді. Әрбір өзгеріс АТС әрекеттер журналында кілттің немесе қолданбаның атауымен көрінеді.

Мекенжайлар#

Не Мекенжай
REST API https://api.cenaly.com/pbx-api/v1
MCP-сервер (streamable HTTP) https://api.cenaly.com/pbx-api/mcp
Әдістер бойынша құжаттама api.cenaly.com/pbx-api/v1/docs
OpenAPI 3.1 сипаттамасы api.cenaly.com/pbx-api/v1/openapi.json
OAuth метадеректері https://api.cenaly.com/.well-known/oauth-authorization-server/pbx-api

Кілт және құқықтар#

Кілтті тек тіркелгі иесі жасай алады: Телефония → API және MCP → Кілттер → Кілт жасау. «АТС әкімшісі» рөліндегі қызметкер кілттерді көрмейді — кілт тіркелгі иесінің атынан әрекет етеді.

  • cpx_… түріндегі кілт бір рет көрсетіледі — жасалғаннан кейін бірден, қосылуға дайын үзінділермен бірге. Бізде тек оның ізтаңбасы (SHA-256) сақталады, кілтті қалпына келтіру мүмкін емес — тек жаңасын шығаруға болады.
  • Кілтті филиалдармен (әйтпесе — барлық филиалдар, соның ішінде болашақтағылары) және мерзіммен (30, 90, 365 күн немесе мерзімсіз) шектеуге болады.
  • «Құқықтар» кілттің құқықтары мен филиалдарын лезде өзгертеді: интеграциялар жұмысын жалғастырады, жаңа құқықтар келесі сұраныстан бастап әрекет етеді.
  • «Қайтарып алу» — бірден және біржола: осы кілтпен келесі сұраныс 401 алады.
  • Тірі кілттер мен қосылымдар — тіркелгіге 20-ға дейін.

Құқықтар дайын жинақпен немесе құсбелгілермен таңдалады:

Құқық Не береді Жинақтар
calls:read қоңыраулар журналы және маршруты бар қоңырау карточкасы CRM, AI-ассистент, тек оқу, барлығы
recordings:read әңгіме жазбасына сілтеме (10 минут) және транскрипт CRM, AI-ассистент, тек оқу, барлығы
calls:dial бір басумен қоңырау шалу: алдымен қызметкердің телефоны шырылдайды, жауап бергеннен кейін АТС нөмірді тереді CRM, AI-ассистент, барлығы
extensions:read қосымша нөмірлер, топтар, қайта бағыттау, «мазаламаңыз» CRM, AI-ассистент, тек оқу, барлығы
extensions:write жеке қайта бағыттауды және «мазаламаңыз» күйін өзгерту AI-ассистент, барлығы
presence:read кім бос, кім шырылдап тұр, кім сөйлесіп тұр AI-ассистент, тек оқу, барлығы
reports:read кезең бойынша колл-орталық метрикалары: қызмет көрсету деңгейі, күту, тасталған қоңыраулар, AHT, FCR, CSAT, қоңырауларды қайда жоғалтамыз, кезектер, желілер, қызметкерлер бойынша бөліністер тек оқу, барлығы
routes:read нөмірлер, кіріс және шығыс ережелері, ережелер тарихы тек оқу, барлығы
routes:write қоңырау ережелерін жасау, өзгерту, жою және қайта реттеу, тарихтан қайтару тек жеке құсбелгімен
config:export АТС параметрлерін файл форматында шығару тек жеке құсбелгімен
config:import параметрлерді кестелерден жүктеу: алдын ала қарау, содан кейін қолдану тек жеке құсбелгімен
webhooks:write қоңырау оқиғаларының вебхуктарын құру, өзгерту, тексеру және жою тек жеке құсбелгімен
daynight:write филиалды тәулік соңына дейін немесе белгілі бір күнге дейін жабу, ашу — телефоннан *28 істегенмен бірдей тек жеке құсбелгімен

Бірдеңені өзгертетін немесе минут жұмсайтын құқықтар терезеде янтарь түспен белгіленген. Соңғы үш құқық ешбір жинаққа кірмейді, тіпті «Барлығына» да — оларды тек саналы түрде, жеке құсбелгімен беруге болады.

ChatGPT, claude.ai, Perplexity, Cursor, VS Code: кілтсіз қосылу#

Бұлттық ассистенттер кілтті тақырыпшаға кірістіре алмайды — олар 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: https://api.cenaly.com/pbx-api/mcp мекенжайымен қашықтағы (HTTP) 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_…" }
    }
  }
}

Кілтіңіз қойылған дайын үзінділер кілт жасалғаннан кейін бірден көрсетіледі. Көмекші тек кілт рұқсат еткен құралдарды көреді және «бүгін кім қоңырау шалып, хабарласа алмады», «Аннаның телефонынан осы қонаққа қайта қоңырау шал», «маған ұялы телефонға қайта бағыттауды қос» деген сұрақтарға жауап бере алады.

REST API#

Кілт — Authorization: Bearer <кілт> тақырыбында (немесе X-Api-Key). Кілтте бір филиал болса, location параметрін бермеуге болады; бірнешеу болса — 400 location_required жауабы оларды тізіп береді.

Әдіс Жол Құқық Не істейді
GET /v1/me — кілттің құқықтары, филиалдары және лимиттері
GET /v1/locations — кілттің филиалдары және олардың АТС
GET /v1/calls calls:read қоңыраулар журналы: since, until, direction, status (answered, missed, ai), number, extension, limit 100-ге дейін, cursor
GET /v1/calls/{id} calls:read маршрутымен қоңырау: қай ереже іске қосылды, кімнің телефоны шалды, кім жауап берді
GET /v1/calls/{id}/recording recordings:read жазбаға 10 минутқа сілтеме
GET /v1/calls/{id}/transcript recordings:read әңгіменің транскрипті және қорытындысы
POST /v1/dial calls:dial бір басумен қоңырау: { "extension": "101", "number": "+995555123456" }
GET /v1/dial/{commandId} calls:dial бір басумен қоңыраудың барысы
GET /v1/extensions extensions:read қосымша нөмірлер, топтар, қайта бағыттау, «мазаламаңыз»
PUT /v1/extensions/{ext}/forwarding extensions:write қосымша нөмірдің жеке қайта бағыттауы
PUT /v1/extensions/{ext}/dnd extensions:write «мазаламаңыз»: { "on": true }
GET /v1/presence presence:read дәл қазір кім бос
GET /v1/metrics reports:read колл-орталықтың кезеңдегі метрикалары: from, to (филиалдың жергілікті күндері YYYY-MM-DD, әдепкі — соңғы 7 күн), compare (prev, year, prev,year немесе бос), sections (metrics,loss,queues,lines,operators,directions,heatmap,daily), callbacks=true — қайта қоңырау жылдамдығы да
GET /v1/routes routes:read нөмірлер, кіріс және шығыс ережелері
GET /v1/routes/history routes:read ережелердің өзгеру тарихы
POST, PUT, DELETE /v1/routes/inbound…, /v1/routes/outbound… routes:write қоңырау ережелерін бір-бірлеп: жасау, берілген өрістерді өзгерту, жою, орнын ауыстыру, қайтару
GET, POST /v1/config/export, /v1/config/import config:export, config:import баптаулар файл форматында; жүктеу — алдын ала қарау, содан кейін қолдану
GET /v1/events calls:read филиалдың 7 күндегі қоңырау оқиғалары (2000-ға дейін): since (оқиға id-і немесе уақыт), types, limit (бір жауапта 500-ге дейін)
GET, POST, PATCH, DELETE /v1/webhooks… webhooks:write вебхуктер: тізім, жасау, өзгерту, жою; …/rotate-secret, …/test, …/deliveries
GET, PUT /v1/open-closed routes:read, daynight:write жабық па және қашанға дейін; тәулік соңына дейін жабу { "closed": true }, күнге дейін { "closed": true, "until": "2026-10-05T09:00" } немесе ашу

Өрістердің толық сипаттамасы — құжаттама бетінде және 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, аударымдар мен боттың үлесі, 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 сияқты операциялар. Клиент тек кілтпен немесе қосылыммен рұқсат етілген құралдарды көреді:

Құралдар Құқық
list_locations —
list_calls, get_call calls:read
get_call_recording, get_call_transcript recordings:read
call_number, get_dial_status calls:dial
list_extensions extensions:read
set_forwarding, set_do_not_disturb extensions:write
get_presence presence:read
get_call_metrics reports:read
list_routes, list_route_history routes:read
save_inbound_rule, delete_inbound_rule, move_inbound_rule, save_outbound_rule, delete_outbound_rule, move_outbound_rule, set_outbound_calls, restore_route_version routes:write
export_config config:export
import_config config:import
get_call_events calls:read
list_webhooks, save_webhook, delete_webhook, rotate_webhook_secret, test_webhook, list_webhook_deliveries webhooks:write
get_open_closed routes:read
set_open_closed daynight:write

Сервер сессиясыз жұмыс істейді (streamable HTTP, JSON-RPC 2.0): initialize, tools/list, tools/call.

Өз коннекторларын жасаушыларға арналған OAuth#

Авторизация сервері MCP авторизация спецификациясына сәйкес келеді — оны қолдайтын кез келген клиент жарайды:

  1. Токенсіз MCP-ге сұрау 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. Токендер: POST /pbx-api/oauth/token. Код бір реттік және 2 минут тұрады (қате code_verifier оны жояды); қатынау токені — 1 сағат; жаңарту токені — 90 күн, әр жаңартуда жаңасы беріледі, алдыңғысы жұмысын тоқтатады.
  6. Қайтарып алу: POST /pbx-api/oauth/revoke (RFC 7009) қосылымды толығымен жояды — «API и MCP» терезесіндегі «Отозвать» сияқты.

Қатынау токені кілт қолданылатын барлық жерде қабылданады: MCP-де де, REST-те де, иесі рұқсат еткен құқықтармен және филиалдармен.

Лимиттер мен қателер#

  • Кілтке немесе қосылымға: минутына 120 сұрау және тәулігіне 20 000 (REST пен MCP бірге).
  • Бір басумен қоңырау шалу — бөлек: минутына 10 және тәулігіне 300.
  • Журнал — сұрауға 100 қоңырауға дейін; АТС филиалының журналында — 90 күндегі соңғы 400 қоңырау.
Код Қате Не істеу керек
401 api_key_missing, api_key_invalid кілт жоқ, ол қайтарып алынған немесе мерзімі біткен; OAuth токенінің мерзімі біткен — оны жаңартыңыз
403 scope_required кілтте құқық жоқ — оны «Права» бөлімінде қосыңыз
400 location_required кілтте бірнеше филиал бар — location жіберіңіз
404 location_not_found филиал жоқ немесе кілт басқа филиалдармен шектелген
429 rate_limited лимит таусылды, Retry-After секундтан кейін қайталаңыз

Қоңырау оқиғалары#

Нақты уақытта — АТС вебхуктары: Телефония → API және MCP → Вебхуктар немесе webhooks:write құқығы бар кілтпен POST /v1/webhooks. Сіздің https мекенжайыңызға әр оқиға үшін бірнеше секунд ішінде POST келеді: call.started (басталды: бағыты, кім, қайда, желі), call.ringing (кімде шырылдап тұр — әр телефонға бір-бірден), call.answered (кім жауап берді), call.transferred (кім және кімге ауыстырды), call.ended (қорытынды, ұзақтығы, әңгіме, кім жауап берді). Вебхукты филиалдармен және оқиға түрлерімен шектеуге болады.

{ "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=<вебхук секретімен "t.дене" үшін HMAC-SHA256> тақырыбы. Қайта есептеп, тұрақты уақытта салыстырыңыз және 5 минуттан асқан t мәнін қабылдамаңыз. whsec_… секреті бір рет көрсетіледі; «Жаңа секрет» алдыңғысын бірден жояды.

Жеткізу — 10 секунд ішінде 2xx деп жауап беріңіз. Әйтпесе 10 с, 30 с, 2, 5, 10, 15 және 15 минут үзілістермен қайталаймыз (8 әрекет, шамамен бір сағат); қайталау сол id мәнін алып жүреді — соған қарап қайталамаларды сүзіп тастаңыз. Жеткізу журналы (жауап коды, уақыты, әрекет) — вебхук терезесінде және GET /v1/webhooks/{id}/deliveries; «Тексеру» қызметтік webhook.ping жібереді. Мекенжай 3 тәулік қатарынан бірде-бір жеткізуді қабылдамаса — вебхук өзі өшеді: иесіне хат келеді, «Вебхуктар» терезесінде «Автоматты түрде өшірілді» белгісі және «Қосу» түймесі (немесе { "enabled": true } мәнімен PATCH /v1/webhooks/{id}) пайда болады.

Өз серверіңіз болмаса — сол лентаны сұрау арқылы алыңыз: GET /v1/events?since=<соңғы оқиғаның id> немесе MCP құралы get_call_events (филиалдың соңғы 7 күндегі оқиғалары, 2000-ға дейін; бір жауапта — 500-ге дейін, more: true — сол since мәнімен әрі қарай парақтаңыз).

Жазбаны өңдегеннен кейін — транскрипті және талдауы бар қоңырау «Қоңыраулар» бөліміндегі «Вебхук» көзінің вебхугымен келеді.

«Ашық / жабық» — { "closed": true } мәнімен PUT /v1/open-closed филиалды тәулік соңына дейін жабады (телефоннан *28 сияқты: қоңыраулар «жұмыс уақытынан тыс» ережелерімен жүреді), false — ашады; GET жабық па және кім жабқанын көрсетеді. "until" мәнімен — сол сәтке дейін жабық (30 күннен аспайды), кейін өзі ашылады: ығысуы жоқ уақыт (2026-10-05T09:00) филиалдың белдеуінде оқылады; false оны да алып тастайды. Маршруттауда «*28 кодымен жабу» құсбелгісі қосулы болуы керек (әйтпесе 409).

Қауіпсіздік#

  • Кілт бір рет көрсетіледі және бізде тек із ретінде сақталады; тарап кеткен кілт бір түймемен қайтарып алынады.
  • OAuth қосылымына тек иесі рұқсат ете алады және қай мекенжайға қатынау кететіні көрінеді; рұқсат етілген қосылымды құқықтармен және филиалдармен шектеуге және кез келген сәтте қайтарып алуға болады.
  • Телефон нөмірлері — сіздің клиенттеріңіздің дербес деректері: журнал мен жазбаларға құқықты оларға шынымен қажет интеграцияларға ғана беріңіз.
  • Кілт немесе қосылым бойынша барлық өзгерістер АТС әрекеттер журналында кілттің немесе қолданбаның атауымен тіркеледі.
Was this article helpful?
PBX & call handling
Қонақ мәзірінің демо нұсқасы Тегін бастау