Как создать API-интеграцию

API-интеграция связывает Chatonio с одним из ваших бэкенд-сервисов, чтобы ИИ мог вызывать его как инструмент прямо в диалоге — посмотреть заказ, проверить баланс, создать тикет, сделать всё, что умеет ваш API. У каждой интеграции есть базовый URL и настройки авторизации; одна интеграция может содержать сколько угодно инструментов (по одному на каждый эндпоинт, который вы хотите дать ИИ).

Когда нужна API-интеграция

Ответ клиенту зависит от данных, которые лежат в вашей системе (номер заказа, статус подписки, баланс счёта).
Вы хотите, чтобы ИИ что-то делал за клиента — оформил возврат, отменил бронь, закрыл тикет.
Для обычных вопросов и ответов лучше подходят статьи базы знаний — интеграции нужны для живых данных конкретного клиента.

Шаг 1 — Откройте страницу «Интеграции»

В панели оператора перейдите в Проекты → ваш проект → Интеграции. Нужна роль ADMIN или MANAGER в проекте. На странице перечислены все интеграции проекта, а справа — инструменты выбранной интеграции.

The Integrations page, with the + Add button above the integrations list

Шаг 2 — Создайте интеграцию

Нажмите + Добавить над списком интеграций. Форма состоит из двух коротких шагов — Подключение и Доступ и каналы — и спрашивает:

Название — внутренняя подпись (например, Stripe, OrderService).
Базовый URL — корень всех эндпоинтов, без слеша в конце (например, https://api.example.com).
Тип авторизации — одно из: Нет, API-ключ, Bearer-токен или Basic-авторизация.
Доступно в — по умолчанию Все каналы, то есть каждый канал проекта. Переключите на Выбранные каналы, чтобы ограничить интеграцию — Telegram-ботами, групповыми чатами Telegram, виджетами веб-чата, почтовыми адресами или порталом поддержки.

Шаг 3 — Настройте авторизацию

Учётные данные хранятся в зашифрованном виде — вы видите их только один раз, при вводе. Выберите подходящую схему:

The Auth and scope step of the integration wizard, showing Auth type and Available on

API-ключ (произвольный заголовок)

{
  "type": "api_key",
  "header": "X-API-Key",
  "value": "sk_live_…"
}

Уходит как X-API-Key: sk_live_… в каждом запросе. Название заголовка можно указать любое — какое ждёт ваш API.

Bearer-токен

{
  "type": "bearer",
  "token": "eyJhbGciOi…"
}

Уходит как Authorization: Bearer eyJhbGciOi….

Basic-авторизация

{
  "type": "basic",
  "username": "service-user",
  "password": "…"
}

Свои заголовки

{
  "type": "headers",
  "headers": {
    "API-LOGIN": "…",
    "API-KEY": "…"
  }
}

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

Шаг 4 — Добавьте инструменты (сами эндпоинты)

Пока в интеграции нет ни одного инструмента, она бездействует. Инструмент — это один HTTP-эндпоинт, который может вызвать ИИ. Выберите интеграцию в списке слева — справа появится колонка Инструменты — затем нажмите + Добавить инструмент и пройдите три шага: Что делает, Как вызывать, Проверка:

The tools column with the + Add tool button and the Test action on a tool row

Название функции — короткое, в форме действия, snake_case (get_order_status, cancel_subscription). Это имя видит ИИ.
Описание (показывается AI) — одна фраза о том, когда инструмент применять. Именно по ней ИИ принимает решение. Пишите точно: «Возвращает текущий статус доставки по номеру заказа. Используйте, когда клиент спрашивает, где его заказ».
HTTP-метод — GET, POST, PUT или PATCH.
Путь эндпоинта — добавляется к базовому URL интеграции. Поддерживает подстановки {placeholder}, которые заполняются из параметров (например, /orders/{order_id}/status).
Параметры — то, что ИИ должен вытащить из диалога, прежде чем вызвать инструмент. Добавьте по строке на каждое значение и укажите имя, тип, обязательность, описание и, если нужно, шаблон. Рядом с каждой строкой стоит бейдж, показывающий, куда реально уйдёт значение: в пути — если его имя встречается в фигурных скобках в пути эндпоинта, иначе в query для GET и в теле для остальных методов. Под капотом это по-прежнему JSON Schema:

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "Номер заказа, который видит клиент, например ORD-12345"
    }
  },
  "required": ["order_id"]
}

The How to call it step, showing the endpoint path and a parameter badged "in path"

Требует подтверждения — в блоке Дополнительные настройки на последнем шаге. Включайте для любой операции, которая что-то меняет или удаляет (отмена, возврат, удаление). ИИ перескажет клиенту параметры и дождётся явного «да», прежде чем вызвать инструмент.
Шаблон сообщения-подтверждения — необязательный, поддерживает те же подстановки {placeholder}, что и путь.

