Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

What are client actions?


Client actions are actions that Flock clients take when a user interacts with


controls like Slash CommandsAttachment PickersLauncher Buttons, and so on. 

Flock currently supports three kinds of client actions. They are:


  • Opening a widget inside the Flock client
  • Opening a URL in the system browser;


  • Sending an event to the


How do I configure a client action?

Typically you setup a client action by providing a ClientActionConfig object while configuring a button or a slash command, either in the app manifest or in an attachment.

A client action can also be triggered by a widget using methods provided in flock.js, or by FlockML content using anchor tags.

Which client action is performed depends on the type attribute of this object:

  • open_widget – opens a widget
  • open_browser – opens the system browser
  • dispatch_event – sends an event to the app backend

How do I open a widget?

Open a widget by providing a ClientActionConfig object with type open_widget and the following attributes:

  • url – the widget URL to open
  • widget_type – the type of widget to open. should be either modal or sidebar


For example, to open a widget anytime a user presses a chat tab button, provide this configuration:

Code Block
chat_tab_button: {
    description: "<button help text>",
    icon: "chat-button.png",   // if missing, the app icon is used
    action: { type: "open_widget", url: "<url>", widget_type: "sidebar" }

How do I open the system browser?

Open the system browser by providing a ClientActionConfig object with type open_browser and the following attributes:

  • url – the URL to open
  • send_context – whether to append Flock specific query parameters (like flock_clientflock_user_token, etc.) to the URL or not. The default value is false. Never set this to true if you are opening a third party URL in the browser.

For example, to open the browser anytime a user presses the attachment picker button, provide this configuration:

Code Block
attachment_picker: {
    description: "<attachment picker help text>",
    icon: "attachment-picker.png",
    action: { type: "open_browser", url: "<url>", send_context: true }

How do I dispatch an event to the app backend?

Send an event to your app backend by providing a ClientActionConfig object with the type dispatch_event.

Which event is sent to your app backend is covered in the next section.

For example, to dispatch an event when user enters a slash command, provide this configuration:

Code Block
slash_command: {
    command: "<name of the command>",
    help_text: "<help text for the slash command>",
    action: { type: "dispatch_event" }

How does my app discover what triggered the client action?

An event is generated anytime a client action is triggered. The event alongwith its attributes is

  • either sent to the app backend using the Events API if the configured action was to dispatch the event
  • or passed as the URL query params flock_event and flock_event_attributes to the widget or browser URL

The table below explains what event is generated for each trigger:


Opening a Widget

You can use widgets to render web applications inside an iframe or a webview within Flock. They can not only do everything that a normal webapp can, but also interact with the Flock client hosting them.

To open a widget, the following info is required:

  • URL of the widget
  • Type of widget in desktop – it can be either modal or sidebar
  • Type of widget in mobile – this is usually optional. The only acceptable value is modal.

Opening the Browser

You can also choose to open a URL in the browser. To open the browser, provide the following:

  • The URL to open.
  • Whether to send event context or not. When enabled, event parameters are appended to the URL.

Sending an event to the event listener URL

Or if you prefer to remain silent, you can send an event to the event listener URL.

What happens when a client action is triggered?

An event is generated every time a client action is triggered.

The events sent by various controls when a client action is triggered are listed below:

The event name along with its attribute provides sufficient context for the client action.

How do I configure a client action?

There are multiple ways to configure client actions in Flock, all of which are described below.

Developer Dashboard

Use the developer dashboard to configure an action for a Slash CommandLauncher ButtonChat Tab Button or Attachment Picker. Once you have enabled the control, you can select the appropriate action and provide any additional info that's required.

Opening a WidgetImage Added

Attachment Buttons

Client actions for attachment buttons are configured while creating the corresponding Attachment. Use the action property of a button to set the appropriate ActionConfig object.

Code Block
titleConfiguring Actions in Attachment Buttons
    "description": "attachment description",
    "views": {
        "widget": { "src": "<widget url>", "width": 400, "height": 400 }
    "buttons": [{
        "name": "<button 1>",
        "icon": "<icon 1 url>", 
        "action": { "type": "openWidget", "desktopType": "modal", "mobileType": "modal", "url": "<action url>" },
        "id": "<button id 1>"
    }, {
        "name": "<button 2>", 
        "icon": "<icon 2 url>", 
        "action": { "type": "openBrowser", "url": "<url>", "sendContext": true }
        "id": "<button id 2>"


Widgets can open another widget or the browser using flock.js.

Code Block
titleOpening a widget using flock.js
flock.openWidget("<widget url>", "modal")
Code Block
titleOpening the browser using flock.js
flock.openBrowser("<url>", true);


FlockML's action tag can also be used to trigger client actions:

Code Block
titleOpening a widget using FlockML
<flockml>click <action type="openWidget" url="<url>" desktopType="sidebar" mobileType="modal">here</action> to launch a widget.</flockml>
Code Block
titleOpening the browser using FlockML
<flockml>click <action type="openBrowser" url="<url>" sendContext="true">here</action> to open the browser.</flockml>
Code Block
titleSending event to the event listener using FlockML
<flockml>client <action type="sendEvent">here</action> to send an event to the event listener URL.</action>

Can client actions be triggered for users who haven't installed the app?



. Your app may send a message to a user who may not have installed your app, or a group where


some users


may not have installed your app


In case the configured action is to open a widget or the browser, the Flock client allows it, however no user token is passed. See this section in the widgets page for more details.

In the configured action is to dispatch an event to the app backend, the Flock client doesn't allow it, and instead prompts the user to install your app.

. When these users interact with this message's attachment (e.g. click on an attachment button, or take some action inside the attachment widget), a client action is triggered.

If you verify that the event token sent with the corresponding event is really signed using your app's secret (you should always do this anyways), you can be certain that the event originated from Flock and was actually triggered by the user whose userId is included in the event token (even if they haven't installed the app).