API: быстрый старт

Что даёт API

Через REST API можно подключить CRM, собственный скрипт или ИИ-агента к данным и действиям Умного Диалога. Запросы и ответы — JSON.

• читать диалоги и переписку, отвечать клиентам от имени оператора, передавать диалог оператору и возвращать ИИ;
• пополнять базу знаний — файлом, страницей сайта или обходом сайта — и искать по ней;
• читать и править карточки клиентов, читать заявки, которые собрал бот;
• смотреть агентов и включать или выключать их — например, на ночь.

Всего 29 операций — все в справочнике. ИИ-клиенты с поддержкой MCP по HTTP подключаются к тем же операциям через MCP-сервер.

Ключ

Каждый запрос несёт личный ключ API в заголовке Authorization: Bearer sd_live_…. Ключ выпускается в кабинете: «Настройки» → «Ключи API». Там же выбираются права ключа и срок действия.

• Ключ показывается один раз, сразу после выпуска. Потерян — отзовите его и выпустите новый.
• Ключ действует от имени сотрудника, который его выпустил: взятый диалог назначится на него, а ответ клиенту в кабинете будет помечен «через API» и названием ключа.
• Заводите отдельный ключ на каждую интеграцию — тогда утёкший ключ можно отозвать, не останавливая остальные.

Всё о выпуске, правах и отзыве — в руководстве «Ключи API».

Первый запрос

Адрес API — https://smartdialogue.ru/api/v1. Сохраните ключ в переменную окружения и запросите список агентов:

export SD_KEY="sd_live_…"
curl -H "Authorization: Bearer $SD_KEY" https://smartdialogue.ru/api/v1/agents

В ответ придёт массив агентов компании — поля описаны в справочнике у операции «Список агентов». Ответ 401 — ключ передан не так или уже недействителен; 403 — у ключа нет права agents:read.

Ответить клиенту в диалоге. Замените значение DIALOG_ID на ID нужного диалога; запрос отправит сообщение клиенту:

DIALOG_ID="идентификатор-диалога"
curl -X POST "https://smartdialogue.ru/api/v1/inbox/dialogs/$DIALOG_ID/messages" \
  -H "Authorization: Bearer $SD_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{"content": "Здравствуйте! Заказ передан в доставку."}'

Права

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

Никакой ключ не управляет командой, оплатой, настройками компании и другими ключами, не меняет настройки агента (только включает и выключает его) и не настраивает каналы — такие запросы получают 403.

Лимиты

Запросов в минуту на компанию — суммарно по всем ключам всех сотрудников. Второй ключ лимит не удваивает. Работа операторов в кабинете в лимит не входит.

Без действующей подписки действует лимит «Старта». В каждом ответе на запрос с ключом:

Сверх лимита — ответ 429 с заголовком Retry-After: через сколько секунд повторить.

Повторы запросов

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

Ключ привязан к содержимому запроса: тот же Idempotency-Key с другим текстом сообщения или другим файлом получит 422 — новому действию нужен новый ключ. Повтор, пришедший, пока первый запрос ещё выполняется, получит 409: дождитесь ответа на первый.

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

Постраничное чтение

Диалоги, сообщения диалога, документы, контакты и заявки отдаются страницами. Размер страницы задаёт limit, а в ответе, кроме записей и total, приходят has_more — есть ли записи дальше — и next_cursor. Следующую страницу запрашивайте с cursor=<next_cursor>, пока has_more не станет false: тогда и next_cursor — null. Выгрузить все заявки:

url="https://smartdialogue.ru/api/v1/leads?limit=100"
page=$(curl -s -H "Authorization: Bearer $SD_KEY" "$url")
while true; do
  echo "$page" | jq -c '.leads[]'
  [ "$(echo "$page" | jq -r .has_more)" = true ] || break
  cursor=$(echo "$page" | jq -r .next_cursor)
  page=$(curl -s -H "Authorization: Bearer $SD_KEY" "$url&cursor=$cursor")
done

• Курсор держит место по самим записям, а не по номеру: заявка, пришедшая между запросами, не сдвинет следующую страницу и не повторит на ней строку. Передавайте его как получили — формат курсора может меняться. Курсор, которого сервер не выдавал, получит 400 с кодом invalid_cursor: начните с первой страницы.
• Диалоги идут по последнему сообщению, поэтому диалог, в котором во время обхода появилось новое сообщение, поднимается наверх — свежие диалоги берите с первой страницы.
• offset оставлен для совместимости, но для обхода списка не рекомендуется; вместе с cursor он не передаётся. Список агентов не делится на страницы: агентов у компании не больше, чем разрешает тариф.
• Документы базы знаний без limit и cursor отдаются все разом. По курсору они, как и остальные списки, идут страницами; если limit не указан — по 50.

Ошибки

Любая ошибка — объект в формате RFC 9457 с типом application/problem+json. detail — текст по-русски, его можно показать человеку как есть. code — машинный код: ветвитесь по нему, а не по тексту — текст может поменяться, код нет. У 422 есть ещё errors — ошибки по полям.

{
  "type": "https://smartdialogue.ru/docs/api/#error-api_key_invalid",
  "title": "Ключ API недействителен",
  "status": 401,
  "detail": "Ключ API недействителен, отозван или истёк",
  "code": "api_key_invalid"
}

Машинные коды. Ссылка в поле type ведёт на строку этой таблицы.

Дальше

• Справочник API — все операции с параметрами и полями.
• Подключение по MCP — настройка ИИ-клиента по API-ключу или OAuth; адрес сервера https://smartdialogue.ru/api/mcp.
• Спецификация OpenAPI 3.1 для генераторов клиентов и Postman: https://smartdialogue.ru/api/v1/openapi.json.
• Состояние API: https://smartdialogue.ru/api/v1/health.