What is URL Preview?

When a user sends a message containing a URL, Flock will attempt to show a preview of the page that the URL points to. For eg

While Flock does this automatically for public URLs, your app can register to generate URL previews for specific URL patterns. For eg

  • A Google Drive Integration app may register to provide URL previews for any URLs beginning with http://docs.google.com
  • A GitHub Integration app may register to provide URL previews for any URLs beginning with http://github.com

How do I handle URL previews from my app?

  1. Go through Creating an App to setup your app in the dev dashboard
  2. In the Advanced Info section, provide a list of domains that your app can generate previews for.

  3. Save these changes, then go through App Installation and install this app into your own Flock account.

  4. After the app is installed, whenever a user shares a URL that matches the domains you have entered above, the chat.generateUrlPreview event will be sent to your event listener URL. For example:

    chat.unfurlUrl
    {
    "name": "chat.unfurlUrl",
    "userId": "u:8c67055b-202f-4ffe-a18f-1c4553a50175",
    "url": "https://flock.co",
    "chat": "u:1e6429de-16b7-48b3-acc0-c2d7ec5ad195",
    "messageId": "4458f0a9-eca7-4efb-8560-2a0fd3ac858d"
}

  5. Respond to the event with an Attachment object. Check Sending Attachments for more details also. Include the original URL in the url attribute. When a user clicks on the attachment, Flock will open the URL in the browser.

    chat.unfurlUrl response
    {
    "attachment": {
        "title": "Flock -- A Communication app for teams"
        "description": "Flock is a free enterprise tool for business communication. Packed with tons of productivity features, Flock drives efficiency and boosts speed of execution.",
        "url": "https://flock.co",
        "views": {
            "image": {
            "original": { "src": "https://flock.co/logo.png", "width": 400, "height": 400 },
        }
    }
}
  6. Any authentication required to generate the URL Preview will have to be handled by you. For eg if your app is generating a URL Preview for a Google Docs URL you may need OAuth permissions from the user for his Google account. You can send a message to a user from your Bot with a link asking him to provide you with these permissions.