Оглавление

...

Вступление

В данной статье рассмотрены 2 варианта интеграции чат-бота TWIN с собственным приложением. 

1. Интеграция через websockets
   • Более продвинутая технически
   • Позволяет вести общение через сервис чатов TWIN
     • Имеет большое количество дополнительных настроек
     • Ознакомиться с возможностями чатов можно по ссылке 
2. Интеграция через HTTP REST API
   • Упрощенный способ интеграции
   • Интеграция производится напрямую с сервисом бота TWIN
     • Дополнительные настройки отсутствуют
     • Простое взаимодействие с ботом в формате "вопрос-ответ"

Интеграция через websockets

Основные шаги интеграции

• Создание сессии бота
  • Происходит путем запроса к API
  • В ответ будет получено сообщение бота (если есть) и id созданной сессии
• Подключение к соккет-серверу
  • В соккеты будут приходить события от бота и оператора
• Обмен сообщениями бот-клиент
  • Отправка сообщений клиента производится через API
  • Получение сообщений и событий бота и оператора происходит через соккеты

Основные методы API

Создание сессии бота

(Детальное описание с комментариями будет позже)

https://developers.twin24.ai/reference/startchatsessions

Отправка сообщений клиента в сессию бота

(Детальное описание с комментариями будет позже)

https://developers.twin24.ai/reference/continuelastorstartnewchatsessions

Прочие доступные методы

Со всеми доступными методами можно ознакомиться в документации разработчика:

https://developers.twin24.ai/reference/operatorchatsessionlist

Live события

Подключение к соккет-серверу

Для работы с соккет-сервером используется инструмент Centrifuge. 

Подробности о доступных SDK для работы с Centrifuge можно получить в официальной документации Centrifuge. 

Эндпоинт для подключения: wss://twin24.ai/centrifugo/connection/websocket 

• При подключении нужно отправить data и name

{
    "application": "widget", // REQUIERD. Всегда widget
    "settings": {
        "userId": "bce7d22e-dde6-4427-b391-ebbdfda44de6", // OPTIONAL. Уникальный идентификатор пользователя
        "sessions": [
            "bce7d22e-dde6-4427-b391-ebbdfda44de6" // REQUIRED. Идентификатор сессии бота (можно передать несколько для прослушивания сразу нескольких сессий)
        ]
    }
}

Всегда равно "js"

• В ответ на подключение будет получено следующее сообщение:

{
    "id": 1, // Порядковый номер сообщения
    "connect": { // Подробная информация о подключении
        "client": "bce7d22e-dde6-4427-b391-ebbdfda44de6", // Идентификатор клиента
        "version": "6.2.1 OSS", // Системная информация. Не имеет роли для интеграции
        "subs": { // Список доступных подписок
            "widget:bce7d22e-dde6-4427-b391-ebbdfda44de6": { // Имя канала подписки
                "recoverable": true, // Системная информация. Не имеет роли для интеграции
                "epoch": "1769579399", // Системная информация. Не имеет роли для интеграции
                "positioned": true // Системная информация. Не имеет роли для интеграции
            }
        },
        "ping": 25, // Частота пинга
        "pong": true // Флаг наличия понга
    }
}

• Далее необходимо подписаться на доступные каналы подписки, чтобы получать в них события. Название канала – ключи из объектов subs ("widget:bce7d22e-dde6-4427-b391-ebbdfda44de6")
• Далее нужно присоединиться к сессии 
  • Нужно передать rpc
  • Метод: joinSession
  • data: {"id": "bce7d22e-dde6-4427-b391-ebbdfda44de6"} // Идентификатор сессии
  • При успешно подключении в ответ будет получено сообщение: {"success": true}
• Теперь в соккеты будут приходить события от бота и оператора, а также системные события

Список событий

