Перейти к содержанию
AI-SNS.IO — CHAT SUPPORTAI-SNS.IO — CHAT SUPPORT
Работа в AI SNS CHAT

REST API в AI SNS CHAT: как расширить агента под свои задачи

Редакция AI SNS CHATОпубликовано 7 мин чтения

Когда нужен REST API AI SNS CHAT, а когда хватит готовых каналов: ключи, SSE-стриминг, подписанные вебхуки, лимиты и чек-лист безопасности.

Готовых каналов и встроенных интеграций хватает не всегда. У вас может быть собственное мобильное приложение, закрытый личный кабинет или внутренняя CRM, куда нужно передавать диалоги. В таких случаях пригодится REST API. В статье разберём, когда он действительно нужен, из каких частей состоит интеграция, какие лимиты учесть и что проверить перед запуском.

Когда API — правильный инструмент, а когда нет

Начните с простого вопроса: есть ли у вас задача, которую нельзя решить настройками? Чаще всего ответ «нет», и лишняя разработка только создаёт нагрузку на команду.

API оправдан, если:

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

API не нужен, если:

  • вам нужно подключить Telegram, WhatsApp, Messenger или VK: для них есть готовые каналы;
  • достаточно виджета на сайте: его вставляют готовым скриптом;
  • нужны уведомления в Slack, Teams или по почте при передаче диалога человеку: это настраивается в разделе Helpdesk;
  • связку можно собрать через готовые Actions или Zapier.
Готовый маршрут
Собственный API
Telegram, WhatsApp, VK, виджет на сайте
Своё приложение или закрытый портал
Настройка в панели за вечер
Разработка и поддержка кода
Обновления каналов на стороне платформы
Вы сами следите за изменениями
Подходит большинству команд
Нужен, когда готовые варианты не подходят
Готовый маршрут или собственный API?Пример для иллюстрации

Из чего состоит интеграция

REST API AI SNS CHAT работает с JSON. Для получения ответов по мере генерации есть потоковая передача через SSE: достаточно указать параметр stream=1. Для уведомлений в обратную сторону используются вебхуки с HMAC-подписью. Все доставки записываются в журнал.

Интеграция складывается из четырёх частей.

API-ключ

Ключ создают в настройках рабочего пространства, в разделе API keys. Он показывается один раз, поэтому сразу сохраните его в менеджере секретов. Если ключ утёк или сотрудник ушёл, ключ можно отозвать. Доступ к API-ключам открывается с тарифа Hobby.

Запросы к агенту

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

Вебхуки

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

Ваша серверная часть

Между пользователем и API стоит ваш сервер. Он хранит ключ, проверяет подписи, решает, что показывать клиенту, и пишет в вашу систему.

  1. 01Пользователь в вашем приложении
  2. 02Ваш сервер с API-ключом
  3. 03AI SNS CHAT: запрос и ответ
  4. 04Вебхук в вашу систему
Как собирается собственная интеграцияПример для иллюстрации

Точные адреса методов, поля запросов и названия заголовков смотрите в справочнике API на сайте. В этой статье мы описываем принципы, а не заменяем документацию.

Уважайте опубликованные лимиты

В справочнике API опубликованы три ограничения:

Что ограниченоЛимит
Авторизация20 запросов за 5 минут с одного IP
Публичный чат30 запросов в минуту с одного IP
Опрос (poll)120 запросов в минуту

Рассмотрим гипотетический пример. Допустим, вся ваша клиентская база сидит за одним корпоративным шлюзом, то есть с одного IP. Тогда лимит публичного чата в 30 запросов в минуту делится на всех. Если одновременно пишут 50 человек, часть запросов упрётся в ограничение. Это не ошибка платформы, а следствие архитектуры. Лучше проектировать сервис так, чтобы запросы шли с вашего сервера, а не напрямую из браузеров за одним шлюзом.

Что делать на практике:

  • не опрашивайте API чаще необходимого: если можно получать уведомления вебхуком, не гоняйте poll по таймеру;
  • при ответе об ограничении не повторяйте запрос немедленно, увеличивайте паузу между попытками;
  • не авторизуйтесь на каждый запрос: получив доступ, используйте его повторно;
  • закладывайте запас: работать на пределе лимита в пиковые часы опасно.

Шаблоны, которые работают

Тонкий прокси вместо прямых запросов из браузера

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

Стриминг для живого интерфейса

Если в вашем кабинете пользователь ждёт ответа, показывайте текст по мере появления. Стрим снижает ощущение задержки: человек видит, что система работает. Не забудьте корректно закрывать соединение при уходе пользователя со страницы.

Очередь для вебхуков

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

Идемпотентность

Уведомление может прийти дважды, например при повторной отправке после сбоя. Храните идентификатор уже обработанных событий и пропускайте дубли. Иначе в CRM появятся две заявки вместо одной.

Разделение сред

Заведите отдельный ключ для тестов и отдельный для рабочей среды. Тогда отзыв тестового ключа не остановит продакшн.

Чек-лист безопасности перед запуском

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

  1. Ключ хранится только на сервере. Его нет в репозитории, в клиентском коде и в логах.
  2. Подпись вебхука проверяется. Считайте HMAC от необработанного тела запроса с вашим секретом и сравнивайте со значением из заголовка за постоянное время. Всё, что не совпало, отбрасывайте. Название заголовка и алгоритм указаны в справочнике API.
  3. Есть план отзыва. Вы знаете, кто и как отзовёт ключ при утечке, и можете быстро выпустить новый.
  4. Журналы не содержат секретов. Не пишите в логи ключи и персональные данные клиентов.
  5. Вы ограничиваете частоту на своей стороне. Это защищает и от злоупотреблений, и от лишней траты кредитов.
  6. Включены фильтры агента. В настройках безопасности агента есть защита от prompt-инъекций и злоупотреблений, не отключайте её без причины.
  7. Права в рабочем пространстве разумны. Доступ к настройкам получают только те, кому он нужен.

