Ключи API

Ключ API нужен для подключения CRM, собственного скрипта или ИИ-ассистента к SmartDialogue. Система с ключом может читать диалоги, отвечать клиентам, пополнять базу знаний и работать с контактами в пределах выданных прав. Пароль вашей учётной записи ей не нужен.

Для внешнего ИИ-ассистента по MCP также предусмотрен вход через OAuth: вы разрешаете доступ в кабинете, а ассистент получает отдельный токен. Этот способ по умолчанию доступен во всех компаниях.

Где это

Откройте «Настройки» из меню профиля в правом верхнем углу. Найдите карточку «Ключи API» и нажмите «Открыть»: список ключей появится в отдельном окне. Прямая ссылка сразу открывает это окно после входа в кабинет.

Карточка «Подключённые приложения» открывает отдельное окно OAuth-доступов. Окна закрываются крестиком, кнопкой «Закрыть» или Esc; клик по фону их не закрывает.

В окне показаны действующие ключи в двух списках:

• «Мои ключи» — ключи, которые выпустили вы;
• «Ключи команды» — ключи остальных участников компании. Этот список видят только администратор и владелец, и только если у коллег есть ключи.

Архив ключей

Отозванные ключи и ключи с истёкшим сроком действия находятся в «Архиве ключей». Кнопка со счётчиком открывает отдельное окно; в нём есть «Мои ключи» и, для администратора или владельца, «Ключи команды».

Ключи в архиве не работают. Вернуть их в действие или продлить срок нельзя: выпустите новый ключ и замените его в интеграции. Журнал старого ключа остаётся доступен; отзыв сам по себе его не удаляет.

Главное: ключ действует от вашего имени

Ключ — не отдельный пользователь и не «ключ компании». Запрос с ключом выполняется от имени того, кто его выпустил. Из этого следует:

• Права ключа никогда не шире ваших. Действуют только те права, которые есть и у вашей роли, и у ключа. Это пересчитывается на каждом запросе: если администратора понизили до оператора, его ключи в ту же секунду теряют права администратора.
• Сообщение клиенту, отправленное через ключ, в переписке выглядит как ответ оператора, но под ним стоит пометка «через API · <название ключа>» — коллеги видят, что писала внешняя система, а не человек.
• Диалог, который интеграция взяла на себя, назначается на вас.
• Если вас удалят из команды, ваши ключи удаляются вместе с вами, и интеграции на них перестают работать. Если вас заблокируют, ключи не работают, пока блокировка действует.

Поэтому ключ для постоянной интеграции компании лучше выпускать тому сотруднику, который останется с ней надолго, — например, владельцу.

Выпуск ключа

1. В настройках нажмите «Открыть» в карточке «Ключи API», затем «Выпустить ключ».
2. В поле «Название» напишите, для чего ключ: «amoCRM», «MCP-клиент», «Скрипт отчётов». Название видно только в списке ключей и нужно, чтобы потом узнать ключ и не отозвать не тот.
3. Отметьте права. Можно нажать готовый набор — «Только чтение», «Ответы в диалогах», «Пополнение базы знаний» — и поправить галочки вручную.
4. Выберите «Срок действия».
5. Нажмите «Выпустить».

Откроется окно «Скопируйте ключ сейчас» с ключом вида sd_live_ab12cd34_…. Скопируйте его и сохраните туда, где его будет брать интеграция.

⚠️ Ключ показывается один раз. SmartDialogue хранит не сам ключ, а только его отпечаток, поэтому показать ключ повторно невозможно — ни вам, ни поддержке. Если вы закрыли окно и не сохранили ключ, отзовите его и выпустите новый.

Интеграция передаёт ключ в каждом запросе заголовком Authorization: Bearer <ключ>. Первый запрос, полный список операций и подключение ИИ-ассистентов по MCP — в документации API.

Отправка сообщения клиенту и загрузка документа принимают заголовок Idempotency-Key — любую строку до 255 символов, уникальную для каждого действия. Если интеграция не дождалась ответа и повторила запрос с тем же значением, второе сообщение клиенту не уйдёт, а документ не загрузится дважды: повтор в течение суток получит ответ на первый запрос с заголовком Idempotent-Replayed: true. Упавший запрос с ключом не запоминается — его повтор выполнится заново. Значение привязано к содержимому: с тем же Idempotency-Key, но другим текстом или другим файлом запрос получит ошибку 422 — новому действию нужен новый ключ.

Через MCP то же самое делает аргумент idempotency_key у инструментов отправки сообщения и добавления документа — это тот же ключ: действие, начатое по API, повтор через MCP с тем же значением второй раз не выполнит. Предел у обоих — 255 байт (латиница — байт на символ, кириллица — два). Заголовок Idempotency-Key на вызовы MCP не действует: без аргумента повторённый вызов может ещё раз отправить сообщение или загрузить документ. После обрыва связи проверьте результат первого действия перед повтором.

