Chatter REST API Developer's Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

This content describes an older version of this product. View Latest

News Feed Resources

A feed containing feed elements of interest to the context user. You can post feed items to the news feed.

The composition of this feed may change between releases in order to match the feed displayed in the Chatter Web UI.

Note

Available resources are:

Resource Description
/chatter/feeds/news/me Returns a URL to the feed elements for all feeds for the context user. Also returns an Is-Modified resource for polling the feed for updates.
/chatter/feeds/news/me/is-modified Returns information about whether the news feed has been updated or changed since the specified time and date.
/chatter/feeds/news/me/feed-elements All feed elements from all groups the context user either owns or is a member of, as well as all files, records, and users the context user follows. Use this resource to get information about feed elements and to post feed elements.

News Feed URL

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

Resource

userId must be the ID of the context user or the alias me.

Note

Available since version
23.0
Requires Chatter
Yes
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 by most recent creation date.
  • LastModifiedDateDesc—Sorts by most recent activity.
The default value is CreatedDescDate.
Response body
Feed
Example response body

News Feed Is-Modified

Returns information about whether the news feed has been updated or changed since the specified time and date.

Though the Is-Modified resource is generally available, your organization may not have permission to use it automatically. If you can’t access this resource, contact your Salesforce representative and ask about the “Enabled Chatter Feed Polling” permission.

Note

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.

If you are working with remote organizations as an ISV, use the Organization resource and the feedPolling property of the Feature response body to shape your polling strategy. If feedPolling is not enabled, be conservative in how often you poll for new content.

Note

Use the Is-Modified resource to poll the news feed
  1. Use either of the following resources to get the latest elements from a news feed or to get information about the feed: /chatter/feeds/news/me/feed-elements, /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 Elements 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

userId must be the ID of the context user or the alias me.

Note

Available since version
26.0
Requires Chatter
Yes
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

News Feed Elements

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

For information about posting a feed element, see Feed Elements, Post and Search.

For information about uploading and attaching a binary file to a feed element, 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.

Resource

userId must be the ID of the context user or the alias me.

Note

Available since version
31.0
Requires Chatter
Yes
HTTP methods
GET, 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 updates from people and records the user follows and groups the user is a member of.
  • FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but hides some system-generated updates from records.

The default value is AllUpdates.

 Optional 31.0
elementsPerBundle Integer Maximum number of feed elements to include in a bundle. The value must be an integer between 0 and 10. The default value is 3.

Bundled posts contain feed-tracked changes. In Salesforce1 downloadable apps, bundled posts are in record feeds only.

Note

 Optional 31.0
filter String Specifies the filter values that can be applied to a feed.
  • AllQuestions—Only feed elements that are questions.
  • SolvedQuestions—Only feed elements that are questions and that have a best answer.
  • UnansweredQuestions—Only feed elements that are questions and that don’t have any answers.
  • UnsolvedQuestions—Only feed elements that are questions and that don’t have a best answer.
 Optional 32.0
page String A generated token that indicates the view of feed elements in the feed.
Page tokens are returned as part of the response body, in one of the URL parameters, such as nextPageURL, for example:
Optional 31.0
pageSize Integer Specifies the number of elements per page. Valid values are between 1 and 100. If you don't specify a size, the default is 25. Optional 31.0
q String One or more keywords to search for in the body and comments of feed elements in this feed.

The search string can contain wildcards and must contain at least two characters that aren’t wildcards. See Wildcards.

 Optional 31.0
recentComment​Count Integer Maximum number of comments to include per feed element. The default value is 3. The maximum value is 25. Optional 31.0
sort String Specifies the order returned by the sort, such as by date created or last modified:
  • CreatedDateDesc—Sorts by most recent creation date.
  • LastModifiedDateDesc—Sorts by most recent activity.
The default value is CreatedDescDate.		 Optional 31.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 Element Page response body.

 Optional 31.0
Response body for GET
Feed Element Page

News Feed Items

All feed items from all groups the context user either owns or is a member of, as well as all files, records, and users the context user follows. Use this resource to get information about the feed items and to post feed items, including attaching files, posting links, polls, and questions, and sharing posts.

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

userId must be the ID of the context user or the alias me.

