Shortcuts
Let's have a brief talk about shortcuts, bot actions, message actions or just menus. All of the words I just listed describe the same feature and let's officially call them shortcuts.
Last updated
Let's have a brief talk about shortcuts, bot actions, message actions or just menus. All of the words I just listed describe the same feature and let's officially call them shortcuts.
Last updated
What exactly are shortcuts in the tekos chat? They appear in the chat menu as pre-programmed blocks for you to use. And don't worry, by programming we mean connecting nodes in the flow, as usual.
We split them to two types: Global shortcut & Message shortcut.
For the Global shortcut. You can find the menu next to the message input in the chat. It appears as a three bar hamburger. Don't worry if you can't find the menu right now, by default this element does not exist until you create your first shortcut or join the room with an already created one. Similar case is for the mobile, You can find the menu under the message input it also appears as a three bar hamburger.
Contrary to global, the Message shortcut has some basic options like: Remove, Forward Message, Share Content, Quote. Maybe you already know where that menu is placed, if not you can find it after hovering on any message in the tekos chat. It's a three dots menu on the right side. And for the mobile you have to press and hold down the message to see the options.
As always your imagination is the limit and also the four types of shortcuts action type.
"Display Modal" - (AdaptiveCard) Popup that displays the Adaptive Card.
"External URL" - (url) Link to external page, you can also display pages from flow by GET request.
"Backend action" - (post_request) It is used to trigger an POST request. Most use cases will work with this action type. And also here we can find a big difference between global and message shortcuts payloads.
Using the eventId you can get the message content. See the reference: https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-rooms-roomid-event-eventid
“Predefined message” - (postback) Allows to send the predefined message to the chat set in the value field.
As you already know we have 4 types of shortcut action and two places in which the shortcut can be placed
Remember that shorctcuts require HTTP PUT Method
PUT https://{{tekos_homeserver}}/_matrix/client/r0/rooms/{{room_id}}/state/{{shortcut_type}}
This method allows to create shortcut assigned to the room
| Name | Type | Description |
|---|---|---|
shortcut_type | string | The shortcut type: bot.actions (Message shortcut) bot.menu (Global shortcut) |
room_id | string | Room Id in which the bot is presented |
tekos_homeserver | string | Your home server address, the default one is m.tekos.co, but we suggest to use env.get('BASE_URL') |
| Name | Type | Description |
|---|---|---|
access_token | string | Thi is the access token of the bot presented in the room We suggest using the flow.get('bot.default_room') |
| Name | Type | Description |
|---|---|---|
menu | array | Array of menu object assigned to the same bot, check the bellow function. |
bot_id | string | Bot Id presented in the room |
active | boolean | Turn on and of the shortcut, values: true / false |
icon | string | Url to icon displayed in the global shortcut |
Body - It's the name displayed in the menu Type - all actions types can be found above Value - Depends on the action type. For postback just enter a text that will be send to the chat, for url enter the url to page that you want to be opened on click. For AdaptiveCard & post_request should contain link to the endpoint
env.get("FLOW_URL") - This enviorment contains link to your flow instance (e.g. https://instance-name.tekos.co)
The subflow we previously showcased allows the user to create only one shortcut for the bot, but it’s possible to have more than one shortcut for each bot.
Let’s take a look at the code with multiple shortcuts
We have an menu array which contains multiple shortcuts that will be available with our bot.
This subflow was built to easily create shortcut connected with the bot created in the same flow tab.
Example use cases:
Let's take a look whats is inside the red subflow named "Create 1 shortcut"
Name that will be displayed in the flow editor
Input Name to be displayed in the Menu.
Select a type Global | Message
Choose select response type: Display Modal | External URL | Backend Action | Predefined message
For the Response URL / Value stuff gets a little bit more complicated, but don't worry. Links may vary on the response type. For the External Url just paste the link to the page, but for the Display Modal and Backend Action enter the link to the post action. Let's take an example on the image above about "Send a simple message to the current room". The response url should contain an endpoint for /message. By default the link contains your tekos instance name as a prefix before .tekos.co and the trigger for the post webhook.
URl of the image field is to set the custom image displayed in the global shortcut menu.
We suggest using the “Create 1 Shortcut” with create bot flow
Code for the "Create 1 Shortcut" subflow:
Information about each shortcut is stored in the room state event, so to get them working the bot needs to be together with you in the same room and you don’t need the admin privileges in the room to get it working. That means you can invite your team members to the room and they will have access to the same actions as you, but keep in mind that for apps that require api keys or oauth access all users in the room with the bot will have access to your data.
All you need to do is just quit the room with the bot responsible for specified shortcut
