Chat API

Краткое руководство по ChatAPI.

• Соглашения
• Управление адаптерами
• Список адаптеров
• Создание адаптера
• Редактирование адаптера
• Удаление адаптера
• Каналы чатов
• Список каналов
• Подключение адаптера
• Список подключений
• Создание подключения
• Изменение подключения
• Удаление подключения
• Chat API
• Аутентификация адаптера в Chat API
• Методы Chat API
  • Создание чата
  • Завершение чата
  • Трансфер чата
  • Отправка сообщения
  • Добавление ресурса
  • Получение данных ресурса
• Обратные вызовы
  • Создание аккаунта
  • Изменение аккаунта
  • Удаление аккаунта
  • Создание канала
  • Изменение канала
  • Удаление канала
  • Новый чат
  • Обновление чата
  • Завершение чата
  • Закрепление чата за оператором
  • Новое сообщение
  • Обновление сообщения
  • Изменение статуса сообщения
  • Обновление информации о посетителе
• Работа с каналом типа waba
• История изменений

Соглашения

• Личный кабинет - веб-приложение находящееся в домене go.comagic.ru или go.uiscom.ru
• Рабочее место оператора (РМО) - приложение, позволяющее сотрудникам вести диалоги с клиентами.
• Адаптер - пользовательский сервис реализующей при помощи вызовов методов Chat API и обработки обратных вызовов собственную реализацию РМО.
• Канал чатов - подключенный канал чатов (Чат на сайте, Telegram, Viber, и т.д.) в аккаунте клиента.
• Аккаунт адаптера - подключение адаптера клиентом личного кабинета
• Канал адаптера - подключение канала чата в адаптере
• Обратный вызов - HTTP-запрос, который ChatAPI отправляет адаптеру в случае изменения сущностей, происходящих без непосредственного участия самого адаптера (например создание чата или отправка сообщения посетителем, отправка системных сообщений и прочее).

Управление адаптерами

Для начала работы необходимо зарегистрировать интеграционный адаптер. Это можно сделать ~~через личный кабинет, либо~~ отправив запрос в основной API чатов, доступный по адресу https://chats-prod-logic.uiscom.ru/. Доступ к API имеют только авторизованные пользователи личного кабинета. Для получения аутентификационного токена необходимо отправить запрос

POST https://go.uiscom.ru/api/auth/json_rpc?method=login
{
 "jsonrpc": "2.0",
 "id": "0",
 "method": "login",
 "params": {
  "login": "username",
  "password": "password",
  "project":"uis2" # uis2 если для входа используется go.uiscom.ru
           # comagic если для входя используется go.comagic.ru
 }
}

Аутентификация запросов в основном API чатов выполняется с использованием токена, переданного в заголовке.

POST https://chats-prod-logic.uiscom.ru/v1/
Authorization: Bearer <token>

Адаптер в API представлен сущностью Adapter

{
 "id": 0,
 "type": "string",
 "name": "string",
 "status": "active",
 "supported_channel_types":
  "comagic",
  "telegram",
  "auto_ru",
  "avito",
  "realty_yandex",
  "facebook",
  "viber",
  "telegram_private",
  "whatsapp",
  "instagram",
  "vkontakte_groups",
  "waba",
  "sms"
 ],
 "owner": 0,
 "visibility_status": "private",
 "login": "string",
 "password": "string",
 "webhook_url": "string",
 "webhook_version": "string",
 "webhook_token": "string",
 "webhook_auth": {
  "type": "Bearer",
  "token": "string",
 },
 "webhook_kwargs": {}
}

Объект webhook_auth задает способ аутентификации для обратных вызовов. Позволяет использовать аутентификацию с токеном:

{
 "type": "Bearer",
 "token": "string"
}

либо c парой логин-пароль

{
 "type": "Basic",
 "login": "string",
 "password": "string"
}

Список адаптеров

GET /v1/integration/adapter

Возвращает список сущностей типа Adapter, среди которых возвращаются как адаптеры, добавленные пользователями, так и системные адаптеры. Отличительной особенностью системных адаптеров является значение null в атрибуте owner. Управлять системными адаптерами запрещено.