Тестирование и выкатка

Не запускайте интеграцию для всех сразу. Разумный порядок такой:

  1. Проверьте поведение самого агента в Playground. Если он отвечает плохо, API этого не исправит.
  2. Подключите тестовый ключ и прогоните основные сценарии: обычный вопрос, длинный ответ, потоковый режим, вопрос вне темы.
  3. Отдельно проверьте вебхуки: правильная подпись, неправильная подпись, повторная доставка, недоступность вашего сервера. Журнал доставок покажет, что именно произошло.
  4. Нагрузите систему умеренно и убедитесь, что вы укладываетесь в опубликованные лимиты.
  5. Запустите на небольшую группу пользователей, например на внутренних сотрудников или одного филиала.
  6. Пересматривайте реальные диалоги в Activity → Chat logs, исправляйте ответы и дообучайте агента.

Для расчёта нагрузки полезен простой пример. Допустим, магазин получает 300 диалогов в месяц, и в каждом в среднем по 6 ответов агента. Это около 1 800 ответов, то есть примерно столько же кредитов, ведь один ответ равен одному кредиту. Цифры условные, но такой расчёт помогает заранее выбрать тариф и не получить неожиданностей.

Как это делается в AI SNS CHAT

Вот последовательность действий в панели.

1. Выберите тариф. API-ключи доступны с тарифа Hobby и выше. Актуальные цены читаются из системы при открытии страницы, поэтому смотрите их на странице /pricing.

2. Создайте и протестируйте агента. Агента собирают мастером, добавляют источники знаний в разделе Data sources (файлы, сайт, вопросы и ответы, Notion и другие) и проверяют в Playground. Перед серьёзными изменениями создавайте точки восстановления: можно откатиться, если новая версия работает хуже. Хранится до 40 точек на агента.

3. Выпустите ключ. Откройте настройки рабочего пространства и перейдите в раздел API keys. Ключ показывается один раз, скопируйте его сразу. Позже его можно отозвать.

4. Подключите канал API. В боковом меню откройте Channels. В списке есть пункт API, а рядом готовые каналы: Telegram, WhatsApp, Messenger, VK, виджет на сайте и другие. Если нужен только мессенджер, берите готовый канал, API не потребуется. Для проверки подписи входящих запросов в части каналов (LINE, Meta, Twilio, Discord) платформа делает это сама, а вебхуки Telegram, Viber и Discord регистрируются автоматически. Обзор каналов есть на странице /connections, а общий список возможностей на /features.

5. Настройте вебхуки. Уведомления приходят с HMAC-подписью, а журнал доставки показывает результат каждой попытки. Передачу диалога человеку можно настроить в Helpdesk: оповещения уходят в Slack, Teams, LINE WORKS, WhatsApp, на почту или на вебхук. Смены операторов задаёт раздел Scheduling.

6. Для доработок без кода используйте Actions. Custom actions, Collect leads, Stripe, Shopify, Slack и другие работают без собственного сервера. Количество Actions на агента зависит от тарифа.

7. Закройте доступ. Права участников задаются ролями, а любые изменения видны в журнале Workspace settings → Activity. Если вам нужен собственный домен для виджета и ссылки на агента, он настраивается в Agent → Settings → Custom domains на тарифе Hobby и выше. Включите 2FA для учётных записей, которые управляют ключами. Подробности о защите данных описаны на странице /security: практики разработаны с учётом GDPR и APPI, но платформа не заявляет сертификацию SOC 2, ISO 27001 или HIPAA.

8. Следите за расходом. Страница Usage показывает кредиты по каждому агенту. После запуска заглядывайте туда ежедневно, пока нагрузка не стабилизируется.

Начать можно на странице /signup, а перед этим убедитесь, что вам действительно нужен API. Во многих случаях хватает готовых каналов, и это дешевле в поддержке.

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

Какой тариф нужен для работы с REST API?

API-ключи доступны с тарифа Hobby и выше. На бесплатном тарифе создать ключ не получится. Актуальные цены подтягиваются на странице /pricing в момент открытия, поэтому ориентируйтесь на неё.

Можно ли выводить ответы потоком в собственном интерфейсе?

Да. API поддерживает SSE-стриминг, он включается параметром stream=1. Текст приходит частями по мере генерации, и вы показываете его пользователю сразу. Детали формата событий смотрите в справочнике API.

Как убедиться, что вебхук действительно пришёл от AI SNS CHAT?

Вебхуки подписаны по HMAC. Считайте подпись от необработанного тела запроса с общим секретом и сравните с присланной за постоянное время. Если значения не совпали, отклоните запрос. Название заголовка и порядок расчёта указаны в справочнике API.

Какие есть лимиты запросов?

Опубликованы три лимита: авторизация 20 запросов за 5 минут с одного IP, публичный чат 30 запросов в минуту с одного IP, опрос 120 запросов в минуту. Проектируйте интеграцию так, чтобы не упираться в них, и не повторяйте запросы мгновенно после отказа.

Нужен ли API, чтобы подключить агента к WhatsApp или Messenger?

Нет. WhatsApp и Messenger есть среди готовых каналов в разделе Channels, так же как Telegram и VK. API нужен, когда вы строите собственный интерфейс или процесс, который готовыми средствами не закрыть.

#REST API#интеграции#вебхуки#безопасность#AI SNS CHAT

Попробуйте на практике в AI SNS CHAT

Создайте ИИ-агента, обученного на ваших материалах, и подключите его к сайту, WhatsApp, Messenger и другим каналам. Начать можно бесплатно, без банковской карты.