Перейти к содержанию

Создание виджетов

В инструкции описаны базовые способы создания виджетов для чат-ботов. Виджет ─ это одно или несколько сообщений, с которыми можно взаимодействовать с помощью кнопок. Пример: сообщение со списком задач, в котором для пролистывания списка используются кнопки Вперед и Назад:


carousel


Далее:


Взаимодействие с виджетом построено следующим образом:

  1. Выполняется отправка сообщения.
  2. При последующих взаимодействиях ранее отправленное сообщение обновляется, при этом контент сообщения может изменяться.


Сохранение контекста между обновлениями реализовывается с помощью двух атрибутов сообщения:

  • data ─ прикрепляется к кнопке и отправляется боту при нажатии на эту кнопку. Используется для передачи контекста определенной кнопки (например, нажатие кнопки Назад или Вперед).

  • metadata ─ прикрепляется к сообщению и отправляется боту при нажатии на любую кнопку. Используется для передачи контекста всего виджета (например, список элементов, который прокручивается в виджете).


Создание виджета из одного сообщения

Рассмотрим процесс создания на примере виджета, который будет показывать числа от 1 до 10 с возможностью перехода вперед и назад.

Начнем с команды /range-widget, которая будет управлять виджетом. Хендлер этой команды будет отправлять и обновлять сообщение.

Если в команду пришло сообщение с пустой metadata, значит виджет еще не был отправлен и это только предстоит сделать. Введем переменную current_index, которая будет отвечать за активный элемент в виджете. Будем пытаться получить его из data, а при отсутствии такого ключа выставлять на начало - 0.

Отправим сообщение:

POST /api/v4/botx/notifications/direct

{
  "notification": {
    "body": "Current element: 1",
    "metadata": {"elems": [1, 2, 3]},
    "bubble": [
      [
        {
          "command": "/range-widget",
          "label": "Вперед",
          "data": {"current_index": 1}
        }
      ]
    ],
    ...
  },
...
}

В ответ на запрос получаем source_sync_id ─ это уникальный идентификатор отправленного сообщения.

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

{
  "source_sync_id": "<source_sync_id>",
  "command": {
    "body": "/range-widget",
    "command_type": "user",
    "data": {"current_index": 1},
    "metadata": {"elems": [1, 2, 3]},
  },
  ...
}

Опираясь на current_index: 1 из data сообщения, отобразим второй по счету элемент массива elems - "2". Но теперь, кроме кнопки Вперед, нам нужно добавить кнопку Назад с декрементированным на единицу current_index:

POST /api/v3/botx/events/edit_event

{
  "sync_id": "<source_sync_id>",
  "payload": {
    "body": "Current element: 2",
    "metadata": {"elems": [1, 2, 3]},
    "bubble": [
      [
        {
          "command": "/range-widget",
          "label": "Вперед",
          "data": {"current_index": 2}
        },
        {
          "command": "/range-widget",
          "label": "Назад",
          "data": {"current_index": 0}
        }
      ]
    ],
    ...
  },
  ...
}

Теперь у нас есть сообщение с текстом "Current element: 2" и двумя кнопками: Назад и Вперед. Если пользователь еще раз нажмет Вперед, боту придет сообщение:

{
  "source_sync_id": "<source_sync_id>",
  "command": {
    "body": "/range-widget",
    "command_type": "user",
    "data": {"current_index": 2},
    "metadata": {"elems": [1, 2, 3]},
  },
  ...
}

Теперь отобразим последний, 3 по счету и 2 по индексу элемент массива ─ "3". Обновим сообщение, убрав кнопку Вперед:

POST /api/v3/botx/events/edit_event

{
  "sync_id": "<source_sync_id>",
  "payload": {
    "body": "Current element: 3",
    "metadata": {"elems": [1, 2, 3]},
    "bubble": [],
    "bubble": [
      [
        {
          "command": "/range-widget",
          "label": "Назад",
          "data": {"current_index": 1}
        }
      ]
    ],
    ...
  },
  ...
}


Создание виджета из нескольких сообщений


carousel


При создании виджета, который должен состоять из нескольких сообщений, элементы управления (Вперед/Назад) находятся в последнем сообщении. Рассмотрим процесс создания на примере виджета из 3 сообщений.

Мы будем прокручивать по 3 элемента из списка [1, 2, 3, 4] на странице. Отслеживать текущие активные элементы будем с помощью поля page, у первой страницы индекс 0.

Отправим первое сообщение:

POST /api/v4/botx/notifications/direct

{
  "notification": {
    "body": "Element: 1",
  },
  ...
}

Примечание

Мы отправили сообщение без кнопок и метадаты. На практике к сообщению могут быть прикреплены кнопки для удаления или другого взаимодействия с элементом.

В ответ на сообщение мы получили sync_id отправленного сообщения, <sync_id_1>, сохраним его. Отправим такое же второе сообщение со вторым элементом, в ответ получаем <sync_id_2>, сохраним и его.

POST /api/v4/botx/notifications/direct

{
  "notification": {
    "body": "Element: 3",
    "metadata": {
      "elems": [1, 2, 3, 4],
      "sync_ids": [<sync_id_1>, <sync_id_2>]
    },
    "bubble": [
      [
        {
          "command": "/widget",
          "label": "Вперед",
          "data": {"page": 1}
        }
      ]
    ],
  },
  ...
}

К этому сообщению мы добавили кнопку Вперед с инкрементированным page. Добавим в metadata сообщения sync_id ранее отправленных сообщений ─ это нужно, чтобы виджет знал, какие сообщения обновлять.

При нажатии на кнопку Вперед придет следующая команда:

{
  "source_sync_id": "<sync_id_3>",
  "command": {/widget

    "body": "/widget",
    "command_type": "user",
    "data": {"page": 1},
    "metadata": {
      "elems": [1, 2, 3, 4],
      "sync_ids": [<sync_id_1>, <sync_id_2>]
    },
  },
  ...
}

На странице должно быть по 3 элемента, но для второй страницы остался только один ─ 4. Обновим первое сообщение последним элементом списка:

POST /api/v3/botx/events/edit_event

{
  "sync_id": "<sync_id_1>",
  "payload": {
    "body": "Element: 4",
  },
  ...
}

Для второго сообщения нет контента, поэтому обновим его текстом "Конец списка".

Сделаем то же самое для последнего сообщения, добавляем элементы управления:

POST /api/v3/botx/events/edit_event

{
  "sync_id": "<source_sync_id>",
  "payload": {
    "body": "Конец списка",
    "metadata": {
      "elems": [1, 2, 3, 4],
      "sync_ids": [<sync_id_1>, <sync_id_2>]
    },
    "bubble": [
      [
        {
          "command": "/widget",
          "label": "Назад",
          "data": {"page": 0}
        }
      ]
    ],
  },
  ...
}

Виджет готов. С помощью виджетов из нескольких сообщений можно создавать удобный пользовательский интерфейс.