Создание адаптера

POST /v1/integration/adapter
{
 "type": "string",       
 "name": "string",       
 "login": "string", 
 "password": "string",
 "webhook_url": "string",
 "webhook_token": "string",
 "webhook_auth": {
  "type": "Bearer",
  "token": "string",
 },
 "supported_channel_types": [ 
  "comagic",
  "telegram",
  "whatsapp"
 ],
}

В результате возвращается сущность Adapter

Редактирование адаптера

PATCH /v1/integration/adapter/{adapter_id}
{
 "name": "string",
 "login": "string",
 "password": "string",
 "status": "active",
 "webhook_url": "string",
 "webhook_token": "string",
 "webhook_auth": {
  "type": "Bearer",
  "token": "string",
 },
 "webhook_kwargs": {},
 "supported_channel_types": [
  "comagic"
 ]
}

Метод позволяет менять следующие атрибуты сущности: name, login, password, status, webhook_url, webhook_token, webhook_auth, supported_channel_types.

Удаление адаптера

DELETE /v1/integration/adapter/{adapter_id}

Адаптер можно удалить только в том случае, если он не используется.

Каналы чатов

Сущность Channel представляющая подключенный канал чатов в аккаунте клиента.

{
 "id": 0,
 "type": "comagic",
 "name": "string",
 "is_removed": true,
 "status": "string", 
 "status_reason": "string"
}

Список каналов

GET /v1/integration/channel

Возвращает список сущностей типа Channel.

Подключение адаптера

Подключение адаптера представлено сущностью Account.

{
 "name": "string",
 "adapter_id": 0,
 "channels": [
  0
 ],
 "context": {},
 "id": 0,
 "status": "string"
}

Список подключений

GET /v1/integration/account

Возвращает список сущностей типа Account.

Создание подключения

POST /v1/integration/account
{
 "name": "string",
 "adapter_id": 0,
 "channels": [
  0
 ],
 "context": {}
}

Изменение подключения

PATCH /v1/integration/account/{account_id}
{
 "name": "string",
 "channels": [
  0
 ],
 "context": {}
}

Метод позволяет изменять следующие атрибуты сущности: name, channels, context.

Удаление подключения

DELETE /v1/integration/account/{account_id}

Chat API

Сервис доступен по адресу https://chat-integration-api-prod.uiscom.ru/

Сущности

Account - представляет подключение адаптера клиентом.

{
 "id": 0,
 "name": "string",
 "adapter_id": 0,
 "client_id": 0,
 "context": {},
 "status": "active"
}

Channel - представляет подключение канала чата в аккаунте.

{
 "id": 0,
 "name": "string",
 "type": "comagic",
 "account_id": 0,
 "context": {},
 "status": "active"
}

Аутентификация адаптера в Chat API

Все запросы к Chat API должны содержать заголовок Authorization:

Authorization: Bearer <token>

Для получения токена адаптер должен выполнить запрос:

POST /v1/adapter/login
Content-Type: application/x-www-form-urlencoded

username={adapter_login}&password={adapter_password}

Ответ будет содержать токен, тип и unix-timestamp указывающий на окончание времени жизни токена:

{
 "access_token": "string",
 "token_type": "bearer"
 "expires_at": 0,
}

По истечении времени жизни токена требуется повторить процедуру аутентификации.

Методы Chat API

Создание чата

Создание чата из адаптера возможно только для каналов, позволяющих начать коммуникацию первым. В данный момент только канала чата с мнемоникой whatsapp поддерживает такую функцию.

POST /v1/adapter/chat
{
 "account_id": 0,
 "channel_id": 0,
 "visitor_phone": "string",
 "operator_id": 0,
 "initiator": "operator",
 "created_at": "2023-01-01T00:00:00.000Z"
}

Описание сущности Chat

