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:

Користувач вводить App Secret або генерує його, натиснувши на іконку
Поле виглядає так:

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

Користувач може скопіювати значення або перегенерувати його .
Навіть після зберігання значення завжди відображається в полі і присутні дві іконки.
Підказка: Зміна цього поля перерве інтеграцію.

Вкладка “Шаблони” (Рис. 4) містить поля (аналогічно до наявних провайдерів):

Анонімне ім’я абонента в Workspace
Повідомлення про завершення чату
Повідомлення про приєднання оператора
Повідомлення про відключення оператора

Важливо! Має бути можливість в повідомлення підставляти змінні (наприклад ім'я оператора, який приєднався до чату. Приклад - як наразі є в Telegram Bot:

join

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

Валідація

Для усіх повідомлень, які беруть участь у запитах, необхідно розраховувати підпис. Тіло повідомлення розраховується за допомогою 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"
      }
      ]
    
  }
}