News Feed Resources

Returns a URL to the feed items for all feeds for the logged-in user. Also returns an Is-Modified resource for polling the feed for updates.

Resource

1/chatter/feeds/news/me

or

1/chatter/feeds/news/userId

userId must be the ID of the logged-in user or the alias me.

Note

Available since version

23.0

HTTP methods

GET or HEAD

Request parameter

Parameter Name	Type	Description
sort	String	Specifies the order returned by the sort, such as by date created or last modified: CreatedDateDesc—Sorts the feed items by most recent post date. LastModifiedDateDesc—Sorts the feed items by most recent activity, which includes new feed items and comments. The default value is CreatedDescDate.

Response body

Feed

Example response body

1{ 
2   "feedItemsUrl": "/services/data/v30.0/chatter/feeds/news/005xx000001Sv1mAAB/feed-items", 
3   "isModifiedUrl": "/services/data/v30.0/chatter/feeds/news/005xx000001Sv1mAAB/is-modified?since=2%3A1344352279000" 
4}

Before the introduction of the Is-Modified resource, you had to poll the news feed directly using the News Feed Items resource, then do a comparison to see if the news feed had changed. Retrieving a news feed is a costly use of computing resources. In addition, when you poll a feed directly, you run a greater risk of exceeding the rate limit imposed by Chatter REST API.

If your application polls the news feed directly, we recommend that you adapt your code to use the Is-Modified resource to lessen your chances of reaching the rate limit and to save computing resources.

Use the Is-Modified resource to poll the news feed

1. Use either of the following resources to get the latest items from a news feed or to get information about the feed: /chatter/feeds/news/me/feed-items, /chatter/feeds/news/me.

   The response bodies for both resources contain the isModifiedUrl property. This property contains the URL to the Is-Modified resource, which includes a since request parameter that defines the last modified date of the feed. If the sort order of the request to the news feed changes, the news feed is modified.

2. Issue a GET request to the URL in the isModifiedUrl property.
   The Feed Modified Info response contains the following properties:

   • isModified—a boolean indicating whether the feed has been updated since the last time you checked. Conditions under which this property is true depend on the sort order of the original request to the news feed. For example, if the feed is sorted by posts (CreatedDateDesc) and a comment was added, isModified is false.
   • nextPollUrl—a string containing the URL of the Is-Modified resource. This property contains a URL only if isModified is false. If isModified is true, nextPollUrl is null.
3. If the isModified property is true, issue a GET request to the News Feed Items resource to refresh the news feed.
4. If the isModified property is false, issue a GET request to the URL in the nextPollUrl property. This request also returns a Feed Modified Info response body that contains the isModified and nextPollUrl properties.

We don’t recommend exceeding one poll per minute.

Note

Resource

1/chatter/feeds/news/me/is-modified

or

1/chatter/feeds/news/userId/is-modified

userId must be the ID of the logged-in user or the alias me.

Note

Available since version

26.0

HTTP methods

GET or HEAD

Request parameter

Parameter Name	Type	Description	Required or Optional	Available Since
since	String	An opaque token containing information about the modification time stamp of the feed and the sort order. Do not construct this token. Retrieve this token from the isModifiedToken property of the Feed Item Page or Feed Modified Info response body.	Required	23.0

Response body

Feed Modified Info

All feed items from all groups the logged-in user either owns or is a member of, as well as all files, records, and users the logged-in user follows. Use this resource to get information about the feed items and to post feed items.

For information about posting a feed item, see Using POST, PATCH, or PUT for Input.

For information about uploading and attaching a binary file to a feed item, see Uploading Binary Files.

GET requests for this resource return the isModifiedUrl property, which contains a News Feed Is-Modified resource for polling the feed for updates.

As of API version 29.0, feed items can contain 5000 characters. This change is backwards compatible; all earlier API versions support the 5000 character limit.

Resource

1/chatter/feeds/news/userId/feed-items

userId must be the ID of the logged-in user or the alias me.

Note

Available since version

23.0

HTTP methods

GET, POST, HEAD

Request parameters for GET

