Документация › Для разработчиков › Своя интеграция по API
Своя интеграция по API
Обновлено 1 октября 2026 г.
Бот посреди разговора обращается к вашему сервису: проверить остаток на складе, создать заказ, достать данные из своей базы. Делается функцией «Своя интеграция по API», писать код не нужно, всё заполняется в полях. Готовый пример на настоящем сервисе: МойСклад.
⏱ 8 мин · 👤 для разработчика и владельца · 🟢 live
За 30 секунд:
- Функции → Новая функция → «Своя интеграция по API». Адрес, метод, тело, авторизация, описание для бота.
- В адрес, тело и заголовки подставляются данные разговора через выражения:
{{phone}}, имя, дата.- Большой ответ API сжимается вкладкой «Что бот увидит в ответе», иначе бот утонет в сотне лишних полей.
- Таймаут до 60 секунд, повторы при сбое, ключи к вашему API хранятся зашифрованными. Внутренние адреса заблокированы.
📌 Не путайте с вебхуками. Здесь бот сам идёт к вам, когда нужно по разговору. Если нужно, чтобы платформа сообщала вашей системе о событиях (новый лид, оплата), это Вебхуки.
Как настроить
Создайте функцию «Своя интеграция по API» (см. Функции) и заполните:
- Адрес вашего API. Данные разговора подставляются выражениями:
https://api.shop.kz/order?phone={{phone}}. - Метод: GET, POST, PUT, PATCH или DELETE.
- Описание для бота: когда звать функцию. Его читает бот, а не человек, поэтому пишите словами клиента: «клиент спрашивает про наличие или цену товара».
- Параметры функции: что бот должен выяснить у клиента и передать (например,
search_term).
Вкладки под адресом:
| Вкладка | Что задаёт |
|---|---|
| Тело запроса | что отправить (JSON подходит 9 API из 10) |
| Заголовки | свои HTTP-заголовки, обычно не нужны |
| Авторизация | Bearer-токен, Basic, API-ключ в заголовке или свой заголовок |
| Параметры URL | query-параметры, которые подставит бот |
| Что бот увидит в ответе | какие поля ответа отдать боту, и поиск по запросу клиента |
| Повторы при сбое | число попыток и паузу между ними |
| Постраничная загрузка | собрать все страницы ответа (cursor, offset, page) |
Вкладки после разделителя «Продвинутое» нужны не всегда. Точка рядом с названием вкладки значит, что в ней что-то настроено.
Что бот увидит в ответе
API часто отвечает сотней полей на каждый объект. Бот видит их все, путается и платит за лишние токены. На вкладке «Что бот увидит в ответе»:
- Включите «Включить маппинг ответа» и укажите, какие поля передавать боту (слева путь в ответе, например
rows[*].name, справа короткое имя для бота). - Для каталога включите «Поиск по запросу клиента»: сервер сам отфильтрует ответ по словам клиента, и бот получит десятки позиций вместо тысяч.
- Ограничьте максимальную длину ответа: чем она выше, тем дороже каждый вызов.
API отвечает «не нашлось» с кодом 200 и {success:false}? Отметьте, что такой ответ считается нормальным, иначе функция будет числиться сбойной.
Надёжность
| Параметр | Поведение |
|---|---|
| Таймаут | по умолчанию 10 секунд, можно до 60 |
| Повторы | настраиваются на вкладке «Повторы при сбое»: число попыток и пауза |
| Всегда повторяются | 408, 429, 502, 503, 504, 522, 524; для 429 пауза берётся из заголовка Retry-After |
Сервис лёг, и бот не зависнет: отработает таймаут и повторы, а клиенту честно скажет, что сейчас не получается, и пометит диалог «ответьте руками». Подробно: Функция не вызывается или падает.
Безопасность адреса
Раз бот умеет ходить по чужим адресам, кто-то мог бы попытаться направить его во внутреннюю сеть сервера (атака SSRF). Поэтому каждый адрес проверяется перед запросом:
- запрос не пойдёт, если адрес ведёт в частную или служебную сеть:
127.x,10.x,192.168.x,172.16-31.x,169.254.x,100.64-127.x, IPv6::1,fc/fd,fe80::; - адрес с логином и паролем внутри (
https://user:pass@…) не принимается, протоколы толькоhttpиhttps; - после проверки запрос идёт ровно на тот IP, который её прошёл: подменить адрес между проверкой и запросом нельзя;
- размер ответа ограничен.
Что это значит для вас: адрес должен быть публичным и лучше по HTTPS, а пароли и токены к вашему API кладите во вкладку «Авторизация» (они хранятся зашифрованными), а не в сам адрес. Подписи у исходящих запросов нет: если вашему API нужно убедиться, что запрос от бота, проверяйте секретный заголовок.
Простыми словами
Это для тех, у кого есть своя программа или сайт с API. Вы говорите боту: вот адрес, вот как войти, вот что отправить. И бот по ходу разговора спрашивает вашу систему и отвечает клиенту настоящими данными: есть товар или нет, сколько стоит, создан ли заказ. Сервер тормозит, и бот не зависнет, а честно скажет клиенту, что сейчас не получается.
Дальше: → Язык выражений
Связано: Функции · МойСклад: готовый пример · Вебхуки
Не получилось? → Функция не вызывается или падает