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

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

Копировать

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

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

Название параметра	Тип	Описание
`id`	`int`	Идентификатор адаптера
`type`	`str`	Уникальная мнемоника адаптера, соответствует регулярному выражению `^[a-z0-9_]+$`
`name`	`str`	Название адаптера
`status`	`enum`	Статус адаптера. Допустимые значения: `active`, `disabled`
`supported_channel_types`	`enum`	Список мнемоник каналов. Допустимые значения: `comagic`, `telegram`, `auto_ru`, `avito`, `realty_yandex`, `viber`, `telegram_private`, `whatsapp`, `waba`, `sms`, `email`
`owner`	`int`	Идентификатор владельца адаптера. Может принимать значение `null`, в этом случае адаптер является системным
`visibility_status`	`enum`	Статус видимости адаптера, для пользовательских адаптеров принимает только значение `private`
`login`	`str`	Логин для авторизации адаптера
`password`	`str`	Пароль для авторизации адаптера
`webhook_url`	`str`	Адрес для обратных вызовов из Chat API
`webhook_version`	`str`	Версия обратных вызовов. Доступные версии: `v1`, `v2`; по-умолчанию используется версия `v2`.
`webhook_token`	`str`	Токен для аутентификации Chat API используемый для обратных вызовов. Не допускается совместное использование с `webhook_auth`. Данный атрибут является устаревшим и не рекомендуется к использованию.
`webhook_auth`	`object`	Конфигурация аутентификации Chat API для обратных вызовов. Не допускается совместное использование с `webhook_token`.
`webhook_kwargs`	`dict[str, Any]`	Ассоциативный массив с дополнительными аргументы для обратных вызовов. Допустимые ключи `timeout` со значением типа `float`, для управления временем ожидания ответа от адаптера; ассоциативный массив дополнительных заголовков `headers`, вида `{"name": "value"}`

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

Для аутентификации с постоянным токеном необходимо задать значение webhook_auth следующим образом:

Копировать

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

В этом случае все обратные вызовы будут содержать заголовок Authorization: Bearer <token>.

Для использования пары логин-пароль значение webhook_auth задается следующим образом:

Копировать

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

В этом случае все обратные вызовы будут содержать заголовок Authorization: Basic <credentials>, где credentials это закодированная в Base64 пара <login>:<password>.

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

Копировать

GET /v1/integration/adapter

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

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

Копировать

POST /v1/integration/adapter
{
 "type": "string",       
 "name": "string",       
 "login": "string", 
 "password": "string",
 "webhook_url": "string",
 "webhook_version": "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_version": "string",
 "webhook_token": "string",
 "webhook_auth": {
  "type": "Bearer",
  "token": "string",
 },
 "webhook_kwargs": {},
 "supported_channel_types": [
  "comagic"
 ]
}

Метод позволяет менять следующие атрибуты сущности: name, login, password, status, webhook_url, webhook_version, 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"
}

Название параметра	Тип	Описание
`id`	`int`	Идентификатор канала
`type`	`enum`	Мнемоника канала
`name`	`str`	Название канала
`is_removed`	`bool`	Флаг логического удаления
`status`	`enum`	Статус
`status_reason`	`str`	Причина смены статуса

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

Копировать

GET /v1/integration/channel

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

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

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

Копировать

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

Название параметра	Тип	Описание
`id`	`int`	Идентификатор аккаунта
`adapter_id`	`int`	Идентификатор адаптера
`name`	`str`	Название аккаунта
`channels`	`list[int]`	Список идентификаторов каналов
`context`	`dict[str, Any]`	Ассоциативный массив с дополнительными параметрами. Допустимые ключи: `is_chat_integration_scenario_created` со значение булева типа, позволяет управлять автоматическим прикреплением сценария "Переадресация в CRM" для подключаемых каналов
`status`	`enum`	Статус подключения. Допустимые значения `active`, `disabled`

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

Копировать

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

Название параметра	Тип	Описание
`id`	`int`	Уникальный идентификатор аккаунта
`name`	`str`	Название аккаунта
`adapter_id`	`int`	Идентификатор адаптера
`client_id`	`int`	Идентификатор внутренней сущности, всегда принимает значение `1`
`context`	`dict[str, Any]`	Дополнительные параметры, всегда содержит ключ `app_id` с идентификатором клиента, подключившего адаптер
`status`	`enum`	Статус адаптера. Возможные значения `active`, `disabled`

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