Parameter Name	Type	Description	Required or Optional	Available Version
density	String	The density of the feed. One of these values: AllUpdates—Displays all posts and comments from people and records the user follows and groups the user is a member of. FewerUpdates—Displays all posts and comments from people and records the user follows and groups the user is a member of, but hides system-generated posts from records that nobody commented on. The default value is AllUpdates.	Optional	29.0
page	String	A generated token that indicates the view of feed items in the feed. Page tokens are returned as part of the response body, in one of the URL parameters, such as nextPageURL, for example: 1"nextPageUrl": 2"/services/data/v30.0/ 3chatter/feeds/news/ 4005D0000001GLowIAN 5/feed-items 6?page=2011-03-30T17:34:50Z, 70D5D0000000DSv4KAG"	Optional	23.0
pageSize	Integer	Specifies the number of items per page. Valid values are between 1 and 100. If you don't specify a size, the default is 25.	Optional	23.0
q	String	One or more keywords to search for in the body and comments of feed items in this feed. The search string can contain wildcards and must contain at least two characters that aren’t wildcards. See Wildcards.	Optional	28.0
recentComment​Count	Integer	Maximum number of comments to include per feed item. The default value is 3. The maximum value is 25.	Optional	29.0
sort	String	Specifies the order returned by the sort, such as by date created or last modified: CreatedDateDesc—Sorts the feed items by most recent post date. LastModifiedDateDesc—Sorts the feed items by most recent activity, which includes new feed items and comments. The default value is CreatedDescDate.	Optional	23.0
updatedSince	String	An opaque token defining the modification time stamp of the feed and the sort order. Do not construct this token. Retrieve this token from the updatesToken property of the Feed Item Page response body.	Optional	30.0

Request body for POST

Root XML tag

<feedItem>

JSON

The following example attaches a poll to a feed item:

1{ "attachment": 
2  {
3     "attachmentType":"Poll",
4     "pollChoices": [
5        "Monday", 
6        "Tuesday"
7     ]
8  },
9  "body" : {
10     "messageSegments" : [
11     {
12        "type" : "Text",
13        "text" : "When should we meet for release planning?"
14     }
15     ]
16  }
17}

Properties

Name	Type	Description	Available Version
attachment	Depends on type.	Optional. You can specify only one of these values in the attachment parameter. Values are: Attachment Input: Canvas App (v29.0) Attachment Input: Existing Content (v23.0) Attachment Input: Feed Poll (v26.0) Attachment Input: Link (v23.0) Attachment Input: New File Upload (v23.0) To upload a new file, you must include it in a multipart/form–data message. See Uploading Binary Files. Note
body	Message Body Input	Description of message body. The body can contain up to 25 mentions. If you specify originalFeedItemId to share a feed item, use the body property to add a comment to the feed item. If this feed item is shared, this value is the body of the first comment.	23.0
isBookmarked​ByCurrentUser	Boolean	Optional. Specifies if the new feed item should be bookmarked for the user (true) or not (false). Default value is false.	24.0
originalFeedItemId	String	Optional. If this feed item is shared, this is the original feed item 18-character ID This parameter takes precedence over all other parameters. For example, if you share a post and also try to upload a file, the generated feed-item only contains the shared post. You should only share a post or upload a file, not both in the same post. Note	24.0
visibility	String	Optional. Who can see the post. Valid values are: InternalUsers—If Communities is enabled, only members of the default, internal community can see the feed item. AllUsers—If Communities is enabled, all members of the community can see the feed item. Default values: For external users, the default value is AllUsers. External users must use this value to see their posts. For internal users, the default value is InternalUsers. Internal users can accept this value or use the value AllUsers to allow external users to see their posts. If the parent of the feed item is a User or a Group, the visibility of the feed item must be AllUsers.	26.0

Request parameters for POST

Use one of the following sets of parameters. For example, you can’t post a link and attach a file in the same request.

Parameters for attaching an existing file

