| Please note: We are in the process of deprecating the REST API, so if you are building a new application you shouldn't use this function. Instead use the Graph API and POST a Post object to the `feed` connection of the User object |
This method publishes a post into the stream — on the Wall of the current or specified user, or on the Wall of a friend or a Facebook Page, group, or event connected to the current session or specified user (but not to an application profile page). By default, this call publishes to the current session user's Wall, but if you specify a user ID, Facebook Page ID, group ID, or event ID as the target_id, then the post appears on the Wall of the target, and not the user posting the item.
The post also appears in the streams (News Feeds) of any user connected to both the actor and the target of the post.
Before your application can publish to the stream using this method, the user or Page must grant your application the publish_stream extended permission. If the user previously granted your application the permission to publish short stories into the News Feed automatically, then you don't need to prompt for this permission in order to call this method.
Note: To give users control over what gets published to their streams, you should use Feed forms (rendered with Facebook.streamPublish or FB.Connect.streamPublish) instead of stream.publish. This method is intended to be used in cases where Feed forms are not available or do not make sense in the natural workflow. For more information, read about the publish_stream permission.
You can give your users the opportunity to add their own message to the post.
To provide rich content like MP3 audio, Flash, or an image, you can supply a predefined JSON-encoded object called attachment. Facebook formats the attachment into the post. The attachment is described in Stream Attachments.
Note: The examples below are all server-side versions of the call in PHP. To see the JavaScript equivalents, check out FB.Connect.streamPublish.
You can use this method to simply update a user's status. When you do so, the status message appears at the top of the user's profile and on the Friends > Status Updates page. The message also appears in the stream with your application icon.
To use this method to set a user's status do the following:
In order to use stream.publish to post on the Wall of your application profile page (your application's About Page), all the following conditions must be true:
| Name | Type | Description |
|---|---|---|
| callback | string | Name of a function to call. This is primarily to enable cross-domain JavaScript requests using the <script> tag, also known as JSONP, and works with both the XML and JSON formats. The function will be called with the response passed as the parameter. |
| message | string | The message the user enters for the post at the time of publication. If the message is a status update (that is, you're not including an attachment or an action link), it can contain up to 420 characters. Otherwise, if the post contains an attachment or action link, the message can contain up to 10,000 characters. |
| attachment | object | A JSON-encoded object containing the text of the post, relevant links, a media type (image, mp3, flash), as well as any other key/value pairs you may want to add. See Attachment (Streams) for more details. Note: If you want to use this call to update a user's status, don't pass this parameter. See Updating a User's Status above. |
| action_links | array | A JSON-encoded array of action link objects, containing the link text and a hyperlink. If you want to use this call to update a user's status, don't pass this parameter. See Updating a User's Status above. |
| target_id | string | The ID of the user, Page, group, or event where you are publishing the content. If you specify a target_id, the post appears on the Wall of the target profile, Page, group, or event, not on the Wall of the user who published the post. This mimics the action of posting on a friend's Wall on Facebook itself. Note: If you specify a Page ID as the uid, you cannot specify a target_id. Pages cannot write on other users' Walls. Note: You cannot publish to an application profile page's Wall. |
| uid | string | The ID of the user or Page publishing the post. If this parameter is not specified, then it defaults to the session user. If you want to publish as page, you should use the 'enable_profile_selector' option with FB.login. This option enables the profile selector on the permission dialog. Note: If you specify a Page ID as the uid, you cannot specify a target_id. Pages cannot write on other users' Walls. |
| privacy | object | A JSON-encoded object that defines the privacy setting for a post, video, or album. It contains the following fields.
Only the user can specify the privacy settings for the post. You can create an interface that lets the user specify the privacy setting. For CUSTOM settings, use Note: This privacy setting only applies to posts to the current or specified user's own Wall; Facebook ignores this setting for targeted Wall posts (when the user is writing on the Wall of a friend, Page, event, group connected to the user). Consistent with behavior on Facebook, all targeted posts are viewable by anyone who can see the target's Wall. Privacy Policy: Any non-default privacy setting must be intentionally chosen by the user. You may not set a custom privacy setting unless the user has proactively specified that they want this non-default setting. |
This call returns a post_id string containing the ID of the stream item upon success. If the call fails, it returns an error code instead.