Копировать

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

Название параметра	Тип	Описание
`id`	`int`	Уникальный идентификатор канала
`account_id`	`int`	Уникальный идентификатор аккаунта
`name`	`str`	Название канала
`type`	`enum`	Мнемоника канала чатов. Возможные значения `comagic`, `telegram`, `auto_ru`, `avito`, `realty_yandex`, `viber`, `telegram_private`, `whatsapp`, `waba`, `sms`, `email`
`context`	`dict[str, Any]`	Дополнительные параметры. Всегда содержит ключи `app_id` с уникальным идентификатором клиента, выполнившего подключение, а так же `chat_channel_id` - уникальный идентификатор подлюченного канала чатов
`status`	`enum`	Статус канала. Возможные значения `active`, `disabled`

Аутентификация адаптера в 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, waba, telegram_private, sms, email.

Копировать

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

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

Название параметра	Тип	Описание
`account_id`	`int`	Идентификатор аккаунта
`channel_id`	`int`	Идентификатор канала
`operator_id`	`int`	Идентификатор оператора. Оператор должен быть заведен в личном кабинете и иметь соответствующие привилегии
`initiator`	`enum`	Мнемоника инициатора. Возможные значения: `operator`, `visitor`, `autoinvite`, `chat_channel`. Допустимые значения: `operator`
`visitor_phone`	`Optional[str]`	Номер телефона пользователя, с которым будет вестись диалог (используется для каналов типа `whatsapp`, `waba`, `sms`, `telegram_private`)
`visitor_email`	`Optional[str]`	Адрес электронной почты пользователя, с которым будет вестись диалог (используется для канала типа `email`)
`visitor_username`	`Optional[str]`	Короткое имя пользователя, с которым будет вестись диалог, в формате `@username` (используется для канала типа `telegram_private`)
`created_at`	`str`	Дата и время в формате `ISO 8601`

При создании чата обязательно должен быть передан один из атрибутов visitor_phone, visitor_email или visitor_username, в зависимости от типа канала, в котором инициализируется коммуникация. В ответе вернется отправленная сущность с атрибутами 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"
}

Название параметра	Тип	Описание
reason	`enum`	Причина завершения. Возможные значения: `closed_by_timeout`, `invite_rejected`, `closed_by_operator`, `closed_by_visitor`, `visitor_banned`, `external_window_closed`, `visitor_disconnected`, `visitor_session_expired`, `closed_by_scenario`. Допустимые значения: `closed_by_operator`
operator_id	`int`	Идентификатор оператора. Параметр является опциональным, необходимо передавать его, если в значении параметра `reason` передается `closed_by_operator`

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

Копировать

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

Название параметра	Тип	Описание
from_operator_id	`int`	Идентификатор текущего оператора чата
to_operator_id	`int`	Идентификатор оператора, на которого будет назначен чат

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

Для передачи сообщения в чат нужно знать идентификатор чата 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

Название параметра	Тип	Описание
`account_id`	`int`	Идентификатор аккаунта
`channel_id`	`int`	Идентификатор канала
`chat_id`	`int`	Идентификатор чата
`operator_id`	`int`	Идентификатор оператора
`reply_to_id`	`int`	Опциональный идентификатор сообщения для цитирования
`text`	`str`	Текст сообщения
`created_at`	`str`	Дата и время в формате `ISO 8601`
`source`	`enum`	Мнемоника отправителя сообщения. Допустимые значения: `operator`
`resource`	`Resource`	Объект `Resource` с описанием ресурса (файла), прикрепленного к сообщению
`context`	`Optional[dict[str, Any]]`	Опциональный объект с дополнительной информацией

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

Копировать

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

...

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

Название параметра	Тип	Описание
`account_id`	`int`	Идентификатор аккаунта
`channel_id`	`int`	Идентификатор канала
`type`	`enum`	Тип ресурса. Возможные значения `photo`, `video`, `audio`, `voice`, `document`
`file`	`bytes`	Передаваемый файл

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

Название параметра	Тип	Описание
`id`	`int`	Идентификатор ресурса
`token`	`str`	Токен ресурса
`type`	`enum`	Тип ресурса. Возможные значения `photo`, `video`, `audio`, `voice`, `document`
`name`	`str`	Название файла
`size`	`int`	Размер файла в байтах

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