Защита от повторов зависит от хранилища Redis. Если оно недоступно или результат запроса не удалось сохранить, запрос может выполниться без защиты от дублей. После обрыва связи проверьте переписку или список документов, прежде чем повторять действие.

Какие права давать

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

Чего ключу дать нельзя никогда — даже владельцу: управлять командой, оплатой, настройками компании, удалять компанию, передавать владение, выпускать и отзывать ключи. Эти действия остаются за человеком с паролем.

Чего ключ не умеет в принципе, какие бы права у него ни были: менять настройки агента (в том числе его промпт) — только включать и выключать, настраивать каналы, работать с шаблонами ответов и подсказками ИИ, получать обновления в реальном времени (как обновляется экран «Входящих» в кабинете). Запрос туда получит отказ «Эта операция недоступна по ключу API». Заявки через ключ только читаются.

Удаление диалогов через ключ

Сначала интеграция запрашивает предварительный состав удаления, затем подтверждает его. За один раз можно выбрать от 1 до 100 разных диалогов своей компании. Удаление связанных заявок и контактов выключено по умолчанию; перед подтверждением проверьте, что попадёт в операцию и какие контакты будут сохранены.

Подтверждение требует preview_token и обязательного idempotency_key в теле запроса. Это отдельный механизм повторов: одного HTTP-заголовка Idempotency-Key для удаления недостаточно. Если ответ потерялся, повторите тот же запрос с тем же ключом и составом; по полученному operation_id можно запросить результат. Изменившийся или просроченный состав нужно проверить заново.

⚠️ Удалённые диалоги исчезают из кабинета, поиска и обычной статистики. Использованный лимит и расходы сохраняются. Удаление окончательное: вы не сможете восстановить удалённую переписку. Сохраните нужные сведения до подтверждения. Подробнее о составе удаления — в руководстве по диалогам.

Ограничения значений

Подключение MCP через OAuth

OAuth по умолчанию доступен во всех компаниях. Если в карточке «Подключённые приложения» указано, что новые подключения недоступны, используйте API-ключ по инструкции выше.

1. В настройках внешнего ассистента начните подключение удалённого MCP-сервера и укажите адрес https://smartdialogue.ru/api/mcp.
2. Ассистент откроет вход в Умный Диалог. Войдите под своим аккаунтом на https://app.smartdialogue.ru. Пароль вводится в нашем кабинете; ассистенту он не передаётся.
3. На странице «Подключение приложения» проверьте название приложения, компанию и аккаунт, под которым вы вошли.
4. В списке «Разрешения приложения» снимите лишние галочки. Список содержит только запрошенные приложением права, доступные вашей роли. Можно выбрать «Только чтение», «Только запись» или «Выбрать всё», затем поправить галочки. Добавить незапрошенное право на этом экране нельзя.
5. Нажмите «Разрешить доступ». Для согласия нужно оставить хотя бы одно право. Кнопка «Отказать» завершит подключение без выдачи доступа.
6. Браузер вернётся в ассистент. Он получит отдельный токен для обращения к MCP и будет обновлять его через OAuth.

Запрос на подключение действует 10 минут. Если срок истёк, запрос уже использован или результат подтверждения неизвестен после обрыва связи, начните подключение заново в ассистенте.

Приложение действует от имени сотрудника, разрешившего доступ. На каждом запросе проверяются его текущая роль, выбранные права и доступность компании. OAuth-токен предназначен для MCP; использовать его вместо входа в кабинет или ключа REST API нельзя.

Выполнение действий MCP

Через OAuth и API-ключ приложение выполняет операции в пределах выданных прав и текущей роли сотрудника. Разрешённые изменения данных и отправка сообщений выполняются сразу. Дополнительно подтверждать их в кабинете «Умного Диалога» не нужно. Сам ассистент может запрашивать подтверждение по правилам своего приложения.

Ранее выпущенные специальные MCP-ключи продолжают работать через MCP. Для них сохраняется ограничение: запись через REST недоступна.

Подключённые приложения и отзыв доступа

1. Откройте «Настройки» и нажмите «Открыть» в карточке «Подключённые приложения».
2. Найдите приложение. В карточке показаны компания, разрешивший доступ сотрудник, права и время последнего запроса.
3. Нажмите «Отозвать доступ» и подтвердите кнопкой «Отозвать».

Сотрудник видит свои подключения. Администратор и владелец компании также могут просматривать и отзывать доступы команды. Если нужного приложения нет, проверьте, в каком аккаунте и от имени какого сотрудника вы разрешали доступ. Подключения по API-ключу находятся в отдельной карточке «Ключи API».

