Модуль для работы с Web-чатом

Модуль описывает интеграцию виджета чата на вашем сайте с платформой: как сайт и веб-чат обмениваются авторизационными данными и устанавливают сессию. Ниже приведены используемые понятия и последовательность подключения.

Понятия

SFE - интерфейс сайта, загруженный в браузере. SBE - серверная часть сайта, выполняющая авторизацию пользователя по предоставленным SFE данным. CFE - интерфейс вебчата, загруженный в браузере. CBE - серверная часть web-чата, выполняющая авторизацию пользователя. SAC - сервис обмена авторизационных данных на идентификационные данные. channel_token - уникальный идентификатор канала в CBE. site_token - уникальный идентификатор для авторизации запросов от CBE к SBE. session_token - уникальный идентификатор сессии чата, выданный CBE. auth_token - Уникальный идентификатор сессии пользователя SFE, выданный SBE.

Подключение

Сначала пользователь заходит на портал / сайт (SFE) и проходит авторизацию. Браузер получает от SBE идентификатор сессии.

Затем SFE загружает CFE. Среди данных передается уникальный токен канала channel_token. Находится в файле chat.webchat.{lk_domain}.json. После загрузки CFE получает новую сессию / продлевает текущую у CBE. Запрос вида POST https://{CBE}/api/omni/

{
    "obj": "DOCWebChat",
    "action": "get_session",
    "params": {
        "channel_token": channel_token
    },
    "action_id": "some id"
}

При получении запроса CBE проверяет доступность сервиса SAC, выполняя запрос:

{
    "obj": "WebChat",
    "action": "ping",
    "params": {
        "site_token": site_token
    }
}

В случае прохождения теста SBE формирует ответ:

{
    "action": "ping",
    "obj": "WebChat",
    "code": 200
}

После завершения теста CBE формирует ответ:

{
    "action": "get_session",
    "action_id": "some id",
    "obj": "DOCWebChat",
    "code": 200,
    "notifies": null,
    "body": {
        "session_token": "some  token"
    }
}

После получения session_token выполняется авторизация. Запрос:

 {
    "obj": "DOCWebChat",
    "action": "auth",
    "params": {
        "session_token": session_token,
        "auth_token": auth_token
    },
    "action_id": "some id"
}

При выполнении авторизации CBE отправляет запрос к SBE:

{
    "action": "get_user_data",
    "action_id": str(uuid.uuid4()),
    "obj": "WebChat",
    "params": {
        "auth_token": auth_token,
        "site_token": site_token
     }
}

SBE проверяет наличие сессии auth_token и, в случае прохождения валидации, отвечает:

{
    "action": "auth",
    "obj": "WebChat",
    "code": 200,
    "body": {
        "ident": "1234567890",
        "name": "Алексей",
        "surname": "Паневин",
        "phone": "79066800404",
        "email": "a@runtel.ru"
    }
}

CBE проверяет полученные данные, находит запись с ident или создает новую. Далее следует ответ для CFE:

{
    "action": "auth",
    "action_id": "some id",
    "obj": "DOCWebChat",
    "code": 200,
    "notifies": null
}

Затем CFE подключается к CBE по WebSocket (см. ниже).

Публичный чат (без авторизации на сайте)

Описанный выше сценарий с auth_token и запросом к SBE относится к портальному чату (провайдер DOCChannelProviderPortalChat). Для публичного (анонимного) чата (DOCChannelProviderPublicWebChat) авторизация проще и без SBE: клиент сам передаёт имя и произвольные данные.

{
    "obj": "DOCWebChat",
    "action": "auth",
    "action_id": "some id",
    "params": {
        "session_token": session_token,
        "name": "Имя клиента",
        "data": {
            "email": "a@runtel.ru",
            "profile.send_dialog_via_email": true
        }
    }
}

Ответ: {"obj": "DOCWebChat", "action": "auth", "code": 200}.

Форма предчата и продление сессии

В ответе get_session для новой сессии, помимо session_token, возвращаются form_options (элементы формы предчата) и delay_adding_new_dialogs (задержка создания нового диалога, сек). Чтобы продлить существующую сессию, передайте в get_session дополнительно session_token. Если канал вне расписания работы, get_session вернёт ошибку RMOutSchedule.

Обмен сообщениями по WebSocket

После авторизации CFE подключается к wss://{CBE}/omni/ws/:

Сервер сразу присылает {"obj": "OmniWebChatWSMember", "action": "connect", "code": 200}.
Клиент первым сообщением (таймаут 5 секунд) отправляет авторизацию:

{
    "obj": "OmniWebChatWSMember",
    "action": "auth",
    "action_id": "some id",
    "params": {"session_token": session_token}
}

Затем клиент подписывается на обновления действием subscribe с params: {"name": "omni|customer|dialog"} (отписка — unsubscribe), а завершает работу действием logout.

Ping/Pong. Сервер каждые 15 секунд шлёт {"obj": "WebSocketMember", "action": "ping", "params": {"dt": "..."}}; клиент обязан ответить {"action": "pong"}. Если ответа нет 35 секунд — сервер закрывает соединение.

После авторизации по WebSocket доступны действия:

DOCDialog / list — список диалогов клиента;
DOCDialog / append — создать новый диалог;
DOCDialog / get_agents — получить операторов по диалогам (dialog_id_list);
DOCDialogMessage / list — список сообщений;
DOCDialogMessage / append — отправить сообщение (dialog_id, message);
DOCDialogMessage / status_update — обновить статус доставки (id, dialog_id, status);
DOCDialogMessage / get_attachment — метаданные вложения (id);
DOCCustomer / get — данные текущего клиента;
DOCCustomer / get_channels — каналы клиента;
DOCCustomer / update_profile — обновить профиль (send_dialog_via_email).

Загрузка файла и экспорт диалога

Загрузка файла в диалог: POST /omni/dialog/{dialog_id}/file/ с заголовком Authorization: Bearer {session_token} и телом multipart/form-data (поле file). Ограничение — 15 МБ.
Экспорт диалога в текст: GET /omni/dialog/{dialog_id}/export/ с тем же заголовком; возвращает файл .txt.

Коды и статусы

Статус диалога (DOCDialog.status): 0 — открыт, 1 — закрыт, 2 — простой, 3 — на удержании.
Статус сообщения (DOCDialogMessage.status): 0 — сохранено, 1 — доставлено, 2 — прочитано.
Отправитель/получатель (sender / recipient): -1 — клиент, -2 — система, -3 — оператор-владелец, значение > 0 — ID оператора.
Тип канала (channel_model_id): 0 — звонок, 1 — email, 2 — SMS, 3 — Telegram, 4 — портальный чат, 5 — публичный чат, 6 — WhatsApp (Edna), 7 — Max, 8 — UseResponse.