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

Chatter REST API: How do I. . .

While using the Chatter REST API, keep this in mind:

  • Request parameters may be included as part of the Chatter REST API resource URL, for example, /chatter/users?q=searchtext. A request body is a rich input which may be included as part of the request. When accessing a resource, you can use either a request body or request parameters. You cannot use both.
  • With a request body, use Content-Type: application/json or Content-Type: application/xml.
  • With request parameters, use Content-Type: application/x-www-form-urlencoded.

For more information on request bodies, see Using POST, PATCH, or PUT for Input.

For examples of how to upload a binary file, see Uploading Binary Files.

Filter a response body
Resource: All
HTTP method: GET
Request body: NA
Request parameter: exclude, include, and filterGroup

Use the exclude and include query parameters to filter a response body when making a request. The query value is a bar (|) delimited list of properties. URL encode the bar as %7C. Use a forward slash (/) before each property name.

Use the filterGroup query parameter to specify whether to return a Big, Medium, or Small response body. Every property in every response body is assigned one of these group sizes.
Request body example: This News Feed URL resource:
1/chatter/users/me?include=/aboutMe%7C/address
Returns this for the Feed response body:
1{
2   "aboutMe": "Salesforce Administrator and Citizen Developer",
3   "address": {
4      "city": "San Francisco",
5      "country": "US",
6      "formattedAddress": "1 Market St\nSan Francisco, CA 94105\nUS",
7      "state": "CA",
8      "street": "1 Market St",
9      "zip": "94105"
10   }
11}

For a detailed list of rules and examples, see Specifying Response Sizes.
Returns: A filtered response body
Make a request in a specific community
Resource: A resource supports Communities unless the documentation states that it doesn’t.
HTTP method: Various
Example: To make a request to a specific community, prefix the resource with /connect/communities/communityId. For example, this resource gets the feed items from a news feed in a specific community:

/connect/communities/communityId​/chatter/feeds/news/me/feed-items

For more information, see Building the Chatter REST API Resource URL and Connecting to Salesforce Communities.
Returns: Various
Post feed item
Resource: Use one of the feed resources, such as /chatter/feeds/news/userId/feed-items.
HTTP method: POST
Request body: Feed Item Input
Request parameter: text
Request body example: 
1{ "body" : 
2   { 
3      "messageSegments" : [ 
4         { 
5           "type": "Text", 
6           "text" : "New post" 
7         }
8      ]
9    }
10}
Request parameter example: 
1/services/data/v30.0/chatter/feeds/news
2/me/feed-items?text=New+post
Returns: Feed Item
Add comments
Resource: /chatter/feed-items/feedItemId/comments
HTTP method: POST
Request body: Comment Input
Request parameter: text
Request body example: 
1{ "body" : 
2   { 
3      "messageSegments" : [ 
4         { 
5           "type": "Text", 
6           "text" : "New comment" 
7         }
8      ]
9    }
10}
Request parameter example: 
1/services/data/v30.0/chatter/feed-items/
20D5D0000000DaSbKAK/comments?text=New+comment
Returns: Comment
Post @mentions
Resource: To post a feed-item with an @mention, use one of the feed resources, such as /chatter/feeds/user-profile/userId/feed-items. To post a comment, use the Feed-Items resource: /chatter/feed-items/feedItemId/comments
HTTP method: POST
Request body: The appropriate container input, such as comment input or feed-item input, with the message segment input: mention
Request body example: 
1{ "body" : 
2   { 
3      "messageSegments" : [ 
4         { 
5           "type": "mention", 
6           "id" : "005D0000001GpHp" 
7         },
8         { 
9           "type": "text", 
10           "text" : " Did you see the new plans?" 
11         }
12      ]
13    }
14}

No spaces are added either before or after the @mention, so the text message segment includes a space.

