Client Actions

What are client actions?

Client actions are the actions that a Flock client takes when a user interacts with controls like buttons, slash commands, and so on, that have been provided by an app. Flock currently supports three kinds of client actions. They are:

• Actions that open a widget containing the app's content;
• Actions that open a URL in the system browser;
• Actions that dispatch an event to the app backend.

How do I configure a client action?

Typically, you set up 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. The various options are:

• openWidget. Opens a widget.
• openBrowser. Opens the system browser.
• dispatchEvent. Sends an event to the app backend.

How do I open a widget?

See the relevant section in the widgets page.

How do I open the system browser?

You can open the system browser by providing a ClientActionConfig object with type open_browser and the following attributes:

• url. The URL to open.
• sendContext. This is a boolean value that specifies if specific query parameters (like flockClient, flockEvent, and so on) should be appended to the URL. 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 each time a user presses the attachment picker button, provide the configuration as below.

attachmentPicker: {
    description: "<attachment picker help text>",
    icon: "attachment-picker.png",
    action: { type: "openBrowser", url: "<action url>", sendContext: true }
}

How do I dispatch an event to the app backend?

You can dispatch an event to the app backend by providing a ClientActionConfig object with the type dispatchEvent. The type of event that 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:

slashCommand: {
    command: "<name of the command>",
    helpText: "<help text for the slash command>",
    action: { type: "dispatchEvent" }
}

How does my app discover what triggered the client action?

An event is generated anytime a client action is triggered. The event, along with 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 param flockEvent to the widget or browser URL.

The table below explains the specific events generated for each trigger.

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

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

Yes. There are a couple of scenarios in which a Flock client might trigger a client action for a user who hasn't installed the app, as listed below.

• An attachment that contains a widget is shared with a user or a group where a predefined number of users hasn't installed your app.
• An attachment shared with such a user contains a button that triggers a client action.

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.) The Flock client doesn't allow the configured action to dispatch an event to the app backend; instead, it prompts the user to install the app.