Подсказка

title	Для кого нужна эта статья

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

Предупреждение

title	Актуальность информации

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

note

Предупреждение

title	Учтите при интеграции

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

Оглавление

...

title	SDK как основной инструмент интеграции

...

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

Оглавление

...

Вступление

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

Блок кода

language	json
title	data
linenumbers	true

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

Блок кода

language	json
title	name
linenumbers	true

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

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

Блок кода

language	json
linenumbers	true

{
    "id": 1, // Порядковый номер сообщения
    "connect": { // Подробная информация о подключении
        "client

Оглавление

Оглавление

Информация об интеграции

Интеграция чат-платформы TWIN в приложение (кодовую базу) клиента идёт на стороне клиента. Так как интеграция осуществляется силами клиента, счёт за такую интеграцию не выставляется.

Возможность интеграции и её срок определяется специалистами на стороне клиента. Со своей стороны TWIN предоставляет необходимую документацию по методам подключения и взаимодействия платформы с приложением заказчика.

Для обеспечения двухсторонней связи используется библиотека Socket.IO, построенная на основе протокола WebSocket.

Интеграция осуществляется в несколько простых шагов:

Старт чат-сессии. Происходит при помощи API.
Отправка сообщения в чат сессию. Происходит при помощи API.
Получение сообщений, подтверждение получения сообщений - происходит с помощью socket.io.

Ниже детально описаны все перечисленные этапы с примерами кода на языке python 3.11.

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

Метод: POST

Authorization: No Auth

URL: https://tcl.twin24.ai/api/chats/v1/chats/{chat_id}/sessions?x_widget=1

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

Пример функции на языке python:

Блок кода

language	py
theme	Confluence
firstline	1
title	Функция старта чат-сессии
linenumbers	true

def start_chat_session(chat_id: str, name: str = "integration_example"):
    url = f"https://tcl.twin24.ai/api/chats/v1/chats/{chat_id}/sessions?x_widget=1"
    headers = {"Content-Type": "application/json"}
    payload = json.dumps({"name": name})
    response = requests.request("POST", url, headers=headers, data=payload)
    
    return response

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

...

Поле

...

Тип

...

Обязательно

...

Описание

...

chatId

...

string

...

Да

...

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

Тело запроса

Блок кода

language	py
firstline	1
title	Тело запроса в формате Json:
linenumbers	true

{
  "name": "string",
  "botId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
  "sessionId": "bce7d22e-dde6-4427-b391-ebbdfda44de6", // Идентификатор клиента
     "sessionTtl": 3600,
  "messengerTypeversion": "WHATSAPP",
  "messengerUserId": "string",
  "messageBody": "string",
  "messageAttachments": [
6.2.1 OSS", // Системная информация. Не имеет роли для интеграции
        "subs": { // Список доступных подписок
            "widget:bce7d22e-dde6-4427-b391-ebbdfda44de6": { // Имя канала подписки
  ],
              "clientNameForOperatorrecoverable": "string",
  "clientId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
  "clientExternalId": "string",
  "clientPhone": 75555673245,
  "clientEmail": "string",
  "clientDeviceId": "string",
  "clientTimezone": 300,
  "clientMetadata": {
    "var1": "val1"true, // Системная информация. Не имеет роли для интеграции
                "epoch": "1769579399", // Системная информация. Не имеет роли для интеграции
                "positioned": true // Системная информация. Не имеет роли для интеграции
            }
        },
        "var2ping": "val2",25, // Частота пинга
        "var3pong": "val3"
  },true // Флаг наличия понга
  "returnAnswerAsync": true
}

...

Поле

...

Тип

...

Обязательно

...

Описание

...

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

...

Нет

...

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

}
}

Далее необходимо подписаться на доступные каналы подписки, чтобы получать в них события. Название канала – ключи из объектов 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 события

...

returnAnswerAsync

...

boolean

...

Нет

Ответы

Код 201

Description: Successful session creation

...


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. Текст на кнопке действия

...

Описание полей ответа

...

Поле

...

Тип

...

Обязательно

...

Описание

...

id

...

clientId

...

startedAt

...

ttl

...

messages

...

| body

...

| answers

...

| actions

...

| attachments

...

| | id

...

| | isPrivate

...

| | createdAt

...

| | name

...

| | baseName

...

| | extension

...

| | sugestedExtension

...

| | path

...

| | size

...

| | url

...

| | downloadLink

В успешном ответе содержится идентификатор чат-сессии. Именно этот параметр будет в дальнейшем использоваться для отправки сообщения в чат-сессию и подключения socket.io для "прослушивания" событий в данной чат-сессии.

Отправка сообщения в чат сессию

Метод: POST

Authorization: No Auth

URL: https://chats-api.twin24.ai/api/v1/sessions/{session_id}/messages

Пример функции на языке python:

...

language	py
theme	Confluence
firstline	1
title	Функция отправки сообщения в чат-сессию
linenumbers	true

...

        "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'. Тип автора исходного сообщения

...

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

...

Поле

...

Тип

...

Обязательно

...

Описание

...

sessionId

...

string

...

Да

...

Идентификатор чат-сессии.

...

"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":

...

Поле

...

Тип

...

Обязательно

...

Описание

...

body

...

string

...

 null // REQUIRED. URL аватара предыдущего оператора
}

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

...

attachments

...

array of strings

...

replyToMessageId

...

string

...

Ответы

Код 201

Description: Successful message creation

...

linenumbers true
{ "

...

sessionId": "bce7d22e-dde6-4427-b391-ebbdfda44de6", // REQUIRED. Идентификатор закрываемой сессии 
    "

...

chatId": "

...

Описание полей ответа

...

Поле

...

Тип

...

Обязательно

...

Описание

...

id

...

createdAt

...

Подключение к сокетам

...

title	О библиотеки socket.io

...

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

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

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

Быстрые ссылки

Дерево страниц

Сравнение версий

Старая версия 16

Новая версия Текущий

Ключ

Вступление

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

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

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

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

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

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

Live события

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

Информация об интеграции

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

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

Отправка сообщения в чат сессию

Подключение к сокетам

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

Быстрые ссылки

Дерево страниц

История страницы

Сравнение версий

Старая версия 16

Новая версия Текущий

Ключ

Вступление

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

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

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

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

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

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

Live события

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

Информация об интеграции

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

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

Отправка сообщения в чат сессию

Подключение к сокетам

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