Sending Attachments

What is an Attachment?

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. Here are a few examples:

The Poll app uses a widget to render a live interactive poll inside a chat tab.

URL Preview uses static HTML, for example, to display YouTube previews inline.

The Trello app uses FlockML to render card information in attachments.

Unlike widgets or static HTML that can only be rendered inline on desktop, FlockML can be rendered inline in mobile too.

Your app can also send images using attachments.

Or share files.

How can I send an attachment?

Since an attachment is a part of a message, to send an attachment you will need to send a message. If you haven't, read Sending Messages first.

Include the Attachment inside the attachments array that is passed to chat.sendMessage. The example below shows an attachment with a title, description and a widget.. See the Attachment reference for more details on the attachment object.

Sending an Attachment

POST /v1/chat.sendMessage HTTP/1.1
Host: api.flock.co
Content-Type: application/x-www-form-urlencoded
Content-Length: 70
 
token=632542db-1a23-4e06-8b39-01f8b0868d57&to=u:513a9f4ae409&text=hello&attachments=[{"title":"attachment title","description":"attachment description","views":{"widget":{"src":"http:%2F%2Fwww.polls.com%2Fyour-poll-url","width": 400,"height": 400}}}]

What are Attachment buttons?

Each attachment can also provide one or more buttons to perform custom actions in Flock when they are pressed.

For example, the to-do app adds a View button for any attachment that it sends.

To add a button one or more buttons to an attachment, use the buttons array.

{
    "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": "openWidget", "desktopType": "sidebar", "mobileType": "modal", "url": "<action url>" }
        "id": "<button id 2>"
    }]
}

Each button can have a name, icon, an identifier and an action associated with it. An attachment button can perform any of these three actions:

Open a widget
Open the browser
Send an event to the event listener URL

See ActionConfig for details on how an action can be configured for attachment buttons.

How do I create different kinds of attachments?

Widgets

Create an attachment with a widget as follows. Note that an attachment widget opens inline in the chat pane only on the desktop and not on mobile (where it opens in a full screen modal on click). width and height are only used on desktop to fix the dimensions of the inline attachment widget. See Widgets for more details.

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

HTML

Static HTML included in an attachment shows up inline in desktop. On mobile clients, clicking on the attachment opens this HTML in a modal webview. Again, width and height are only used on desktop.

{
    "title": "attachment title",
    "description": "attachment description",
    "views": {
        "html": { "inline": "<inline html>", "width": 400, "height": 400 }
    }
}

FlockML

FlockML is an alternative to static HTML that can be shown inline in both desktop and mobile.

{
    "title": "attachment title",
    "description": "attachment description",
    "views": {
        "flockml": "<inline flockml>"
    }
}

Images

An image and optionally its thumbnail can be added to an attachment as follows. Images are rendered inline on both mobile and desktop

{
    "title": "attachment title",
    "description": "attachment description",
    "views": {
        "image": {
            "original": { "src": "<image 1 url>", "width": 400, "height": 400 },
            "thumbnail": { "src": "<image 2 url>", "width": 100, "height": 100 }
        }
    },
}

Files

One can also share files using attachments via the downloads attribute

{
    "downloads": [
        { "src": "<download 1 url>", "mime": "<mime type>", "filename": "<filename 1>", "size": <bytes> },
    ]
}

What is the precedence order for attachment rendering?

Flock selects of the following "Views" for display in the chat screen. The order of precedence (highest to lowest) is as follows:

Widget
HTML
FlockML
Image

On mobile, widget and HTML are not displayed on the chat screen, so only the last two are used. If a user taps on the attachment though, widget or HTML are shown in a modal.

Content

Space Tools