Note

Available versions
23.0–31.0

In version 32.0 and later, use News Feed Elements.

Important

Requires Chatter
Yes
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 updates from people and records the user follows and groups the user is a member of.
  • FewerUpdates—Displays all updates from people and records the user follows and groups the user is a member of, but hides some system-generated updates from records.

The default value is AllUpdates.

 Optional 29.0–31.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:
Optional 23.0–31.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–31.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–31.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–31.0
sort String Specifies the order returned by the sort, such as by date created or last modified:
  • CreatedDateDesc—Sorts by most recent creation date.
  • LastModifiedDateDesc—Sorts by most recent activity.
The default value is CreatedDescDate.		 Optional 23.0–31.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–31.0
Request body for POST
Root XML tag
<feedItem>
JSON
The following example attaches a poll to a feed item:
Feed items support more than one capability. The following example attaches a file to a feed item and bookmarks it.
Properties
Name Type Description Required or Optional Available Version
attachment Depends on type. You can specify only one of these values in the attachment parameter. Values are:

As of API version 32.0, use the capabilities property.

Important

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

 Required unless the feed item has a content capability or a link capability 23.0
capabilities Feed Element Capabilities Input The capabilities that define the behavior of this feed element. Optional 31.0
isBookmarked​ByCurrentUser Boolean Specifies if the new feed item should be bookmarked for the user (true) or not (false). Default value is false.

As of API version 32.0, use the capabilities.bookmarks.​isBookmarkedByCurrentUser property.

Important

 Optional 24.0–31.0
feedElementType String The type of feed element this input represents.

The only valid value is FeedItem.

 Required 31.0
originalFeedElementId String If this feed element is shared, this is the original feed element 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

 Optional 31.0
originalFeedItemId String If this feed item is shared, this is the original feed item 18-character ID.

As of API version 32.0, use the originalFeedElementId property.

Important

 Optional 24.0–31.0
subjectId String The ID of the parent this feed element is being posted to. This value can be the ID of a user, group, or record, or the string me to indicate the context user. Required 31.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
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–31.0
contentDocumentId String 18-character ID of an existing file. Required 23.0–31.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–31.0
text String Text of the feed item. Optional 23.0–31.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–31.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–31.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–31.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–31.0
text String Text of the feed item. Optional 23.0–31.0
title String File name of a file to be uploaded and posted. Required 24.0–31.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–31.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–31.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–31.0
text String Text of the feed item. Optional 23.0–31.0
url String URL of the link. Required 23.0–31.0
urlName String Name of the URL. Optional 23.0–31.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–31.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–31.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–31.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–31.0
text String Text of the feed item. Required 23.0–31.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–31.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–31.0
originalFeedItemId String The 18-character ID of the feed item you want to share.

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–31.0
text String A comment on the shared feed item. Optional 28.0–31.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–31.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–31.0
text String Text of the feed item. The maximum number of characters is 1000. Required 23.0–31.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–31.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–31.0
description String Description of the canvas app Optional 29.0–31.0
developerName String The developer name (API name) of the canvas app Required 29.0–31.0
height String The height of the canvas app in pixels. Default height is 200 pixels. Optional 29.0–31.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–31.0
namespacePrefix String The namespace prefix of the Developer Edition organization in which the canvas app was created. Optional 29.0–31.0
parameters String Parameters passed to the canvas app in JSON format. The JSON must be URL-encoded:
 Optional 29.0–31.0
text String Text of the feed item Optional 29.0–31.0
thumbnailUrl String The URL to a thumbnail image for the canvas app. Maximum dimensions are 120x120 pixels. Optional 29.0–31.0
title String The title of the link to the canvas app Optional 29.0–31.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–31.0
Response body for GET
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.
This is an example in Java of updating a news feed with a file post.
Example of a link post
This request creates a link post using the request parameters:
This is the request body for creating a link in a feed-item post:
This is the request body for including a link as an attachment to a feed-item post:

News Feed Items Flat

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
or

userId must be the ID of the context user or the alias me.

Note

Available since version
25.0–26.0

As of API version 32.0, use /chatter/feeds/news/userId/feed-elements.

Important

Requires Chatter
Yes
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