Отозванные токены перестают давать доступ к MCP. Завершённые действия отзыв не отменяет. Для повторного подключения понадобится новое согласие в кабинете. Просмотр выданных доступов и их отзыв доступны и при остановке новых OAuth-подключений.

Сколько ключей и запросов можно

Ключей в компании может быть до 50 действующих одновременно — на всех участников вместе. Отозванные и истёкшие не считаются. Упёрлись в потолок — отзовите ненужные.

Запросов через REST API и MCP — ограниченное число в минуту на компанию, суммарно по всем API-ключам и OAuth-подключениям всех участников. Второй ключ, новое приложение или обновление OAuth-токена не увеличивают квоту. Каждый вызов в разрешённом пакете MCP учитывается отдельно.

Без действующей подписки действует лимит «Старта». Запросы из кабинета в этот лимит не входят. Для MCP дополнительно ограничено число одновременно выполняющихся запросов на компанию и на весь backend. Эти технические ограничения одинаковы для ключей и OAuth.

Сверх лимита интеграция получает отказ с кодом 429 и заголовком Retry-After — через сколько секунд начнётся следующая минута. Остаток лимита приходит в каждом ответе в заголовках X-RateLimit-Limit и X-RateLimit-Remaining.

MCP также возвращает 429, если у компании уже выполняется предельное число параллельных вызовов. Ответ 503 означает, что нет общей свободной ёмкости, исполнение временно отключено, недоступен общий ограничитель или истёк срок запроса. Соблюдайте Retry-After и снизьте параллельность. Перед повтором действия на запись проверьте результат в переписке или карточке объекта и используйте прежний ключ повтора, если инструмент его поддерживает.

Отзыв ключа

1. Найдите ключ в списке и нажмите «Отозвать».
2. Подтвердите в окне «Отозвать ключ?».

Ключ перестаёт работать сразу. Он остаётся в списке со статусом «Отозван» — так видно, что он был и когда его сняли.

⚠️ Отзыв необратим. Вернуть ключ нельзя — только выпустить новый и заменить его во всех интеграциях.

Администратор и владелец могут отозвать ключ любого участника в списке «Ключи команды» — например, если сотрудник уходит, а его интеграцию пора перевыпустить на другого. Выпуск и отзыв каждого ключа видны в «Команда» → «История изменений команды»: кто и когда это сделал.

Журнал ключа: что интеграция меняла

Кнопка «Журнал» у ключа показывает последние 100 действий, которые по нему что-то меняли: ответ клиенту, передачу диалога, загрузку и удаление документов, обход сайта (он платный: страницы классифицирует ИИ), правку контакта, включение агента — и через API, и через инструменты MCP. Для каждого действия видно, когда, через что (API или MCP), с каким объектом и чем кончилось: «выполнено», «отказ в доступе» или «ошибка».

Действия по ключу выполняются от вашего имени. Журнал помогает отличить их от ваших действий в кабинете. Если в переписке появился ответ, который никто не писал, или пропал документ, журнал ключа покажет, что это сделала интеграция и когда.

Запросы на чтение, например получение списка диалогов или поиск по базе знаний, в журнал не записываются. Не пишется и повтор с тем же Idempotency-Key: он возвращает сохранённый ответ и ничего не выполняет, так что одно действие — одна строка, сколько бы раз интеграция его ни повторила.

Записи старше 90 дней удаляются автоматически раз в сутки. Журнал пропадает и вместе с ключом — когда из команды удаляют сотрудника, которому ключ принадлежал. Отзыв ключа журнал не стирает.

Свой журнал видит владелец ключа; журналы ключей всей команды — администратор и владелец компании.

Письмо о новом ключе

О каждом выпущенном ключе приходит письмо — вам и всем, кто управляет ключами команды (администраторам и владельцу компании, кроме заблокированных). В письме: название ключа, его начало (sd_live_…), права, срок, время выпуска и IP-адрес, с которого ключ выпустили. Самого ключа в письме нет.

Ключ действует от вашего имени, пока его не отзовут, и не отключается ни выходом из кабинета, ни сменой пароля. Если кто-то воспользовался вашей открытой сессией и выпустил себе ключ, письмо — первый способ об этом узнать.

⚠️ Если пришло письмо о ключе, который вы не выпускали, — откройте «Настройки» → «Ключи API», отзовите его и смените пароль. Смена пароля без отзыва ключ не отключит.

Письмо уходит после выпуска и не задерживает его: если почта недоступна, ключ всё равно выпущен и работает.

Что показывает список

Когда элементы недоступны

Если интеграция получает отказ

Каждый отказ приходит с машинным кодом в поле code — по нему интеграция понимает причину, не разбирая текст. Полный словарь кодов — в документации API.