В ответе вернется отправленная сущность с атрибутами chat_id, являющимся идентификатором обращения, и visitor_id, являющимся идентификатором пользователя с которым ведется диалог. Оба параметра в дальнейшем должны использоваться при отправке сообщений в чат.

Завершение чата

POST /v1/adapter/chat/close
{
 "context": {},
 "account_id": 0,
 "channel_id": 0,
 "chat_id": 0,
 "operator_id": 0,
 "reason": "closed_by_timeout"
}

Трансфер чата

POST /v1/adapter/chat/transfer
{
 "context": {},
 "account_id": 0,
 "channel_id": 0,
 "chat_id": 0,
 "from_operator_id": 0,
 "to_operator_id": 0
}

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

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

POST /v1/adapter/message
{
 "account_id": 0,
 "channel_id": 0,
 "chat_id": 0,
 "operator_id": 0,
 "reply_to_id": 0,
 "text": "string",
 "created_at": "2023-01-01T00:00:00.000Z",
 "source": "system",
 "resource": {
  "id": 0,
  "token": "string",
  "type": "photo",
  "name": "string",
  "size": 0
 }
}

Описание сущности Message

Добавление ресурса

POST /v1/adapter/resource
Content-Type: multipart/form-data

...

Форма должна содержать следующие атрибуты

В ответе возвращается сущность Resource

Получение данных ресурса

GET /v1/adapter/resource/{account_id}/{channel_id}/{resource_id}/{resource_token}/payload

Обратные вызовы

Обратные вызовы отправляются в ответ на взаимодействие с сущностями чата, выполненными на адрес webhook_url, указанный в конфигурации адаптера. Данные для аутентификации передаются в заголовке Authorization:

Authorization: {Type} {Credentials}

В случае, когда при создании адаптера указан атрибут webhook_token, заголовок Authorization формируется следующим образом:

Authorization: Bearer {webhook_token}

Создание аккаунта

Доступно в версиях: v1, v2

POST /account
{
 "id": 0,
 "name": "string",
 "adapter_id": 0,
 "client_id": 0,
 "context": {},
 "status": "active"
}

Изменение аккаунта

Доступно в версиях: v1, v2

PATCH /account/{account_id}
{
 "id": 0,
 "name": "string",
 "adapter_id": 0,
 "client_id": 0,
 "context": {},
 "status": "active"
}

Удаление аккаунта

Доступно в версиях: v1, v2

DELETE /account/{account_id}
{
 "id": 0,
 "name": "string",
 "adapter_id": 0,
 "client_id": 0,
 "context": {},
 "status": "active"
}

Создание канала

Доступно в версиях: v1, v2

POST /channel
{
 "id": 0,
 "name": "string",
 "type": "comagic",
 "account_id": 0,
 "context": {},
 "status": "active"
}

Изменение канала

Доступно в версиях: v1, v2

PATCH /channel/{channel_id}
{
 "id": 0,
 "name": "string",
 "type": "comagic",
 "account_id": 0,
 "context": {},
 "status": "active"
}

Удаление канала

Доступно в версиях: v1, v2

DELETE /channel/{channel_id}
{
 "id": 0,
 "name": "string",
 "type": "comagic",
 "account_id": 0,
 "context": {},
 "status": "active"
}

Новый чат

Доступно в версиях: v1, v2

POST /chat
{
 "context": {},
 "account_id": 0,
 "channel_id": 0,
 "chat_id": 0,
 "visitor_id": 0,
 "visitor_phone": "string",
 "operator_id": 0,
 "initiator": "operator",
 "created_at": "2023-01-01T00:00:00.001Z"
}

Обновление чата

Доступно в версиях: v2

PATCH /chat
{
 "context": {},
 "account_id": 0,
 "channel_id": 0,
 "chat_id": 0,
 "operator_id": 0,
}

Завершение чата

Доступно в версиях: v1, v2

POST /chat/close
{
 "context": {},
 "account_id": 0,
 "channel_id": 0,
 "chat_id": 0,
 "operator_id": 0,
 "reason": "closed_by_timeout"
}

Параметр operator_id опциональный.

Закрепление чата за оператором

