Эта статья поможет вам интегрировать чат-бота TWIN в стороннее приложение. Как мобильное, так и десктопное.

Мы стараемся поддерживать информацию в данной статье в актуальном состоянии. Все последние обновления для работы с сервисами TWIN в первую очередь публикуются на ресурсе https://developers.twin24.ai.

Команда TWIN постоянно совершенствуем свои сервисы. В связи с этим возможно внесение изменений в наше API. Просим вас учитывать этот факт при реализации интеграции чат-платформы TWIN с вашими приложениями. Важно обратить на это внимание при согласовании гарантийных обязательств.

Оглавление

Вступление

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

Интеграция через websockets
- Более продвинутая технически
- Позволяет вести общение через сервис чатов TWIN
  - Имеет большое количество дополнительных настроек
  - Ознакомиться с возможностями чатов можно по ссылке
Интеграция через 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 – уведомление о наборе сообщения ботом или оператором
{ "authorType": "BOT" // Автор события: BOT | OPERATOR }

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

{
    "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 – событие переключение диалога с бота или оператора на другого оператора или бота

{
    "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 – уведомление о прочтении сообщения оператором

{
    "messageId": "bce7d22e-dde6-4427-b391-ebbdfda44de6" // REQUIRED. Идентификатор сообщения
}

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

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

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

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