Оглавление

...

...

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

Оглавление

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

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

Возможность интеграции и её срок определяется специалистами на стороне клиента.

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

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

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

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

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

Список зависимостей окружения

aiohttp==3.8.4
aiosignal==1.3.1
async-timeout==4.0.2
attrs==23.1.0
bidict==0.22.1
certifi==2023.5.7
charset-normalizer==3.1.0
frozenlist==1.3.3
idna==3.4
multidict==6.0.4
python-engineio==3.14.2
python-socketio==4.6.1
requests==2.31.0
six==1.16.0
urllib3==2.0.3
websocket-client==1.6.0
yarl==1.9.2

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

Метод: POST

Authorization: No Auth 

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

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

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

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

...

Да

...

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

Тело запроса

{
  "name": "string",
  "botId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
  "sessionId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
  "sessionTtl": 3600,
  "messengerType": "WHATSAPP",
  "messengerUserId": "string",
  "messageBody": "string",
  "messageAttachments": [
    "bce7d22e-dde6-4427-b391-ebbdfda44de6"
  ],
  "clientNameForOperator": "string",
  "clientId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
  "clientExternalId": "string",
  "clientPhone": 75555673245,
  "clientEmail": "string",
  "clientDeviceId": "string",
  "clientTimezone": 300,
  "clientMetadata": {
    "var1": "val1",
    "var2": "val2",
    "var3": "val3"
  },
  "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

...

Нет

...

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

...

returnAnswerAsync

...

boolean

...

Нет

Ответы

Код 201

Description: Successful session creation

{
  "id": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
  "clientId": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
  "startedAt": "2018-10-31T11:56:07+00:00",
  "ttl": 3600,
  "messages": [
    {
      "body": "string",
      "answers": [
        "string"
      ],
      "actions": [
        {
          "key1": "value1",
          "key2": "value2",
          "key3": "value3"
        }
      ],
      "attachments": [
        {
          "id": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
          "isPrivate": true,
          "createdAt": "2018-10-31T11:56:07+00:00",
          "name": "bot.png",
          "baseName": "bot",
          "extension": "png",
          "sugestedExtension": "png",
          "path": "string",
          "size": 12400,
          "url": "string",
          "downloadLink": "string"
        }
      ]
    }
  ]
}

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

...

Поле

...

Тип

...

Обязательно

...

Описание

...

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:

def send_msg_to_chat_session(session_id: str, msg: str):
    url = f"https://chats-api.twin24.ai/api/v1/sessions/{session_id}/messages"
    headers = {'Content-Type': 'application/json'}
    payload = json.dumps({
        "body": msg,
        "attachments": []
    })
    response = requests.request("POST", url, headers=headers, data=payload)

    return response

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

...

Поле

...

Тип

...

Обязательно

...

Описание

...

sessionId

...

string

...

Да

...

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

Тело запроса

{
  "body": "string",
  "attachments": [
    "bce7d22e-dde6-4427-b391-ebbdfda44de6"
  ],
  "replyToMessageId": "string"
}

...

Поле

...

Тип

...

Обязательно

...

Описание

...

body

...

string

...

attachments

...

array of strings

...

replyToMessageId

...

string

...

Ответы

Код 201

Description: Successful message creation

{
  "id": "bce7d22e-dde6-4427-b391-ebbdfda44de6",
  "createdAt": "2018-10-31T11:56:07+00:00"
}

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

...

Поле

...

Тип

...

Обязательно

...

Описание

...

id

...

createdAt

...

...

Вступление

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

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

Справочная информация о событиях socket.io для виджета чат-платформы TWIN

Протокол Socket.IO основан на событиях. Когда сервер хочет установить связь с клиентом, он создает событие. Каждое событие имеет имя и список аргументов.

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

Процесс набора текста

[
    "showTypingIndicatorEmit",
    {
        "authorType": "BOT"
    }
]

Описание параметров события showTypingIndicatorEmit

...

Поле

...

Тип

...

Обязательно

...

Описание

...

authorType

...

СООБЩЕНИЯ

Создание сообщения ботом

[
    "chatMessageCreatedEmit",
    {
        "id": "d0f10a74-53fe-4a83-ac1f-ce55c0939df2",
        "authorId": "4f8151ed-8e7a-4a12-a6a5-c94f99c58019",
        "authorType": "BOT",
        "authorName": "МетроБот",
        "type": "REGULAR",
        "body": "Переключаю на оператора",
        "answers": [],
        "createdAt": "2021-03-10T08:37:53+00:00",
        "sessionId": "4d32dc5a-73d3-457e-9b30-5f7ff4c5fa24",
        "attachments": [],
        "actions": [],
        "avatar": null
    }
]

Создание сообщения оператором

[
    "chatMessageCreatedEmit",
    {
        "id": "25d27d8f-f633-42ef-b359-aeff3ce05001",
        "authorId": "389",
        "authorType": "OPERATOR",
        "authorName": "Первый Оператор V",
        "type": "REGULAR",
        "body": "\nHi",
        "answers": [],
        "createdAt": "2021-03-10T08:49:41+00:00",
        "sessionId": "b1a69f04-a759-4376-b8e5-ee82a7e0d247",
        "attachments": [],
        "actions": [],
        "avatar": {
            "id": "ed661c07-2d50-4b1f-b2c8-32f09a83065e",
            "isPrivate": false,
            "createdAt": "2021-02-05T12:58:33+00:00",
            "contentType": "image/jpeg",
            "name": "мяч.jpg",
            "baseName": "мяч",
            "extension": "jpg",
            "suggestedExtension": "jpg",
            "path": "",
            "size": 310723,
            "url": "https://minio.twin24.ai/twin-iam-dev/public/2021-02-05/ed661c07-2d50-4b1f-b2c8-32f09a83065e?response-content-type=image%2Fjpeg&response-content-disposition=inline%3B%20filename%3Dmyac.jpg%3B%20filename%2A%3Dutf-8%27%27%25D0%25BC%25D1%258F%25D1%2587.jpg",
            "downloadLink": "https://minio.twin24.ai/twin-iam-dev/public/2021-02-05/ed661c07-2d50-4b1f-b2c8-32f09a83065e?response-content-type=image%2Fjpeg&response-content-disposition=attachment%3B%20filename%3Dmyac.jpg%3B%20filename%2A%3Dutf-8%27%27%25D0%25BC%25D1%258F%25D1%2587.jpg&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=minio%2F20210310%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20210310T084942Z&X-Amz-SignedHeaders=host&X-Amz-Expires=604799&X-Amz-Signature=8810cdb3f30b4ccff3c521e7db6ece5d4dfe5814fbecd36b9eed4ae65e99c6fb",
            "ownerId": null
        }
    }
]

Описание параметров события chatMessageCreatedEmit

...

Поле

...

Тип

...

Обязательно

...

Описание

...

id

...

authorId

...

authorType

...

authorName

...

type

...

body

...

answers

...

createdAt

...

sessionId

...

attachments

...

actions

...

avatar

...

Подтверждение о прочтении сообщения

[
    "chatMessageReadEmit",
    {
        "messageId": "23280e7d-8d2f-409b-9480-82c805fcbb95"
    }
]

Описание параметров события chatMessageReadEmit

...

Поле

...

Тип

...

Обязательно

...

Описание

...

messageId

...

ОПЕРАТОРЫ

Назначение оператора после бота (первичное назначение)

[
    "operatorChangedEmit",
    {
        "operatorId": "494",
        "operatorName": "III Operator",
        "avatar": null,
        "previousOperatorId": "4f8151ed-8e7a-4a12-a6a5-c94f99c58019",
        "previousOperatorName": "МетроБот",
        "previousOperatorAvatar": null
    }
]

Назначение другого оператора (смена операторов)

[
    "operatorChangedEmit",
    {
        "operatorId": "472",
        "operatorName": "II Dev",
        "avatar": null,
        "previousOperatorId": "389",
        "previousOperatorName": "Первый Оператор V",
        "previousOperatorAvatar": {
            "id": "ed661c07-2d50-4b1f-b2c8-32f09a83065e",
            "isPrivate": false,
            "createdAt": "2021-02-05T12:58:33+00:00",
            "contentType": "image/jpeg",
            "name": "мяч.jpg",
            "baseName": "мяч",
            "extension": "jpg",
            "suggestedExtension": "jpg",
            "path": "",
            "size": 310723,
            "url": "https://minio.twin24.ai/twin-iam-dev/public/2021-02-05/ed661c07-2d50-4b1f-b2c8-32f09a83065e?response-content-type=image%2Fjpeg&response-content-disposition=inline%3B%20filename%3Dmyac.jpg%3B%20filename%2A%3Dutf-8%27%27%25D0%25BC%25D1%258F%25D1%2587.jpg",
            "downloadLink": "https://minio.twin24.ai/twin-iam-dev/public/2021-02-05/ed661c07-2d50-4b1f-b2c8-32f09a83065e?response-content-type=image%2Fjpeg&response-content-disposition=attachment%3B%20filename%3Dmyac.jpg%3B%20filename%2A%3Dutf-8%27%27%25D0%25BC%25D1%258F%25D1%2587.jpg&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=minio%2F20210310%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20210310T090557Z&X-Amz-SignedHeaders=host&X-Amz-Expires=604799&X-Amz-Signature=6156df5e15d5ab535fdcf80204de440a3cfb8b8fa4d8e3a92b93cc6796f539a3",
            "ownerId": null
        }
    }
]

Описание параметров события chatMessageCreatedEmit

...

Поле

...

Тип

...

Обязательно

...

Описание

...

id

...

operatorId

...

operatorName

...

avatar

...

previousOperatorId

...

previousOperatorName

...

previousOperatorAvatar

...

Статус оператора

[
    "operatorStatusChangedEmit",
    {
        "operatorId": "389",
        "previousStatus": "ACTIVE",
        "currentStatus": "PAUSED"
    }
]

Описание параметров события operatorStatusChangedEmit

...

Поле

...

Тип

...

Обязательно

...

Описание

...

operatorId

...

previousStatus

...

currentStatus

...

Выход оператора из системы

[
    "operatorLoggedOutEmit",
    {
        "operatorId": "389"
    }
]

Описание параметров события operatorStatusChangedEmit

...

Поле

...

Тип

...

Обязательно

...

Описание

...

operatorId

...

Подключение чат-сессии к socket.io

Создание клиентского экземпляра

import socketio

# Создаем экземпляр клиента
socket_session = socketio.Client()

Определение обработчиков событий

Регистрируем функцию обработчика событий с помощью декоратора socketio.Client.on() указывая имя события:

@socket_session.on("chatMessageCreatedEmit")
def on_message(data):
    print('I received a message!')

Подключаемся к серверу используя TLS/SSL подключение.
URL для подключения к серверу: https://tcl.twin24.ai/operator/socket.io/?key={session_id}

Параметр session_id предварительно был получен при вызове функции start_chat_session

...

...

• "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Это минимальная программа, отображающая все шаги, необходимые для интеграции чат-платформы TWIN в кодовую базу приложения клиента.