Stream Attachments

Introduction

You can add a lot of rich information to a stream story by including an attachment. The attachment gives you the opportunity to expand on the post by describing what the user did in your application. Attachments are optional, however.

The attachment is an array of structured data that defines the post. It contains these optional fields:

name: The title of the post. The post should fit on one line in a user's stream; make sure you account for the width of any thumbnail.
href: The URL to the source of the post referenced in the name. The URL should not be longer than 1024 characters.
caption: A subtitle for the post that should describe why the user posted the item or the action the user took. This field can contain plain text only, as well as the {*actor*} token, which gets replaced by a link to the profile of the session user. The caption should fit on one line in a user's stream; make sure you account for the width of any thumbnail.
description: Descriptive text about the story. This field can contain plain text only and should be no longer than is necessary for a reader to understand the story. The description can contain up to 1,000 characters, but Facebook displays the first 300 or so characters of text by default; users can see the remaining text by clicking a "See More" link that we append automatically to long stories, or attachments with more than one image.
properties: A dictionary of key/value pairs that provide more information about the post. The key should be the label of the property (e.g., "Length"). The value can either be a string or an array. If it's a string, it will be rendered as the value (e.g., if the value is "0:17", then the full property will be rendered as "Length: 0:17"). If it's an array, the array can contain two properties -- "text" and "href". The text key will point to the value (again, "0:17"). The href key will point to a link which will hyperlink the value. The key can have a maximum length of 50 characters. The value can have a maximum length of 70 characters.
media: Rich media that provides visual content for the post. media is an array that contains one of the following types: image, flash, or mp3, which are described below. Make sure you specify only one of these types in your post.
comments_xid: An application-specific xid associated with the stream post. The xid allows you to get comments made to this post using the comments.get. It also allows you to associate comments made to this post with a Comments Box for FBML fb:comments.
Your own key/value pairs: You can include your own key/value pairs for your own use later on. These key/value pairs won't appear in any user's stream when published, but Facebook stores them. When you retrieve the user's stream later with stream.get, these key/value pairs get returned with the rest of the user's stream. For example, you might have an application that uses geo-tagging. You could pass through key/value pairs that record the user's latitude and longitude when the user publishes the post. Then, when you retrieve the streams for many of your users, you can use that data to plot out a geographic distribution of your users and their actions.

Including Media in the Attachment

You can include rich media in the attachment for a post into a user's stream. The media parameter contains a type, which can be one of the following: image, flash, or mp3; these media types render photos, Flash objects, and music, respectively.

Note: If you include more than one media type in the array, Facebook will choose only one of these types, in this order:

image
flash
mp3

Using the `image` Media Type

The image media type is part an array which itself contains an array of up to five JSON-encoded photo records. Each record must contain a src key, which maps to the photo URL, and an href key, which maps to the URL where a user should be taken if he or she clicks the photo.

You can include up to 5 photos in the media array. However, only one photo gets displayed in the Feed story; the user can see the remaining photos by clicking a "See More" link that gets appended to the story. Photos can be up to 90 pixels in both height and width.

Here"s an example of a JSON-encoded array of an image media type in an overall attachment array.

{"media": [
    { 
        "type": "image", 
        "src": "http://icanhascheezburger.files.wordpress.com/2009/03/funny-pictures-kitten-finished-his-milk-and-wants-a-cookie.jpg", 
        "href": "http://icanhascheezburger.com/2009/03/30/funny-pictures-awlll-gone-cookie-now/"
    }, 
    {
        "type": "image", 
        "src": "http://photos.icanhascheezburger.com/completestore/2009/1/18/128768048603560273.jpg", 
        "href": "http://ihasahotdog.com/upcoming/?pid=20869"
    }]
}

Note: Although you pass photos and other images as type image, when you get the attachment by calling stream.get or querying on the stream (FQL) table, the image gets returned as type photo.

Note: Don't reference images that are hosted on the fbcdn.net domain. The images associated with these URLs aren't always optimized for stream stories and occasionally resulted in errors, leading to a poor user experience. Make sure your stream attachments don't reference images with this domain. You should host the images locally.

Using the `flash` Media Type

The flash media type is part of an array containing two other required fields:

swfsrc, which is the URL of the Flash object to be rendered. This is also known as the Flash 'source' attribute.
imgsrc, which is the URL of an photo that should be displayed in place of the Flash object until the user clicks to prompt the Flash object to play. This is also known as the Flash 'image' attribute.

By default, the photo and the Flash object are rendered in a space up to 90 pixels in both height or width, with an emphasis on scaling the image to be 90 pixels wide.

The array can include two optional fields, width and height, which can be used to override the default choices. Both the height and width must be an integer between 30 and 90, inclusive.

The array can also include two optional fields to specify the width and height of the Flash object once the user clicks on it. If you specify both expanded_width and expanded_height in the array, when the user clicks on the Flash object, it will resize to the specified size. The maximum dimensions are 398px in both height or width, and the minimum dimensions are 30px wide and 30px high. If expanded dimensions are not specified, the dimensions of the Flash object will be the same as its thumbnail. Note that these dimensions are subject to change and your content will be scaled accordingly.

Here's an example of a JSON-encoded array of a flash media type in an overall attachment array:

{"media": [{
    "type": "flash", 
    "swfsrc": "http://www.mapsofwar.com/photos/EMPIRE17.swf", 
    "imgsrc": "http://icanhascheezburger.files.wordpress.com/2009/04/funny-pictures-hairless-cat-phones-home.jpg", 
    "width": "80", 
    "height": "60",
    "expanded_width": "160", 
    "expanded_height": "120"
}]}

Using the `mp3` Media Type

The mp3 media type is part of an array containing one other required field: src, which is the URL of the MP3 file to be rendered within Facebook's MP3 player plugin.

The array can optionally include title, artist, and album fields, all of which map to strings.

Here"s an example of a JSON-encoded array of a mp3 media type in an overall attachment array:

{"media": [{
    "type": "mp3", 
    "src": "http://www.looptvandfilm.com/blog/Radiohead%20-%20In%20Rainbows/01%20-%20Radiohead%20-%2015%20Step.MP3", 
    "title": "15 Step", 
    "artist": "Radiohead", 
    "album": "In Rainbows"
}]}

Translating Attachments

If your application works with the Facebook Translations framework, you can include fb:intl and its child tags in your attachments.

Updated about 3 months ago