Note
Returns Feed Item
Post multiple @mentions
Resource: To post a feed item with up to 25 mentions, use the News Feed resource, the Record Feed resource, or the User Profile Feed resource. To post a comment with up to 25 mentions, use the Feed Items Comment resource.
HTTP method: POST
Request body: Feed Item Input or Comment Input, with up to 25 Message Segment Input: Mention bodies.
Request body example: 
1{ "body" : 
2   {
3      "messageSegments" : [ 
4         {
5            "type": "mention",
6            "id":"005D0000001LL8YIAW"
7          },
8          {
9            "type": "mention",
10            "id":"005D0000001LL8sIAG"
11          },
12          {
13             "type": "text",
14             "text":" Did you see the new plans?"} ]
15           }
16      ]
17   }
18}

No spaces are added either before or after the mention, so the text message segment includes a space.

Note
Returns Feed Item or Comment
Get a list of @mention proposals
Resource: Use the Mentions Completions resource to get a list of mention proposals: /chatter/mentions/completions. Use the Mentions Validations resource to determine which of those proposals are valid for the context user: /chatter/mentions/validations.
HTTP method: GET
Request parameters: contextId, page, pageSize, q, type
Returns: Mention Completion Page

Mention Validations
Like feed items
Resource: /chatter/feed-items/feedItemId/likes
HTTP method: POST
Request body: NA
Request parameter: NA
Example: 
1/services/data/v30.0/chatter/feed-items/0D5D0000000DaZBKA0
2/likes
Returns: Like
Like a feed item and return the total number of likes
Resource: /connect/batch/
HTTP method: POST
Request parameter: NA
Request body: Batch Input
Request body example: 
1{
2   "batchRequests" : [
3    {
4       "method" : "Post",
5       "url" : "/v30.0/chatter/feed-items/feedItemId/likes"
6    },
7    {
8       "method" : "Get",
9       "url" : "/v30.0/chatter/feed-items/feedItemId"
10    }
11   ],
12   "haltOnError" : "false"
13}
Returns: Batch Results
Share a feed item
Resource: Use one of the feed resources, such as /chatter/feeds/user-profile/userId/feed-items.
HTTP method: POST
Request body: originalFeedItemId
Request parameter: originalFeedItemId
Request body example: 
1{
2
3   "originalFeedItemId": "0D5D0000000DaZBKA0"
4}
Returns: Feed Item
Get feed items updated since the last request

To keep a response size small, you may want to get only feed items that have been updated.

Resource: To get feed items that were updated since the last call to a feeds resource, make a request to the value of the updatesUrl property of the Feed Item Page response body.
These feeds return an updatesUrl property:
  • Company—/chatter/feeds/company/feed-items
  • Files—/chatter/feeds/files/me/feed-items
  • Filter—/chatter/feeds/filter/me/filterId/feed-items
  • Groups—/chatter/feeds/groups/me/feed-items
  • News—/chatter/feeds/news/me/feed-items
  • People—/chatter/feeds/people/me/feed-items
  • Record—/chatter/feeds/record/recordId/feed-items
This excerpt from the Feed Item Page response body shows a sample value for the updatesUrl property:
1{
2...
3..."updatesUrl" : "/services/data/v30.0/chatter/feeds
4   /news/005D0000001LL8OIAW/feed-items?updatedSince=2:1384811809000"
5...
6}

A feed item is considered to be updated if it was created since the last feed request, or if sort=LastModifiedDateDesc and a comment was added to the feed item since the last feed request. Adding likes and topics doesn’t update a feed item.
HTTP method: GET
Request body: NA
Request parameter: NA
Request body example: NA
Returns: Feed Item Page
Poll my news feed for updates
Resource:
  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 polling the news feed for updates more than once a minute.

