Интеграция чат-ботов

В этом разделе мы опишем, как вы можете интегрировать свой чат-сервис с нашими чат-ботами.

Наша платформа предоставляет возможность интеграции чат-ботов, таких как Claude Opus, GPT-4 и других моделей, с внешними чат-сервисами через систему взаимодействия вебхуков. Этот интерфейс позволяет легко подключить ваш чат-сервис к нашим чат-ботам и обеспечить бесшовное общение между пользователями и ботами.

Принцип работы

Для интеграции чат-бота с внешним чат-сервисом необходимо настроить вебхуки с каждой стороны. Обмен данными происходит через авторизованные POST-запросы, где токен авторизации передается в заголовке Authorization. Данные передаются в формате JSON, что требует наличия специального заголовка Content-Type: application/json.

Общая схема взаимодействия

Инициатором обмена всегда выступает сторона чат-сервиса. При отправке сообщения пользователем, чат-сервис отправляет событие CLIENT_MESSAGE на вебхук нашего чат-бота. Бот обрабатывает полученное сообщение и генерирует ответ, который отправляется обратно на вебхук чат-сервиса в событии BOT_MESSAGE.

В случае, если бот считает необходимым перевести диалог на живого оператора, он отправляет событие INVITE_AGENT на вебхук чат-сервиса. Это событие сигнализирует о том, что дальнейшее общение должно быть передано реальному оператору для более персонализированной поддержки.

Адрес для отправки POST событий

https://gptunnel.ru/api/bot

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

curl --request POST \
  --url https://gptunnel.ru/api/bot \
  --header 'Authorization: YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "event": "CLIENT_MESSAGE", "id": "9f7b373e-fce1-11ee-9da4-a912f79ee445", "chat_id": "4976", "client_id": "30005", "message": { "type": "TEXT", "text": "Добрый день", "timestamp": 1713375646 }, "agents_online": false }'

При получении события мы ответим кодом 200 👍

Чтобы получать ответы от чат-бота, баланс пользователя или организации должен быть положительный!

Мы будем отправлять ответ на ваш webhook, который вы можете задать при создании интеграции на нашем сервисе в разделе Боты

Примеры основных событий

CLIENT_MESSAGE

{
  "event": "CLIENT_MESSAGE",
  "id": "9f7b373e-fce1-11ee-9da4-a912f79ee445",
  "chat_id": "4976",
  "client_id": "30005",
  "message": {
    "type": "TEXT",
    "text": "Добрый день",
    "timestamp": 1713375646
  },
  "agents_online": false
}

BOT_MESSAGE

{
  "event": "BOT_MESSAGE",
  "id": "6620ce58bb349500015fa366",
  "chat_id": "4976",
  "client_id": "30005",
  "client_event_id": "9f7b373e-fce1-11ee-9da4-a912f79ee445",
  "message": {
    "type": "MARKDOWN",
    "content": "Здравствуйте! Чем могу помочь?",
    "text": "Здравствуйте! Чем могу помочь?",
    "timestamp": 1713375648
  }
}

INVITE_AGENT

{
  "event": "INVITE_AGENT",
  "id": "6620ce58bb349500015fa367",
  "chat_id": "4976",
  "client_id": "30005",
  "client_event_id": "9f7b373e-fce1-11ee-9da4-a912f79ee445"
}

Если есть необходимость в использовании функции Vision (только для моделей Сlaude и GPT-4) в message также будет необходимо передать список изображения "images": ["url"]

Существую еще несколько событий, которые мы рекомендуем отправлять нам:

AGENT_JOINED

Отправьте это событие если оператор принял чат,

{
  "event": "AGENT_JOINED",
  "id": "9f7b373e-fce1-11ee-9da4-a912f79ee445",
  "chat_id": "4976",
  "client_id": "30005"
}

AGENT_UNAVAILABLE

Отправьте это событие если после получения INVITE_AGENT не оказалось доступных операторов.

{
  "event": "AGENT_UNAVAILABLE",
  "id": "9f7b373e-fce1-11ee-9da4-a912f79ee445",
  "chat_id": "4976",
  "client_id": "30005"
}

CHAT_CLOSED

Отправьте это событие если клиент закрыл чат.

{
  "event": "CHAT_CLOSED",
  "id": "9f7b373e-fce1-11ee-9da4-a912f79ee445",
  "chat_id": "4976",
  "client_id": "30005"
}

Получить баланс

Для интеграции может понадобиться знать текущий баланс, чтобы клиент мог отслеживать необходимость оплаты сервиса. Для того чтобы получить баланс необходимо отправить запрос

curl --request POST \
  --url https://gptunnel.ru/api/bot/balance \
  --header 'Authorization: YOUR_TOKEN' \
  --header 'Content-Type: application/json'

В ответ мы отдадим вот такой JSON

{
	"ok": true,
	"message": "OK",
	"balance": "354.91"
}

Настройка обратного Webhook через API

Для удобства клиентов вам может потребоваться настроить URL для ответов программно без участия клиента, это можно сделать запросом.

curl --request POST \
  --url https://gptunnel.ru/api/bot/config \
  --header 'Authorization: YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "webHookUrl": "https://bestbotever.com/webhook" }'

Если все гуд то ответ будет такой:

{
	"ok": true,
	"message": "OK",
}

Если у вас остались вопросы по интеграции сервиса, вы можете задать их в нашем Телеграм сообществе: https://t.me/gptunnel_ru