Events

What are events?

Flock uses events to notify apps in real-time about interesting things like:

• App installs and uninstalls
• New messages received by the app bot
• User actions like when a button is pressed, or when a slash command is entered.

List of Events

• app.install
• app.uninstall
• chat.generateUrlPreview
• chat.receiveMessage
• client.pressButton
• client.slashCommand
• client.widgetAction
• client.flockmlAction
• client.openAttachmentWidget

Receiving Events

Whenever an event is triggered, it is sent to the app in one of two ways

• Either they are sent to the Event Listener URL.
• Or they may be sent to a widget or the browser (in the form of a URL query parameter)

Some events like app.install can only be sent to the event listener URL, whereas others like client.pressButton (that are triggered in response to user actions in Flock), can be sent either to the event listener or to a widget or browser URL, depending on how the corresponding integration was configured. See Can any event be sent a to widget or browser URL? for a list of these events.

Receiving Events on the Event Listener URL

The event listener URL is an HTTPS endpoint that you provide while creating the app in the dev dashboard. Events are sent to this URL in the form of an HTTP POST request with a JSON body. The app may choose to process certain events and ignore others.

For example, if the callback URL is https://example.com/events, the HTTP request as shown below is sent to the app.

POST /events HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 162
X-Flock-Event-Token: eyJhbGciOiJI.Zm9vYmFy.DNKgXrWOe0WEeU3j5ZTVSU9LKWE

{
    "name": "<event name>",
    "userId": "u:<identifier>",
    "customAttribute1": "<value 1>",
    "customAttribute2": "<value 2>"
}

The headers X-Flock-Event-Token provides an event token that has been signed with the app secret. Your app can use it to verify that the request did indeed originate from Flock.

The body of the HTTP request contains an event object. Each event object contains the following fields:

• name. The name of this event.
• userId. Id of the user related to this event.
• Any other custom event attributes related to this event.

Responding to Events

For most events Flock ignores the response to the HTTP request. However, for some events, a response is useful and may in fact be required. For example, the chat.generateUrlPreview event expects an attachment object in the response. This attachment is added to the message for which the preview was requested. The snippet below shows how a response to such an event might be sent.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 235

{
    "attachment": {
        "title": "<title>",
        "description": "<description>",
        "views": {
            "widget": { "src": "<url>", "width": 400, "height": 400 },
            "flockml": "<flockml>some content</flockml>"
        }
    }
}

Receiving Events on a Widget or in the Browser

A few events are sent as a query parameter to the widget or the browser if the action configured for their corresponding integrations is either to open a widget or to open the browser. 

The following parameters are added to the widget or browser URL:

For example, if one configures an attachment picker button in the developer dashboard, when a user clicks on this button, the client.pressButton event alongwith the event token and other parameters is added to the URL like this:

https://<widget url>?flockEventToken=<token>&flockClient=desktop&flockWidgetType=modal&flockEvent=%7B%22name%22%3A%22client.pressButton%22%2C%22button%22%3A%22chatTabButton%22%2C%22userId%22%3A%22u%3Aguid1%22%2C%22userName%22%3A%22Alyssa%20P.%20Hacker%22%2C%22chat%22%3A%22u%3Aguid2%22%2C%22chatName%22%3A%22Ben%20Bitdiddle%22%7D

List of Events sent to a Widget or Browser

Only the following events can be sent to a widget or browser.

• client.pressButton
• client.slashCommand
• client.widgetAction
• client.flockmlAction
• client.openAttachmentWidget