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

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

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

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

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:

Функция старта чат-сессии

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	Да	Идентификатор чата. Он определяет настройки чата и схему работы бота.

Тело запроса

Тело запроса в формате Json:

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

Ответ в формате JSON

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

Тело запроса

Тело запроса в формате Json:

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

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

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

Ответы

Код 201

Description: Successful message creation

Ответ в формате JSON

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Интеграция чат-платформы TWIN с использованием socket.io

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

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

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

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