Перейти к основному содержимому

Интеграция с операторской платформой

В этом примере показана интеграция операторской платформы с JAICP. Операторская платформа включает 2 компонента:

  • Приложение для чатов, которое уже имеет интеграцию с разными каналами. Это приложение будет взаимодействовать с JAICP с помощью Chat API. Например, оно будет передавать сообщения пользователя в бота и отслеживать события в чате JAICP.
  • Операторское приложение, которое будет взаимодействовать с JAICP по Operator API. Например, оно будет сообщать о доступных группах операторов и отправлять ответы операторов в JAICP. Операторское приложение должно быть связано с веб-сервером, который может отвечать на запросы Operator API.
Общая схема работы

  1. Пользователь пишет в любой канал: мобильное приложение, мессенджер и т. д.

  2. Приложение для чатов в вашей операторской платформе уже должно иметь интеграцию со всеми этими каналами. Запрос пользователя приходит в ваше приложение.

  3. Приложение для чатов передает запрос в бота JAICP с помощью Chat API.

  4. Бот обрабатывает запрос пользователя. При необходимости бот обращается к внешним ресурсам, например, к CRM или BI-системам.

    Возможности бота
    • Понимание намерений пользователей с помощью NLU-ядра.
    • Хранение данных о запросе пользователя. Данные доступны в переменной $request.
    • Адаптация ответов под разные каналы с помощью типа ответа raw.
    • Перевод диалога на оператора с помощью типа ответа switch.
    • Отправка HTTP-запросов через сервис $http.

  5. Далее возможны два сценария:

    • Перевод на оператора не требуется:

      1. Бот отправляет ответ в приложение для чатов.
      2. Приложение отправляет ответ пользователю в исходном канале.

    • Бот переводит диалог на оператора:

      1. Бот инициирует перевод на оператора через Operator API.
      2. Оператор получает сообщения через Operator API и отправляет ответы в бота.

Подготовка​

  1. Настройте интеграцию с Operator API:

    • Создайте веб-сервер, который сможет отвечать на запросы Operator API.
    • Подключите канал Operator API и получите вебхук, через который операторское приложение будет отправлять события в JAICP.
    подсказка

    Смотрите инструкции в статье Operator API.

  2. Создайте канал Chat API. В поле Оператор выберите Operator API.

Обработка запроса через бота​

  1. Пользователь отправляет вопрос в канале, например, в мессенджере: По какому графику вы работаете?. Запрос передается в ваше приложение для чатов.

  2. Приложение для чатов отправляет запрос в бота через Chat API, например с помощью метода POST /chatapi/{token}:

    curl -X POST "https://bot.jaicp.com/chatapi/abcd:123456789" \
      -H "Content-Type: application/json" \
      -d '{
        "query": "По какому графику вы работаете?",
        "clientId": "user123"
      }'
    подсказка

    Запрос в бота также можно отправить с помощью других методов: GET /chatapi/{token} или POST /chatapi/{token}/async.

  3. Бот обрабатывает запрос пользователя. Приложение для чатов получает ответ на запрос POST /chatapi/{token} — объект BotResponse:

    {
        "token": "abcd:123456789",
        "clientId": "user123",
        "questionId": "aaaaaaaa-1234-5678-9000-000000000000",
        "data": {
            "replies": [
                {
                    "type": "text",
                    "text": "Мы работаем ежедневно с 09:00 до 18:00",
                    "state": "/WorkHours",
                    "lang": "ru"
                }
            ],
            "answer": "Мы работаем ежедневно с 09:00 до 18:00",
            "newSessionStarted": true,
            "transitionHistory": [
                "/WorkHours"
            ],
            "isNewClient": true,
            "endSession": false
        },
        "timestamp": "2024-12-26T14:54:59.966",
        "blockForm": false
    }

  4. Приложение для чатов отправляет сообщение пользователю в мессенджер.

Обработка запроса с переводом на оператора​

Шаг 1. Перевод на оператора​

  1. Пользователь отправляет запрос в канале, например, в мессенджере: Хочу говорить с оператором. Запрос передается в ваше приложение для чатов.

  2. Приложение для чатов отправляет запрос в бота через Chat API, например с помощью метода POST /chatapi/{token}:

    curl -X POST "https://bot.jaicp.com/chatapi/abcd:123456789" \
      -H "Content-Type: application/json" \
      -d '{
        "query": "Хочу говорить с оператором",
        "clientId": "user123"
      }'
    подсказка

    Запрос в бота также можно отправить с помощью других методов: GET /chatapi/{token} или POST /chatapi/{token}/async.

  3. Бот обрабатывает запрос и переводит диалог на оператора с помощью типа ответа switch. При этом в параметре closeChatPhrases должны быть указаны команды, с помощью которых пользователь сможет прекратить диалог с оператором и вернуться к диалогу с ботом:

    $response.replies.push({
        "type": "switch",
        "closeChatPhrases": ["/closeChat", "Закрыть диалог"]
    });

