[ GUIDE · Speech ]
Публичный API для чата
Публичный API чата A5X: список чатов, отправка сообщения, история диалога, режимы и пространства базы знаний.
Чат на сайте и в Telegram — готовые каналы. Публичный API даёт того же агента из вашей CRM, мобильного приложения, бота или внутреннего сервиса: без вставки скрипта, со своим интерфейсом и своей историей диалога.
Адрес сервиса: https://s2t.a5x.pro/api/public. Авторизация — ключ из личного кабинета A5X (начинается с sk_live_) в заголовке Authorization: Bearer или X-API-Key.
Зачем вызывать чат через API
Свой интерфейс
Вопрос и ответ в карточке сделки, в тикете или в мобильном приложении — без кнопки чата на сайте.
Тот же агент
Сценарий, режимы и пространства базы знаний берутся из конфигурации чата в кабинете.
Несколько чатов
Сайт, поддержка, внутренний раздел помощи — разные идентификаторы из списка, как разные вкладки в Настройки → Чат.
Один ответ на запрос
Полный ответ агента приходит сразу: текст и источники. Чтобы отменить — оборвите соединение.
Что подготовить
- Аккаунт с включённым продуктом «Чат».
- Хотя бы одну активную конфигурацию в Настройки → Чат (сценарий, режимы, пространства базы знаний).
- Ключ API из кабинета — не храните его в открытом репозитории.
- Понимание, какой чат вызывать: «По умолчанию» или отдельный под канал.
Список активных чатов
/v1/chats/listВозвращает активные чаты аккаунта: идентификатор, имя, public_key для эмбеда на сайте (data-widget-key), пространства базы знаний по умолчанию и признак «по умолчанию». id нужен для POST /v1/chats/{chat_id}/messages; public_key — чтобы собрать сниппет на стороне интегратора.
Сообщение агенту
/v1/chats/{chat_id}/messagesВ теле обязательно поле text (текст вопроса). В ответе: идентификатор запроса, markdown (текст ответа) и context (источники: звонки, документы, память).
- Идентификатор чата берётся из списка чатов.
- Тарификация как у сообщений чата в кабинете и на сайте.
- Чтобы отменить долгий запрос — оборвите соединение.
История, режимы и пространства
По желанию в теле можно передать историю диалога, режимы и список пространств базы знаний. Без них используются настройки выбранного чата.
- История —
historyПредыдущие реплики с ролями «пользователь» и «ассистент». Историю хранит ваша система — сервер не ведёт сессию между вызовами. - Пространства —
space_idsИдентификаторы пространств базы знаний. Пустой или отсутствующий список — как в настройках чата.
Как читать ответ
Текст ответа
Поле markdown — готовый ответ для показа пользователю или для обработки в вашей системе.
Источники
Поле context: звонки, документы и память — чтобы показать цитаты или открыть карточку звонка.
Идентификатор запроса
Поле request_id — для логов и обращений в поддержку.
Документация
Полные примеры запросов и схемы — в разделе публичного API: список чатов и сообщение в чат.
Ошибки и пауза аккаунта
401— нет ключа, ключ недействителен или отозван.403на списке чатов — продукт «Чат» отключён.403на отправке сообщения — аккаунт на паузе; пополните баланс или активируйте аккаунт.404— чат не найден или неактивен.400— пустой или слишком длинный текст вопроса, либо неверное тело запроса.
Чек-лист интеграции
1. Чат в кабинете
Конфигурация активна, сценарий и база знаний проверены вопросом в кабинете.
2. Ключ
Ключ API только на сервере; список чатов возвращает нужный идентификатор.
3. Сообщение
Запрос с текстом вопроса даёт ответ; при диалоге передаёте историю.
4. Боевой запуск
Обработаны ошибки авторизации, паузы и «чат не найден»; на паузе сообщения не отправляете.
Частые вопросы
Чем API чата отличается от расшифровки звонков?
API чата — диалог с агентом и базой знаний. Расшифровка — отдельный контур задач по аудио: расшифровка по запросу.
Нужен ли webhook?
Для длинных сценариев удобны уведомления; для коротких ответов часто хватает синхронного запроса — смотрите справочник.
Как не светить ключ?
Держите ключ на бэкенде, не в открытом коде сайта и не в мобильном приложении «как есть».
Попробуйте в кабинете
Зарегистрируйтесь за пару минут: стартовый баланс, веб-кабинет и первые звонки без NDA.