API и MCP своей АТС

Своя АТС Cenaly открыта для ваших программ и ИИ-ассистентов:

• CRM, учётная система, свой сайт — REST API: журнал звонков, записи и расшифровки, звонок в клик, добавочные, переадресация, метрики, правила звонков, выгрузка и загрузка настроек;
• Claude, ChatGPT, Cursor, VS Code, Perplexity — MCP-сервер: по ключу или без ключа — вы входите в свой аккаунт и разрешаете доступ (OAuth);
• события звонков в реальном времени — вебхуки на ваш адрес с подписью или лента событий опросом.

Всё работает от имени владельца аккаунта и только с правами, которые он выдал. Каждое изменение видно в журнале действий АТС с названием ключа или приложения.

Три темы#

Адреса#

Готовые адреса и вставки для подключения — в окне Телефония → API и MCP → Как подключить.

У точки со своей АТС запросы смогут идти прямо на сервер АТС, минуя облако. API уже сообщает, готов ли такой адрес, — поле direct в /v1/me и /v1/locations. Пока эта возможность внедряется, используйте адреса из таблицы: они остаются рабочими и как запасной путь.

Ключ и права#

Ключ создаёт только владелец аккаунта: Телефония → API и MCP → Ключи → Создать ключ. Сотрудник с ролью «Администратор АТС» ключей не видит — ключ действует от имени владельца.

• Ключ вида cpx_… показывается один раз — сразу после создания, вместе с готовыми вставками для подключения. У нас хранится только его отпечаток (SHA-256), восстановить ключ нельзя — только выпустить новый.
• Ключ можно ограничить точками (иначе — все точки, включая будущие) и сроком (30, 90, 365 дней или бессрочно).
• «Права» меняют права и точки ключа на лету: интеграция продолжает работать, новые права действуют со следующего запроса.
• «Отозвать» — сразу и навсегда: следующий запрос с этим ключом получит 401.
• Живых ключей и подключений — до 20 на аккаунт.

Ключ передаётся в заголовке Authorization: Bearer cpx_… (или X-Api-Key: cpx_…) — никогда в адресе запроса.

Права выбираются готовым набором или галками:

Права, которые что-то меняют или тратят минуты, в окне помечены янтарным. Пять последних прав не входят ни в один набор, даже во «Всё» — их можно дать только осознанно, отдельной галкой.

ChatGPT, claude.ai, Perplexity, Cursor, VS Code: подключение без ключа#

Облачные ассистенты подключают MCP-сервер https://api.cenaly.ru/pbx-api/mcp по OAuth — ключ создавать не нужно. Где в каждом клиенте добавить сервер — в статье MCP-сервер своей АТС.

Ассистент откроет окно входа Cenaly. После входа вы увидите:

• кто просит доступ — приложение называется по адресу, куда вернётся ответ: «Проверенный коннектор · chatgpt.com» (так же — claude.ai, perplexity.ai, vscode.dev, Cursor), «Программа на этом компьютере» или предупреждение «Незнакомый адрес». Название, которое прислало приложение, показано мелко — его может написать кто угодно;
• права — отмечено то, что просит приложение (если оно просит «всё подряд», отмечен набор «ИИ-ассистент»); права «только отдельной галкой» заранее не отмечаются никогда;
• точки — все или выбранные.

«Разрешить» возвращает вас в ассистента, и он сразу видит инструменты АТС. Подключение появляется в Телефония → API и MCP → Ключи строкой с меткой OAuth и адресом приложения — там же меняются права и отзывается доступ. Повторное подключение того же приложения обновляет его права, а не заводит второе подключение.

Разрешать подключения может только владелец аккаунта.

OAuth для разработчиков своих коннекторов#

Сервер авторизации следует спецификации авторизации MCP — подойдёт любой клиент, который её поддерживает:

1. Запрос к MCP без токена получает 401 с заголовком WWW-Authenticate: Bearer resource_metadata="https://api.cenaly.ru/.well-known/oauth-protected-resource/pbx-api/mcp".
2. Метаданные ресурса (RFC 9728) называют сервер авторизации — https://api.cenaly.ru/pbx-api; его метаданные (RFC 8414) — по адресу https://api.cenaly.ru/.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 звонков за запрос; API видит последние 400 звонков точки за 90 дней.
• Лента событий — до 2000 событий точки за 7 дней, до 500 за ответ.

Полная таблица ошибок — в статье REST API своей АТС.

Безопасность#

• Ключ показывается один раз и хранится у нас только отпечатком; утёкший ключ отзывается одной кнопкой.
• OAuth-подключение разрешает только владелец, и видно, какому адресу уходит доступ; разрешённое подключение можно ограничить правами и точками и отозвать в любой момент.
• Номера телефонов — персональные данные ваших клиентов: давайте права на журнал и записи только тем интеграциям, которым они действительно нужны.
• Все изменения по ключу или подключению — в журнале действий АТС с названием ключа или приложения.
• Вебхуки подписаны секретом: проверяйте подпись каждого запроса, а не адрес отправителя — как именно, в статье Вебхуки событий звонков.