Копировать

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}

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

Копировать

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

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

Копировать

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

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

Копировать

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

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

Копировать

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

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

Копировать

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

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

Копировать

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

Новый чат

Копировать

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

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

Копировать

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

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

Копировать

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

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

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

Копировать

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

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

Копировать

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

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

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

Копировать

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

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

Копировать

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

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

Название параметра	Тип	Описание
`name`	`str`	Имя
`company`	`str`	Компания
`comment`	`str`	Комментарий
`phones`	`list[str]`	Список номеров телефонов
`emails`	`list[str]`	Список адресов электронной почты

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

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

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

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

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

Название параметра	Тип	Описание
`id`	`int`	Идентификатор шаблона
`name`	`str`	Наименование шаблона
`content`	`MessageTemplateContent`	Содержимое шаблона
`createdAt`	`datetime`	Дата и время создания шаблона

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

Название параметра	Тип	Описание
`text`	`str`	Текст сообщения
`header`	`MessageTemplateContentHeader`	Заголовок
`footer`	`MessageTemplateContentFooter`	Сноска
`keyboard`	`MessageTemplateContentKeyboard`	Кнопки меню

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

Название параметра	Тип	Описание
`text`	`Optional[str]`	Текст заголовка
`headerType`	`Optional[enum]`	Тип заголовка. Допустимые значения: `TEXT`, `VIDEO`, `IMAGE`, `DOCUMENT`
`headerExampleMediaUrl`	`Optional[str]`

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

Название параметра	Тип	Описание
`text`	`Optional[str]`	Текст сноски

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

Название параметра	Тип	Описание
`rows`	`list[MessageTemplateContentKeyboardRow]`	Список объектов типа `MessageTemplateContentKeyboardRow`

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

Название параметра	Тип	Описание
`buttons`	`list[MessageTemplateContentButton]`	Список объектов типа `MessageTemplateContentButton`

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

Название параметра	Тип	Описание
`text`	`str`	Текст кнопки
`buttonType`	`enum`	Тип кнопки. Допустимые значения: `QUICK_REPLY`, `URL`, `PHONE`
`payload`	`str`	Текст ответа. Применимо только для кнопок типа `QUICK_REPLY`
`url`	`str`	Ссылка. Применимо только для кнопок типа `URL`
`phone`]	`str`	Номер телефона. Применимо только для кнопок типа `PHONE`

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

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

Название параметра	Тип	Описание
`id`	`int`	Идентификатор шаблона
`text`	`str`	Текст сообщения
`header`	`MessageTemplateContentHeader`	Заголовок
`footer`	`MessageTemplateContentFooter`	Сноска
`keyboard`	`MessageTemplateContentKeyboard`	Кнопки меню

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

Примеры

В данном примере выполняется регистрация адаптера, подключение канала типа whatsapp, создание чата и отправка сообщения.

Настройка

Получение токена аутентификации

Запрос

Копировать

POST https://go.uiscom.ru/api/auth/json_rpc?method=login

{
 "jsonrpc": "2.0",
 "id": "1742467134",
 "method": "login",
 "params": {
  "login": "my_login",
  "password": "my_password",
  "project":"uis2"
 }
}

Ответ

Копировать

{
  "error" : null,
  "id" : "U7-r8Ld5BUakw2OP337Xy",
  "jsonrpc" : "2.0",
  "result" : {
   "is_2fa_enabled" : false,
   "jwt" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
   "refresh" : "69cc054cf22042d38f39bd06bc4d7707"
  }
}

Полученное в результате значение result["jwt"] используется в качестве токена

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

Запрос

Копировать

POST https://chats-prod-logic.uiscom.ru/v1/integration/adapter
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

{
 "type": "custom_solutions_llc_adapter",
 "name": "Custom Solutions LLC Chat Adapter",
 "login": "my_very_secret_and_unique_login",
 "password": "something_stronger_than_just_1234567890",
 "webhook_url": "https://webhook.my-custom-solutions.com/chat-integration",
 "webhook_auth": {
  "type": "Basic",
  "login": "my_webhook_basic_login",
  "password": "my_webhook_basic_password"
 },
 "supported_channel_types": [
  "comagic",
  "whatsapp"
 ]
}

Ответ

Копировать

