საკუთარი PBX-ის API და MCP
Cenaly-ის საკუთარი PBX თქვენი პროგრამებისა და AI-ასისტენტებისთვის ღიაა:
- CRM, სააღრიცხვო სისტემა, საკუთარი საიტი — REST API: ზარების ჟურნალი, ჩანაწერები და ტრანსკრიფციები, დაწკაპუნებით ზარი, დამატებითი ნომრები, გადამისამართება, მეტრიკები, ზარების წესები, პარამეტრების ატვირთვა და ჩამოტვირთვა;
- Claude, ChatGPT, Cursor, VS Code, Perplexity — MCP-სერვერი: გასაღებით ან გასაღების გარეშე — შედიხართ საკუთარ ანგარიშში და წვდომას (OAuth) ნებას რთავთ;
- ზარების რეალურ დროში მოვლენები — ვებჰუკები თქვენს მისამართზე ხელმოწერით ან მოვლენების ნაკადი გამოკითხვით.
ყველაფერი ანგარიშის მფლობელის სახელით და მხოლოდ მის მიერ გაცემული უფლებებით მუშაობს. ყოველი ცვლილება PBX-ის მოქმედებების ჟურნალში ჩანს გასაღების ან აპლიკაციის სახელით.
სამი თემა#
| სტატია | რა არის მასში |
|---|---|
| საკუთარი PBX-ის REST API | ყველა მეთოდი უფლებებით, პარამეტრებითა და პასუხებით, შეცდომები, curl-ის მაგალითები, მზა სცენარები: ჟურნალი CSV-ში, CRM-დან click-to-call, ღამის რეჟიმი განრიგით |
| საკუთარი PBX-ის MCP-სერვერი | Claude Code-ის, Cursor-ის, VS Code-ის, Claude Desktop-ის გასაღებით და ღრუბლოვანი ასისტენტების OAuth-ით დაკავშირება, 33 ინსტრუმენტის კატალოგი, დიალოგების მაგალითები, JSON-RPC ხელით |
| ზარების მოვლენების ვებჰუკები | ვებჰუკის შექმნა, ყველა მოვლენის სხეულები, ხელმოწერის შემოწმება Node.js-ში, Python-ში, PHP-სა და Go-ში, გამეორებები და დუბლიკატები, ნაკადი საკუთარი სერვერის გარეშე, გამართვა |
მისამართები#
| რა | მისამართი |
|---|---|
| REST API | https://api.cenaly.ge/pbx-api/v1 |
| MCP-სერვერი (streamable HTTP) | https://api.cenaly.ge/pbx-api/mcp |
| მეთოდების დოკუმენტაცია | api.cenaly.ge/pbx-api/v1/docs |
| OpenAPI 3.1-ის აღწერა | api.cenaly.ge/pbx-api/v1/openapi.json |
| OAuth-ის მეტამონაცემები | https://api.cenaly.ge/.well-known/oauth-authorization-server/pbx-api |
მიერთებისთვის მზა მისამართები და ჩასასმელი კოდები არის ფანჯარაში ტელეფონია → API და MCP → როგორ მივუერთდეთ.
საკუთარი სატელეფონო სადგურის მქონე ობიექტში იმავე API-სა და MCP-ს თავად სადგურის სერვერიც ემსახურება — პირდაპირი მისამართი, ღრუბლის გვერდის ავლით: https://sip-<ობიექტის id>.cenaly.ge/pbx-api/v1 და …/pbx-api/mcp. ჟურნალი, ჩანაწერები, მოვლენები, ხელმისაწვდომობა, შიდა ნომრები, ზარი ერთი დაწკაპუნებით და ღია/დაკეტილი იქიდან პასუხობს; წესები, კონფიგურაცია, ვებჰუკები, მეტრიკები და ტრანსკრიფციები ღრუბელში რჩება (სადგური აბრუნებს 501 served_by_cloud-ს cloudUrl-ით). პირდაპირი მისამართი მხოლოდ გასაღებებს იღებს (OAuth — მხოლოდ ღრუბლის მისამართი). მზად არის თუ არა მისამართი, ჩანს ფანჯარაში «როგორ მივუერთდეთ» და ველში direct პასუხებში /v1/me და /v1/locations. ცხრილის მისამართები ყოველთვის მუშაობს — სარეზერვო გზად იმავე გასაღებით.
გასაღები და უფლებები#
გასაღებს ქმნის მხოლოდ ანგარიშის მფლობელი: ტელეფონია → API და MCP → გასაღებები → გასაღების შექმნა. თანამშრომელი როლით „სატელეფონო სადგურის ადმინისტრატორი“ გასაღებებს ვერ ხედავს — გასაღები მფლობელის სახელით მოქმედებს.
cpx_…ფორმატის გასაღები გამოჩნდება მხოლოდ ერთხელ — შექმნისთანავე, დასაკავშირებლად მზა ფრაგმენტებთან ერთად. ჩვენთან მხოლოდ მისი ანაბეჭდი (SHA-256) ინახება, გასაღების აღდგენა შეუძლებელია — მხოლოდ ახლის გამოშვება.- გასაღები შეგიძლიათ შეზღუდოთ ობიექტებით (სხვა შემთხვევაში — ყველა ობიექტი, მომავლის ჩათვლით) და ვადით (30, 90, 365 დღე ან უვადოდ).
- „უფლებები“ გასაღების უფლებებსა და ობიექტებს დაუყოვნებლივ ცვლის: ინტეგრაცია მუშაობას აგრძელებს, ახალი უფლებები შემდეგი მოთხოვნიდან მოქმედებს.
- „გაუქმება“ — დაუყოვნებლივ და სამუდამოდ: ამ გასაღებით შემდეგი მოთხოვნა მიიღებს 401-ს.
- აქტიური გასაღებებისა და კავშირების რაოდენობა — ანგარიშზე 20-მდე.
გასაღები გადაიცემა სათაურში Authorization: Bearer cpx_… (ან X-Api-Key: cpx_…) — არასოდეს მოთხოვნის მისამართში.
უფლებები აირჩევა მზა ნაკრებით ან მოსანიშნი ველებით:
| უფლება | რას იძლევა | ნაკრებები |
|---|---|---|
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-სერვერს https://api.cenaly.ge/pbx-api/mcp OAuth-ით უერთდებიან — გასაღების შექმნა საჭირო არ არის. თითოეულ კლიენტში სერვერის დამატების წესი მოცემულია სტატიაში საკუთარი PBX-ის MCP-სერვერი.
ასისტენტი Cenaly-ის შესვლის ფანჯარას გახსნის. შესვლის შემდეგ დაინახავთ:
- ვინ ითხოვს წვდომას — აპლიკაცია სახელდება პასუხის დასაბრუნებელი მისამართით: „შემოწმებული კონექტორი · chatgpt.com“ (ასევე claude.ai, perplexity.ai, vscode.dev, Cursor), „პროგრამა ამ კომპიუტერზე“ ან „უცნობი მისამართი“. აპლიკაციის მიერ გამოგზავნილი სახელი წვრილად ჩანს — მისი დაწერა ნებისმიერს შეუძლია;
- უფლებებს — მონიშნულია ის, რასაც აპლიკაცია ითხოვს; თუ ის „ყველაფერს“ ითხოვს, მონიშნულია „AI-ასისტენტი“. უფლებები ცალკე მონიშვნით წინასწარ არასოდეს მოინიშნება;
- წერტილებს — ყველას ან არჩეულებს.
„დაშვება“ ასისტენტში დაგაბრუნებთ და ის მაშინვე PBX-ის ინსტრუმენტებს დაინახავს. მიერთება ჩნდება ტელეფონია → API და MCP → გასაღებები-ში OAuth ნიშნითა და აპლიკაციის მისამართით — იქვე იცვლება უფლებები და უქმდება წვდომა. იმავე აპლიკაციის ხელახალი მიერთება მის უფლებებს აახლებს და მეორე მიერთებას არ ქმნის.
მიერთებების დაშვება მხოლოდ ანგარიშის მფლობელს შეუძლია.
OAuth საკუთარი კონექტორების დეველოპერებისთვის#
ავტორიზაციის სერვერი MCP-ის ავტორიზაციის სპეციფიკაციას მიჰყვება — გამოდგება ნებისმიერი კლიენტი, რომელიც მას მხარს უჭერს:
- MCP-ზე მოთხოვნა ტოკენის გარეშე იღებს 401-ს სათაურით
WWW-Authenticate: Bearer resource_metadata="https://api.cenaly.ge/.well-known/oauth-protected-resource/pbx-api/mcp". - რესურსის მეტამონაცემები (RFC 9728) ასახელებს ავტორიზაციის სერვერს —
https://api.cenaly.ge/pbx-api; მისი მეტამონაცემები (RFC 8414) — მისამართზეhttps://api.cenaly.ge/.well-known/oauth-authorization-server/pbx-api(და…/pbx-api/.well-known/openid-configuration). - კლიენტის დინამიკური რეგისტრაცია (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. - ავტორიზაციის კოდი PKCE-ით (მხოლოდ
S256):GET /pbx-api/oauth/authorize→ მფლობელის შესვლისა და თანხმობის ფანჯარა → დაბრუნება თქვენს მისამართზეcode,stateდაissპარამეტრებით. პარამეტრიresource— MCP-სერვერის მისამართი. - ტოკენები:
POST /pbx-api/oauth/token. კოდი ერთჯერადია და მოქმედებს 2 წუთი (არასწორიcode_verifierმას აუქმებს); წვდომის ტოკენი — 1 საათი; განახლების ტოკენი — 90 დღე, ყოველი განახლებისას ახალი გაიცემა, ძველი მუშაობას წყვეტს. - გაუქმება:
POST /pbx-api/oauth/revoke(RFC 7009) კავშირს მთლიანად აუქმებს — როგორც „გაუქმება“ ფანჯარაში „API და MCP“.
წვდომის ტოკენი ყველგან მიიღება, სადაც გასაღები: MCP-შიც და REST-შიც, მფლობელის მიერ დაშვებული უფლებებითა და ობიექტებით.
ლიმიტები და შეცდომები#
- ერთ გასაღებზე ან კავშირზე: 120 მოთხოვნა წუთში და 20 000 დღეში (REST და MCP ერთად).
- ერთი დაჭერით ზარი — ცალკე: 10 წუთში და 300 დღეში.
- ჟურნალი — მოთხოვნაზე 100-მდე ზარი; API ხედავს ობიექტის ბოლო 400 ზარს 90 დღის განმავლობაში.
- მოვლენების ზოლი — ობიექტის 2000-მდე მოვლენა 7 დღეში, პასუხზე 500-მდე.
| კოდი | შეცდომა | რა გააკეთოთ |
|---|---|---|
| 401 | api_key_missing, api_key_invalid |
გასაღები არ არის, გაუქმებულია ან ვადაგასულია; OAuth ტოკენს ვადა გაუვიდა — განაახლეთ |
| 403 | scope_required |
გასაღებს უფლება არ აქვს — დაამატეთ „უფლებებში“ |
| 400 | location_required |
გასაღებს რამდენიმე ობიექტი აქვს — გადასცით location |
| 404 | location_not_found |
ობიექტი არ არის ან გასაღები სხვა ობიექტებითაა შეზღუდული |
| 429 | rate_limited |
ლიმიტი ამოიწურა, გაიმეორეთ Retry-After წამის შემდეგ |
შეცდომების სრული ცხრილი — სტატიაში საკუთარი სატელეფონო სადგურის REST API.
უსაფრთხოება#
- გასაღები მხოლოდ ერთხელ ჩანს და ჩვენთან მხოლოდ ანაბეჭდის სახით ინახება; გაჟონილი გასაღები ერთი ღილაკით უქმდება.
- OAuth-კავშირს მხოლოდ მფლობელი უშვებს და ჩანს, რომელ მისამართს ენიჭება წვდომა; დაშვებული კავშირი შეგიძლიათ უფლებებითა და ობიექტებით შეზღუდოთ და ნებისმიერ დროს გააუქმოთ.
- ტელეფონის ნომრები თქვენი კლიენტების პერსონალური მონაცემებია: ჟურნალსა და ჩანაწერებზე უფლებები მხოლოდ იმ ინტეგრაციებს მიეცით, რომლებსაც ნამდვილად სჭირდება.
- გასაღებით ან კავშირით შესრულებული ყველა ცვლილება სადგურის მოქმედებების ჟურნალშია, გასაღების ან აპლიკაციის სახელით.
- ვებჰუკები საიდუმლო გასაღებითაა ხელმოწერილი: შეამოწმეთ თითოეული მოთხოვნის ხელმოწერა და არა გამგზავნის მისამართი — როგორ, სტატიაში ზარების მოვლენების ვებჰუკები.