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

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

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

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

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

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

Примечание

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

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

Оглавление

Оглавление

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

Интеграция чат-платформы 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	Функция старта чат-сессии

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

Блок кода

language	py
firstline	1
title	Ответ в формате JSON
linenumbers	true

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

Блок кода

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

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

Тело запроса

Блок кода

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

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

Описаниеполейметода:

Поле	Тип	Обязательно	Описание
body	string	Да	Текст сообщения
attachments	array of strings	Нет
replyToMessageId	string	Нет

Ответы

Код 201

Description: Successful message creation

Блок кода

language	py
firstline	1
title	Ответ в формате JSON
linenumbers	true

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

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

Поле	Тип	Обязательно	Описание
id	string	Да	Идентификатор сообщения
createdAt	string	Да	Отметка даты и времени, когда было отправлено сообщение

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

Информация

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

Socket.IO - это библиотека для создания приложений, работающих в режиме реального времени, имеющих двунаправленный канал связи и основанных на событиях. Более подробно ознакомиться с библиотекой можно на сайте официальной документации.

Информация

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

Для взаимодействия с socket.io взята библиотека python-socketio версии 4.6.1

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

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

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

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

Блок кода

language	py
title	Событие: showTypingIndicatorEmit
collapse	true

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

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

Поле	Тип	Обязательно	Описание
authorType	string	Да	Определяет, кто отправил сообщение: бот или оператор.

СООБЩЕНИЯ

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

Блок кода

language	py
firstline	1
title	Событие: chatMessageCreatedEmit
collapse	true

[
    "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
    }
]

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

Блок кода

language	py
title	Событие: chatMessageCreatedEmit
collapse	true

[
    "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	string	Да	Идентификатор сообщения
authorId
authorType
authorName
type
body
answers
createdAt
sessionId
attachments
actions
avatar
\| id
\| isPrivate
\| createdAt
\| contentType
\| name
\| baseName
\| extension
\| suggestedExtension
\| path
\| size
\| url
\| downloadLink
\| ownerId

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

Блок кода

language	py
theme	Confluence
title	Cобытие: chatMessageReadEmit
collapse	true

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

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

Поле	Тип	Обязательно	Описание
messageId	string	Да	Идентификатор сообщения

ОПЕРАТОРЫ

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

Блок кода

language	py
title	Событие: operatorChangedEmit
collapse	true

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

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

Блок кода

language	py
title	Событие: operatorChangedEmit
collapse	true

[
    "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	string	Да	Идентификатор сообщения.
operatorId	string		Идентификатор оператора.
operatorName	string		Имя оператора
avatar
previousOperatorId	string		Идентификатор предыдущего оператора.
previousOperatorName	string		Имя предыдущего оператора.
previousOperatorAvatar	string		Аватар предыдущего оператора.
\| id
\| isPrivate
\| createdAt
\| contentType
\| name
\| baseName
\| extension
\| suggestedExtension
\| path
\| size
\| url

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

Блок кода

language	py
title	Событие: operatorStatusChangedEmit
collapse	true

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

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

Поле	Тип	Обязательно	Описание
operatorId	string	Да	Идентификатор оператора
previousStatus	string	Да	Предыдущий статус оператора
currentStatus	string	Да	Текущий статус оператора

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

Блок кода

language	py
title	Событие: operatorLoggedOutEmit
collapse	true

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

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

Поле	Тип	Обязательно	Описание
operatorId	string	Да	Идентификатор оператора

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

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

Блок кода

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

import socketio

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

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

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

Блок кода

language	py
theme	Confluence
firstline	1
title	Регистрация события chatMessageCreatedEmit

@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

Блок кода

language	py
theme	Confluence
firstline	1
title	Подключение к серверу

socket_session.connect(url=f"https://tcl.twin24.ai/operator/socket.io/?key={session_id}",
                       transports=["polling", "websocket"],
                       socketio_path="operator/socket.io")

Ниже представлена кодовая база всей программы:

Блок кода

language	py
theme	Confluence
firstline	1
title	Code example
linenumbers	true

# Импортируем все необходимые библиотеки
import json
import requests
import socketio
from datetime import datetime

# Указываем идентификатор чата (получить идентификатор необходимо в личном кабинете)
# Важно: необходимо указывать свои параметры идентификатора чата! Это пример!
CHAT_ID = "15249602-609a-40bb-9887-83c20efd76a4"

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


# Определяем функции, необходимые для работы программы
def start_chat_session(chat_id: str, name: str = "integration_example") -> dict:
    """
    Создаёт чат-сессию и озвращает коллекцию данных о ней.
    :param chat_id: Идентификатор чата.
    :param name: Имя чат-сессии. Задается для облегчения поиска в личном кабинете. Можно убрать этот параметр из функции)
    :return: Коллекция данных о созданной чат-сессии.
    """
    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.json()


def send_msg_to_chat_session(session_id: str, msg: str) -> dict:
    """
    Отправляет сообщение
    :param chat_session_id: Идентификатор чат-сессии.
    :param msg: Текст сообщения.
    :return: Коллекция данных об отправленном сообщении.
    """
    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.json()


# Создаём чат сессию и получаем данные о ней
chat_session_data = start_chat_session(chat_id=CHAT_ID,
                                       name=f"ws test {datetime.now()}")
# Из данных о чат-сессии получаем её id
session_id = chat_session_data['id']
print(chat_session_data, session_id, sep="\n\n")

# Подключаемся к серверу и "слушаем" события в созданной чат-сессии
socket_session.connect(url=f"https://tcl.twin24.ai/operator/socket.io/?key={session_id}",
                       transports=["polling", "websocket"],
                       socketio_path="operator/socket.io")

# Отправляем сообщение в чат-сессию
send_msg_to_chat_session(session_id=session_id,
                         msg="Тестовое сообщение, отправленное программой!")

# Закрываем соединение
socket_session.disconnect()

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

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

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

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

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

Новая версия 23

Ключ

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

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

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

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

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

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

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

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

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

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

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

Новая версия 23

Ключ

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

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

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

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

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

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