$pushgate.createPushback

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

подсказка

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

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

1. В сценарии вызывается метод $pushgate.createPushback. При вызове в метод передаются идентификаторы нужного диалога и строка, определяющая тип события, например myEvent.

2. Пушбэк регистрируется в платформе. Ему присваивается уникальный идентификатор pushbackId, который можно использовать в запросах к методам Pushgate API. По этому идентификатору сторонний сервис сможет отправлять события в бота.

3. Когда в стороннем сервисе происходит событие, о котором необходимо уведомить клиента при помощи бота, сервис делает один за этих HTTP-запросов:

   • GET /push_{pushbackId} — чтобы отправить только событие.
   • POST /push_{pushbackId} — чтобы отправить событие с дополнительными данными.

4. Пушбэк генерирует в диалоге с клиентом заданное ранее событие myEvent, которое можно обработать при помощи тега event и отправить нужную информацию в диалог.

предупреждение

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

Синтаксис

ECMAScript 5

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

ECMAScript 6

В среде ECMAScript 6 метод является асинхронным:

await $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 задает название события, которое будет генерировать пушбэк при обращении к методу GET /push_{pushbackId} или POST /push_{pushbackId}.

предупреждение

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

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

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

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

подсказка

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

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

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

Пример

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

ECMAScript 5

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}}

ECMAScript 6

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

    state: Subscribe
        intent: /Согласие
        intent!: /Подписаться
        scriptEs6:
            // Создание пушбэка.
            $temp.pushback = await $pushgate.createPushback(
                $request.channelType,
                $request.botId,
                $request.channelUserId,
                "newNotification",
                {}
            );
        script:
            // Отправка ссылки на Pushgate API в сторонний сервис.
            $http.post("https://example.com/subscribe", {
                headers: {
                    "Content-Type": "application/json"
                },
                body: {
                    "link": $temp.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} остается доступной и для последующих рассылок.