...

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

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

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

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

...

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

Метод: POST

...

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

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

...

Тело запроса

Блок кода

language	py	theme	DJango
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		Нет 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	Нет

...

Description: Successful session creation

Блок кода

language	py	theme	DJango
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	Функция отправки сообщения в чат-сессию
linenumbers	true

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

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

...

Тело запроса

Блок кода

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

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

...

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

...

Description: Successful message creation

Блок кода

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

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

...

Информация

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

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

Блок кода

language	py
theme	Confluence
firstline	1
title	Определение обработчика событий
linenumbers	true

import json import requests import socketio # Создаем экземпляр клиента socket_session = socketio

.

Client() CHAT_ID = "" def start_chat_session(chat_id: str, name: str = ""): url = f"https://tcl.twin24.ai/api/chats/v1/chats/{chat_id}/sessions?x_widget=1" payload = json.dumps({"name": name}) headers = {"Content-Type": "application/json"} response = requests.request("POST", url, headers=headers, data=payload) return response # Определение обработчика событий @socket_session.on("chatMessageCreatedEmit") def on_message(data): print('I received a message!') @socket_session.event def connect(): print("I'm connected!") @socket_session.event def connect_error(data): print("The connection failed!") @socket_session.event def disconnect(): print("I'm disconnected!") response = start_chat_session(chat_id=CHAT_ID, name=f"imitation {test_time}") session_id = response.json()['id'] # Подключение к серверу socket_session.connect(f"https://tcl.twin24.ai/operator/socket.io/?key={session_id}", transports=["polling", "websocket"], socketio_path="operator/socket.io") socket_session.disconnect()

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

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

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

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

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

Ключ

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

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

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

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

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

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

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

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

Ключ

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

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