Документация › Для разработчиков › Своя интеграция по 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).

Вкладки под адресом:

Вкладки после разделителя «Продвинутое» нужны не всегда. Точка рядом с названием вкладки значит, что в ней что-то настроено.

Что бот увидит в ответе

API часто отвечает сотней полей на каждый объект. Бот видит их все, путается и платит за лишние токены. На вкладке «Что бот увидит в ответе»:

1. Включите «Включить маппинг ответа» и укажите, какие поля передавать боту (слева путь в ответе, например rows[*].name, справа короткое имя для бота).
2. Для каталога включите «Поиск по запросу клиента»: сервер сам отфильтрует ответ по словам клиента, и бот получит десятки позиций вместо тысяч.
3. Ограничьте максимальную длину ответа: чем она выше, тем дороже каждый вызов.

API отвечает «не нашлось» с кодом 200 и {success:false}? Отметьте, что такой ответ считается нормальным, иначе функция будет числиться сбойной.

Надёжность

Сервис лёг, и бот не зависнет: отработает таймаут и повторы, а клиенту честно скажет, что сейчас не получается, и пометит диалог «ответьте руками». Подробно: Функция не вызывается или падает.

Безопасность адреса

Раз бот умеет ходить по чужим адресам, кто-то мог бы попытаться направить его во внутреннюю сеть сервера (атака 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. Вы говорите боту: вот адрес, вот как войти, вот что отправить. И бот по ходу разговора спрашивает вашу систему и отвечает клиенту настоящими данными: есть товар или нет, сколько стоит, создан ли заказ. Сервер тормозит, и бот не зависнет, а честно скажет клиенту, что сейчас не получается.

Дальше: → Язык выражений
Связано: Функции · МойСклад: готовый пример · Вебхуки
Не получилось? → Функция не вызывается или падает