Оглавление

...

...

В скором времени интеграцию чат-платформу TWIN планируется осуществлять с помощью SDK. Это позволит производить процесс интеграции быстрее и обеспечит более высокую стабильность работы. Дополнительно о сроках реализации SDK вы можете узнать у наших специалистов.

...

Вступление

В данной статье рассмотрены 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

--Для интеграции чат-платформы необходимо выполнить следующие шаги--

Старт новой чат-сессии

Метод: POST

Authorization: No Auth 

URL: https://chat-api.twin24.ai/api/v1/chats/{chatId}/sessions

Ссылка на документацию

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

...

Поле

...

Тип

...

Обязательно

...

Описание

...

chatId

...

string

...

Да

...

Идентификатор чата. Он определяет настройки чата и схему работы бота.

{
  "name": "string",
  "botId": "bce7d22e-dde6-4427-b391-ebbdfda44de6", // Идентификатор клиента
       "sessionId": " "version": "6.2.1 OSS", // Системная информация. Не имеет роли для интеграции
        "subs": { // Список доступных подписок
            "widget:bce7d22e-dde6-4427-b391-ebbdfda44de6",
  "sessionTtl: { // Имя канала подписки
                "recoverable": 3600,
true, // Системная информация. Не имеет роли для интеграции
                "messengerTypeepoch": "WHATSAPP1769579399", // Системная информация. Не имеет роли для интеграции
  "messengerUserId": "string",
  "messageBody": "string",
  "messageAttachments": [
                  "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":

...

Поле

...

Тип

...

Обязательно

...

Описание

...

name

...

string

...

Нет

...

Имя сессии

...

botId

...

string

...

Нет

...

Пароль учётной записи аккаунта.

...

sessionId

...

sessionTtl

...

Время жизни чат-сессии. Указывается в секундах и не может быть больше 12 часов. По умолчанию равен 3 600 секундам.

...

messengerType

...

messengerUserId

...

messageBody

...

messageAttachments

...

clientNameForOperator

...

Нет

...

Имя клиента, которое будет видно оператору.

...

clientId

...

Нет

...

clientExternalId

...

string

...

Нет

...

Определяемый пользователем идентификатор клиента, инициировавшего сеанс чата.

...

clientPhone

...

string

...

Нет

...

clientEmail

...

string

...

Нет

...

Электронная почта клиента

...

clientDeviceId

...

string

...

Нет

...

Идентификатор клиентского устройства для отправки PUSH-уведомлений.

...

clientTimezone

...

integer

...

Нет

...

Смещение часового пояса клиента в минутах.

...

clientMetadata

...

object

...

Нет

...

Любые определенные пользователем пары ключ/значение в качестве переменных бота.

...

returnAnswerAsync

...

boolean

...

Нет

Ответы

Код 201

Description: Successful session creation

...

...

• "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. Идентификатор чата

...

Код 400

...

• "sessionRatingRequired": true // REQUIRED. Флаг, требуется ли оценка сессии от пользователя }

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

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

...

Код 404

Description: Entity not found

...

Код 5XX

...