Stream.publish

From Facebook Developer Wiki

Jump to: navigation, search

Contents

Description

This method publishes a post into the stream on the Wall of a user or a Facebook Page, group, or event connected to the user. 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 Attachment (Streams).

Note: The examples below are all server-side versions of the call in PHP. To see the JavaScript equivalents, check out http://developers.facebook.com/docs/?u=facebook.jsdocs.FB.Connect.streamPublish.

Parameters

RequiredNameTypeDescription
optional session_key string The session key of the logged in user. The session key is automatically included by our PHP client. This is only required if you don't specify a uid, or if a desktop application calls stream.publish.
format string The desired response format, which can be either XML or JSON. (Default value is XML.)
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.
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 an attachment; the content of the message parameter will become the user's new status and will appear at the top of the user's profile.
action_links array A JSON-encoded array of action link objects, containing the link text and a hyperlink.
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.
uid string The user ID or Page ID of the user or Page publishing the post. If this parameter is not specified, then it defaults to the session user. If you specified a session_key, and that session user is a Page admin, then you can specify a Page ID here to publish to one Page for which the session user is an admin.


Setting a User's Status.

$message = 'in ur tubez'; $facebook->api_client->stream_publish($message);


Publishing a Post Containing an Image, Action Link, and Custom Metadata

$message = 'Check out this cute pic.'; $attachment = array( 'name' => 'i\'m bursting with joy', 'href' => 'http://icanhascheezburger.com/2009/04/22/funny-pictures-bursting-with-joy/', 'caption' => '{*actor*} rated the lolcat 5 stars', 'description' => 'a funny looking cat', 'properties' => array('category' => array( 'text' => 'humor', 'href' => 'http://www.icanhascheezburger.com/category/humor'), 'ratings' => '5 stars'), 'media' => array(array('type' => 'image', 'src' => 'http://icanhascheezburger.files.wordpress.com/2009/03/funny-pictures-your-cat-is-bursting-with-joy1.jpg', 'href' => 'http://icanhascheezburger.com/2009/04/22/funny-pictures-bursting-with-joy/')), 'latitude' => '41.4', //Let's add some custom metadata in the form of key/value pairs 'longitude' => '2.19'); $action_links = array( array('text' => 'Recaption this', 'href' => 'http://mine.icanhascheezburger.com/default.aspx?tiid=1192742&recap=1#step2')); $attachment = json_encode($attachment); $action_links = json_encode($action_links); $facebook->api_client->stream_publish($message, $attachment, $action_links);


Publishing a Post Containing Flash, Action Link, and a Target

$message = 'Watch this video!'; $attachment = array( 'name' => 'ninja cat', 'href' => 'http://www.youtube.com/watch?v=muLIPWjks_M', 'caption' => '{*actor*} uploaded a video to www.youtube.com', 'description' => 'a sneaky cat', 'properties' => array('category' => array( 'text' => 'pets', 'href' => 'http://www.youtube.com/browse?s=mp&t=t&c=15'), 'ratings' => '5 stars'), 'media' => array(array('type' => 'flash', 'swfsrc' => 'http://www.youtube.com/v/fzzjgBAaWZw&hl=en&fs=1', 'imgsrc' => 'http://img.youtube.com/vi/muLIPWjks_M/default.jpg?h=100&w=200&sigh=__wsYqEz4uZUOvBIb8g-wljxpfc3Q=', 'width' => '100', 'height' => '80', 'expanded_width' => '160', 'expanded_height' => '120'))); $action_links = array( array('text' => 'Upload a video', 'href' => 'http://www.youtube.com/my_videos_upload')); $target_id = 2342314; $facebook->api_client->stream_publish($message, $attachment, $action_links, $target_id);


Publishing a Post With Image and Action Link in C#

attachment attach = new attachment(); attach.caption = "Caption for attachment"; attach.description = "Description for attachment"; attach.href = "http://www.joemagner.com"; attach.name = "Hopefully this works"; attachment_media attach_media = new attachment_media(); attach_media.type = attachment_media_type.image; attachment_media_image image = new attachment_media_image(); image.type = attachment_media_type.image; image.href = "http://icanhascheezburger.com/2009/03/30/funny-pictures-awlll-gone-cookie-now/"; image.src = "http://icanhascheezburger.files.wordpress.com/2009/03/funny-pictures-kitten-finished-his-milk-and-wants-a-cookie.jpg"; List<attachment_media> attach_media_list = new List<attachment_media>(); attach_media_list.Add(image); attach.media = attach_media_list; attachment_property attach_prop = new attachment_property(); attachment_category attach_cat = new attachment_category(); attach_cat.text = "Sample"; attach_cat.href = "#"; attach_prop.category = attach_cat; //attach_prop.ratings = "5 stars"; attach.properties = attach_prop; /* action links */ List<action_link> actionlink = new List<action_link>(); action_link al1 = new action_link(); al1.href = "http://www.genuineinteractive.com/"; al1.text = "Genuine Interactive"; actionlink.Add(al1); // Create the service FacebookService fbService = new FacebookService(); fbService.ApplicationKey = AppSettings.GetKeyAsString("APIKey"); fbService.Secret = AppSettings.GetKeyAsString("Secret"); fbService.IsDesktopApplication = false; fbService.SessionKey = sessionKey; fbService.uid = uid; return fbService.API.stream.publish("Message goes here", attach, actionlink, fbService.uid.ToString(), 0);


Publishing a Post With Image and Action Link in C# using facebook developer toolkit v2

public void Post(facebook.API fbAPI, string appLink) { string response = fbAPI.stream.publish( "{*actor*} is a good guy.", new attachment() { name = "I am a good guy !", href = appLink, caption = "{*actor*} is now a good guy", description = "Helping other people, I became a new good guy.", properties = new attachment_property() { ratings = "5", category = new attachment_category() { text = "My profile", href = appLink } }, media = new List<attachment_media>() { new attachment_media_image() { src = "http://www.goodguy.com/goodGuy.png", href = appLink } } }, new List<action_link>() { new action_link() { text = "Become a good guy", href = appLink } }, null, 0); }



Response

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.

Error Codes

CodeDescription
1 An unknown error occurred.
100 Invalid parameter.
102 Session key invalid or no longer valid (if it's a desktop application and the session is missing).
200 Permissions error. The application does not have permission to perform this action.
210 User not visible. The user doesn't have permission to act on that object.
340 Feed action request limit reached.

Notes

You can call this method using a session secret, and not the application secret (for example, for a Facebook Connect site or desktop application).

See Also

Using the Open Stream API

Retrieved from "http://wiki.developers.facebook.com/index.php/Stream.publish"
reference