Parameter Name	Type	Description	Required or Optional	Available Version
attachmentType	String	The attachment type. Must contain the value ExistingContent.	Required	27.0
contentDocumentId	String	18-character ID of an existing file.	Required	23.0
isBookmarked​​ByCurrentUser	Boolean	Specifies if the new feed item should be bookmarked for the user (true) or not (false). Default value is false.	Optional	26.0
text	String	Text of the feed item.	Optional	23.0
visibility	String	Who can see the post. Valid values are: InternalUsers—If Communities is enabled, only members of the default, internal community can see the feed item. AllUsers—If Communities is enabled, all members of the community can see the feed item. Default values: For external users, the default value is AllUsers. External users must use this value to see their posts. For internal users, the default value is InternalUsers. Internal users can accept this value or use the value AllUsers to allow external users to see their posts. If the parent of the feed item is a User or a Group, the visibility of the feed item must be AllUsers.	Optional	26.0

Parameters for attaching a new file

Parameter Name	Type	Description	Required or Optional	Available Version
attachmentType	String	The attachment type. Must contain the value NewFile.	Required	27.0
desc	String	Description of file being posted. This parameter should not be used as of version 27.0. Use description instead. Attention	Optional	23.0–26.0
description	String	Description of file being posted.	Optional	27.0
fileName	String	File name of the file being posted. This parameter should not be used as of version 24.0. Use title instead. Attention	Required	23.0–24.0
isBookmarked​​ByCurrentUser	Boolean	Specifies if the new feed item should be bookmarked for the user (true) or not (false). Default value is false.	Optional	26.0
text	String	Text of the feed item.	Optional	23.0
title	String	File name of a file to be uploaded and posted.	Required	24.0
visibility	String	Who can see the post. Valid values are: InternalUsers—If Communities is enabled, only members of the default, internal community can see the feed item. AllUsers—If Communities is enabled, all members of the community can see the feed item. Default values: For external users, the default value is AllUsers. External users must use this value to see their posts. For internal users, the default value is InternalUsers. Internal users can accept this value or use the value AllUsers to allow external users to see their posts. If the parent of the feed item is a User or a Group, the visibility of the feed item must be AllUsers.	Optional	26.0

Parameters for posting a link

Parameter Name	Type	Description	Required or Optional	Available Version
attachmentType	String	The attachment type. Must contain the value Link.	Required	27.0
isBookmarked​​ByCurrentUser	Boolean	Specifies if the new feed item should be bookmarked for the user (true) or not (false). Default value is false.	Optional	26.0
text	String	Text of the feed item.	Optional	23.0
url	String	URL of the link.	Required	23.0
urlName	String	Name of the URL.	Optional	23.0
visibility	String	Who can see the post. Valid values are: InternalUsers—If Communities is enabled, only members of the default, internal community can see the feed item. AllUsers—If Communities is enabled, all members of the community can see the feed item. Default values: For external users, the default value is AllUsers. External users must use this value to see their posts. For internal users, the default value is InternalUsers. Internal users can accept this value or use the value AllUsers to allow external users to see their posts. If the parent of the feed item is a User or a Group, the visibility of the feed item must be AllUsers.	Optional	26.0

Parameters for posting a poll

Parameter Name	Type	Description	Required or Optional	Available Version
attachmentType	String	The attachment type. Must contain the value Poll.	Required	27.0
isBookmarked​​ByCurrentUser	Boolean	Specifies if the new feed item should be bookmarked for the user (true) or not (false). Default value is false.	Optional	26.0
pollChoice1 through pollChoice10	String	The choices used to create a new feed item with a poll. You must specify 2–10 poll choices for each poll.	Required	26.0
text	String	Text of the feed item.	Required	23.0
visibility	String	Who can see the post. Valid values are: InternalUsers—If Communities is enabled, only members of the default, internal community can see the feed item. AllUsers—If Communities is enabled, all members of the community can see the feed item. Default values: For external users, the default value is AllUsers. External users must use this value to see their posts. For internal users, the default value is InternalUsers. Internal users can accept this value or use the value AllUsers to allow external users to see their posts. If the parent of the feed item is a User or a Group, the visibility of the feed item must be AllUsers.	Optional	26.0

Parameters for sharing a post

