External event

You use an External Event when you need to launch a bot from an external system or program, for example, CRM.

How to send a request for an External event →
Examples of requests for External Event →
Description of the External event request field →
POST by bm_id →
Description of the request values by bm_id →
Interaction of External event and chat →
How to output certain elements from server response →

In an External Event you send an HTTP POST request to Botmother to launch a specific bot screen for one or more users of your bot. You can also relay variables in the request that will be stored in last_request object.

To create an External Event, go to Settings → Events and click Add Event and enter the event name and select the Type — External Event.

In the Properties, you can select the Type of an External Event — Message or Screen that will be sent to the user when this event happens.

To generate a link, click the save button in the lower-right corner.

To call the event, you need to send a request to the generated URL.

You can use up/down arrow navigation to move the event.

To delete an event, click on the Delete Button.

How to send a request for an External event

You need to make a POST request from your program or system to the event URL.

Make sure that you set header Content-Type: application/json in the request.

The request body must be in JSON format.

For example, this request starts the bot execution for a user with platform_id = 123456 inside the Telegram platform in your bot:

{ 
"platform": "tg",
"users": [ "123456" ],
"data": {}
}

This one starts the bot execution for all users of all your bot platforms:

{ 
"platform": "any",
"users": "everyone",
"data": {}
}

Examples of requests for External Event

Variables can thus be sent to Telegram. In the example, we will send order and phone, but you can replace them with your own variables:

    {
            "platform": "tg",
            "users": ["123456789"],
            "data": {
                    "order": "{{order}}",
                    "phone": "{{phone}}"
            }
    }

So the text will be sent from one user to another one in Telegram. We will save the recipient id in userID variable beforehand:

    {
     "platform": "tg",
     "users": "{{userID}}",
     "data": {
      "text": "{{text}}"
      }
    }

Thus, we send an array or an object:

    {
            "platform": "tg",
            "users": ["123456789"],
            "data": {
                    "information": "{{JSON stringify information}}"
            }
    }

You can check syntactic correctness here: https://jsonlint.com/

Description of the External event request field

platform values (one value is required, any- all the values) — tg, fb, viber, vk, any.

users value — platform_id array or everyone string.

data value — Any JSON that is written in the bot to the last_request object.

POST by bm_id

You can select users for the event not only by the platform ID but also by the ID of the Users in Botmother.

There are several ways to get it:

from this_user.bm_id variable inside the bot;
from the address bar of the builder

Go to the dialogs section in the builder, select the desired user and click on the address bar of the browser. Your address shall be similar to the following: https://app.botmother.com/bot/ffffffffffffffffffff...aaaaaaaaaaaaaaaaaaaaaaaa where "aaaaaaaaaaaaaaaaaaaaaaa" is user's bm_id.

Collected bm_id shall be sent in users_bm array.

Example of the request body:

{ 
"users_bm": [ "5c517b7773515eaha3078e2f" ],
"data": {}
}

Description of the request values by bm_id

users_bm value — array of bm_id.

data value — any JSON that is written in the bot to the last_request object.

Interaction of External event and chat

When External event is sending, open chats with the operator remain open by default. If you need External event to close open chats, add stopDialog: true parameter to the request body stopDialog: true.

{
  "platform": "any",
  "users": "everyone",
  "stopDialog": true,
  "data": {}
}

How to output certain elements from server response

Server Responses get into last_request.

For example, the bot received information about the number of orders:

     "last_request": {
        "order": {
          "laptop": "44",
          "console": "24"
        },
        "sweater": "15"
      }
    }

If you need to output a specific variable, you need to specify the path to it.

Inside last_request, we see order variable first.

Order variable contains laptop and console variables inside, you can tell by a curly brace open at the beginning {and a close one at the end }:

    {
          "laptop": "44",
          "console": "24"
        }

Order variable is nested in last_request, which, in turn, contains laptop and console. Therefore, the path to them will be as follows:

{{last_request.order.laptop}} and {{last_request.order.console}}

Sweater variable is after the close bracket, so it directly obeys last_request and it is output like this:

{{last_request.sweater}}

To the beginning ↑

Categories