Формат тела запроса

Для POST, PUT и PATCH вы выбираете, как передаются параметры:

JSON (по умолчанию) — тело запроса это JSON-объект. Так работает почти любой современный API.
Form-encoded — тело уходит как обычная HTML-форма (application/x-www-form-urlencoded). Это нужно старым PHP-API, которые читают $_POST.

Здесь стоит быть внимательным: ошибка в этом поле обычно не приводит к ошибке запроса. API, который не умеет читать JSON-тело, может просто проигнорировать параметры и ответить 200 с какой-нибудь записью по умолчанию — и ассистент получит полный правдоподобный ответ не о том, о чём спрашивали. Если инструмент возвращает данные, которые выглядят корректно, но всегда описывают одну и ту же запись, что бы вы ни запросили, — переключите этот параметр. Поле показывается только для методов, отличных от GET: в GET параметры всегда уходят в строке запроса.

Шаг 5 — Проверьте инструмент

У каждого инструмента есть действие Тест — в его строке в списке и на последнем шаге мастера. Подставьте тестовые значения параметров и нажмите Проверить. Chatonio отправит настоящий запрос тем же кодом, каким пользуется ИИ, и покажет обе половины:

собранный запрос — метод, итоговый URL, заголовки с замаскированными учётными данными, тело или query-строку;
ответ сервиса — код состояния, отдельные заголовки и тело;
вердикт обычными словами и адрес, с которого ушёл запрос.

A passing tool test, showing the assembled request and the address it was sent from

Последняя деталь важнее, чем кажется. Если ваш API ограничивает доступ по IP и нашего адреса нет в списке разрешённых, отказ придёт как 403 — ровно так же, как при неверном ключе. Строка «Отправлено с 64.7.198.218» рядом превращает долгий разбор в правку на одну строку.

Неудачная проверка никогда не мешает сохранению. API, который временно лежит, или ключ, которого вам ещё не выдали, не должны мешать дописать инструмент.

Проверка доступности — это не тест инструмента

У самой интеграции есть отдельная кнопка Проверка доступности — на её шаге Доступ и каналы. Она шлёт обычный запрос на базовый URL и подтверждает, что хост отвечает, — и больше ничего. Она не использует ваш путь, метод и параметры, поэтому может показать бодрый 200, пока все вызовы инструментов падают. Ею проверяют базовый URL; инструмент проверяют кнопкой Тест.

Что происходит, когда ваш API возвращает ошибку

Chatonio читает код состояния и делит отказы на два вида, потому что реагировать на них нужно противоположным образом:

Данные клиента не сходятся — 400, 404, 409, 410, 422. ИИ передаёт это клиенту и просит перепроверить то, что тот прислал. Никого не дёргают: опечатка в номере заказа — обычный рабочий момент, а не авария.
Что-то не так на нашей стороне — 401, 403, 429, 5xx, таймауты и ошибки DNS. ИИ прямо сообщают, что клиент не виноват и просить его что-то перепроверять нельзя, а диалог эскалируется на живого оператора.

Под это стоит проектировать свой API. Если на неизвестный номер заказа ваш эндпоинт отвечает 403 вместо 400 или 404, каждая опечатка клиента будет поднимать оператора.

Шаг 6 — Посмотрите, как это работает

Откройте реальный диалог. Когда клиент задаст вопрос, ответ на который требует интеграции, ИИ:

Выберет подходящий инструмент.
Извлечёт параметры из диалога (а чего не хватает — спросит у клиента).
Либо вызовет сразу, либо — если включено требует подтверждения — перескажет параметры и дождётся «да».
Построит ответ на том, что вернул сервис.

Разрешите наш IP-адрес

Chatonio обращается к вашему API с одного фиксированного адреса:

64.7.198.218

Если ваш API ограничивает доступ по IP — обычное дело для обменников и платёжных сервисов — добавьте этот адрес вместе с API-ключом. Вызовы, которые делает ИИ в диалоге, кнопка Тест и Проверка доступности идут оттуда же.

Советы

Один инструмент — одна задача. Не пытайтесь одним эндпоинтом закрыть пять сценариев: ИИ выбирает точнее, когда у каждого инструмента узкая и понятная роль.
Качество описания важнее названия. ИИ ориентируется по описанию.
Для всего, что меняет данные, всегда включайте подтверждение. Дешёвая страховка от того, что ИИ слишком буквально поймёт двусмысленное сообщение.
Держите ответы компактными. Возвращайте только те поля, которые нужны для ответа: вывод инструмента ограничен 16 КБ, а шумный ответ размывает внимание модели.