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

$pushgate.createPushback

Метод создает специальную сущность для обработки событий — пушбэк.

подсказка
Пушбэк используется для отправки событий в сценарий при каких-либо действиях в стороннем сервисе. Таким образом при помощи бота становится возможным создавать исходящие рассылки.

Рассмотрим принцип работы пушбэков:

  1. В сценарии вызывается метод $pushgate.createPushback. При вызове в метод передаются идентификаторы нужного диалога и строка, определяющая тип события, например myEvent.
  2. Пушбэк регистрируется в платформе. Ему присваивается уникальный идентификатор pushbackId, который можно использовать в запросах к методам GET и POST /push_{pushbackId}Pushgate API.
  3. Когда в стороннем сервисе происходит событие, о котором необходимо уведомить клиента при помощи бота, сервис делает HTTP-запрос к методу /push_{pushbackId}, чтобы активировать пушбэк.
  4. Пушбэк генерирует в диалоге с клиентом заданное ранее событие myEvent, которое можно обработать при помощи тега event и отправить нужную информацию в диалог.
предупреждение
Пушбэк привязан к диалогу с клиентом в определенном канале. Чтобы клиент получал уведомления в нескольких каналах, он должен дойти до соответствующего места сценария в каждом из них.

Синтаксис​

$pushgate.createPushback(
    $request.channelType,
    $request.botId,
    $request.channelUserId,
    "newNotification",
    {}
);

Принимаемые аргументы​

Метод $pushgate.createPushback принимает 5 аргументов. Все аргументы являются обязательными.

АргументОписаниеПример
channelTypeТип каналаchatwidget
botIdИдентификатор бота3609248-mybot-3609248-drF-2325272
chatIdИдентификатор пользователя747078ed-d270-5664-62bf-0a933b43a15f
eventНазвание событияnewNotification
eventDataДанные, переданные вместе с событием{"text": "Скидка только для вас!"}

Возвращаемое значение​

Метод возвращает объект, в котором как поля содержатся все аргументы, переданные при вызове, а также 3 дополнительных поля, описывающие созданный пушбэк.

ПолеОписаниеПример
idИдентификатор96190b45-84ee-4007-9aab-d257ad22729f
linkСсылка для активацииhttps://{hostName}/pushgate/push_a6c7ed8b-278c-4b85-9c07-14d5d8b6308a
createdВремя создания2021-03-24 15:31:43.059

Идентификация диалога​

Аргументы channelType, botId и chatId определяют диалог, в который в дальнейшем будут отправляться события.

подсказка
Предполагаемое поведение по умолчанию — отправка событий в тот же самый диалог, из которого был создан пушбэк. Чтобы реализовать стандартное поведение, передавайте в качестве данных аргументов поля объекта $request: $request.channelType, $request.botId и $request.channelUserId.

Название события​

Аргумент event задает название события, которое будет генерировать пушбэк при обращении к методу /push_{pushbackId}.

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

Передача данных с событием​

Когда в сценарий приходит событие, которое сгенерировал пушбэк, вместе с ним можно передать произвольный объект JSON с любыми вспомогательными данными.

Для этого используйте для активации пушбэка метод POST /push_{pushbackId} и передайте нужные данные в теле HTTP-запроса.

подсказка
Из сценария данные доступны обработчику события в поле $request.rawRequest.eventData.

Также вспомогательные данные можно задать при создании пушбэка, передав объект с данными как последний аргумент eventData. Эти данные будут по умолчанию передаваться в следующих случаях:

  • Если для активации пушбэка использован метод GET /push_{pushbackId}.
  • Если использован метод POST /push_{pushbackId} с пустым телом.

Пример​

Приведем пример использования метода для рассылки рекламных сообщений.

state: SubscribeOffer
    # ...
    a: Хотите подписаться на нашу рассылку?

    state: Subscribe
        intent: /Согласие
        intent!: /Подписаться
        script:
            // Создание пушбэка.
            var pushback = $pushgate.createPushback(
                $request.channelType,
                $request.botId,
                $request.channelUserId,
                "newNotification",
                {}
            );

            // Отправка ссылки на Pushgate API в сторонний сервис.
            $http.post("https://example.com/subscribe", {
                headers: {
                    "Content-Type": "application/json"
                },
                body: {
                    "link": pushback.link
                }
            });
        a: Ура, вы подписаны! Теперь вы будете первым узнавать о наших акциях и предложениях.

# Включен флаг noContext, чтобы при получении нового уведомления контекст диалога не менялся.
state: NewNotification || noContext = true
    event!: newNotification
    if: $request.rawRequest.eventData && $request.rawRequest.eventData.text
        a: Новое предложение только для вас! {{$request.rawRequest.eventData.text}}

  1. Когда клиент соглашается подписаться на рассылку, он попадает в стейт Subscribe. В обработчике стейта создается пушбэк, генерирующий событие newNotification.

  2. Этот же обработчик отправляет ссылку на пушбэк в сторонний сервис, который добавит ее в рассылку регулярных уведомлений.

    предупреждение
    Сервис должен сам реализовать логику добавления пушбэка в рассылку.

  3. Теперь, когда нужно будет отправить подписанным пользователям новое уведомление, сторонний сервис должен отправить, например, такой запрос к Pushgate API:

    curl --request POST 'https://{hostName}/pushgate/push_{pushbackId}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "text": "Только 25 марта на все наши тарифы скидка 20%!"
    }'

  4. При получении запроса пушбэк сгенерирует событие newNotification, которое будет обработано в сценарии. При корректном запросе пользователь получит уведомление о новой акции:

    Пример диалога
    подсказка
    Поскольку идентификатор пушбэка не меняется, ссылка на метод /push_{pushbackId} остается доступной и для последующих рассылок.