Шаг 2. Выбор оператора​

  1. Бот через Operator API пытается получить список доступных групп операторов. Он отправляет на ваш веб-сервер запрос GET {apiUrl}/getDestinations.

  2. В ответе на запрос GET {apiUrl}/getDestinations ваше операторское приложение передает список доступных групп:

    {
      "destinations":[
          {
            "destinationId":"1",
            "name":"Группа операторов 1",
            "hasOnline":true
          },
          {
            "destinationId":"2",
            "name":"Группа операторов 2",
            "hasOnline":false
          }
      ]
    }

  3. Бот выбирает группу операторов. Он отправляет запрос POST {apiUrl}/selectDestination на ваш веб-сервер.

  4. Бот передает сообщение пользователя и данные о пользователе. Бот отправляет запрос POST {apiUrl}/sendText на ваш веб-сервер.

  5. Операторское приложение передает диалог оператору.

Шаг 3. Диалог с оператором​

  1. Оператор отправляет ответ с помощью запроса POST ​/chatapi​/webhook​/operatorapi​/{apiKey}. Этот запрос нужно отправлять на вебхук JAICP, который вы получили при подключении канала Operator API.

    curl -X POST "http://bot.jaicp.com/chatapi/webhook/operatorapi/1234567-test-1234567-ABC-987654" \
      -H "Content-Type: application/json" \
      -d '{
        "id": "12345",
        "userId": "user123",
        "type": "TextMessage",
        "text": "Здравствуйте! Все верно, работаем каждый день с 09:00 до 18:00",
        "employee": {
          "employeeId": "agent1",
          "firstName": "Ivan",
          "lastName": "Ivanov",
          "avatarUrl": "http://example.com/avatar.png"
        }
      }'

  2. Приложение для чатов запрашивает события чата с помощью GET /chatapi/{token}/events. Это позволяет приложению синхронизироваться с JAICP и убедиться, что ответ от оператора можно отправить в канал пользователю.

    curl -X GET "https://bot.jaicp.com/chatapi/abcd:123456789/events?clientId=user123&ts=2024-12-27T13:53:30.250"

  3. Бот отправляет события чата в ваше приложение для чатов. Далее приложение извлекает ответ оператора из полученных данных:

    {
        "hasMore": false,
        "events": [
            {
                "timestamp": 0,
                "type": "humanResponse",
                "event": {
                    "token": "abcd:123456789",
                    "clientId": "user123",
                    "questionId": "aaaaaaaa-1234-5678-9000-000000000001",
                    "data": {
                        "answer": "Здравствуйте! Все верно, работаем каждый день с 09:00 до 18:00"
                    },
                    "timestamp": "2024-12-27T13:56:53.371",
                    "blockForm": false,
                    "status": "SENT"
                }
            },
            …
        ]
    }

  4. Приложение для чатов отправляет ответ от оператора пользователю в мессенджер.

Далее пользователь может продолжать общаться с оператором. При этом будет следующая последовательность запросов:

Шаг 4. Завершение диалога с оператором​

  1. Пользователь отправляет запрос в канале, например, в мессенджере: Закрыть чат. Запрос передается в ваше приложение для чатов.

  2. Приложение для чатов отправляет запрос в бота через Chat API, например, с помощью метода POST /chatapi/{token}:

    curl -X POST "https://bot.jaicp.com/chatapi/abcd:123456789" \
      -H "Content-Type: application/json" \
      -d '{
        "query": "Закрыть чат",
        "clientId": "user123"
      }'

  3. Бот обрабатывает запрос и определяет, что нужно закрыть чат с оператором. Бот отправляет запрос POST {apiUrl}/closeChat на ваш веб-сервер.

Следующие запросы от пользователя будут обрабатываться только через бота, пока пользователь опять не попросит перевести диалог на оператора.

подсказка

Оператор может сам завершить диалог:

  1. Оператор отправляет в бота запрос POST ​/chatapi​/webhook​/operatorapi​/{apiKey} с типом Closed.

  2. Приложение для чатов получает это событие с помощью GET /chatapi/{token}/events.

Пишите, я помогу!

Пишите, я помогу!

База знаний по документации

Powered byJust AI