Note
HTTP method: GET
Request body: NA
Request parameter: NA
Request body example: This News Feed URL resource:
1/chatter/feeds/news/005xx000001Sv1mAAB
Returns this for the Feed 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}
The Is-Modified resource for polling this news feed is: 
1/chatter/feeds/news/005xx000001Sv1mAAB/is-modified?since=2%3A1344352279000
Returns: Feed Modified Info
Get news feeds
This example gets the news feed of the current user.
Resource: /chatter/feeds/news/me/feed-items
HTTP method: GET
Request body: NA
Request parameter: NA
Example: 
1/services/data/v30.0/chatter/feeds/news/me/feed-items
Returns: Feed Item Page
Get a group feed
This example gets the feed of a group. Substitute recordId with the group ID.
Resource: /chatter/feeds/record/recordId/feed-items
HTTP method: GET
Request body: NA
Request parameter: NA
Example: 
1/services/data/v30.0/chatter/feeds/record/0F9D00000000I4O/feed-items
Returns: Feed Item Page
Get a record feed with internal feed items only
Resource: /chatter/feeds/record/recordId/feed-items
HTTP method: GET
Request body: NA
Request parameter: showInternalOnly
Example: 
1/services/data/v30.0/chatter/feeds/record/0F9D00000000I4O/feed-items?showInternalOnly=true
Returns: Feed Item Page
Search a feed
This example searches the record feed of the current user. Use the same q parameter to search any feed except the Topics feed. The search string can contain wildcards and must contain at least two characters that aren’t wildcards.
Resource: /chatter/feeds/record/me/feed-items
HTTP method: GET
Request body: NA
Request parameter: q
Example: 
1/services/data/v30.0/chatter/feeds
2/record/me/feed-items?q=track
Returns: Feed Item Page
Get list of what a user is following
Resource: /chatter/users/userId/following
HTTP method: GET
Request body: NA
Request parameter: page (optional)
Request parameter example: 
1/services/data/v30.0/chatter/users
2/005D0000001GLowIAB/following?page=1
Returns: Subscription Page
Get Chatter activity statistics for a user
Resource: /chatter/users/userId
HTTP method: GET
Request body: NA
Request parameter: NA
Example: 
1/services/data/v30.0/chatter/users
2/005D0000001GLowIAB?include=/chatterActivity
Returns: User Detail
Get recommendations of users to follow
Resource: /chatter/users/me/recommendations/follow/users
HTTP method: GET
Request body: NA
Request parameter: NA
Example: 
1/services/data/v30.0/chatter/users
2/me/recommendations/follow/users
Returns: Recommendation
Create a group
Resource: /chatter/groups
HTTP method: POST
Request body: Group Input
Request parameters (required): name, visibility
Request body example: 
1{   
2   "name" : "Chatter API",
3   "visibility" : "PublicAccess"
4}
Request parameter example: 
1/services/data/v30.0/chatter/groups?name=Chatter+API&visibility=PublicAccess
Returns: Group Detail
Update and crop a group photo
This example crops an existing photo (a photo that has already been uploaded). You can also upload and crop a photo. To upload a new photo you must use a multipart/form-data request. See Uploading Binary Files.
Resource: /chatter/group/groupId/photo
HTTP method: POST
Request parameters: cropSize, cropX, cropY, fileId
Request parameters example: 
1/services/data/v30.0/chatter/groups
2/0F9300000008ORJ/photo?cropSize=240&cropX=20&cropY=20&fileId=069D00000001IOh
Request body example: 
1{   "cropSize" : "240",
2    "cropX" : "20",
3    "cropY" : "20",
4    "fileId" : "069D00000001IOh"
5}
Returns: Photo
Join a group
Resource: /chatter/groups/groupId/members
HTTP method: POST
Request body: Group Member Input
Request parameter: userId
Request body example: {"userId": "005D0000001GpHp" }
Request parameter example: 
1/services/data/v30.0/chatter/groups/0F9D000000006bOKAQ
2/members?userId=005D0000001GpHp
Returns: Group Member
Request to join a private group
Resource: /chatter/groups/groupId/members/requests
HTTP method: POST
Request body: NA
Request parameter: NA
Request body example: NA
Request parameter example: 
1/services/data/v30.0/chatter/groups/0F9D000000006bOKAQ
2/members/requests
Returns: Group Membership Request
Approve or reject a request to join a private group
Resource: /chatter/group-memberships-requests/requestId
HTTP method: PATCH
Request body: Group Membership Request Update
Request parameters: status and responseMessage

