External event

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

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

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": {}
}

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 user's state 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": {}
}