From Facebook Developer Wiki

Introduction

You can add a lot of rich information to a post 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.
• properties: An array of key/value pairs that provide more information about the post. The properties array can contain plain text and links only. To include a link, the value of the property should be a dictionary with 'text' and 'href' attributes.
• media: Rich media that provides visual content for the post. media is an array that contains one of the following types: image, flash, mp3, or video, 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 API. 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.

Example

To attach a link with a description use the following example:

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 following: image, flash, mp3, or video; these media types render photos, Flash objects, music, and video, respectively.

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

1. image
2. flash
3. mp3
4. video

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.

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.

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.
• 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.

By default, the photo and the Flash object are rendered in a space 30 pixels high and 100 pixels wide.

The array can include two optional fields, width and height, which can be used to override the default choices. The height must be an integer between 30 and 100, inclusive, and the width must one one of three numbers: 100, 110, or 130. If a height outside the [30, 100] range is provided, it is pulled into range. If a width other than 100, 110, or 130 is specified, it will be replaced with the closest of the three allowed values.

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 320px wide and 260px high and the minimum dimensions are 30px wid and 30px high. If expanded dimensions are not specified, the dimensions of the Flash object will be the same as its thumbnail.

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

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 widget.

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:

Using the video Media Type

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

• video_src, which is the URL of the video to be rendered.
• preview_img, which is the URL of an photo that should be displayed in place of the video until the user clicks to play. The preview image can be up to 130px wide and 120px high. When expanded, the video becomes 420px wide.

The array can optionally include video_title, video_type, and video_link. If not included, video_title defaults to an empty string, video_type defaults to "application/x-shockwave-flash", and video_link defaults to the value of video_src.

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

See Also

• stream.publish
• FB.Connect.streamPublish
• Facebook.streamPublish