Свой канал через API: агент в собственном приложении

У компании есть свой личный кабинет — и в нём чат, который писали под собственную задачу и переписывать не собираются только ради чужого виджета. Клиент печатает прямо там, где оформляет заказ или смотрит статус услуги, и уходить в мессенджер не должен. Вопрос в том, как заставить агента Савви отвечать именно в этом окне.

Чем этот канал отличается от готовых

Персональный канал (API) — это способ подключить агента к собственному приложению, личному кабинету или самописной системе напрямую, без промежуточной площадки.

В готовых каналах (Telegram, чужой виджет на сайте, любая CRM) между вами и агентом всегда стоит сторонний сервис: он определяет формат сообщений, отвечает за доставку и решает, что можно передать, а что нельзя. В персональном канале эту роль берёт на себя ваша команда: вы получаете токен, адрес и протокол, а дальше сами пишете код, который принимает ответ агента и выводит его в интерфейсе. Отличие принципиальное: ответ агента забирает именно ваша система, написанная и обслуживаемая вашей командой.

	Готовый канал (Telegram, CRM, виджет)	Персональный канал (API)
Кто отдаёт интерфейс	сторонняя площадка	ваше приложение
Формат сообщений	свой у каждой площадки	единый JSON, описанный в руководстве
Приём ответа агента	площадка уже умеет	ваш вебхук нужно написать самим
Идентификация переписки	ID площадки	chat_id, который придумываете вы
Опыт разработки	не требуется	подразумевается по руководству

Как подключить канал в кабинете

Подключение — пять шагов, и от вас нужен только рабочий вебхук.

1 Открыть раздел «Каналы» Внутри бота выбрать «Персональный канал (API)».

2 Указать URL вебхука Адрес, на который Савви будет отправлять сообщения агента. Уточняется у вашего отдела разработки.

3 Скопировать токен Он показывается один раз сразу после подключения и нужен для авторизации ваших запросов к Савви.

4 Включить передачу секрета Опционально, но рекомендовано: API-токен или секретное слово, по которому вы отличаете запросы от Савви от чужих.

5 Нажать «Тест вебхука» Савви отправит запрос с типом test_request; успех: код 200-299 в течение 20 секунд.

Что отправлять на адрес приёма сообщений

Чтобы передать агенту сообщение клиента, ваша система делает POST-запрос на https://api.suvvy.ai/api/webhook/custom/message с заголовками Authorization: Bearer <токен> и Content-Type: application/json.

Тело запроса — JSON с обязательными и опциональными полями:

Поле	Обязательно	Что в нём
api_version	да	версия API, сейчас только 1
message_id	да	ID сообщения в вашей системе, защищает от повторной отправки
chat_id	да	ID чата в вашей системе, связывает сообщение с диалогом
text или attachments	да, одно из двух	текст сообщения или вложение (картинка либо аудио, до 15 МБ)
message_sender	да	customer или employee
source	да	что показывается в колонке «Источник» в кабинете Савви
client_name, client_phone	нет	имя и телефон клиента
placeholders	нет	переменные для инструкции агента
link	нет	ссылка на чат в вашей системе, отображается кнопкой в кабинете

При успехе агент отвечает телом {"message": "Successful"} — само тело смысловой нагрузки не несёт, важен только код ответа.

Как понять по коду ответа, что пошло не так

Каждая ошибка возвращает код и error_code — по ним видно, где искать проблему, не открывая переписку с поддержкой.

Код	error_code	Что произошло
401	auth_invalid_token	токен неверный или устарел
424	instance_channel_is_disabled	канал не подключён или выключен в настройках
415	file_invalid_type	тип вложения не поддерживается — ответ содержит список разрешённых
402	user_balance_below_zero	баланс Савви ушёл в минус
422	—	ошибка валидации, тело ответа подробно описывает, что передано не так

20 сек на ответ вашего вебхука, иначе сообщение считается недоставленным

15 МБ максимальный размер файла во вложении

~15 ₽ стоимость диалога через персональный канал, как и в любом другом

Как ваша система получает ответ агента

Ответ приходит обратным POST-запросом на вебхук, который вы указали при подключении. В теле — event_type (new_messages или test_request) и массив new_messages с сообщениями агента: текстом или файлом, у каждого указан message_sender — ai или employee, если ответил человек из кабинета Савви.

Правило то же, что и в вашу сторону: код 200-299 и ответ в течение 20 секунд, иначе Савви решит, что сообщение не доставлено. Если при подключении был задан секрет, он приходит в заголовке Authorization: Bearer <секрет>, по нему вы отсеиваете запросы не от Савви, потому что обращаться к вашему вебхуку будут с разных IP-адресов.

Технический идентификатор этого канала в условиях агента — channel_name равный custom. Он пригодится, если тот же агент отвечает ещё и в других каналах и должен вести себя иначе именно в вашем приложении.

Заведите отдельный вебхук под тестирование, прежде чем подключать боевой адрес

Проверьте связку на сервисе вроде webhook.site: подключите его временный адрес вместо своего, нажмите «Тест вебхука» в кабинете и посмотрите, что реально прилетает в тело запроса. Разработчик увидит формат раньше — до того, как начнёт писать обработчик под боевую систему.

Обратная сторона — действия, которые агент вызывает наружу посреди разговора, вебхуки для CRM, 1С и подобных систем — устроена отдельно от персонального канала и разбирается в статье про интеграцию с 1С: там же про авторизацию, лимит вызовов и передачу аргументов. Для точечного запроса к вашей системе во время диалога — узнать остаток на складе, статус заказа — хватит именно такого вебхука, персональный канал здесь избыточен. Общий обзор того, что даёт связка с CRM, — в статье про интеграцию чат-бота с CRM. Полный список полей и форматов, включая получение сообщений, — в руководстве Савви.

Частые вопросы