Skip to main content

$pushgate.createPushback

The method creates a special entity for processing events called a pushback.

tip
Pushbacks are used for triggering events in the script when actions occur in the related external service. The bot therefore becomes a means for outbound text communications.

The following workflow illustrates how pushbacks work:

  1. In the script, the $pushgate.createPushback method is called. The method accepts the necessary dialog identifiers and a string which determines the event type, e.g. myEvent.
  2. The pushback is registered in the platform and assigned a unique identifier. This pushbackId can be used in requests to the GET and POST /push_{pushbackId}methods of the Pushgate API.
  3. In an external service, an action happens which the bot must notify its clients about. The service makes an HTTP request to /push_{pushbackId} in order to activate the pushback.
  4. The pushback generates the myEvent event in the appropriate dialog. This event can be processed in the script with the event tag in order to notify the client of the event.
caution
Each pushback corresponds to a specific dialog in a specific channel. In order for the client to receive notifications in multiple channels, a pushback must be created for each one.

Syntax​

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

Accepted arguments​

The $pushgate.createPushback method accepts 5 arguments. All arguments are required.

ArgumentDescriptionExample
channelTypeChannel typechatwidget
botIdBot identifier3609248-mybot-3609248-drF-2325272
chatIdClient identifier747078ed-d270-5664-62bf-0a933b43a15f
eventEvent namenewNotification
eventDataData passed along with the event{"text": "Huge online sale today!"}

Return value​

The method returns an object containing all the passed arguments as its keys, as well as 3 additional properties describing the pushback created.

PropertyDescriptionExample
idIdentifier96190b45-84ee-4007-9aab-d257ad22729f
linkActivation linkhttps://{hostName}/pushgate/push_a6c7ed8b-278c-4b85-9c07-14d5d8b6308a
createdTime of creation2021-03-24 15:31:43.059

Dialog identification​

The channelType, botId, and chatId arguments identify the dialog where the generated events will be sent.

tip
The most likely desired behavior is sending events to the same dialog from which the pushback was previously created. Pass the following $request properties as these arguments to implement the standard behavior: $request.channelType, $request.botId, and $request.channelUserId.

Event name​

The event argument determines the name of the event which will be generated upon an HTTP request to the /push_{pushbackId} method.

caution
Avoid creating events whose names would conflict with the predefined system events. Such events will be processed in an unexpected way.

Passing data with events​

When a pushback gets activated and sends an event to the script, an arbitrary JSON object with any additional data can be passed along with it.

To pass additional data, use the POST /push_{pushbackId} method to activate the pushback and provide the data in the request body.

tip
The data can be referenced in the event handler as $request.rawRequest.eventData.

You can also define additional data when creating the pushback by passing the appropriate object as the last argument, eventData. This data will be available by default in the following cases:

  • If you use the GET /push_{pushbackId} method to activate the pushback.
  • If you use POST /push_{pushbackId} but pass an empty request body.

Example​

Consider an example of using this method for sending promotion messages.

state: SubscribeOffer
    # ...
    a: Do you want to subscribe to our newsletter?

    state: Subscribe
        intent: /Agree
        intent!: /Subscribe
        script:
            // Create a pushback.
            var pushback = $pushgate.createPushback(
                $request.channelType,
                $request.botId,
                $request.channelUserId,
                "newNotification",
                {}
            );

            // Send the Pushgate API link to an external service.
            $http.post("https://example.com/subscribe", {
                headers: {
                    "Content-Type": "application/json"
                },
                body: {
                    "link": pushback.link
                }
            });
        a: Hooray! Now you’ll be the first to know about all our sales and promotions.

# The noContext flag is on, so that the context is not reset on receiving a new notification.
state: NewNotification || noContext = true
    event!: newNotification
    if: $request.rawRequest.eventData && $request.rawRequest.eventData.text
        a: We have a unique offer just for you! {{$request.rawRequest.eventData.text}}

  1. When the client agrees to subscribe to the newsletter, they transition to the Subscribe state. The state handler creates a pushback generating the newNotification event.

  2. The same handler sends the pushback link to the external service that will add it to the notification mailing list.

    caution
    The service must implement its own business logic for adding pushback links to the mailing list.

  3. From now on, when a new notification should be sent to the bot customers, the service must execute a request to the Pushgate API like the following one:

    curl --request POST 'https://{hostName}/pushgate/push_{pushbackId}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "text": "03/25 only, 20% off all our business plans!"
    }'

  4. When the request has been sent, the pushback will generate a newNotification event that will be processed in the script, and the client will learn about a new promotion:

    Dialog example
    tip
    The pushback identifier always remains the same. Subsequent requests to /push_{pushbackId} can be sent to the same link.