API Интеграция

API интеграция позволяет вам подключать AI-консультантов Wikilect к вашим собственным системам через REST API. Это дает возможность отправлять сообщения боту или создавать новые чаты для пользователей из любых внешних систем.

Настройка API интеграции

Перейдите в раздел Настройки → Консультанты
Выберите навык, для которого хотите настроить API интеграцию
На вкладке Интеграции выберите API
Настройте параметры интеграции и сохраните изменения
Скопируйте URL для API запросов и токен авторизации (если используется)

Взаимодействие с API

Отправка сообщения или создание нового чата

URL-адрес

https://app.wikilect.com/api/bots/{tenant}/integration/{integration_id}/message

Где: - {tenant} — уникальный идентификатор вашего тенанта - {integration_id} — ID интеграции

Метод

POST

Заголовки запроса

Authorization: Bearer {your_token}
Content-Type: application/json

Тело запроса

Для отправки сообщения:

{
  "skill_id": 191,
  "consultant_id": 116,
  "type": "message",
  "message": "Hello!",
  "user_id": "user-1",
  "use_history": true,
  "use_webhook": false,
  "query_context": {"info": "Дополнительная информация о запросе"},
  "user_context": {
    "name": "Иван",
    "last_name": "Иванов"
  }
}

Для создания нового чата:

{
  "skill_id": 191,
  "consultant_id": 116,
  "type": "newChat",
  "message": "Hello!",
  "user_id": "user-1",
  "use_history": true,
  "use_webhook": false,
  "query_context": {"info": "Дополнительная информация о запросе"},
  "user_context": {
    "name": "Иван",
    "last_name": "Иванов"
  }
}

Описание параметров

Параметр	Тип	Описание
skill_id	int	Уникальный ID навыка, с которым связан бот
consultant_id	int	ID консультанта
type	string	Тип операции: `message` для отправки сообщения или `newChat` для создания нового чата
message	string	Содержимое сообщения
user_id	string	Уникальный идентификатор пользователя
use_history	boolean	Опционально, по умолчанию `true`. Указывает, следует ли учитывать историю общения при ответе
use_webhook	boolean	Опционально, по умолчанию `false`. Указывает, следует ли использовать webhook's при запросах к API
user_context	JSON	Опционально. Дополнительная информация о пользователе (например, имя, фамилия), сохраняемая в профиле
query_context	JSON	Опционально. Дополнительная информация, передаваемая вместе с сообщением, для контекстуального понимания ботом

Пример запроса с CURL

curl --location 'https://app.wikilect.com/api/bots/{tenant}/integration/{integration_id}/message' \
--header 'Authorization: Bearer {your_token}' \
--header 'Content-Type: application/json' \
--data '{
  "skill_id": 191,
  "consultant_id": 116,
  "type": "message",
  "message": "Hello!",
  "user_id": "user-1",
  "use_history": true,
  "use_webhook": false,
  "query_context": {"info": "Дополнительная информация о запросе"},
  "user_context": {
    "name": "Иван",
    "last_name": "Иванов"
  }
}'

Ответы API

Синхронный ответ (use_webhook: false)

Если параметр use_webhook установлен в false, бот вернет ответ непосредственно в результате запроса:

{
    "status": "success",
    "data": {
        "type": "message",
        "message": "Здравствуйте! Чем я могу вам помочь сегодня?",
        "metadata": {
            "category": "greeting"
        },
        "role": "BOT",
        "user_id": "user-1",
        "created_at": "2024-10-09T00:08:34.283051+00:00",
        "consultant": 116,
        "skill": 191,
        "tenant": "your-tenant"
    }
}

Асинхронный ответ через webhook (use_webhook: true)

Если параметр use_webhook установлен в true, бот отправит подтверждение о получении запроса и отправит ответ на указанный webhook URL:

{
    "status": "success",
    "detail": "Answer will be sent to https://your-webhook-url.com"
}

Webhooks

Когда используются webhooks, бот отправляет ответы на ваш настроенный URL.

Формат webhook для ответа бота

{
  "type": "message",
  "message": "Здравствуйте! Чем я могу вам помочь сегодня?",
  "metadata": {
    "category": "greeting"
  },
  "role": "BOT",
  "user_id": "user-1",
  "created_at": "2024-10-09T00:08:34.283051+00:00",
  "consultant": 116,
  "skill": 191,
  "tenant": "your-tenant"
}

Формат webhook для ответа менеджера

{
  "type": "message",
  "message": "Здравствуйте, я менеджер Анна. Чем я могу вам помочь?",
  "metadata": null,
  "role": "MANAGER",
  "user_id": "user-1",
  "created_at": "2024-10-09T00:09:48.235597+00:00",
  "consultant": 116,
  "skill": 191,
  "tenant": "your-tenant"
}

Описание полей webhook

Поле	Тип	Описание
role	string	Указывает, кто отправил сообщение: `BOT` или `MANAGER`
type	string	Всегда `message`
skill	int	ID навыка, связанного с разговором
tenant	string	Идентификатор тенанта
message	string	Содержимое сообщения
metadata	JSON	Дополнительные метаданные (могут содержать теги XML)
user_id	string	Уникальный идентификатор пользователя
consultant	int	ID консультанта, управляющего сообщением
created_at	string	Время создания сообщения