Parameter Name	Type	Description	Required or Optional	Available Version
isBookmarked​ByCurrentUser	Boolean	Specifies if the new feed item should be bookmarked for the user (true) or not (false). Default value is false.	Optional	26.0
originalFeedItemId	String	The ID of the feed item you want to share.18-character ID Sharing a post takes precedence over uploading a file. Do not share a post and upload a file in the same post. Note	Required	24.0
text	String	A comment on the shared feed item.	Optional	28.0
visibility	String	Who can see the post. Valid values are: InternalUsers—If Communities is enabled, only members of the default, internal community can see the feed item. AllUsers—If Communities is enabled, all members of the community can see the feed item. Default values: For external users, the default value is AllUsers. External users must use this value to see their posts. For internal users, the default value is InternalUsers. Internal users can accept this value or use the value AllUsers to allow external users to see their posts. If the parent of the feed item is a User or a Group, the visibility of the feed item must be AllUsers.	Optional	26.0

Parameters for posting text only

Parameter Name	Type	Description	Required or Optional	Available Version
isBookmarked​​ByCurrentUser	Boolean	Specifies if the new feed item should be bookmarked for the user (true) or not (false). Default value is false.	Optional	26.0
text	String	Text of the feed item. The maximum number of characters is 1000.	Required	23.0
visibility	String	Who can see the post. Valid values are: InternalUsers—If Communities is enabled, only members of the default, internal community can see the feed item. AllUsers—If Communities is enabled, all members of the community can see the feed item. Default values: For external users, the default value is AllUsers. External users must use this value to see their posts. For internal users, the default value is InternalUsers. Internal users can accept this value or use the value AllUsers to allow external users to see their posts. If the parent of the feed item is a User or a Group, the visibility of the feed item must be AllUsers.	Optional	26.0

Parameters for posting a canvas app

Parameter Name	Type	Description	Required or Optional	Available Version
attachmentType	String	The attachment type. Must contain the value Canvas.	Required	29.0
description	String	Description of the canvas app	Optional	29.0
developerName	String	The developer name (API name) of the canvas app	Required	29.0
height	String	The height of the canvas app in pixels. Default height is 200 pixels.	Optional	29.0
isBookmarked​​ByCurrentUser	Boolean	Specifies if the new feed item should be bookmarked for the user (true) or not (false). Default value is false.	Optional	29.0
namespacePrefix	String	The namespace prefix of the Developer Edition organization in which the canvas app was created.	Optional	29.0
parameters	String	Parameters passed to the canvas app in JSON format. The JSON must be URL-encoded: 1parameters={'isUpdated'='true';}"	Optional	29.0
text	String	Text of the feed item	Optional	29.0
thumbnailUrl	String	The URL to a thumbnail image for the canvas app. Maximum dimensions are 120x120 pixels.	Optional	29.0
title	String	The title of the link to the canvas app	Optional	29.0
visibility	String	Who can see the post. Valid values are: InternalUsers—If Communities is enabled, only members of the default, internal community can see the feed item. AllUsers—If Communities is enabled, all members of the community can see the feed item. Default values: For external users, the default value is AllUsers. External users must use this value to see their posts. For internal users, the default value is InternalUsers. Internal users can accept this value or use the value AllUsers to allow external users to see their posts. If the parent of the feed item is a User or a Group, the visibility of the feed item must be AllUsers.	Optional	29.0

Response body for GET or HEAD

Feed Item Page

Response body for POST

Feed Item

Example of file post

This example updates a news feed with a post that has a new file attachment.

1curl https://instance_name/services/data/v30.0/chatter/feeds/news/me/feed-items 
2     --form "feedItemFileUpload=@Desktop/textFile.txt" 
3     --form "title=Sample" 
4     --form "description=Just a Text File" 
5     --form "text=Please review" 
6     --form "attachmentType=NewFile" 
7     --header 'Authorization: Bearer 00DD0000000Jhd2!AQIAQBgn42jbvCW2SX8JaRO2_JjX1fNKXWBrjYQPXODtDyaT6gT4DJVs4Ki7s6GoxvO8a.Z7gTHKkfqjW6S1.ujlD413PYpF'