The responseMessage parameter is used only if the value of status is Declined.
Request body example: 
1{ "status " : "Accepted" }
Request parameter example: 
1/services/data/v30.0/chatter/group-membership-requests
2/0I5D000000002fwKAA?status=Accepted
Returns: Group Membership Request
Post to a group
Resource: /chatter/feeds/record/groupId/feed-items
HTTP method: POST
Request body: Feed Item Input
Request parameter: Text
Request body example: 
1{ "body" : 
2   { 
3      "messageSegments" : [ 
4         { 
5           "type": "Text", 
6           "text" : "Check out the latest building proposal" 
7         }
8      ]
9    }
10}
Request parameter example: 
1/feeds/record/0F9D000000006bO/feed-items?
2text=Has+everyone+seen+the+latest+building+proposal?
Returns: Feed Item
Follow a record
The subjectId is the ID of the item you want to follow. In versions 29.0 and above, the subjectId can be a topic ID.
Resource: /chatter/users/me/following
HTTP method: POST
Request body: Following Input
Request parameter: subjectId
Request body example: { "subjectId" : "001D000000Iyu2p" }
Request parameter example: 
1/services/data/v30.0/chatter/users/me
2/following?subjectId=001D000000Iyu2p
Returns: Subscription
Unfollow records
Note that a complete structured resource is not returned, just a return code.
Resource: /chatter/subscriptions/subscriptionId
HTTP method: DELETE
Request body: NA
Request parameter: NA
Example: 
1/services/data/v30.0/chatter/subscriptions/0E8D00000001JkFKAU
Returns: 204: Successful Delete
Get feed items for a record
Resource: /chatter/feeds/record/recordId/feed-items
HTTP method: GET
Request body: NA
Request parameter: page (optional)

Page tokens are returned as part of the response body, in one of the URL parameters, such as nextPageURL.

Note
Request parameter example: 
1/services/data/v30.0/chatter/feeds/record
2/005x0000001oXx9AAE/feed-items?page=2011-03-31T20:57:24Z,0D5x0000001C2XPCA0
Returns: Feed Item Page
Update a user profile
Resource: /chatter/users/userId
HTTP method: PATCH
Request parameter: aboutMe
Request parameters example: 
1/services/data/v30.0/chatter/users
2/me?aboutMe=Writer+at+Salesforce
Returns: User Detail
Update and crop a user photo
This example crops an existing photo (a photo that has already been uploaded). You can also upload and crop a photo. To upload a new photo you must use a multipart/form-data request. See Uploading Binary Files.

To use this example to update and crop a group photo, substitute /chatter/groups/groupId/photo.

Resource: /chatter/users/userId/photo
HTTP method: POST
Request parameters: cropSize, cropX, cropY, fileId
Request parameters example: 
1/services/data/v30.0/chatter/users
2/me/photo?cropSize=240&cropX=20&cropY=20&fileId=069D00000001IOh
Request body example: 
1{   "cropSize" : "240",
2    "cropX" : "20",
3    "cropY" : "20",
4    "fileId" : "069D00000001IOh"
5}
Returns: Photo
Send a private message
Resource: /chatter/users/me/messages/
HTTP method: POST
Request body: User Message
Request parameter: recipients OR inReplyTo

text
Request body example: 
1{ "body" : "Are we ready for next week's customer meeting?",
2  "recipients" : ["005D0000001GOYpIAO", "005D0000001GbdHIAS"]
3}
Request parameters example: 
1/services/data/v30.0/chatter/users
2/me/messages?recipients=005D0000001GOYpIAO,
3005D0000001GbdHIAS&text=Are+we+ready+for+next+week's+customer+meeting?
Returns: Message
Return all user information for multiple users
Resource: /chatter/users/batch/user_list where user_list is a list of user Ids. Your app may need to call Chatter REST API twice: once to get the feed items and user Ids, the second time to call this resource with the list of user Ids.
HTTP method: GET
Request parameter: NA
Request parameters example: 
1/services/data/v30.0/chatter/users
2/batch/005D0000001Kl6xIAC,005D0000005J3D4HVB, . . .
Returns: Batch Results