Актуальность информации
Учтите при интеграции
SDK как основной инструмент интеграции
В дальнейшем интеграцию чат-платформу TWIN планируется осуществлять с помощью SDK (находиться в разработке). Это позволит производить процесс интеграции быстрее и обеспечит более высокую стабильность работы.
Оглавление
Информация об интеграции
Интеграция чат-платформы TWIN в приложение (кодовую базу) клиента идёт на стороне клиента.
Возможность интеграции и её срок определяется специалистами на стороне клиента.
Со своей стороны TWIN предоставляет необходимую документацию по методам подключения и взаимодействия платформы с приложением заказчика.
Для обеспечения двухсторонней связи используется библиотека Socket.IO, построенная на основе протокола WebSocket.
Интеграция осуществляется в несколько простых шагов:
- Старт чат-сессии. Происходит при помощи API.
- Отправка сообщения в чат сессию. Происходит при помощи API.
- Получение сообщений, подтверждение получения сообщений - происходит с помощью 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 | string | Да | Идентификатор сообщения |
createdAt | string | Да | Отметка даты и времени, когда было отправлено сообщение |
Подключение к сокетам
О библиотеки socket.io
Socket.IO - это библиотека для создания приложений, работающих в режиме реального времени, имеющих двунаправленный канал связи и основанных на событиях. Более подробно ознакомиться с библиотекой можно на сайте официальной документации.
О библиотеки socket.io
Для взаимодействия с socket.io взята библиотека python-socketio версии 4.6.1
Справочная информация о событиях socket.io для виджета чат-платформы TWIN
Протокол Socket.IO основан на событиях. Когда сервер хочет установить связь с клиентом, он создает событие. Каждое событие имеет имя и список аргументов.
Ниже представлены ключевые события, которые возникают в виджете и описаны параметры каждого события.
Данная информация носит справочный характер и позволяет определить, какие события необходимо инициировать для корректной интеграции чат-платформы в кодовую базу приложения на стороне клиента.
Процесс набора текста
Описание параметров события showTypingIndicatorEmit
Поле | Тип | Обязательно | Описание |
|---|---|---|---|
authorType | string | Да | Тип автора. Определяет, кто отправил сообщение: бот или оператор. |
СООБЩЕНИЯ
Создание сообщения ботом
Создание сообщения оператором
Описание параметров события chatMessageCreatedEmit
Поле | Тип | Обязательно | Описание |
|---|---|---|---|
id | string | Да | Идентификатор сообщения. |
authorId | string | Идентификатор автора сообщения. | |
authorType | string | Тип автора. Определяет, кто отправил сообщение: бот или оператор. | |
authorName | string | Имя автора сообщения. | |
type | string | ||
body | string | Текст сообщения. | |
answers | string | ||
createdAt | string | Отметка времени о созданном сообщении. | |
sessionId | string | Идентификатор чат-сессии. | |
attachments | string | ||
actions | string | ||
avatar | string | ||
| | id | string | ||
| | isPrivate | string | ||
| | createdAt | string | ||
| | contentType | string | ||
| | name | string | ||
| | baseName | string | ||
| | extension | string | ||
| | suggestedExtension | string | ||
| | path | string | ||
| | size | string | ||
| | url | string | ||
| | downloadLink | string | ||
| | ownerId | string |
Подтверждение о прочтении сообщения
Описание параметров события chatMessageReadEmit
Поле | Тип | Обязательно | Описание |
|---|---|---|---|
messageId | string | Да | Идентификатор сообщения |
ОПЕРАТОРЫ
Назначение оператора после бота (первичное назначение)
Назначение другого оператора (смена операторов)
Описание параметров события chatMessageCreatedEmit
Поле | Тип | Обязательно | Описание |
|---|---|---|---|
id | string | Да | Идентификатор сообщения. |
operatorId | string | Идентификатор оператора. | |
operatorName | string | Имя оператора | |
avatar | string | ||
previousOperatorId | string | Идентификатор предыдущего оператора. | |
previousOperatorName | string | Имя предыдущего оператора. | |
previousOperatorAvatar | string | Аватар предыдущего оператора. | |
| | id | string | ||
| | isPrivate | string | ||
| | createdAt | string | ||
| | contentType | string | ||
| | name | string | ||
| | baseName | string | ||
| | extension | string | ||
| | suggestedExtension | string | ||
| | path | string | ||
| | size | string | ||
| | url | string |
Статус оператора
Описание параметров события operatorStatusChangedEmit
Поле | Тип | Обязательно | Описание |
|---|---|---|---|
operatorId | string | Да | Идентификатор оператора |
previousStatus | string | Да | Предыдущий статус оператора |
currentStatus | string | Да | Текущий статус оператора |
Выход оператора из системы
Описание параметров события operatorStatusChangedEmit
Поле | Тип | Обязательно | Описание |
|---|---|---|---|
operatorId | string | Да | Идентификатор оператора |
Подключение чат-сессии к 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
socket_session.connect(url=f"https://tcl.twin24.ai/operator/socket.io/?key={session_id}",
transports=["polling", "websocket"],
socketio_path="operator/socket.io")
После этого шага, всё готово для того чтобы "слушать" происходящие события в указанной чат-сессии. Можно отправлять сообщения и в случае завершения диалога закрывать соединение.
Ниже представлена кодовая база всей программы:
# Импортируем все необходимые библиотеки
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 в кодовую базу приложения клиента.