Доступно в версиях: v1

POST /chat/operator 
{
 "context": {},
 "account_id": 0,
 "channel_id": 0,
 "chat_id": 0,
 "operator_id": 0
}

Новое сообщение

Доступно в версиях: v1, v2

POST /message
{
 "context": {},
 "account_id": 0,
 "channel_id": 0,
 "id": 0,
 "chat_id": 0,
 "source": "system",
 "operator_id": 0,
 "reply_to_id": 0,
 "text": "string",
 "created_at": "2023-01-01T00:00:00.001Z",
 "status": "accepted",
 "resource": {
  "id": 0,
  "token": "string",
  "type": "photo",
  "name": "string",
  "size": 0
 },
 "system_message_mnemonic": "string"
}

Параметр status может принимать следующие значения: accepted, delivered, read, sent, error

Обновление сообщения

Изменение статуса сообщения

Доступно в версиях: v1, v2

Копировать

POST /message/status
{
 "context": {},
 "account_id": 0,
 "channel_id": 0,
 "chat_id": 0,
 "message_id": 0,
 "status": "accepted"
}

Обновление информации о посетителе

Доступно в версиях: v1, v2

POST /visitor/card
{
 "context": {},
 "account_id": 0,
 "channel_id": 0,
 "visitor_id": 0,
 "visitor_card": {}
}

Описание объекта visitor_card:

Переход с версии обратного вызова v1 на v2

Основные отличия v2 от v1: - вместо обратного вызова закрепление чата за оператором используется вызов обновление чата. - добавлен обратный вызов обновления сообщения

Работа с каналом типа waba

Отличительными особенностями канала типа waba является ограничение на создание исходящих коммуникаций только посредством предустановленных шаблонов, а так же возможность вести диалог только в рамках "временно окна", открывающегося с момента ответа посетителем на сообщение оператора.
Информация о доступных для использования шаблонов (а так же их изменения) передается в обратных вызовах связанных с каналом, в атрибуте context["message_templates"] типа list[MessageTemplate]. Для полноценной работы с шаблонами waba адаптер должен реализовать поддержку версии обратных вызовов v2.

Структура шаблона сообщения MessageTemplate:

Структура содержимого шаблона MessageTemplateContent:

Структура заголовка сообщения MessageTemplateContentHeader:

Структура сноски сообщения MessageTemplateContentFooter:

Структура объекта MessageTemplateContentKeyboard:

Структура объекта MessageTemplateContentKeyboardRow:

Структура объекта MessageTemplateContentButton:

Отправка сообщения с использованием шаблона

Для отправки сообщения с шаблоном используется метод отправки сообщения. Шаблон передается в атрибуте context[template] в следующем формате:

Информация о временном окне передается в обратных вызовах новое сообщение и обновление сообщения в атрибуте context["conversation_frame_ts"] типа int. Значением атрибута является unix timestamp, указывает время окончания временного окна. Если атрибут или его значение отсутствуют, то считается что временное окно закрыто.

История изменений

1.7.0 (2024-12-09)

• добавлена информация о новой версии обратных вызовов v2
• расширен список типов каналов, которые может использовать адаптер
• добавлена информация о работе с каналом типа waba

1.6.0 (2024-10-01)

• добавлена информация о новом атрибуте адаптера webhook_auth

1.5.1 (2024-09-26)

• в разделе Соглашения добавлена информация об обратных вызовах.

1.5.0 (2024-04-11)

• добавлена информация о версионировании обратных вызовов.
• добавлена реализация метода завершения чата
• добавлен новый метод для трансфера чата

1.4.0 (2023-09-18)

Добавлена информация о получении токена аутентификации (вход в личный кабинет).

1.3.0 (2023-09-18)

У события нового сообщения удален избыточный атрибут visitor_id.

1.2.0 (2023-09-14)

У всех событий удалены избыточные атрибуты app_id и site_id.

1.1.0 (2023-09-13)

Обновлена информация об аутентификации.

1.0.0 (2023-09-12)

Первоначальная версия.