Client Actions

What are client actions?

A client action is an action that a Flock client takes when a user interacts with a control (e.g. buttons, slash commands, etc.) provided by your app.

Flock supports three kinds of client actions:

• Open a widget containing your app's content
• Open a URL in the system browser
• Dispatch an event to the app backend

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

Or to dispatch an event to the app backend when a user clicks on an attachment button, provide the action type dispatch_event when configuring the button:

{
    title: "<title>",
    description: "<description>",
    app_id: "<app_id>",
    previews: { .. },
    buttons: [{ name: "<button>",
                icon: "<icon url>",
                action: { type: "dispatch_event" },
                tag: "<tag>" }]
}

For more details, see the reference documentation for ClientActionConfig.

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:

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_client, flock_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:

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:

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:

The event name alongwith 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 one for a user who hasn't installed the app

• An attachment that contains a widget is shared with a user or a group where atleast some users haven'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.

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.