• showTypingIndicator – уведомление о наборе сообщения ботом или оператором
  

  Блок кода
  language json title Payload события linenumbers true
  { "authorType": "BOT" // Автор события: BOT | OPERATOR }

• chatMessageCreated – сообщение от бота или оператора
  

  Блок кода
  language json title Payload события linenumbers true
  { "id": "bce7d22e-dde6-4427-b391-ebbdfda44de6", // REQUIRED. Уникальный идентификатор сообщения "authorType": "BOT", // REQUIRED. ENUM: 'BOT' | 'OPERATOR'. Тип автора сообщения "body": "Тестовое сообщение", // REQUIRED. Текст сообщения (может быть пустым) "answers": [ // REQUIRED. Массив предустановленных вариантов ответов для пользователя "Вариант ответа 1", "Вариант ответа 2", "Вариант ответа 3" ], "keyboard": { // OPTIONAL. Объект клавиатуры с кнопками быстрых ответов "buttonsInRow": 2, // Количество кнопок в одном ряду "buttons": [ // Массив кнопок для отображения { "type": "text", // Тип кнопки. Всегда text. "text": "Кнопка 1" // Текст на кнопке }, { "type": "text", "text": "Кнопка 2" } ] }, "createdAt": "2026-01-28T12:00:00+00:00", // REQUIRED. Дата и время создания сообщения в формате ISO 8601 "sessionId": "bce7d22e-dde6-4427-b391-ebbdfda44de6", // REQUIRED. Идентификатор сессии чата "attachments": [ // REQUIRED. Массив прикрепленных файлов (может быть пустым) { "id": "bce7d22e-dde6-4427-b391-ebbdfda44de6", // REQUIRED. Идентификатор вложения "contentType": "image/png", // REQUIRED. MIME-тип файла (например: 'image/png', 'application/pdf') "size": 1024000, // REQUIRED. Размер файла в байтах "downloadLink": "https://example.com/file.png", // REQUIRED. Ссылка для скачивания файла "name": "test-file.png", // REQUIRED. Имя файла "url": "https://example.com/file.png" // OPTIONAL. Альтернативная ссылка на файл } ], "actions": [ // REQUIRED. Массив действий/кнопок для интерактивности (может быть пустым) { "type": "button", // REQUIRED. Тип действия "event": "click_action", // OPTIONAL. Событие, которое триггерится при клике "label": "Нажми меня", // OPTIONAL. Текст на кнопке действия "data": "{\"key\": \"value\"}" // OPTIONAL. Дополнительные данные в формате строки } ], "avatar": "https://example.com/avatar.png", // OPTIONAL. URL аватара автора "authorId": "bce7d22e-dde6-4427-b391-ebbdfda44de6", // OPTIONAL. Идентификатор автора "authorName": "Тестовый Автор", // OPTIONAL. Имя автора сообщения "type": "REGULAR", // OPTIONAL. ENUM: 'REGULAR' | 'TERMINAL'. Тип сообщения "replyId": "bce7d22e-dde6-4427-b391-ebbdfda44de6", // OPTIONAL. Идентификатор сообщения, на которое это сообщение является ответом "replyToMessage": { // OPTIONAL. Объект с информацией о сообщении, на которое отвечают "id": "bce7d22e-dde6-4427-b391-ebbdfda44de6", // REQUIRED. Идентификатор исходного сообщения "authorType": "CLIENT", // REQUIRED. ENUM: 'BOT' | 'OPERATOR' | 'CLIENT'. Тип автора исходного сообщения "body": "Исходное сообщение", // OPTIONAL. Текст исходного сообщения "authorName": "Имя клиента" // OPTIONAL. Имя автора исходного сообщения } }

• operatorChanged – событие переключение диалога с бота или оператора на другого оператора или бота
  

  Блок кода
  language json title Payload события linenumbers true
  { "operatorId": "bce7d22e-dde6-4427-b391-ebbdfda44de6", // REQUIRED. Идентификатор нового оператора "operatorName": "Тестовый Оператор", // REQUIRED. Имя нового оператора "avatar": "https://example.com/avatar.png", // REQUIRED. URL аватара нового оператора "previousOperatorId": "bce7d22e-dde6-4427-b391-ebbdfda44de6", // REQUIRED. Идентификатор предыдущего оператора "previousOperatorName": "Предыдущий Оператор", // REQUIRED. Имя предыдущего оператора "previousOperatorAvatar": null // REQUIRED. URL аватара предыдущего оператора }

• chatMessageRead – уведомление о прочтении сообщения оператором
  

  Блок кода
  language json title Payload события linenumbers true
  { "messageId": "bce7d22e-dde6-4427-b391-ebbdfda44de6" // REQUIRED. Идентификатор сообщения }

• sessionClosed – уведомление о закрытии сессии оператором
  

  Блок кода
  language json title Payload события linenumbers true
  { "sessionId": "bce7d22e-dde6-4427-b391-ebbdfda44de6", // REQUIRED. Идентификатор закрываемой сессии "chatId": "bce7d22e-dde6-4427-b391-ebbdfda44de6", // REQUIRED. Идентификатор чата "sessionRatingRequired": true // REQUIRED. Флаг, требуется ли оценка сессии от пользователя }

Интеграция через HTTP REST API

Подробный рецепт данной интеграции описан в отдельной статье: Рецепт интеграции с ботом по API