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

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

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

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

<figure><img src="/files/xIdXBerPvJ9l8yasUP4M" alt=""><figcaption><p>Общая схема взаимодействия</p></figcaption></figure>

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

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

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

> <https://gptunnel.ru/api/bot>
>
> Пример запроса:
>
> ```bash
> 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** 👍

{% hint style="warning" %}
Чтобы получать ответы от чат-бота, баланс пользователя или организации должен быть положительный!
{% endhint %}

{% hint style="info" %}
Мы будем отправлять ответ на ваш webhook, который вы можете задать при создании интеграции на нашем сервисе в разделе [Боты](https://gptunnel.ru/bots/?view=integration)
{% endhint %}

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

{% tabs %}
{% tab title="CLIENT\_MESSAGE" %}

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

{% endtab %}

{% tab title="BOT\_MESSAGE" %}

```json
{
  "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
  }
}
```

{% endtab %}

{% tab title="INVITE\_AGENT" %}

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

{% endtab %}
{% endtabs %}

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

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

{% tabs %}
{% tab title="AGENT\_JOINED" %}
Отправьте это событие если оператор принял чат,

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

{% endtab %}

{% tab title="AGENT\_UNAVAILABLE" %}
Отправьте это событие если после получения INVITE\_AGENT не оказалось доступных операторов.

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

{% endtab %}

{% tab title="CHAT\_CLOSED" %}
Отправьте это событие если клиент закрыл чат.

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

{% endtab %}
{% endtabs %}

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

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

<pre class="language-bash"><code class="lang-bash"><strong>curl --request POST \
</strong>  --url https://gptunnel.ru/api/bot/balance \
  --header 'Authorization: YOUR_TOKEN' \
  --header 'Content-Type: application/json'
</code></pre>

В ответ мы отдадим вот такой **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" }'
```

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

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

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

или напрямую в техническую поддержку **@ScriptHeads**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gptunnel.ru/bot-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.