API-интеграции ИИ-агента

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

Токен должен иметь scope ai_agents_api_integrations.

Базовый URL: https://api.apx.chat/api

Структура интеграции

JSON
{
  "id": "uuid",
  "name": "Магазин",
  "authPrefix": "Bearer",
  "folders": [
    {
      "id": "uuid",
      "name": "Пользователи",
      "order": 0,
      "endpoints": [
        {
          "id": "uuid",
          "method": "GET",
          "url": "https://api.example.com/users/{id}",
          "description": "Получить пользователя по id",
          "responseExample": "{ \"id\": 1, \"name\": \"Иван\" }",
          "enabled": true,
          "useUserToken": false,
          "order": 0
        }
      ],
      "children": []
    }
  ]
}
  • name — обязательно.
  • authPrefix — опциональный префикс (например Bearer), пробелы убираются.
  • folders — иерархия; у каждой папки есть endpoints и children (вложенные папки).
  • useUserToken — если true, AI-оператор передаёт в ручку клиентский токен (см. widget.setToken).

Endpoints

Список

GET /api/ai-agents/external/api-integrations

Создание

POST /api/ai-agents/external/api-integrations

Опциональное поле agentId сразу привязывает интеграцию к ИИ-агенту — агент получит ссылку на эту интеграцию.

const url = "https://api.apx.chat/api/ai-agents/external/api-integrations";

const payload = {
"name": "Магазин",
"agentId": "b0c6...",
"folders": [
  {
    "name": "Пользователи",
    "endpoints": [
      {
        "method": "GET",
        "url": "https://api.example.com/users/{id}",
        "description": "Получить пользователя по id",
        "enabled": true
      }
    ]
  }
]
};

const response = await fetch(url, {
  method: "POST",
  headers: {
    "X-Api-Token": "tok_xxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

const data = await response.json();
console.log(data);

Получение / обновление / удаление

  • GET /api/ai-agents/external/api-integrations/{id}
  • PATCH /api/ai-agents/external/api-integrations/{id} — частичное обновление (полная замена структуры folders, если передать её)
  • DELETE /api/ai-agents/external/api-integrations/{id} — удаляет интеграцию и снимает её с привязанного агента

Выбор ИИ-агента на канале

Чтобы AI-оператор начал вызывать ваш API, привяжите интеграцию к ИИ-агенту (поле agentId) и выберите агента на канале через настройки AI-оператора канала.