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

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:

Opening the Browser

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

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:

TriggerEvent
Buttonclient.pressButton
Slash Commandclient.slashCommand
Widgetclient.widgetAction
FlockMLclient.flockmlAction

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 Widget

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.

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

flock.js

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

flock.openWidget("<widget url>", "modal")
flock.openBrowser("<url>", true);

FlockML

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

<flockml>click <action type="openWidget" url="<url>" desktopType="sidebar" mobileType="modal">here</action> to launch a widget.</flockml>
<flockml>click <action type="openBrowser" url="<url>" sendContext="true">here</action> to open the browser.</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?

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