Skip to main content


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

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


Accepted arguments

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

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.

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.

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.

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.

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.


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
// Create a pushback.
var pushback = $pushgate.createPushback(

// Send the Pushgate API link to an external service.
$"", {
headers: {
"Content-Type": "application/json"
body: {
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.

    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
    The pushback identifier always remains the same. Subsequent requests to /push_{pushbackId} can be sent to the same link.