Feed.publishTemplatizedAction
From Facebook Developers Wiki
Contents |
[edit] Description
Publishes a Mini-Feed story to the user or Page corresponding to the session_key or page_actor_id parameter. For user stories, this function publishes News Feed stories to the friends of that user. The likelihood of the story showing up in the user's friends' News Feeds depends upon a variety of factors, such as the closeness of the relationship between the users, the interaction data we have about that particular story type, and the quality of the content in the story/on the linked page. Note that you should not be using a session_key for a user who is not actively using your application when calling this method; for example, publishing a story like "John received a present" is not allowed - for more information, see the announcement of this policy.
To publish approved feed stories and stories for inactive users, see feed_forms.
For PHP users the function can be found in facebookapi_php5_restlib.php (for people using PHP5) or facebookapi_php4_restlib.php (for PHP4).
[edit] Parameters
| Required | Name | Type | Description | |
| required | api_key | string | The application key associated with the calling application. | |
|---|---|---|---|---|
| session_key | string | The session key of the logged in user. | ||
| call_id | float | The request's sequence number. Each successive call for any session must use a sequence number greater than the last. We suggest using the current time in milliseconds, such as PHP's microtime(true) function. | ||
| sig | string | An MD5 hash of the current request and your secret key, as described in the authentication guide. | ||
| v | string | This must be set to 1.0 to use this version of the API. | ||
| title_template | markup | The markup template displayed in the Feed story's title section. This template must contain the token {actor} somewhere in it (see the Notes section below for more requirements). | ||
| optional | format | string | Desired response format. Either XML (default) or JSON. | |
| 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. | ||
| title_data | string | A JSON-encoded associative array of the values that should be substituted into the templates in the title_template markup string. The keys of this array are the tokens, and their associated values are the desired substitutions. 'actor' and 'target' are special tokens and should not be included in this array. If your title_template contains tokens besides 'actor' or 'target', then this is a required parameter. | ||
| body_template | markup | The markup template displayed in the Feed story's body section. | ||
| body_data | string | A JSON-encoded associative array of the values that should be substituted into the templates in the body_template markup string. The keys of this array are the tokens, and their associated values are the desired substitutions for the specific instance of this templatized story. If your body_template contains tokens besides 'actor' or 'target', then this is a required parameter. | ||
| body_general | markup | Additional markup that goes in the body that is not aggregated. I.e., if two or more stories are aggregated into one story, the markup in the body_general from any one of those stories may be displayed. | ||
| page_actor_id | int | The ID of the Facebook Page performing the action. Whether the Page must have the application added to its Feed in order for this call to be successful. For Feed stories about users, you will leave this parameter blank and instead use the session_key to indicate the ID of the user who performed the action. For Feed stories about Facebook Pages (where this parameter is used), the usage of a session_key is not required. | ||
| image_1 | string | The URL of an image to be displayed in the Feed story. Similar to body_general, the image displayed is not aggregated -- the image from any one of the aggregated stories may be displayed. | ||
| image_1_link | string | The URL destination after a click on the image referenced by image_1. | ||
| image_2 | string | The URL of an image to be displayed in the Feed story. Similar to body_general, the image displayed is not aggregated -- the image from any one of the aggregated stories may be displayed. | ||
| image_2_link | string | The URL destination after a click on the image referenced by image_2. | ||
| image_3 | string | The URL of an image to be displayed in the Feed story. Similar to body_general, the image displayed is not aggregated -- the image from any one of the aggregated stories may be displayed. | ||
| image_3_link | string | The URL destination after a click on the image referenced by image_3. | ||
| image_4 | string | The URL of an image to be displayed in the Feed story. Similar to body_general, the image displayed is not aggregated -- the image from any one of the aggregated stories may be displayed. | ||
| image_4_link | string | The URL destination after a click on the image referenced by image_4. | ||
| target_ids | string | Comma-delimited list of IDs of friends of the actor, used for stories about a direct action between the actor and these targets of his/her action. This is required if either the title_template or body_template includes the token {target}. |
[edit] Example Return XML
| Example (PHP) $facebook->api_client->feed_publishTemplatizedAction($title_template,$title_data,$body_template,$body_data,$body_general); |
Example Arguments
|
| Example Return XML <?xml version="1.0" encoding="UTF-8"?> <feed_publishTemplatizedAction_response xmlns="http://api.facebook.com/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://api.facebook.com/1.0/ http://api.facebook.com/1.0/facebook.xsd"> 1 </feed_publishTemplatizedAction_response> |
[edit] Response
The function returns 1 on success, 0 on permissions error, or an error response.
[edit] Error Codes
| Code | Description | |
| 1 | An unknown error occurred. Please resubmit the request. | |
|---|---|---|
| 2 | The service is not available at this time. | |
| 4 | The application has reached the maximum number of requests allowed. More requests are allowed once the time window has completed. | |
| 5 | The request came from a remote address not allowed by this application. | |
| 100 | One of the parameters specified was missing or invalid. | |
| 101 | The API key submitted is not associated with any known application. | |
| 102 | The session key was improperly submitted or has reached its timeout. Direct the user to log in again to obtain another key. | |
| 103 | The submitted call_id was not greater than the previous call_id for this session. | |
| 104 | Incorrect signature. | |
| 330 | The markup was invalid. | |
| 341 | Feed action request limit reached. | |
| 360 | Feed story title_data argument was not a valid JSON-encoded array. | |
| 361 | Feed story title template either missing required parameters, or did not have all parameters defined in the title_data array. | |
| 362 | Feed story body_data argument was not a valid JSON-encoded array. | |
| 363 | Feed story body template either missing required parameters, or did not have all parameters defined in body_data array. | |
| 364 | Feed story photos could not be retrieved, or bad image links were provided. | |
| 366 | One or more of the target IDs for this story are invalid. They must all be IDs of friends of the acting user. |
[edit] Notes
Publishing to Feeds requires you to understand the rules of their operation.
- The title_template parameter is required, and is limited to 60 displayed characters (excluding tags).
- The markup must contain the token '{actor}' somewhere, and this token should be placed somewhere such that it makes sense that the name of the actor who is performing an action (or multiple actors) may be substituted.
- The token '{target}' is also special, and is used to provide the Facebook News Feed engine with additional information about the structure of the story template. It is not a required token, but if it is used, then target_ids becomes a required parameter. At display time, {target} is substituted with the names of the friends whose ids are given in target_ids.
- The markup may contain other tokens, which are denoted by putting curly braces {} around a string. These tokens will be substituted with specific values based on the data given in the accompanying data array.
- The <fb:name>, <fb:pronoun>, <fb:if-multiple-actors>, and
<a>tags are allowed. No other tags are allowed.
- The body_template is optional, and is limited to 200 display characters when combined with body_general (excluding tags).
- The markup may contain the tokens '{actor}' or '{target}' somewhere, though they are not required.
- The <fb:userlink>, <fb:name>, <fb:pronoun>, <fb:if-multiple-actors>
<a>,<b>, and<i>tags are allowed. No other tags are allowed.
- The title_data and body_data parameters must be JSON-encoded associative arrays for the story that are used to substitute specific values into $title_template and $body_template.
- Two or more News Feed stories published with this method may be aggregated, which increases the likelihood of it being displayed to friends of the acting users.
- In order for two stories to be aggregated together, the title_template and body_template markup strings must be identical, the target_ids must be the same, and the associative arrays given by title_data and body_data must also contain identical keys and values. (These pieces of data used to generate a unique identifier for this particular story. This includes strings within <fb:if-multiple-actors> tags -- all the strings must be identical.)
- If two or more stories are aggregated, then the {actor} token is replaced with the names of all of the users or Pages whose actions are being aggregated. The fb:if-multiple-actors tag comes into effect when there is more than one actor involved in the story.
- The body_general markup should be used for information that does not need to match in order for the story to aggregate. It could contain, for instance, more details on one particular actor's action (e.g. an example wallpost or gift).
- Up to 4 images can be displayed, which will be shrunk to fit within 75x75 pixels, cached, and formatted by Facebook. You must own the image and grant Facebook the permission to cache it. Each image must have a link associated with it, which must start with http://
- If two or more stories are aggregated for display, then the body_general and all the images chosen for display will come from the same component story
- Stories from the same actor cannot be aggregated, since the story would just look the same as itself anyway.
- Applications are limited to calling this function 10 times for each user or Page in a rolling 48-hour window.
- The story may or may not show up in the user's friends' News Feeds, depending on the number and quality of competing stories.
- If a story template is registered and enabled to be shown to all users, it may be shown to the user's friends that do not have the application installed.
- You may use the Feed Preview Console at to experiment with this method and see previews of your stories.
[edit] See Also
