Description

An attachment is rich content attached to a message. It can include content like dynamic widgets, static HTML, FlockML, images and files. Attachments can also have their own buttons.

To see some examples of attachments see Sending Attachments.

Structure of an Attachment

The code block below shows in complete detail every element that can go inside an attachment. Examples of creating different kinds of attachments is covered under Sending Attachments.

An example attachment
{
    "id": "<id>",
    "title": "<attachment title>",
    "description": "<attachment description>",
    "appId": "<app id>",
    // Precedence order of previews:
    // widget > html > flockml > images
    "color": "#0ABE51",
    "views": {
        // Attachment widget
        "widget": { "src": "<widget url>", "width": 400, "height": 400 },
        // Inline html
        "html": { "inline": "<inline html>", "width": 400, "height": 400 },
        "flockml": "<inline flockml>",
        // For image, only "src" is mandatory, everything else is optional
        "image": {
            "original": { "src": "<image 1 url>", "width": 400, "height": 400 },
            "thumbnail": { "src": "<image 2 url>", "width": 100, "height": 100 },
            "filename": "foo-bar.png"
        }
    },
    "url": "<unfurled url>",
    "forward": "true",  // default: false
    // For downloads, only "src" is mandatory, everything else is optional.
    // The client can use mime to show an appropriate file icon to the user.
    // Slashes and dots from the filename should be stripped.
    "downloads": [
        { "src": "<download 1 url>", "mime": "<mime type>", "filename": "<filename 1>", "size": <bytes> },
        { "src": "<download 2 url>", "mime": "<mime type>", "filename": "<filename 2>", "size": <bytes> }
    ],
    "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": "openWidget", "desktopType": "sidebar", "mobileType": "modal", "url": "<action url>" },
        "id": "<button id 2>"
    }, {
        "name": "<button 3>", 
        "icon": "<icon 3 url>", 
        "action": { "type": "sendEvent" },
        "id": "<button id 3>"
    }]
}

Object Attributes

NameTypeRequiredDescription
idStringNoA unique identifier for the attachment as provided by your app.
appIdStringNo

App id for the app that sent the attachment. Any value that your app provides for this attribute will be overwritten with your app's actual id by Flock.

titleStringNoThe title of the attachment.
descriptionStringNoA longer description of the attachment.
colorStringNoA hex value (e.g. "#0ABE51") for the color bar.
viewsViewsNo*Provides user visible views for the attachment. See below for more details.
urlStringNoThe URL to open when user clicks an attachment, if no widget or FlockML is provided. When generating a URL Preview this should always be set.
forwardBooleanNoIf true, the attachment can be forwarded. Default value is false.
downloadsArrayNo*

An array of download objects. Note: As of now this array should contain at max one object.

Each object has the following attributes:

  • src (StringRequired) – URL of the file
  • mime (String) – Mime type of the file (used to select the file icon)
  • filename (String) – Name of the file
  • size (Number) – Size of the file in bytes
 buttons ArrayNo

 An array of attachment buttons. Each object has the following attributes:

  • name (String) – Name of the button.
  • icon (String) – URL of the button icon.
  • action (ActionConfig) – The action to perform when a user clicks on the button.
  • id (String) – An opaque string provided by your app to uniquely identify the button. The id is sent as an attribute of the client.pressButton event.

* While neither views nor downloads is required, one of these must always be present in the attachment.

Views

Flock will select one of the objects inside Views to display on the chat screen. See Sending Attachments for the precedence order of these views.

NameTypeRequiredDescription
widgetObjectNo*

Displays an attachment widget inside the chat screen in desktop, or pops up a modal when the attachment is opened on mobile.

  • src (String) – URL for the widget
  • width (Number) – Width of the widget
  • height (Number) – Height of the widget
 html ObjectNo*

 Displays the HTML string inside the chat screen in desktop (using an iframe). It has the following attributes:

  • inline (String) – The HTML string
  • width (Number) – Width of the content
  • height (Number) – Height of the content
 flockml StringNo* A string containing FlockML content. It is displayed inside the chat screen on both desktop and mobile.
 image ObjectNo*

An image for the attachment. This is an object with two attributes:

  • original (Image, Required) – the full size image
  • thumbnail (Image) – a thumbnail for the image
  • filename (String) – original file name for the image, if any

The value for both these attributes is an Image object, described below.

* At least one of these objects must be present

Image

NameTypeRequiredDescription
srcStringYesThe URL of the image
widthNumberNoWidth of the image in pixels
heightNumberNoHeight of the image in pixels

ActionConfig

This object describes the action that should be triggered when a user clicks on an attachment button.

It can be used to open a widget:

{
    "type": "openWidget",
    "url": "https://example.com/widget",
    "desktopType": "sidebar",
    "mobileType": "modal"
}

Or open a URL in the browser:

{
    "type": "openBrowser",
    "url": "https://example.com",
    "sendContext": false
}

Or send an event to the event listener URL:

{
    type: "sendEvent"
}

It requires at least one attribute, type:

NameTypeRequiredAttribute Description
typeStringYes

The configured action. It can have any one of the following values:

  • openWidget
  • openBrowser
  • sendEvent

In addition, if type equals openWidget, these attributes may be required:

NameTypeRequiredAttribute Description
urlStringYes

The widget URL

desktopTypeStringYes How the widget should be opened on the desktop. It can be either modal or sidebar.
mobileTypeStringNoHow the widget should be opened on mobile. There is only one possible value for this, modal, which is also the default.

If type equals openBrowser, these attributes may be required:

NameTypeRequiredAttribute Description
urlStringYes

The URL to open in the browser

sendContextBooleanNo Whether context should be sent to the browser or not. Defaults to false.