{
 "id": 322,
 "type": "custom_solutions_llc_adapter",
 "name": "Custom Solutions LLC Chat Adapter",
 "status": "active",
 "supported_channel_types": [
  "comagic",
  "whatsapp"
 ],
 "owner": 4735,
 "visibility_status": "private",
 "login": "my_very_secret_and_unique_login",
 "webhook_url": "https://webhook.my-custom-solutions.com/chat-integration",
 "webhook_kwargs": {}
}

Получение списка подключенных в аккаунте каналов чатов

Запрос

Копировать

GET https://chats-prod-logic.uiscom.ru/v1/integration/channel
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Ответ

Копировать

[
 {
  "id": 740805,
  "channel_id": 28910,
  "type": "whatsapp",
  "name": "Main Whatsapp Channel",
  "is_active": true,
  "is_removed": false,
  "status": "active",
  "status_reason": ""
 }
]

Подключение канала

Для подключения канала обязательным является доступность web-сервера указанного в webhook_url при создании адаптера. В качестве значения adapter_id указывается идентификатор адаптера (id) полученный на шаге создания адаптера. В списке channels указываются идентификаторы каналов (id), которые необходимо подключить. В примере используется идентификатор 740805 соответствующий каналу с наименованием "Main Whatsapp Channel" на предыдущем шаге.
Запрос

Копировать

POST https://chats-prod-logic.uiscom.ru/v1/integration/account
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

{
 "name": "Custom Solutions LLC Chat Adapter Integration",
 "adapter_id": 322,
 "channels": [740805],
 "context": {}
}

Ответ

Копировать

{
 "name": "Custom Solutions LLC Chat Adapter Integration",
 "adapter_id": 322,
 "channels": [740805],
 "context": {},
 "id": 286,
 "status": "active"
}

Обратный вызов (создание аккаунта)

Копировать

POST https://webhook.my-custom-solutions.com/chat-integration/account
Authorization: Basic bXlfd2ViaG9va19iYXNpY19sb2dpbjpteV93ZWJob29rX2Jhc2ljX3Bhc3N3b3Jk 

{
  "id": 286,
  "name": "Custom Solutions LLC Chat Adapter Integration",
  "adapter_id": 322,
  "client_id": 1,
  "context": {"app_id": 4735},
  "status": "active"
}

Обратный вызов (создание канала)

Копировать

POST https://webhook.my-custom-solutions.com/chat-integration/channel
Authorization: Basic bXlfd2ViaG9va19iYXNpY19sb2dpbjpteV93ZWJob29rX2Jhc2ljX3Bhc3N3b3Jk

{
  "id": 3580,
  "name": "Main Whatsapp Channel",
  "type": "whatsapp",
  "account_id": 286,
  "context": {"app_id": 4735, "chat_channel_id": 740805},
  "status": "active"
}

Использование адаптера

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

Запрос

Копировать

POST https://chat-integration-api-prod.uiscom.ru/v1/adapter/login
Content-Type: application/x-www-form-urlencoded

username=my_very_secret_and_unique_login&password=something_stronger_than_just_1234567890

Ответ

Копировать

{
 "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiQWRhcHRlciIsInR5cGVfaWQiOjMyMiwiZXhwIjoxNzQyNTQxNzQxfQ.RMagvgqDBSD8xlr18E8M-8vNazAZwN_01YZopaq7-zg",
 "token_type": "bearer",
 "expires_at": 1742541741
}

Далее для всех запросов к ChatAPI в заголовке Authorization необходимо передавать полученный access_token.

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

Запрос

Копировать

POST https://chat-integration-api-prod.uiscom.ru/v1/adapter/chat
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiQWRhcHRlciIsInR5cGVfaWQiOjMyMiwiZXhwIjoxNzQyNTQxNzQxfQ.RMagvgqDBSD8xlr18E8M-8vNazAZwN_01YZopaq7-zg 

{
 "account_id": 286,
 "channel_id": 3580,
 "visitor_phone": "74959268686",
 "operator_id": 367852,
 "initiator": "operator",
 "created_at": "2025-03-21T05:00:00.000+00:00"
}

В этом и последующих запросах для значения account_id используется идентификатор аккаунта, полученный в обратном вызове создания аккаунта, а в качестве channel_id -- идентификатор канала, полученный в обратном вызове создания канала. Идентификатор сотрудника (operator_id) получен из DataAPI при помощи метода get.employees.

