Пользовательские интеграции API позволяют вашему чатботу запрашивать актуальные данные из вашей ERP, складской системы, CRM или другого сервиса. Они также могут вносить изменения, например создавать запись на прием. Интеграция хранит базовый URL; каждая операция определяет один вызываемый запрос. Затем вы подключаете выбранные операции к чатботу в виде AI actions (действий ИИ).
Перед началом работы
Убедитесь, что ваш тарифный план включает пользовательские интеграции API. Вам понадобятся URL эндпоинта, HTTP-метод, имена и типы параметров, требования к аутентификации и пример ответа. Эндпоинт должен быть доступен с серверов ChatLab; адрес localhost на вашем компьютере не является рабочим эндпоинтом.
Используйте HTTPS и тестовый сервис или тестовые записи для настройки. Тестовый запрос действительно обращается к эндпоинту, поэтому запросы POST, PATCH или DELETE могут изменить внешние данные. По возможности делайте операции безопасными для повторного вызова.
1. Создайте интеграцию
- Откройте Custom Integrations (Пользовательские интеграции) в главном меню навигации.
- Нажмите + Define API Integration (Определить интеграцию API).
- Введите API name (Имя API) и API Base URL (Базовый URL API), например
https://api.example.com. - Нажмите Create API Integration (Создать интеграцию API).
- В списке интеграций нажмите View (Просмотр), затем + Define API Operation (Определить операцию API).
2. Настройте операцию
Задайте понятную метку для интерфейса и машиночитаемое Operation name (Имя операции), например getProductDetails. Используйте в имени операции только буквы и цифры без пробелов и знаков подчеркивания. Опишите, что делает операция и когда чатбот должен ее использовать.
Введите относительный URI, например /v1/products/@productId@. Базовый URL и URI образуют адрес запроса.
На некоторых существующих скриншотах показаны устаревшие примеры имен или плейсхолдеры в фигурных скобках. Используйте актуальный синтаксис, описанный ниже: имена операций вроде getProductDetails и плейсхолдеры параметров, обрамленные символом @.
Параметры пути и строки запроса
Нажмите Add path variable (Добавить переменную пути), чтобы определить productId. Задайте тип данных и источник значения, затем укажите @productId@ в URI. Переменные пути обязательны, и каждая заданная переменная пути должна присутствовать в URI перед сохранением или тестированием.
Используйте Add query parameter (Добавить параметр запроса) для параметров вроде limit или language, которые указываются после вопросительного знака в URL. Введите имя, ожидаемое вашим API, его тип, описание и источник значения.
Доступные источники значений:
- Provided by user or chatbot (Предоставляется пользователем или чатботом): модель берет значение из диалога. Объясните ожидаемый формат и при необходимости отметьте параметры как обязательные.
- Constant (Константа): значение, заданное в настройках операции, например фиксированный идентификатор аккаунта или ограниченный токен API.
- Random value (Случайное значение): автоматически генерируемое значение.
- Client context (Клиентский контекст): значение, передаваемое сайтом, если эта функция доступна на вашем аккаунте. См. Chat API.
Скалярные типы включают string (строка), integer (целое число), double (число с плавающей точкой) и boolean (логическое значение). Параметры тела запроса также поддерживают массивы строк и целых чисел.
3. Настройте метод и тело запроса
Выберите GET, POST, PUT, PATCH или DELETE в соответствии с вашим эндпоинтом. Для методов, отличных от GET, редактор предлагает формат запроса raw или form-data.
Для тела в формате raw JSON определите параметры тела и вставьте их плейсхолдеры @name@ в шаблон. Добавьте соответствующий заголовок Content-Type, требуемый вашим эндпоинтом. Например, со строковым параметром name и массивом строк tags:
{
"name": "@name@",
"tags": @tags@
}
Это шаблон, а не готовый JSON до момента подстановки. Плейсхолдеры массивов нельзя оборачивать в кавычки. Каждый определенный параметр тела должен использоваться в шаблоне, если включен редактор raw JSON. Проверяйте сформированный запрос во время тестирования, особенно если текст содержит кавычки или спецсимволы.
4. Добавьте заголовки аутентификации
Используйте Add header (Добавить заголовок), чтобы указать заголовки, ожидаемые вашим API. Для bearer-токена укажите имя заголовка Authorization, источник значения Constant и значение Bearer YOUR_RESTRICTED_TOKEN.
Не передавайте конфиденциальные данные через промпты и URL. Избегайте операций, возвращающих токены авторизации модели с расчетом на то, что системные инструкции скроют их от пользователя. Рекомендуется использовать промежуточный серверный эндпоинт, который сам управляет аутентификацией и предоставляет доступ только к разрешенной операции.
5. Сохраните и протестируйте запрос
- Нажмите Save changes (Сохранить изменения) в редакторе операции. В отличие от стандартного раздела Settings (Настройки) чатбота, в этом редакторе предусмотрена отдельная кнопка сохранения.
- Нажмите Test API Operation (Протестировать операцию API). Она недоступна, пока изменения не сохранены.
- Введите подходящие тестовые значения параметров. Для передачи массивов разделяйте значения запятыми.
- Выполняйте тест только на тех данных, которые вам разрешено читать или изменять.
- Проверьте код ответа, тело ответа, URL запроса, заголовки, тело запроса и любые предупреждения в окне результатов.
- Исправьте ошибки, сохраните изменения и при необходимости повторите тест.
Не делитесь результатами тестирования, содержащими учетные данные. По возможности настройте возврат точечных данных с пагинацией: слишком большие ответы могут обрезаться до передачи модели.
6. Подключите операцию к чатботу
Откройте вашего чатбота, затем перейдите в Settings > Actions (Настройки > Действия). Нажмите кнопку со знаком «плюс», чтобы добавить действие, найдите вашу операцию в списке пользовательских API и подключите или включите ее. Одно лишь создание интеграции на уровне аккаунта не делает операцию доступной во всех чатботах автоматически.
Проверьте инструкции действия и доступные параметры безопасности, затем дождитесь подтверждения сохранения. Описание работы с редактором действий см. в статье AI actions.
7. Объясните, когда использовать действие
Перейдите в раздел Settings > Role & Behavior (Настройки > Роль и поведение).
Если вы используете собственные инструкции для роли, выберите Custom Role Definition (Пользовательское определение роли) и добавьте четкое правило, например: «Когда посетитель спрашивает, есть ли товар в наличии, вызови getProductDetails с ID этого товара. Сообщи полученный статус наличия. Если поиск завершился ошибкой, объясни, что проверить наличие не удалось».
Сохраняйте остальные полезные инструкции чатбота. Дождитесь подтверждения сохранения, затем перейдите во вкладку предпросмотра Overview (Обзор), чтобы протестировать реалистичные вопросы, поведение при отсутствии параметров, ошибки и несанкционированные запросы. В диалогах предпросмотра могут выполняться реальные операции.
Вызов инструментов моделью не гарантирован на 100% и не обязательно происходит строго один раз. Обязательно тестируйте сценарии на той модели, которая выбрана для вашего чатбота; само по себе название модели не гарантирует корректный вызов инструментов.
Безопасность и устранение неполадок
Ваш эндпоинт должен аутентифицировать запросы и проверять права доступа каждого пользователя перед возвратом конфиденциальных данных или внесением изменений. Идентификатор клиента, email, номер заказа или поле контекста, переданные браузером, не являются достаточным подтверждением личности. Если вы передаете пользовательский токен через клиентский контекст, ваш сервер обязан его проверять.
Возвращайте только те поля, которые действительно нужны чатботу, например статус заказа вместо полного профиля клиента. Инструкции в промпте помогают скорректировать формулировки, но не могут гарантировать, что конфиденциальные данные, переданные модели, не попадут в ответ пользователю.
Если запрос успешно выполняется в тестовом редакторе, но не работает в диалоге, проверьте привязку действия, его статус (включено ли оно), инструкции, обязательные параметры и доступный контекст. Если запрос не работает ни в редакторе, ни в чате, проверьте URL, HTTP-метод, аутентификацию, сформированное тело запроса и логи вашего эндпоинта. Не повторяйте запросы на запись данных многократно, пока не убедитесь, завершился ли успехом предыдущий запрос.