Custom Chat Gateway: типичные сценарии работы и настройка

На стороне Webitel реализован новый тип профиля — Custom.

Webitel Admin → Маршрутизация → Текстовые шлюзы → Нажать на кнопку “Добавить“ → Custom Chat Gateway (Рис. 1).

*Рис. 1. Модальное окно “Новый текстовый шлюз”*

Карта профиля имеет 2 вкладки

Вкладка Общее (Рис. 3) содержит поля:

Имя — произвольное название, текстовое поле, обязательное;
URI — webhook на стороне Webitel. Генерируется автоматически, доступен для копирования. Текстовое поле, обязательное;
Callback — webhook на стороне заказчика. Текстовое поле, обязательное;
App Secret — случайная строка, используемая при расчёте подписи. Можно сгенерировать и скопировать. Обязательное;
Схема — схема, которая будет выполняться. Выбор из списка всех схем. Обязательное.

Примечание: внешний вид поля URI и App Secret остаётся текущим. Разделение (подписи или оформление) пока не добавляется.

Поведение поля App Secret:

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

*Рис. 2. Пример заполненного поля “App Secret“*

Пользователь может скопировать значение или сгенерировать заново .
Даже после сохранения значение остаётся отображённым, с двумя иконками.
Тултип: Изменение этого поля прервет интеграцию.

Вкладка Шаблоны (Рис. 4) содержит поля (аналогично существующим провайдерам):

Анонимное имя абонента в Workspace
Сообщение завершения чата
Сообщение присоединения оператора
Сообщение отключения оператора

Важно! В сообщениях должна быть возможность использовать переменные (например, имя оператора, подключившегося к чату). Пример — как реализовано в Telegram Bot:

join

👤 __*$(md2 .FirstName)$(if .LastName) $(md2 .LastName)$(end)*__

Шаблоны.png — *Рис. 4. Вкладка “Шаблоны“*

Валидация

Для всех сообщений, участвующих в запросах, необходимо рассчитывать подпись. Подпись формируется на основе тела сообщения, используя sha256 и AppSecret:

JavaScript

const hash = crypto.createHmac('sha256', AppSecret)
                   .update(Payloads)
                   .digest('hex');

Результат расчета необходимо добавлять в заголовок X-Webitel-Sign

Сообщения

Пример обмена сообщениями:

JSON

POST /chat/oprzxtblgubhixwsvewqupzjpgalsrl HTTP/1.1
X-Webitel-Sign: f7e109787f6f012883352ce63ec90849a5e76011db2c7da132742c277414935a

{
  // New incoming message of any kind - text, media
  "message": {
    // Unique message identifier inside this chat
    "id": "$messageId",
    "chatId": "$id",
    // Sender of the message.
    "sender": {
      // Unique identifier for this sender.
      "id": "_3dRxWevBkGX/z3pw7LZw==",
      // OPTIONAL. Type of the chat, e.g.: telegram, viber, whatsapp, etc
      "type": "viber",
      "name": "John Doe",
      "nickname": "John Doe",
    },
    // --- content --- //
    // Date the message was sent.
    "date": 1710348821689,
    // For text messages, the actual UTF-8 text of the message.
    "text": "Hi! Can U help me, please ..",
    // Extra variables to associate with this chat.
      "metadata": {
        "extra_var": "my_value"
      },
    // Message with a general file, information about the file
    "file": {
      "url": "https://example.org/path/to/media/file",
      "mime":  "image/png",
      "size":  179491,
      "name": "$save_as"
    }
  }
}

Пример ответа:

JSON

{
  "success": "true",
  "error": "some error"
}

События

Пример закрытия чата:

JSON

POST /chat/oprzxtblgubhixwsvewqupzjpgalsrl HTTP/1.1
X-Webitel-Sign: f7e109787f6f012883352ce63ec90849a5e76011db2c7da132742c277414935a

{
  // Chat dialog complete.
  "close": {
    "chatId": "jkmuiokji"
  }
}

Пример ответа:

JSON

{
  "success": "true",
  "error": "some error"
}

Инициация исходящего чата

Пример отправки запроса на отправку исходящего сообщения нескольким получателям с Webitel на веб-сервис чат-бота:

JSON

{
  "broadcast": { // broadcast indicates the broadcast event
    "eventId": "someId", // id of the event as the response will be async (generated on our side)
    "recipients": [ // array of recipients 
      {
        "id": "someId",
        "type": "telegram"
      },
      {
        "id": "otherId",
        "type": "telegram"
      }
      ],
    "text": "text of the message", // text of the broadcast outgoing message
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    }
  }
}

eventId — генерируется в Webitel, чтобы по нему затем идентифицировать ответ с ошибкой.
recipients — массив в Webitel, так как так работает интеграция с другими мессенджерами.

В случае данной интеграции в массиве recipients всегда будет передаваться один получатель.

Чат-бот может асинхронно отправить в Webitel запрос, если для какого-либо из получателей возникла ошибка (успешные не требуют подтверждений). Пример:

JavaScript

{
  "broadcast": {
    "eventId": "someId", // id of the event this response correlated to
    "recipients": [ // if not succeeded the array of recipients which not recieved message (if field is not present - no errors occured and all recipients received their message)
      {
        "id": "someId",
        "type": "telegram",
        "error": "error message"
      }
      ]
    
  }
}