Ответ

Копировать

{
 "context": {},
 "account_id": 286,
 "channel_id": 3580,
 "chat_id": 199304420,
 "visitor_id": 9012381597,
 "visitor_phone": "74959268686",
 "visitor_email": null,
 "visitor_username": null,
 "operator_id": 367852,
 "initiator": "operator",
 "created_at": "2025-03-21T05:00:00.248137+00:00"
}

Обратный вызов с системным сообщением о начале чата.

Копировать

POST https://webhook.my-custom-solutions.com/chat-integration/message
Authorization: Basic bXlfd2ViaG9va19iYXNpY19sb2dpbjpteV93ZWJob29rX2Jhc2ljX3Bhc3N3b3Jk

{
  "context": {"app_id": 4735, "chat_channel_id": 740805},
  "account_id": 286,
  "channel_id": 3580,
  "id": 623010892,
  "chat_id": 199304420,
  "source": "system",
  "operator_id": null,
  "reply_to_id": null,
  "text": "Чат начат оператором Марина",
  "created_at": "2025-03-21T05:00:00.248137+00:00",
  "status": "sent",
  "resource": null,
  "system_message_mnemonic": "chat_started"
}

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

Запрос

Копировать

POST https://chat-integration-api-prod.uiscom.ru/v1/adapter/message
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiQWRhcHRlciIsInR5cGVfaWQiOjMyMiwiZXhwIjoxNzQyNTQxNzQxfQ.RMagvgqDBSD8xlr18E8M-8vNazAZwN_01YZopaq7-zg

{
 "account_id": 286,
 "channel_id": 3580,
 "chat_id": 199304420,
 "source": "operator",
 "operator_id": 367852,
 "text": "Сообщение от оператора",
 "created_at": "2025-03-21T05:00:01+00:00"
}

Идентификатор чата chat_id получен в ответе на запрос создания чата.

Ответ

Копировать

{
 "context": null,
 "account_id": 286,
 "channel_id": 3580,
 "id": 623010897,
 "chat_id": 199304420,
 "source": "operator",
 "operator_id": 367852,
 "reply_to_id": null,
 "text": "Сообщение от оператора",
 "created_at": "2025-03-21T05:00:01+00:00",
 "status": null,
 "resource": null,
 "system_message_mnemonic": null
}

Обратный вызов со статусом доставки сообщения

Копировать

POST https://webhook.my-custom-solutions.com/chat-integration/message/status
Authorization: Basic bXlfd2ViaG9va19iYXNpY19sb2dpbjpteV93ZWJob29rX2Jhc2ljX3Bhc3N3b3Jk

{
  "context": {"app_id": 4735, "chat_channel_id": 740805},
  "account_id": 286,
  "channel_id": 3580,
  "chat_id": 199304420,
  "message_id": 623010897,
  "status": "delivered"
}

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

1.10.0 (2025-05-15)

уточнена информация о каналах, поддерживающих инициализацию коммуникации

1.9.0 (2025-04-11)

уточнена документация о создании адаптера (указание webhook_version)

1.8.0 (2025-03-20)

добавлен раздел Примеры

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)

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

Chat API

Соглашения

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

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

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

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

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

Каналы чатов

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

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

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

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

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

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

Chat API

Сущности

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

Методы Chat API

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

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

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

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

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

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

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

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

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

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

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

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

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

Новый чат

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

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

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

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

Обновление сообщения Изменение статуса сообщения Доступно в версиях: v1, v2 Копировать POST /message/status { "context": {}, "account_id": 0, "channel_id": 0, "chat_id": 0, "message_id": 0, "status": "accepted" }

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

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

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

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

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

Примеры

Настройка

Получение токена аутентификации

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

Получение списка подключенных в аккаунте каналов чатов

Подключение канала

Использование адаптера

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

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

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

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

1.10.0 (2025-05-15)

1.9.0 (2025-04-11)

1.8.0 (2025-03-20)

1.7.0 (2024-12-09)

1.6.0 (2024-10-01)

1.5.1 (2024-09-26)

1.5.0 (2024-04-11)

1.4.0 (2023-09-18)

1.3.0 (2023-09-18)

1.2.0 (2023-09-14)

1.1.0 (2023-09-13)

1.0.0 (2023-09-12)

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

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

Копировать

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

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

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