This is an example in Java of updating a news feed with a file post.

1swfobject.registerObject("clippy.codeblock-10", "9");import java.io.File;
2
3import org.apache.commons.httpclient.*;
4import org.apache.commons.httpclient.methods.PostMethod;
5import org.apache.commons.httpclient.methods.multipart.*;
6
7...
8
9String oauthToken = "00Dx0000000X42V!AQgAQClp6UqGWNJUf4d3LQkVCysBIS6a";
10String url = "https://instance_name/services/data/v30.0/chatter/" +
11              "feeds/user-profile/me/feed-items";
12String text = "I love posting files to Chatter!";
13File contentFile = getFile();
14String description = "This is a test file that I'm posting.";
15String title = "contentFile";
16Part[] parts = {
17        new StringPart("description", description),
18        new StringPart("title", fileName),
19        new StringPart("text", text),
20        new FilePart("feedItemFileUpload", contentFile),
21};
22
23final PostMethod postMethod = new PostMethod(url);
24                
25try {
26    postMethod.setRequestEntity(new MultipartRequestEntity(parts, 
27                                postMethod.getParams()));
28    postMethod.setRequestHeader("Authorization", "Bearer " + oauthToken);
29    postMethod.setRequestHeader("Content-type", "multipart/form-data")
30    postMethod.addRequestHeader("X-PrettyPrint", "1");
31    
32    HttpClient httpClient = new HttpClient();
33    httpClient.getParams().setSoTimeout(60000);
34    
35    int returnCode = httpClient.executeMethod(postMethod);
36    
37    System.out.println(postMethod.getResponseBodyAsString());
38    
39    assertTrue("Expected return code of: " + HttpStatus.SC_CREATED, 
40                returnCode == HttpStatus.SC_CREATED);
41} finally {
42    postMethod.releaseConnection();
43}
44

Example of a link post

This request creates a link post using the request parameters:

1/chatter/feeds/news/me/feed-items?text=Did+you+see+this?&url=http://www.chatter.com

This is the request body for creating a link in a feed-item post:

1{ "body" : { 
2     "messageSegments" : [ 
3        { 
4           "type": "Link", 
5           "url" : "http://www.chatter.com" 
6        },
7        { 
8           "type": "Text", 
9           "text" : "Is everyone following this?" 
10        }
11      ]
12  }
13}

This is the request body for including a link as an attachment to a feed-item post:

1{ "body" : { 
2      "messageSegments" : [ 
3         { 
4            "type": "Text", 
5            "text" : "Is everyone following this?" 
6         }
7      ]
8   },
9  "attachment" :{ 
10     "url" : "http://www.chatter.com",
11     "urlName" : "The Future of Social Enterprise"
12  }
13}

This resource is deprecated as of version 26.0.

Returns a flat feed, that is, a feed where there is no hierarchy between feed items and comments: Feed items and comments are at the same level. All items are returned in chronological order.

Resource

1/chatter/feeds/news/me/feed-items/flat

or

1/chatter/feeds/news/userId/feed-items/flat

userId must be the ID of the logged-in user or the alias me.

Note

Available since version

25.0

HTTP methods

GET or HEAD

Request parameters

Parameter Name	Type	Description
numFeedItems	Integer	Specifies the number of feed items returned. Valid values are between 0 and 100. Default value is 25. Because feed items may include comments, specifying 25 flat feed items may actually return more. For example, if each feed item has one comment, and recentCommentCount is greater than 1, 50 flat feed items are returned.
page	String	A generated token that indicates the view of feed items in the feed. Page tokens are returned as part of the response body, in one of the URL parameters, such as nextPageURL.
recentComment​Count	Integer	Specifies the number of recent comments returned. Valid values are between 0 and 25. Default value is 3.
sort	String. One of the following: CreatedDateDesc LastModifiedDateDesc	Sorts the returned feed either by created date in ascending order, or by last modified date, also in ascending order. The default is LastModifiedDateDesc

Response body

Flat Feed