Post on 11-Feb-2022
Version 30.0: Spring ’14
Database.com Chatter REST APIDeveloper's Guide
Last updated: June 2, 2014
© Copyright 2000–2014 salesforce.com, inc. All rights reserved. Salesforce.com is a registered trademark of salesforce.com, inc., as are othernames and marks. Other marks appearing herein may be trademarks of their respective owners.
Table of Contents
Chapter 1: Introducing Chatter REST API...........................................................................................1Deciding When to Use Chatter REST API.............................................................................................................................2Chatter REST API Architecture..............................................................................................................................................3Building the Chatter REST API Resource URL......................................................................................................................4Sending HTTP Requests..........................................................................................................................................................5Understanding a Chatter REST API Request and Response...................................................................................................5Using Chatter REST API Inputs.............................................................................................................................................9Working with Feeds and Feed Items......................................................................................................................................12Working with Salesforce Files.................................................................................................................................................17Wildcards................................................................................................................................................................................19Specifying Response Sizes.......................................................................................................................................................19
filterGroup...................................................................................................................................................................20exclude.........................................................................................................................................................................21include.........................................................................................................................................................................23
Response Body Encoding........................................................................................................................................................25Status Codes and Error Responses..........................................................................................................................................25Understanding OAuth and Chatter REST API.....................................................................................................................26
Understanding the Web Server OAuth Authentication Flow.....................................................................................28Understanding the User-Agent OAuth Authentication Flow.....................................................................................32Using Tokens...............................................................................................................................................................34Requesting Static Assets and Posting Forms Directly from HTML...........................................................................35
Chapter 2: Quick Start........................................................................................................................37Prerequisites............................................................................................................................................................................38Step One: Obtain a Database.com Developer Edition Organization......................................................................................38Step Two: Set Up Authorization.............................................................................................................................................38Step Three: Connect to Chatter REST API Using OAuth....................................................................................................39
Chapter 3: Chatter REST API: How do I. . .........................................................................................41
Chapter 4: Chatter REST API Resources............................................................................................55Batch Resource........................................................................................................................................................................56Chatter Resource.....................................................................................................................................................................62Comments Resources..............................................................................................................................................................63Communities Moderation Resources......................................................................................................................................65Connect Resources..................................................................................................................................................................72Feeds Resources.......................................................................................................................................................................73
Bookmarks Feed Resources.........................................................................................................................................74Communities Moderation Feed Resource...................................................................................................................78Company Feed Resources............................................................................................................................................82Favorites Feed Resources.............................................................................................................................................85Feeds Resource............................................................................................................................................................93Files Feed Resources....................................................................................................................................................95
i
Table of Contents
Filter Feed Resources..................................................................................................................................................99Groups Feed Resources.............................................................................................................................................109News Feed Resources................................................................................................................................................113People Feed Resources..............................................................................................................................................128Record Feed Resource...............................................................................................................................................132To Feed Resources....................................................................................................................................................146Topics Feed Resources..............................................................................................................................................150User Profile Feed Resources......................................................................................................................................152
Feed Items Resources............................................................................................................................................................164Feed-Items Batch......................................................................................................................................................164Feed-Items Query......................................................................................................................................................165Feed-Items, Specific Feed Item.................................................................................................................................166Feed Items Comments..............................................................................................................................................167Feed-Items Likes.......................................................................................................................................................169Feed-Items Polls........................................................................................................................................................170Feed-Items Topics.....................................................................................................................................................171
Files Resources......................................................................................................................................................................173Folders Resources..................................................................................................................................................................179Groups Resources..................................................................................................................................................................182
List of Groups...........................................................................................................................................................183Group Information....................................................................................................................................................188Batch Group Information..........................................................................................................................................192Group Files................................................................................................................................................................192Group Members........................................................................................................................................................193Group Members—Private.........................................................................................................................................195Group Membership Requests—Private.....................................................................................................................198Group Memberships Resources.................................................................................................................................199Group Photo..............................................................................................................................................................202Group Settings..........................................................................................................................................................205Group Topics............................................................................................................................................................206
Influence Resource................................................................................................................................................................206Likes Resource.......................................................................................................................................................................207Mentions Resources..............................................................................................................................................................208
Mentions Completions..............................................................................................................................................208Mentions Validations................................................................................................................................................210
Motifs Resources...................................................................................................................................................................211Record View Resources.........................................................................................................................................................213
Record View Information..........................................................................................................................................213Record View Search...................................................................................................................................................214
Records Resources.................................................................................................................................................................220Topics on Records Resource......................................................................................................................................222
Subscriptions Resource..........................................................................................................................................................223Topics Resources...................................................................................................................................................................224
List of Topics............................................................................................................................................................224
ii
Table of Contents
Topics Suggestions....................................................................................................................................................226Trending Topics........................................................................................................................................................228Topic.........................................................................................................................................................................229Topics, Endorse People.............................................................................................................................................231Topic Endorsements..................................................................................................................................................232Topic Files.................................................................................................................................................................233Topic Groups............................................................................................................................................................234Topics, Knowledgeable People List...........................................................................................................................236Related Topics...........................................................................................................................................................237Topics, Opt Outs from Knowledgeable People List..................................................................................................237Topics, Opt Out from Knowledgeable People List...................................................................................................238
User Profiles Resource...........................................................................................................................................................238Users Resources.....................................................................................................................................................................239
User Information.......................................................................................................................................................240User Profile Information...........................................................................................................................................241Batch User Information.............................................................................................................................................244User Conversations, General.....................................................................................................................................244User Conversations, Specific.....................................................................................................................................245Change Status of Conversations................................................................................................................................247Get Unread Count for Conversations........................................................................................................................248Users Files, General...................................................................................................................................................248User Files, Filtered by Group....................................................................................................................................250User Files, Filtered by Sharing..................................................................................................................................251User Followers...........................................................................................................................................................252Following...................................................................................................................................................................253User Groups..............................................................................................................................................................255Topics a User is Knowledgeable About.....................................................................................................................256User Messages, General.............................................................................................................................................256User Messages, Specific.............................................................................................................................................262User Photo.................................................................................................................................................................263User Recommendations, General..............................................................................................................................265User Recommendations for a Specific Action...........................................................................................................266User Recommendations for a Specific Action and Object Category.........................................................................267User Recommendations for a Specific Action and Key Prefix...................................................................................268User Recommendations for a Specific Action and Object ID...................................................................................269User Records, Recently Used.....................................................................................................................................271User Settings..............................................................................................................................................................271User Status.................................................................................................................................................................273Topics Recently Used................................................................................................................................................274
Zones Resources....................................................................................................................................................................274List of Zones.............................................................................................................................................................274Zone Information......................................................................................................................................................275Zone Search Results..................................................................................................................................................275
Chapter 5: Chatter REST API Request Bodies..................................................................................277
iii
Table of Contents
Attachment Input: Canvas App............................................................................................................................................277Attachment Input: Existing Content....................................................................................................................................278Attachment Input: Feed Poll.................................................................................................................................................279Attachment Input: Link........................................................................................................................................................279Attachment Input: New File Upload....................................................................................................................................280Batch Input............................................................................................................................................................................281Batch Request Input..............................................................................................................................................................282Comment Input.....................................................................................................................................................................283Dashboard Component Snapshot Input...............................................................................................................................284Feed Favorite Input...............................................................................................................................................................285Feed Item Input....................................................................................................................................................................286Feed Item Topic Input..........................................................................................................................................................287Feed Poll Input......................................................................................................................................................................288File Input...............................................................................................................................................................................288File Shares Input...................................................................................................................................................................289Folder Input..........................................................................................................................................................................289Folder Item Input..................................................................................................................................................................290Following Input.....................................................................................................................................................................290Group Chatter Settings Input...............................................................................................................................................291Group Information Input......................................................................................................................................................291Group Input..........................................................................................................................................................................292Group Member Input............................................................................................................................................................293Group Membership Request Update....................................................................................................................................293Message Body Input..............................................................................................................................................................294Message Segment Input: Hash Tag......................................................................................................................................294Message Segment Input: Link...............................................................................................................................................295Message Segment Input: Mention........................................................................................................................................295Message Segment Input: Text...............................................................................................................................................295Moderation Flag Input..........................................................................................................................................................296Photo Input...........................................................................................................................................................................296Share Input............................................................................................................................................................................297Topic Assignment Input.......................................................................................................................................................297Topic Endorsement Input.....................................................................................................................................................298Topic Input...........................................................................................................................................................................298User Chatter Settings Input..................................................................................................................................................299User Input.............................................................................................................................................................................299User Message.........................................................................................................................................................................300User Message Recipient Input...............................................................................................................................................301User Message Recipient List Input.......................................................................................................................................301User Status Input...................................................................................................................................................................301User Stream (Conversation) Input........................................................................................................................................302
Chapter 6: Chatter REST API Response Bodies................................................................................303Address..................................................................................................................................................................................303Batch Results.........................................................................................................................................................................303
iv
Table of Contents
Batch Result Item..................................................................................................................................................................304Chatter Activity.....................................................................................................................................................................305Chatter Directory..................................................................................................................................................................305Chatter Influence..................................................................................................................................................................305ClientInfo..............................................................................................................................................................................306Comment..............................................................................................................................................................................306Comment Page......................................................................................................................................................................307Community...........................................................................................................................................................................307Community Page...................................................................................................................................................................308Connect Directory.................................................................................................................................................................309Conversation Detail...............................................................................................................................................................309Conversation Summary.........................................................................................................................................................309Conversation Summary Collection........................................................................................................................................310Conversation Unread Count.................................................................................................................................................310Email Address.......................................................................................................................................................................310Error Message.......................................................................................................................................................................310Error with Output.................................................................................................................................................................311Explanation Details...............................................................................................................................................................311Explanation Summary...........................................................................................................................................................312Favorite..................................................................................................................................................................................312Favorites Page........................................................................................................................................................................313Features.................................................................................................................................................................................313Feed.......................................................................................................................................................................................314Feed Body..............................................................................................................................................................................314Feed Directory.......................................................................................................................................................................315Feed Directory Item..............................................................................................................................................................315Feed Item..............................................................................................................................................................................317Feed Item Attachment: Basic Template................................................................................................................................321Feed Item Attachment: Canvas Template............................................................................................................................321Feed Item Attachment: Content...........................................................................................................................................322Feed Item Attachment: Link.................................................................................................................................................323Feed Item Attachment: Poll..................................................................................................................................................324Feed Item Attachment: Record Snapshot.............................................................................................................................324Feed Item Attachment: Tracked Change..............................................................................................................................324Feed Item Page......................................................................................................................................................................324Feed Item Preamble Message Body......................................................................................................................................325Feed Item Topics..................................................................................................................................................................326Feed Modified Info...............................................................................................................................................................326Feed Poll Choice...................................................................................................................................................................326Feed Tracked Change...........................................................................................................................................................327File Detail..............................................................................................................................................................................327File Share Link......................................................................................................................................................................327File Shares Page....................................................................................................................................................................328File Summary........................................................................................................................................................................328
v
Table of Contents
File Summary Page................................................................................................................................................................331Flat Feed................................................................................................................................................................................331Flat Feed Item.......................................................................................................................................................................331Folder....................................................................................................................................................................................332Folder Item............................................................................................................................................................................332Folder Item Page...................................................................................................................................................................333Follower Page........................................................................................................................................................................333Following Counts..................................................................................................................................................................333Following Page......................................................................................................................................................................334Group....................................................................................................................................................................................334Group Chatter Settings.........................................................................................................................................................336Group Detail.........................................................................................................................................................................336Group Information................................................................................................................................................................338Group Member.....................................................................................................................................................................338Group Member Page.............................................................................................................................................................339Group Membership Request.................................................................................................................................................339Group Membership Request Collection...............................................................................................................................340Group Page...........................................................................................................................................................................340Icon.......................................................................................................................................................................................340Influence Thresholds.............................................................................................................................................................340Knowledgeable People...........................................................................................................................................................341Knowledgeable People Collection.........................................................................................................................................341Like.......................................................................................................................................................................................342Like Message Body...............................................................................................................................................................342Like Page...............................................................................................................................................................................342List View Definition.............................................................................................................................................................343List View Column.................................................................................................................................................................343List View Object...................................................................................................................................................................344List View Record...................................................................................................................................................................344List View Sort.......................................................................................................................................................................345Mention Completion............................................................................................................................................................345Mention Completion Page....................................................................................................................................................346Mention Validation...............................................................................................................................................................347Mention Validations..............................................................................................................................................................347Message.................................................................................................................................................................................348Message Collection...............................................................................................................................................................348Message Segment: Entity Link.............................................................................................................................................349Message Segment: Field Change..........................................................................................................................................349Message Segment: Field Change Name................................................................................................................................350Message Segment: Field Change Value................................................................................................................................350Message Segment: Hashtag...................................................................................................................................................350Message Segment: Link........................................................................................................................................................351Message Segment: Mention..................................................................................................................................................351Message Segment: More Changes........................................................................................................................................352
vi
Table of Contents
Message Segment: Resource Link.........................................................................................................................................352Message Segment: Text.........................................................................................................................................................352Moderation Flags..................................................................................................................................................................353Motif.....................................................................................................................................................................................353Organization..........................................................................................................................................................................354Phone Number......................................................................................................................................................................355Photo.....................................................................................................................................................................................356Recommendation..................................................................................................................................................................356Record Field..........................................................................................................................................................................357Record Field: Blank...............................................................................................................................................................357Record Field: Compound......................................................................................................................................................357Record Field: Currency.........................................................................................................................................................358Record Field: Date................................................................................................................................................................359Record Field: Percent............................................................................................................................................................359Record Field: Picklist............................................................................................................................................................359Record Field: Reference........................................................................................................................................................360Record Field: Reference with Date.......................................................................................................................................360Record Search List View.......................................................................................................................................................361Record Search Results...........................................................................................................................................................361Record Summary...................................................................................................................................................................361Record Summary List............................................................................................................................................................362Record View..........................................................................................................................................................................362Record View Section.............................................................................................................................................................363Reference...............................................................................................................................................................................364Shares....................................................................................................................................................................................364Subscription...........................................................................................................................................................................365Subscription Page..................................................................................................................................................................365Time Zone............................................................................................................................................................................365Topic.....................................................................................................................................................................................366Topic Collection....................................................................................................................................................................366Topic Endorsement...............................................................................................................................................................366Topic Endorsement Collection.............................................................................................................................................367Topic Opt Out......................................................................................................................................................................367Topic Opt Out Collection.....................................................................................................................................................367Topics People Are Knowledgeable About.............................................................................................................................368Topics People Are Knowledgeable About Collection...........................................................................................................368Topic Suggestion...................................................................................................................................................................369Topic Suggestion Collection.................................................................................................................................................369User Capabilities...................................................................................................................................................................369User Chatter Settings............................................................................................................................................................370User Detail............................................................................................................................................................................370User Group Page...................................................................................................................................................................372User Page...............................................................................................................................................................................373User Profile............................................................................................................................................................................373
vii
Table of Contents
User Profile Tab....................................................................................................................................................................373User Settings.........................................................................................................................................................................374User Status.............................................................................................................................................................................375User Summary.......................................................................................................................................................................375Zone......................................................................................................................................................................................376Zone Page.............................................................................................................................................................................377Zone Search Page..................................................................................................................................................................377Zone Search Result...............................................................................................................................................................378
Index...............................................................................................................................................379
viii
Table of Contents
Chapter 1
Introducing Chatter REST API
Chatter REST API provides programmatic access to Chatter feeds and socialdata such as users, groups, followers, and files. Use Chatter REST API to
In this chapter ...
• Deciding When to Use ChatterREST API
integrate Chatter into a variety of applications such as mobile applications,intranet sites, and third-party Web applications. Chatter REST API is similarto APIs offered by other companies with feeds, such as Facebook and Twitter.• Chatter REST API Architecture
• Building the Chatter REST APIResource URL To use this documentation, you should have a basic familiarity with software
development, Web services, OAuth, and Chatter.• Sending HTTP RequestsThe following sections include:• Understanding a Chatter REST API
Request and Response• Quick Start on page 37
• Using Chatter REST API Inputs• Chatter REST API Architecture on page 3• Working with Feeds and Feed Items• Understanding a Chatter REST API Request and Response on page 5• Working with Salesforce Files• Understanding OAuth and Chatter REST API on page 26• Wildcards
• Specifying Response Sizes• Response Body Encoding• Status Codes and Error Responses• Understanding OAuth and Chatter
REST API
1
Deciding When to Use Chatter REST APIUse Chatter REST API to:
• Build a mobile client that displays a Chatter feed.
• Integrate a third-party Web application with Chatter so it can notify groups of users about events.
• Display the Chatter feed on an external system, such as an intranet site, after users are authenticated.
• Make feeds actionable and integrated with third-party sites. For example, an app that posts a Chatter item to Twitterwhenever the post includes #tweet hashtag.
• Create simple games that interact with the feed for notifications. Games might include things like sales incentivecompetitions.
• Creating a custom, branded skin for Chatter for your organization.
How is Chatter REST API Different from other APIs?Chatter REST API complements the SOAP API and the REST API by making it easy to interact with Chatter data, suchas feeds, group information, and Chatter user-profile details.
The following are some of the differences between Chatter REST API and the SOAP API and REST API:
• Returned information is automatically localized to the user's time zone and language.• Feed items are structured in a way that makes it easy to render on Web sites and mobile devices.• Changed values that are tracked in a feed are returned as value-pair representations.• Relationships between objects can easily be traversed without having to resolve foreign keys. For example, using Chatter
REST API you can get all of a user's followers or groups with one request per page.• Rate limiting for Chatter REST API is per user, per application, per hour. The rate limiting for SOAP API and REST
API is by organization. For more information, see Understanding a Chatter REST API Request and Response.
Selecting the Right API for Your ApplicationDatabase.com provides many types of APIs for various use cases, including both SOAP API and REST API. These APIsprovide access to the majority of Database.com data, including most of the Chatter data.
So when should you use which API?
Situations where you would want to use SOAP API or REST API include:
• Migrating or synchronizing user profiles and their associated user photos from one system to another.• Creating analytic applications for Chatter.• Queries where you want to select specifically which records or fields are returned.
SOAP API and REST API’s rate limiting and powerful query language more suited to these use cases and contains most ofthe applicable Chatter data.
However, Chatter REST API is the only API that supports some of Chatter’s more complex data structures, for exampleposting photos or using @mention rich text in feed items. If necessary, you can use SOAP API or REST API for the bulk ofyour queries, then use the feed item or comment Ids you’ve extracted to selectively work with Chatter REST API.
Chatter in ApexMany Chatter REST API resource actions are exposed as static methods on Apex classes in the ConnectApi namespace.This namespace is also referred to as Chatter in Apex. Use Chatter in Apex to develop Chatter applications without usingHTTP callouts from Apex.
The documentation for Chatter in Apex is available in the Apex Code Developer’s Guide.
2
Deciding When to Use Chatter REST APIIntroducing Chatter REST API
Chatter REST API ArchitectureTo use Chatter REST API, understand a few fundamental characteristics of its architecture, like how to authenticate, whatthe request limits are, and which data formats it supports.
These are important characteristics of Chatter REST API resources and architecture:
AuthenticationChatter REST API uses OAuth 2.0.
Note: Database.com is generally accessed securely, that is, using HTTPS.
Default HTML entity encodingChatter REST API strings are minimally HTML entity encoded by default, which is suitable in most cases for displaybetween HTML tags, but not necessarily in other HTML contexts.
For non-HTML contexts, such as native mobile applications, Chatter REST API clients may request raw (unencoded)output by setting the X-Chatter-Entity-Encoding HTTP header in your request to false.
For more information, see Response Body Encoding on page 25.
JSON and XML supportThe JavaScript Object Notation (JSON) format is supported with UTF-8. Date-time information is in ISO8601 format.
XML serialization is similar to SOAP API. XML requests are supported in UTF-8 and UTF-16, and XML responsesare provided in UTF-8.
Responses are in JSON format by default. To specify XML, use the HTTP header Accept: application/xml.(To specify JSON, use Accept: application/json.)
You can append either .json or .xml to the URI of any resource to specify how the return is formatted. For example,/chatter/feeds/filter/me/001/feed-items.xml.
Note: Not all features support XML.
LimitsChatter REST API requests are subject to rate limiting. Chatter REST API has a per user, per application, per hourrate limit. When you exceed the rate limit, all Chatter REST API resources return a 503 Service Unavailable error codefor both the user and application.
If an application uses a regular session ID for authentication instead of an OAuth token, that application's requests countagainst a general allocation of requests where there is no associated OAuth consumer key. However, any other applicationthe user accesses, that is also authenticating with session IDs, is contending for the same allocation of requests. Forexample, your app connects a user to Database.com using a regular session ID. This user now has the same number ofrequests regardless of the app they are using. They no longer have a separate request limit per application: all applicationsare now using the same limit. Because of this, we recommend clients use OAuth tokens whenever feasible.
Note: Stated limits aren't a promise that the specified resource is available at its limit in all circumstances. Forexample, load, performance and other system issues might prevent some limits from being reached. The statedlimit may change without notice. Applications should make efficient use of available requests and gracefullyhandle the 503 error code.
3
Chatter REST API ArchitectureIntroducing Chatter REST API
Localized names and timesChatter REST API localizes both the names and datetimes to the locale setting of the user. Users set their locale in theirpersonal information. If the user hasn’t set their locale, Chatter REST API uses the default locale for the organization.
Clients can use any locale available in the organization to override the default locale. Use the Accept-Language HTTPheader to override the locale for any API request.
Note: ISO-8601 dates are always in GMT.
UI ThemesClients can use the X-Connect-Theme HTTP header to specify a UI theme for any API request. There are two themes,each with their own set of motif icons: Classic and Salesforce1. Theme names are case sensitive.
Method overridingIf you use an HTTP library that doesn’t allow overriding or setting an arbitrary HTTP method name, you can send aPOST request and provide an override to the HTTP method with the request parameter _HttpMethod. For example:
https://instance_name/services/data/v30.0/chatter//chatter/users/me/conversations/03MD0000000008KMAQ?_HttpMethod=PATCH&read=true
Note: The _HttpMethod parameter is case sensitive. Be sure to use the correct case for all values.
StatelessEach request from client to server must contain all the information necessary to understand the request, and not use anystored context on the server. However, the representations of the resources are interconnected using URLs that allowthe client to progress between states.
Uniform interfaceAll resources are accessed with a generic interface over HTTP.
Building the Chatter REST API Resource URLAccess all Chatter REST API resources by using the URI for your company's instance, combined with version information,and the URI for the resource.
For example, building a URL, if your instance is:
https://na1.database.com
And the version information is:
/services/data/v30.0
And the resource is :
/chatter/feeds/news/me/feed-items
4
Building the Chatter REST API Resource URLIntroducing Chatter REST API
Put together, the full URL is:
https://na1.database.com/services/data/v30.0/chatter/feeds/news/me/feed-items
Sending HTTP RequestsChatter REST API uses HTTP methods to send and receive JSON and XML content, so it is very simple to build clientapplications using the tool or the language of your choice.
Your HTTP requests to a Chatter REST API resource should contain the following information:
• An HTTP method (such as HEAD, GET, POST, or DELETE).
• An OAuth 2.0 access token used to authenticate the request. For information on how to retrieve the token, see Step Two:Set Up Authorization on page 38.
• The Chatter REST API resource URL.
• Any JSON or XML files containing information needed for requests, such as updating a record with new information.
The HTTP methods are used to indicate the desired action, such as retrieving information, as well as creating, updating, anddeleting records.
• GET is used to retrieve information, such as basic resource summary information.
• POST is used to create a new Chatter REST API item, such as a comment or like, or subscribe to a group.
• PATCH is used for partial updates to an item, for example, renaming a file.
• PUT is used for whole updates to an item, for example, marking a conversation as read.
• DELETE is used to delete a Chatter REST API item, such as a feed-item, or unsubscribe from a group.
• HEAD is used to retrieve resource metadata. It's similar to using GET but without the response body. You can use HEADfor testing the availability of a resource.
To access a resource, submit an HTTP request containing a header, method, and resource URL.
Understanding a Chatter REST API Request and ResponseThe general process flow for using Chatter REST API is as follows:
1. Send an HTTP request to Database.com.2. The system authenticates the user and client app.3. Request Chatter REST API resources using an HTTP request.4. The system returns an HTTP return code. Additional information (such as a Chatter REST API response body) is
optionally included in the response.
Each resource in Chatter REST API is a URI used with an HTTP method (such as GET, POST, DELETE, or HEAD).Each resource represents something in Chatter, such as a user's news feed, or the comments on a post.
Many of the resources use either a specified user ID or the keyword me to indicate the current, logged-in user. For example,to return the user-profile information for the current, logged-in user, use the following resource:
/chatter/users/me
You could also specify a particular user by user Id:
/chatter/users/005D0000001GLoh
5
Sending HTTP RequestsIntroducing Chatter REST API
When you successfully access a resource, a response body is returned in JSON or XML. By default, JSON is returned. Eachresponse body may contain one or more response bodies. For example, the following is the response body of the above resource(users). Note that it includes other response bodies as well, such as address, current status, and phone numbers:
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Big, 29.0Text from user's profileStringaboutMe
30.0Small, 30.0An additional label for the user, for example,“Customer,” “Partner,” or “Acme Corporation.” If
StringadditionalLabel
the user doesn’t have an additional label, the valueis null.
23.0Big, 29.0AddressAddressaddress
23.0Big, 29.0Chatter activity statisticsChatter ActivitychatterActivity
23.0Big, 29.0User’s influence rankChatter InfluencechatterInfluence
23.0Small, 29.0Company nameStringcompanyName
23.0–25.0User StatuscurrentStatusNote: This property is no longer availableas of version 25.0.
User's current status
23.0Medium, 29.0User's email addressStringemail
23.0Small, 29.0User's first nameStringfirstName
23.0Big, 29.0Number of users following this userIntegerfollowersCount
23.0Big, 29.0Information about items the user is followingFollowing CountsfollowingCounts
23.0Big, 29.0Number of groups user is followingIntegergroupCount
23.0Small, 29.018-character ID of the userStringid
23.0Small, 29.0true if user is active, false otherwiseBooleanisActive
23.0–25.0BooleanisChatterGuestNote: This property is no longer availableas of version 26.0. Use the userTypeproperty instead.
true if user is a Chatter customer, falseotherwise
28.0Small, 29.0true if user is in the same community as thecontext user; false otherwise. Can be false for
BooleanisInThisCommunity
record feed @mentions on posts with the scope “AllUsers.”
23.0Small, 29.0User's last nameStringlastName
23.0Big, 29.018-character ID of the user’s managerStringmanagerId
23.0Big, 29.0Locale-based concatenation of manager's first andlast names
StringmanagerName
6
Understanding a Chatter REST API Request and ResponseIntroducing Chatter REST API
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
27.0Small, 29.0Small, medium, and large icons indicating that theobject is a user. The motif can also contain theobject’s base color.
The motif icon is not the user’s profile picture.
Motifmotif
23.0Medium, 29.0If the logged-in user is following this user, thiscontains information about the subscription, elsereturns null
ReferencemySubscription
23.0Small, 29.0Locale-based concatenation of user's first and lastnames
Stringname
23.0Big, 29.0Collection of user's phone numbersPhone Number[]phoneNumbers
23.0Small, 29.0Information about the user's photosPhotophoto
30.0Small, 30.0The URL of the Chatter REST API record viewresource for this record, or null if this record does
StringrecordViewUrl
not have a record view layout, or if “ConnectRecords API” is not enabled for this organization,or if the record type isn’t supported.
29.0Big, 29.0Number of thanks the user has receivedIntegerthanksReceived
23.0Small, 29.0Title of the userStringtitle
23.0Small, 29.0UserStringtype
23.0Small, 29.0URL to the user's profileStringurl
24.0Small, 29.0User name of the user, such asAdmin@mycompany.com
Stringusername
26.0Medium, 29.0Type of user. Values are:StringuserType
• ChatterGuest—User is a Chattercustomerin an external group
• ChatterOnly—User is a Chatter Freecustomer
• Guest—Unauthenticated users
• Internal—User is a standard organizationmember
• Portal—User is a Customer Portal User, acommunities user, and so on.
• System—User is Chatter Expert or a systemuser
• Undefined—User is a user type that is acustom object.
In JSON format, the output is as follows:
{"aboutMe": "I'm excited to be part of the team focused on building out our apps
7
Understanding a Chatter REST API Request and ResponseIntroducing Chatter REST API
businessand showing our customers their future.","address": {
"city": "Seattle","country": "US","state": "WA","street": "2001 8th Ave","zip": "98121""formattedAdress": "2001 8th Ave\nSeattle, WA 98121\nUS"
},"chatterActivity": {
"commentCount": 0,"commentReceivedCount": 1,"likeReceivedCount": 0,"postCount": 2
},"companyName": "Seattle Apps","email": "mraven@seattleapps.com","firstName": "Marion","followersCount": 1,"followingCounts": {
"people": 5,"records": 0,"total": 5
},"groupCount": 3,"id": "005D0000001Kl6xIAC","isActive": true,"lastName": "Raven","managerId": null,"managerName": null,"motif": {
"largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Marion Raven","phoneNumbers": [{
"number": "(206) 999-2846","type": "Work"
}],"photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cGW2pGjfqoWUUgTENHjVyS1i9x6Z16L8wXEGigpcWjAd",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/F","photoVersionId": "729D00000000BDV","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/T","standardEmailPhotoUrl":
"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cGW2pGjfqoWUUgTENHjVyS1q43x_rW2ciXBHst0Eh3Y6",
"url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001Kl6xIAC","userType": "Internal";"username": "mraven@seattleapps.com"
}
Note: Database.com runs on multiple server instances. The examples in this guide use instance_name to indicatethe instance. The instance for your organization may be similar to na3.database.com or na6.mycompany.com.
Some of the items in a response body have a fully qualified URL, however, most of the returned URLs are relative.If the URL is relative, prepend it with the instance given to the client app when the item is authenticated.
8
Understanding a Chatter REST API Request and ResponseIntroducing Chatter REST API
Using Chatter REST API Inputs
Using POST, PATCH, or PUT for InputWhen you make a request using the HTTP POST, PATCH, and PUT methods, you can use request parameters or a requestbody. The request body can contain JSON or XML. If you pass request parameters and a request body, the request parametersare usually ignored. However, if you pass both a request body and a text parameter, you’ll receive a 400 error.
To submit a request using request parameters, use a Content-Type header field with the valueapplication/x-www-form-urlencoded.
To submit a request using a request body, use one of the following values in a Content-Type header field and in an Acceptheader field:
• application/json
• application/xml
Uploading Binary FilesTo upload a binary file, you must send it as a body part in a multipart/form-data request. You can send information such asthe text of a post or comment as a JSON or XML rich input body part in the same multipart/form-data request. Alternately,you can choose to send that information in request parameters. If you pass both a rich input request body and request parameters,the request parameters are ignored.
To create a multipart/form-data request, in the head of the request, set the Content-Type HTTP header tomultipart/form-data.
For information about additional HTTP headers, see W3C Form content types, and RFC 2388, which defines themultipart/form-data internet media type.
The following table describes the HTTP headers and parameters required in the rich input body part of a multipart/form-datarequest:
DescriptionHeader Value and ParametersHTTP Headers for RichInput Body Part
The request body for a post or comment.
For JSON, the value of name must be "json".
form-data; name="json"
form-data; name="xml"
Content-Disposition
For XML, the value of name must be "xml".
The data format and character set of the requestbody.
For JSON, the value must beapplication/json.
application/json; charset=UTF-8
application/xml; charset=UTF-8
Content-Type
For XML, the value must beapplication/xml.
The following table describes the HTTP headers and parameters required in the binary upload body part of a multipart/form-datarequest:
9
Using Chatter REST API InputsIntroducing Chatter REST API
DescriptionHeader Value and ParametersHTTP Headers for BinaryUpload Body Part
To upload a binary file to a post or comment,the value of name must be"feedItemFileUpload".
To upload a user or group photo, the value ofname must be "fileUpload".
form-data;name="feedItemFileUpload";filename=string
form-data; name="fileUpload"filename=string
Content-Disposition
To upload a file to the File list, the value of namemust be "fileData".
form-data; name="fileData"filename=string
Note: You must specify a filenameparameter and value. However, pleasenote that Chatter uses the value of theAttachment Input: New File Uploadtitle property as the file name, notthe value of the filename parameter.
The media type and character set of the binaryfile.
application/octet-stream;charset=ISO-8859-1
Content-Type
The following example posts a new feed item, uploads a binary file, and attaches it to the new feed item. The multipart requestin this example includes a part for the request body that has a Content-Type of application/json.
POST /services/data/v30.0/chatter/feeds/user-profile/005x0000001T9PwAAK/feed-items HTTP/1.1Authorization: OAuth 00DD0000000Jhd2!AQIAQC.lh4qTQcBhOPm4TZom5IaOOZLVPVK4wI_rPYJvmE8r2VW8XA.OZ7S29JEM_7Ctq1lst2dzoV.owisJc0KacUbDxyaeUser-Agent: Jakarta Commons-HttpClient/3.0.1Host: instance_nameContent-Length: 845Content-Type: multipart/form-data; boundary=a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgqAccept: application/json
--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgqContent-Disposition: form-data; name="json"Content-Type: application/json; charset=UTF-8
{ "body":{
"messageSegments" : [{
"type" : "Text","text" : "High priority content "
}, {"type" : "Hashtag","tag" : "important"
}, {"type" : "Text","text" : "Please review this as soon as possible."
}]
},"attachment":{
"attachmentType" : "NewFile","description": "Quarterly review","title" : "2012_q1"
}}
--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq
10
Using Chatter REST API InputsIntroducing Chatter REST API
Content-Disposition: form-data; name="feedItemFileUpload"; filename="foo"Content-Type: application/octet-stream; charset=ISO-8859-1
This is the content of the file.--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq--
The following is the same example using XML instead of JSON:
POST /services/data/v30.0/chatter/feeds/user-profile/005x0000001TBMVAA4/feed-items HTTP/1.1Authorization: OAuth 00DD0000000Jhd2!AQIAQC.lh4qTQcBhOPm4TZom5IaOOZLVPVK4wI_rPYJvmE8r2VW8XA.OZ7S29JEM_7Ctq1lst2dzoV.owisJc0KacUbDxyaeUser-Agent: Jakarta Commons-HttpClient/3.0.1Host: instance_nameContent-Length: 897Content-Type: multipart/form-data; boundary=0HWq8x4y4DSQ4fqjXt6MinVMyqbf1rAccept: application/xml
--0HWq8x4y4DSQ4fqjXt6MinVMyqbf1rContent-Disposition: form-data; name="xml"Content-Type: application/xml; charset=UTF-8
<feedItem><body>
<messageSegments><segment>
<text>High priority content </text><type>Text</type>
</segment><segment>
<tag>important</tag><type>Hashtag</type>
</segment><segment>
<text>Please review this as soon as possible</text><type>Text</type>
</segment></messageSegments>
</body><attachment attachmentType="NewFile">
<description>Quarterly review 2012 Q1</description><title>2012_q1</title>
</attachment></feedItem>
--0HWq8x4y4DSQ4fqjXt6MinVMyqbf1rContent-Disposition: form-data; name="feedItemFileUpload"; filename="foo"Content-Type: application/octet-stream; charset=ISO-8859-1
This is the content of the file.--0HWq8x4y4DSQ4fqjXt6MinVMyqbf1r--
The following example posts a comment to a feed item and uploads a binary attachment:
POST /services/data/v30.0/chatter/feed-items/0D5x00000000RryCAE/comments HTTP/1.1Authorization: OAuth 00DD0000000Jhd2!AQIAQC.lh4qTQcBhOPm4TZom5IaOOZLVPVK4wI_rPYJvmE8r2VW8XA.OZ7S29JEM_7Ctq1lst2dzoV.owisJc0KacUbDxyaeAccept: application/jsonUser-Agent: Jakarta Commons-HttpClient/3.0.1Host: instance_nameContent-Length: 978Content-Type: multipart/form-data; boundary=F9jBDELnfBLAVmLNbnLIYibT5Icp0h3VJ7mkI
--F9jBDELnfBLAVmLNbnLIYibT5Icp0h3VJ7mkIContent-Disposition: form-data; name="json"Content-Type: application/json; charset=UTF-8
{ "body":{
11
Using Chatter REST API InputsIntroducing Chatter REST API
"messageSegments" : [{
"type" : "Text","text" : "Here's another file for review."
}, {"type" : "Hashtag","tag" : "important"
}, {"type" : "Text","text" : "Again, please review this as soon as possible."
}]
},"attachment":{
"attachmentType" : "NewFile","description": "Quarterly review 2012 Q2","title" : "2012_q2"
}}
--F9jBDELnfBLAVmLNbnLIYibT5Icp0h3VJ7mkIContent-Disposition: form-data; name="feedItemFileUpload"; filename="foo"Content-Type: application/octet-stream; charset=ISO-8859-1
This is the content of the file.
--F9jBDELnfBLAVmLNbnLIYibT5Icp0h3VJ7mkI--
Note: Spacing and carriage returns and line feeds (CRLF) are important. For example, the following line requiresspaces: Content-Disposition: form-data; name="feedItemFileUpload";title="2012_q1_review.ppt" If you had used CRLF instead of spaces, you would have received an error.
Working with Feeds and Feed ItemsFeeds are made up of feed items. A feed item is a piece of information posted by a user (for example, a poll) or by an automatedprocess (for example, when a tracked field is updated on a record). Because feeds and feed items are the core of Chatter,understanding them is crucial to developing applications with Chatter REST API and Chatter in Apex.
Note: Salesforce Help refers to feed items as posts.
How the Salesforce UI Displays Feed ItemsTo give customers a consistent view of feed items and to give developers an easy way to create UI, the Salesforce UI uses onelayout to display every feed item, regardless of the feed item type. The layout always contains the same elements and theelements are always in the same position; only the content of the layout elements changes. If you stick to this structure, youwon’t have to create a unique layout for every feed item type.
12
Working with Feeds and Feed ItemsIntroducing Chatter REST API
These are the feed item layout elements:
1. Actor (ConnectApi.FeedItem.actor)—A photo or icon of the creator of the feed item. (You can override the creatorat the feed item type level. For example, the dashboard snapshot feed item type shows the dashboard as the creator.)
2. Preamble (ConnectApi.FeedItem.preamble)—Provides context. The same feed item can have a different preambledepending on who posted it and where. For example, Gordon posted this feed item to his profile. If he then shared it toa group, the preamble of the feed item in the group feed would be “Gordon Johnson (originally posted by Gordon Johnson)”and the “originally posted” text would link to the feed item on Gordon’s profile.
3. Body (ConnectApi.FeedItem.body)—All feed items have a body, but the body can be null, which is the case whenthe user doesn’t provide text for the feed item. Because the body can be null you can’t use it as the default case for renderingtext. Instead, use the text property of the feed item’s preamble, which always contains a value.
4. Auxiliary Body (ConnectApi.FeedItem.attachment)—The visualization of the attachment. There are multipleattachment types. For example, for a link post, the attachment is the link and name, for a poll, it’s the poll data. In Chatterin Apex, the attachment types are subclasses of ConnectApi.FeedItemAttachment. In Chatter REST API, theattachment types are exposed as response bodies with the name Feed Item Attachment: Name, for example, Feed ItemAttachment: Link and Feed Item Attachment: Poll. Make sure your code has a default case that doesn’t display an auxiliarybody if it doesn’t recognize the attachment type.
5. Created By Timestamp (ConnectApi.FeedItem.relativeCreatedDate)—The date and time when the feed itemwas posted. If the feed item is less then two days old, the date and time are formatted as a relative, localized string, forexample, “17m ago” or “Yesterday”. Otherwise, the date and time are formatted as an absolute, localized string.
Here’s another example of a feed item in the Salesforce UI. This feed item’s auxiliary body contains a poll:
Feed Item VisibilityThe feed items a user sees depend on how the administrator has configured feed tracking, sharing rules, and field-level security.For example, if a user doesn’t have access to a record, they don’t see updates for that record. If a user can see the parent of thefeed item, the user can see the feed item. Typically, a user sees feed updates for:
• Feed items that @mention the user if the user can access the feed item’s parent• Feed items that @mention groups the user is a member of• Record field changes on records whose parent is a record the user can see, including User, Group, and File records
13
Working with Feeds and Feed ItemsIntroducing Chatter REST API
• Feed items posted to the user• Feed items posted to groups the user owns or is a member of• Feed items for standard and custom records, for example, tasks, events, leads, accounts, files, and so on
Feed TypesThere are many types of feeds. Each feed type is an algorithm that defines a collection of feed items.
Important: The algorithms, and therefore the collection of feed items, can change between releases.
In Chatter REST API, the feed types are exposed in the resources. For example, these are the resources for the news feed andtopics feed:
/chatter/feeds/news/userId/chatter/feeds/topics/topicId
In Chatter in Apex, all feed types except Filter and Favorites are exposed in the ConnectApi.FeedType enum and passedto the ConnectApi.ChatterFeeds.getFeedItemsFromFeed method or to theConnectApi.ChatterFeeds.postFeedItem method. This example gets the feed items from the logged-in user’s newsfeed and topics feed:
ConnectApi.FeedItemPage newsFeedItemPage =ConnectApi.ChatterFeeds.getFeedItemsFromFeed(null,ConnectApi.FeedType.News, 'me');
ConnectApi.FeedItemPage topicsFeedItemPage =ConnectApi.ChatterFeeds.getFeedItemsFromFeed(null,ConnectApi.FeedType.Topics, '0TOD00000000dUg');
To get a filter feed, call ConnectApi.ChatterFeeds.getFeedItemsFromFilterFeed. To get a favorites feed, callConnectApi.ChatterFavorites.getFeedItems.
These are the feed types and their descriptions:
• Bookmarks—Contains all feed items saved as bookmarks by the logged-in user.• Company—Contains all feed items except feed items of type TrackedChange. To see the feed item, the user must have
sharing access to its parent.• Files—Contains all feed items that contain files posted by people or groups that the logged-in user follows.• Filter—Contains the news feed filtered to contain feed items whose parent is a specified object type.• Groups—Contains all feed items from all groups the logged-in user either owns or is a member of.• Moderation—Contains all feed items that have been flagged for moderation. The Communities Moderation feed is
available only to users with “Moderate Community Feeds” permissions.• News—Contains all updates for people the logged-in user follows, groups the user is a member of, files and records the
user is following, all updates for records whose parent is the logged-in user, and every feed item and comment that mentionsthe logged-in user or that mentions a group the logged-in user is a member of.
• People—Contains all feed items posted by all people the logged-in user follows.• Record—Contains all feed items whose parent is a specified record, which could be a group, user, object, file, or any other
standard or custom object. When the record is a group, the feed also contains feed items that mention the group.• To—Contains all feed items with mentions of the logged-in user, feed items the logged-in user commented on, and feed
items created by the logged-in user that are commented on.• Topics—Contains all feed items that include the specified topic.• UserProfile—Contains feed items created when a user changes records that can be tracked in a feed, feed items whose
parent is the user, and feed items that @mention the user. This feed is different than the news feed, which returns morefeed items, including group updates.
14
Working with Feeds and Feed ItemsIntroducing Chatter REST API
• Favorites—Contains favorites saved by the logged-in user. Favorites are feed searches, list views, and topics.• Filter—Contains the news feed filtered to contain items whose parent is a specified entity type.
Posting a Feed ItemUse these resources and methods to post feed items:
Chatter in Apex MethodChatter REST API ResourceFeed Type
ConnectApi.ChatterFeeds.postFeedItem(communityIdOrNull,ConnectApi.FeedType.News, userId)
userId must be the ID of the logged-in user or thealias me.
POST /chatter/feeds/news/userId/feed-items
userId must be the ID of the logged-in user or thealias me.
News Feed
ConnectApi.ChatterFeeds.postFeedItem(communityIdOrNull,ConnectApi.FeedType.Record, recordId)
POST /chatter/feeds/record/recordId/feed-items
Record Feed
ConnectApi.ChatterFeeds.postFeedItem(communityIdOrNull,
POST /chatter/feeds/user-profile/userId/feed-items
User ProfileFeed
ConnectApi.FeedType.UserProfile,userId)
When you post a feed item, you’re creating a child of a standard or custom object. For Chatter REST API, specify the parentobject in the userId or recordId section of the resource. For Chatter in Apex, specify the parent object in the in the userIdor recordId argument.
The parent property of the posted feed item contains information about the parent object.
Select the correct feed type and parent object for the task you want to complete:
Post to yourselfMake a POST request to the news feed, the record feed, or the user profile feed.
For userId, specify the user ID of the logged-in user or the alias me.
The parent property of the newly posted feed item contains the User Summary object (ConnectApi.UserSummary)of the logged-in user.
Post to another userMake a POST request to the record feed or the user profile feed.
For recordId or userId, specify the user ID of the target user.
The parent property of the newly posted feed item contains the User Summary object (ConnectApi.UserSummary)of the target user.
Post to a groupMake a POST request to the record feed.
For recordId, specify the group ID.
The parent property of the newly posted feed item contains the Group object (ConnectApi.ChatterGroupSummary)of the specified group.
Post to a record (such as a file or an account)Make a POST request to the record feed.
15
Working with Feeds and Feed ItemsIntroducing Chatter REST API
For recordId, specify the record ID.
The parent property of the new feed item depends on the record type specified in recordId. If the record type is File,the parent is the File Summary object (ConnectApi.FileSummary). If the record type is Group, the parent is a Groupobject (ConnectApi.ChatterGroupSummary). If the record type is User, the parent is a User Summary object(ConnectApi.UserSummary). For all other record types, the parent is a Record Summary object(ConnectApi.RecordSummary).
Getting Feed Items from a FeedGetting feed items from a feed is similar, but not identical, for each feed type.
To get the feed items from the company feed or the moderation feed, you don’t need to specify a subject ID:
Chatter in Apex MethodChatter REST API ResourceFeed Type
ConnectApi.ChatterFeeds.getFeedItemsFromFeed
GET /chatter/feeds/company/feed-itemsCompany
(communityIdOrNull,ConnectApi.FeedType.Company)
ConnectApi.ChatterFeeds.getFeedItemsFromFeed
GET /connect/communities/communityId/chatter/feeds/moderation/feed-items
Moderation
(communityIdOrNull,ConnectApi.FeedType.Moderation)
To get the feed items from the favorites and filter feeds you need to specify a favoriteId or a keyPrefix. The keyPrefixindicates the object type and is the first three characters of the object ID. For these feeds, the subjectId must be the ID ofthe logged-in user or the alias me.
Chatter in Apex MethodChatter REST API ResourceFeed Type
ConnectApi.ChatterFavorites.getFeedItems(communityIdOrNull,subjectId, favoriteId)
GET /chatter/feeds/favorites/subjectId/favoriteId/feed-items
Favorites
ConnectApi.ChatterFeeds.getFeedItemsFromFilterFeed
GET /chatter/feeds/filter/subjectId/keyPrefix/feed-items
Filter
(communityIdOrNull, subjectId,keyPrefix)
To get the feed items from a record feed you need to specify a record ID.
Chatter in Apex MethodChatter REST API ResourceFeed Type
ConnectApi.ChatterFeeds.getFeedItemsFromFeed
GET/chatter/feeds/record/recordId/feed-items
Record
(communityIdOrNull,ConnectApi.FeedType.Record, recordId)
Tip: The recordId can be a record of any type that supports feeds, including group. The feed on the group pagein the Salesforce UI is a record feed.
16
Working with Feeds and Feed ItemsIntroducing Chatter REST API
To get the feed items from all other feed types you need to specify a subject ID. Replace the feedType to specify a differentfeed. For all the feed types in this table except the user profile feed and the topics feed, the subjectId must be the ID ofthe logged-in user or the alias me.
Chatter in Apex MethodChatter REST API ResourceFeed Type
ConnectApi.ChatterFeeds.getFeedItemsFromFeed(communityIdOrNull, feedType, subjectId)
For example: ConnectApi.ChatterFeeds.getFeedItemsFromFeed
GET/chatter/feeds/feedType/subjectId/feed-items
For example: GET/chatter/feeds/news/me/feed-items
Bookmarks,Files, Groups,News, People,To, Topics, UserProfile
(communityIdOrNull,ConnectApi.FeedType.News, 'me')
See Also:Feeds Resources
Working with Salesforce FilesUse Chatter REST API to work with Salesforce Files.
Use Salesforce Files to upload, store, find, follow, share, and collaborate on files in the cloud.
Use Salesforce Files Sync to securely store, sync, and share files between Chatter, the desktop, and mobile devices. Access filesand folders from anywhere, and keep them instantly updated across your organization. Chatter REST API for Salesforce FilesSync is available through a pilot program in version 30.0.
TasksHTTPMethods
Resource
Returns all feed items posted with files by people orgroups that the logged-in user follows.
GET/chatter/feeds/files/me/feed-items
All feed items from all groups the logged-in user eitherowns or is a member of, as well as all files, records,
GET, POST/chatter/feeds/news/me/feed-items
and users the logged-in user follows. Use this resourceto get information about the feed items and to postfeed items.
Returns the feed-items for all the records thelogged-in user is following, or all the feed-items of
GET, POST/chatter/feeds/records/recordId/feed-items
the specified recordId. Use this resource to post anew feed item and to search a feed. To use thisresource to get the feed items for a specific group,specify the group ID as the recordId.
Returns the feed-items for all actions on all recordsthat can be tracked in a feed. You can also use thisresource to post a new feed item.
GET, POST/chatter/feeds/user-profile/userId/feed-items
17
Working with Salesforce FilesIntroducing Chatter REST API
TasksHTTPMethods
Resource
Returns details about the specified file. Can also beused to rename a file, upload a new version of an
GET, POST,PATCH,DELETE
/chatter/files/fileId
existing file, move a file to a different folder, anddelete a file.
Returns the content of the file. The content isstreamed as the body of the response.
GET/chatter/files/fileId/content
Returns information about the objects with which thespecified file has been shared. Objects can be users,
GET, POST/chatter/files/fileId/file-shares
groups, or records. Can also be used to share thespecified file with users.
A description of a file shared as a link. Create, access,and delete a file’s share link.
GET, PUT,DELETE
/chatter/files/fileId/file-shares/link
A rendition of the file. A rendition is a binary previewof the file. The format of the binary depends on theformat specified in the request.
GET/chatter/files/fileId/rendition
Information about a list of files, specified by file IDs.Get information about a list of files and delete a listof files.
GET,DELETE
/chatter/files/batch/fileIds
Get information about the specified folder. You canalso move, rename, and delete a folder. Folders
GET, PATCH,DELETE
/chatter/folders/folderId
resources are available through a pilot program inversion 30.0.
Get information about the contents of a folder. Youcan also add a file to a folder and create a folder.
GET, POST/chatter/folders/folderId/items
Folders resources are available through a pilot programin version 30.0.
Returns information about the files posted to thespecified group.
GET/chatter/groups/groupId/files
Returns information about the five files most recentlyposted to the specified topic.
GET/connect/topics/topicId/files
Post a file or get information about files a user owns.These files don’t include files shared with a user, filesa user follows, or general organization files.
GET, POST/chatter/users/userId/files
Returns information about files posted to groups thatthe specified user is a member of.
GET/chatter/users/me/files/filter/groups
Returns information about files that have been sharedwith the specified user.
GET/chatter/users/me/files/filter/shared-with-me
Note: You can replace the alias me with the user ID of the logged-in user.
18
Working with Salesforce FilesIntroducing Chatter REST API
WildcardsUse wildcard characters to match text patterns in Chatter REST API and Chatter in Apex searches.
A common use for wildcards is searching a feed. Pass a search string and wildcards in the q parameter. This example is aChatter REST API request:
/chatter/feed-items?q=chat*
This example is a Chatter in Apex method call:
ConnectApi.ChatterFeeds.searchFeedItems(null, 'chat*');
You can specify the following wildcard characters to match text patterns in your search:
DescriptionWildcard
Asterisks match zero or more characters at the middle or end (not the beginning) of your search term. Forexample, a search for john* finds items that start with john, such as, john, johnson, or johnny. A search for
*
mi* meyers finds items with mike meyers or michael meyers. If you are searching for a literal asterisk in aword or phrase, then escape the asterisk (precede it with the \ character).
Question marks match only one character in the middle or end (not the beginning) of your search term.For example, a search for jo?n finds items with the term john or joan but not jon or johan.
?
When using wildcards, consider the following issues:
• Wildcards take on the type of the preceding character. For example, aa*a matches aaaa and aabcda, but not aa2a or aa.!//a,and p?n matches pin and pan, but not p1n or p!n. Likewise, 1?3 matches 123 and 143, but not 1a3 or 1b3.
• A wildcard (*) is appended at the end of single characters in Chinese, Japanese, Korean, and Thai (CJKT) searches, exceptin exact phrase searches.
• The more focused your wildcard search, the faster the search results are returned, and the more likely the results will reflectyour intention. For example, to search for all occurrences of the word prospect (or prospects, the plural form), it ismore efficient to specify prospect* in the search string than to specify a less restrictive wildcard search (such as prosp*)that could return extraneous matches (such as prosperity).
• Tailor your searches to find all variations of a word. For example, to find property and properties, you would specifypropert*.
• Punctuation is indexed. To find * or ? inside a phrase, you must enclose your search string in quotation marks and youmust escape the special character. For example, "where are you\?" finds the phrase where are you?. The escapecharacter (\) is required in order for this search to work correctly.
Specifying Response SizesTo specify the response size, use filterGroup as a request parameter or in a request body to specify a group of propertiesby size. In addition, use either exclude or include as a request parameter or in a request body to exclude or include specificproperties. Use filters to return only the data the application needs.
filterGroup
Use the filterGroup parameter in a request URL or in a request body to specify whether to return a small, medium, orbig group of properties. The filterGroup property is available in API version 29.0 and later.
19
WildcardsIntroducing Chatter REST API
exclude
To exclude specific properties from a response body, use the exclude request parameter. The exclude parameter is availablein API version 27.0 and later.
include
To limit the response body to specific properties, use the include query string parameter.
filterGroupUse the filterGroup parameter in a request URL or in a request body to specify whether to return a small, medium, or biggroup of properties. The filterGroup property is available in API version 29.0 and later.
Note: The filterGroup parameter is supported for JSON only and for REST only.
Every property in every response body is assigned a group size:
• Big—The default size. Includes every property in a response body, including those marked Big, Medium, and Small.• Medium—Includes properties marked Medium and Small.• Small—The smallest response size. Includes only properties marked Small.
Note: The size assignments are visible only in the documentation. They aren’t visible in the response bodies.
When a request includes a filterGroup, the response body only includes properties that are part of the specified group.
Things to know about using filter groups:
• The default filterGroup size is Big.• Each filter group size assigned to a property has an API version. In future API versions properties may move to different
filter groups.• Filter groups affect all HTTP verbs except DELETE and HEAD.• You can use a filterGroup parameter on any request URL, including subrequests in a batch request body, unless
otherwise stated.• You can use a filterGroup parameter in conjunction with either an include or an exclude filter parameter to change
the set of properties returned. The resulting set is a union of the two sets.
Using a filterGroup parameter with an include or exclude parameterRequests can contain a filterGroup parameter and group size value, and either an include or an exclude filter parameterand value on the URL. This is also true for subrequests in a generic batch request.
When a request (or a subrequest) contains both a filterGroup parameter and an include parameter, the response alwaysincludes the properties specified by the include parameter.
When a request (or a subrequest) contains both a filterGroup parameter and an exclude parameter, the response alwaysexcludes the properties specified by the exclude parameter.
In this table, read a row from left to right to see whether the property is included in the response.
20
filterGroupIntroducing Chatter REST API
PropertyIncluded InResponse
PropertyProvided infilterGroupin Request
filterGroupProvided inRequest
PropertyProvided inexclude Filterin Request
exclude FilterProvided inRequest
PropertyProvided ininclude Filterin Request
include FilterProvided inRequest
NoNoNoNoNoNoYes
YesYes or NoYes or NoNoNoYesYes
YesNoNoNoYesNoNo
NoNoYesNoYesNoNo
NoYes or NoYes or NoYesYesNoNo
NoNoYesNoNoNoNo
YesYesYesNoNoNoNo
Error (400)Yes or NoYes or NoYes or NoYesYes or NoYes
ExampleThis example gets the Small response body for the User Profile resource:
GET /chatter/users/me?filterGroup=Small
This is the response:
{"companyName": "Universal Containers","firstName": "Deanna","id": "005D0000001LL8OIAW","isActive": true,"isInThisCommunity": true,"lastName": "Li","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"name": "Deanna Li","photo": {
"photoVersionId": "729D00000000LJFIA2","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/T","standardEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sYVo6fntPnCQ_-xIH-GU3vI","url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo"
},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW","username": "dli@uc.com"
}
excludeTo exclude specific properties from a response body, use the exclude request parameter. The exclude parameter is availablein API version 27.0 and later.
The value for the exclude query is a list of properties separated by bars (|). You must URL encode the bars as %7C. Youmust include a forward slash before each property name.
21
excludeIntroducing Chatter REST API
The following request excludes both the aboutMe and address properties from a response body:
/chatter/users/me?exclude=/aboutMe%7C/address
The following table lists rules for using the exclude query parameter, as well as additional examples.
Filtered OutputExclude ValueOriginal OutputDescription
400 error with error codeINVALID_FILTER_VALUE
exclude=bar{"bar" : "bar value","baz" : "baz value"}
Include a forwardslash (/) beforeproperty names or therequest returns anerror.
{"baz" : "baz
exclude=/bar{"bar" : "bar value",
Filter properties byname.
value"}
"baz" : "baz value"}
<foo><bar>bar value
exclude=/foo<foo><bar>bar value</bar>
Top-level propertiescannot be filtered.
</bar><baz>baz value</baz></foo>Note that this query
string doesn’t returnan error.
<baz>baz value</baz></foo>
{"baz" : "baz
exclude=/foo%7C/bar{"foo" : "foo value",
Use a bar (|) delimiterto filter multiple
value"}
"bar" : "bar value","baz" : "baz value"}
properties. URLencode the delimiteras %7C.
<foo><bar>bar value
exclude=/someObject<foo><bar>bar value</bar>
Filtering a responsebody filters everythingin the response body. </bar>
<baz>baz value<baz>baz value</baz><someObject>
</baz></foo>
<sub>sub 1</sub></someObject></foo>
<foo><bar>bar value
exclude=/someObject/sub<foo><bar>bar value</bar>
To filter a propertynested in a response
</bar><baz>baz value</baz>body, include the <baz>baz value<someObject>parent response body </baz><sub>sub value</sub>name as a filtersegment.
<someObject></someObject></foo>
</someObject></foo>
<foo><bar>bar value
exclude=/someList/item/id<foo><bar>bar valu</bar>
Identify an item in alist by its property
</bar><baz>baz value</baz>name. This exampleuses XML.
<baz>baz value</baz><someList>
<someList><item><id>1</id>
<item/></item><item/><item><item/><id>2</id>
</someList></foo>
</item><item>
22
excludeIntroducing Chatter REST API
Filtered OutputExclude ValueOriginal OutputDescription
<id>3</id></item>
</someList></foo>
{"bar" : "bar value",
exclude=/someList/item/id{"bar" : "bar value",
Identify an item in alist by its property
"baz" : "baz value","baz" : "baz value",name. This exampleuses JSON.
"someList" : [{},{},
"someList" : [{"id" : "1"
{}},]}
{"id" : "2"
} ,{"id" : "3"
}]}
includeTo limit the response body to specific properties, use the include query string parameter.
The value for the include query string parameter is a list of properties separated by bars (|). You must URL encode the barsas %7C. Include a forward slash before every property name.
The following request includes only the aboutMe property and the address property in a response body:
/chatter/users/me?include=/aboutMe%7C/address
The following table lists rules for using the include query parameter.
Filtered OutputInclude ValueOriginal OutputDescription
400 error with error codeINVALID_FILTER_VALUE
include=bar{"bar" : "bar value","baz" : "baz value"}
Include a forwardslash (/) beforeproperty names or therequest returns anerror.
{"bar" : "bar
include=/bar{"bar" : "bar value",
Filter properties byname.
value",}
"baz" : "baz value"}
<foo><bar>bar value
include=/foo<foo><bar>bar value</bar>
Top-level propertiesare ignored. Note
</bar><baz>baz value</baz></foo>there is no error when
you try this.<baz>baz value</baz>
</foo>
23
includeIntroducing Chatter REST API
Filtered OutputInclude ValueOriginal OutputDescription
{"foo" : "foo
include=/foo%7C/bar{"foo" : "foo value",
Use a bar (|) delimiterto filter multiple
value","bar" : "bar value",properties. URL "bar" : "bar"baz" : "baz value"}encode the delimiter
as %7C.value",}
<foo><someObject>
include=/someObject<foo><bar>bar value</bar>
Filtering a responsebody filters everythingbelow it. <sub>sub 1
</sub><baz>baz value</baz><someObject>
</someObject></foo>
<sub>sub 1</sub></someObject></foo>
<foo><someObject>
include=/someObject/sub<foo><bar>bar value</bar>
To filter a propertynested in a response
<sub>sub 1<baz>baz value</baz>body, include the </sub><someObject>parent response body </someObject>
</foo><sub>sub value</sub></someObject>
</foo>name as a filtersegment.
<foo><someList>
include=/someList/item/id<foo><bar>bar valu</bar>
Identify an item in alist by its property
<item><baz>baz value</baz>name. This exampleuses XML.
<id>1</id></item><item>
<someList><item><id>1</id>
<id>2</id></item></item><item><item><id>2</id><id>3</id></item>
</item><item></someList>
</foo><id>3</id>
</item></someList></foo>
{"someList" : [
include=/someList/item/id{"bar" : "bar value",
Identify an item in alist by its property
{"baz" : "baz value",name. This exampleuses JSON.
"id" : "1"},{
"someList" : [{"id" : "1"
"id" : "2"},} ,{{"id" : "2""id" : "3"} ,
}{]}
"id" : "3"}
]}
24
includeIntroducing Chatter REST API
Response Body EncodingChatter REST API serves user-submitted content that is often not filtered at input and may come from many different sourcesincluding third-party mobile and web applications. Therefore, developers creating applications that consume Chatter RESTAPI output must take care to properly process the output for the context in which they use the data. Failing to do so mayexpose their application and their users to Cross Site Scripting (XSS) exploits and other problems that may result in data loss,application failure and exposure of confidential company information.
Chatter REST API strings are minimally HTML entity encoded by default, which is suitable in most cases for display betweenHTML tags, but not necessarily in other HTML contexts.Chatter REST API output may be used in many contexts. Developersshould not assume that the default entity encoding is appropriate for all contexts. In particular, using Chatter REST APIoutput inside HTML attribute values, inside URLs, with javascript, inside script tags and inside CSS all require differentencoding and whitelisting. See the Open Web Application Security Project for information on how to handle API output indifferent contexts.
Chatter REST API response returns are encoded on output. We escape the following characters in all strings:
Escaped asCharacter
<<
>>
""
''
\\
&&
For non-HTML contexts, such as native mobile applications, Chatter REST API clients may request raw (unencoded) outputby setting the X-Chatter-Entity-Encoding HTTP header in your request to false.
Chatter REST API does special encoding of any URL values included in response payloads. The main part of the URL isURL-encoded as per RFC2396, and the query string is HTML-form encoded. This encoding cannot be turned off.
Status Codes and Error ResponsesEither when an errors occur, or a response is successful, the response header contains an HTTP code, and the response bodyusually contains the HTTP response code, the message accompanying that error, and if appropriate, the field or object wherethe error occurred.
DescriptionHTTP Response Code
Success with GET or HEAD request200
Success with POST request201
Success with DELETE204
The request could not be understood, usually because the ID is not valid for the particular resource.For example, if you use a userId where a groupId is required, the request returns 400.
400
The session ID or OAuth token used has expired or is invalid. The response body contains themessage and errorCode.
401
25
Response Body EncodingIntroducing Chatter REST API
DescriptionHTTP Response Code
The request has been refused. Verify that the context user has the appropriate permissions toaccess the requested data, or that the context user is not an external user.
403
Either the specified resource was not found, or the resource has been deleted.404
A conflict has occurred. For example, an attempt was made to update a request to join a group,but that request had already been approved or rejected.
409
A precondition has failed. For example, in a batch request, if haltOnError is true and asub-request fails, subsequent sub-requests return 412.
412
An error has occurred within Force.com, so the request could not be completed. Contactsalesforce.com Customer Support.
500
Too many requests in an hour.503
ExamplesThe following are examples of what is returned for errors.
• Incorrect ID:
Using a non-existent ID in a request using JSON or XML (request_body.json or request_body.xml)
{"fields" : [ "Id" ],"message" : "User ID: id value of incorrect type: 001900K0001pPuOAAU","errorCode" : "MALFORMED_ID"
}
• Resource does not exist:
Requesting a resource that does not exist, for example, you try to create a record using a misspelled object name
{"message" : "The requested resource does not exist","errorCode" : "NOT_FOUND"
}
Understanding OAuth and Chatter REST APIOAuth is an open protocol that allows secure authentication for access to a user's data, without handing out the user's usernameand password. It is often described as the valet key of software access: a valet key only allows access to certain features of yourcar: for example, you can’t open the trunk or glove compartment using a valet key.
Chatter REST API uses OAuth to securely identify your application before connecting to Database.com.
When you use OAuth, you can avoid storing login credentials in your application. Instead, your application can prompt theuser to login using a standard Database.com page, which returns an access token to your application. Your application can usethis access token to access Chatter REST API Web services. This approach to authentication can be used in both mobile appsand from a Web page.
Chatter REST API uses OAuth 2.0.
26
Understanding OAuth and Chatter REST APIIntroducing Chatter REST API
Understanding Connected AppsTo use Chatter REST API, you must create a REST entry point in your organization. Database.com defines this entry pointas a Connected App definition.
For an example in creating a Connected App definition, see Step Two: Set Up Authorization on page 38.
Considerations when creating and using a Connected App:
• The following maps the labels used in the Connected App definition to OAuth terms:
DescriptionOAuth TermConnected App Label
A unique identifier that identifies yourapplication to Database.com.
client_idConsumer Key
A secret key associated with yourapplication.
client_secretConsumer Secret
A URL associated with your clientapplication. In some contexts, this must
redirect_uriCallback URL
be a real URL that the client’s Webbrowser is redirected to. In others, theURL isn’t used; however, between yourclient application and the server (theConnected App definition) the valuemust be the same. For example, youmay want to use a value that identifiesthe application, such ashttp://mycomponent.myapp.
• If you are developing a mobile app, you can use the following value for the Callback URL (redirect_uri) to avoidsetting up an application server of your own:
https://login.instance_name/services/oauth2/success
This value should NOT be used when developing a Web application.• Your Connected App does not have to reside in the same organization as your users. The Connected App you create can
be used to sign into any organization.• We recommend creating more than one Connected App definition: one for testing and one for production. If you create
only one, you must change the value of the Callback URL to reflect the location of your application code. In addition,you should create more than one Connected App if you are developing for different platforms, such as iOS and Android.
OAuth Basics• OAuth grants access by client applications to resources owned by resource owners. In terms of OAuth, a resource is anything
that must be kept secured. For Chatter REST API, the resource we are concerned about protecting is all the data accessiblethrough the API.
• It is up to a resource owner to grant access to resources. In our context, the resource owner is a combination of theadministrator (who administers users and the connected app) and the users (who log in and grant access to third partyapplications).
• When an application wants to access a resource, it requests authorization from the resource owner. OAuth outlines variousways that an application can be granted access to a resource. These are referred to as grant types or flows. Different flowsare suitable for different contexts.
• Once a client application has been authorized to access to a resource, the client application is given an access token and arefresh token. The access token must be included by the authorized client application in any subsequent Web service
27
Understanding OAuth and Chatter REST APIIntroducing Chatter REST API
requests to identify itself. Access tokens have a limited lifetime. When an access token expires, the authorized clientapplication can make a special request using the refresh token to obtain a new access token.
OAuth FlowsA user must be authenticated before accessing Database.com. OAuth has multiple authentication flows. There are severalsteps in each authentication flow, as dictated by the OAuth standard and the type of application trying to access Database.com.On successful authorization, the client application is provided with access and refresh tokens.
Database.com supports the following flows for use with the Chatter REST API:
• Web server flow• User-agent flow
In addition, you can also use the refresh token to get a new access token after your application has been authorized for access.
Revoking AccessAfter users have been granted access to a client application, they can revoke access by clicking Revoke in the Connected Appssection of their Personal Information page.
Understanding the Web Server OAuth Authentication FlowTypically this flow is used by web applications that can confidentially store the client secret. A critical aspect of the Web serverflow is that the application must be able to protect the consumer secret.
The following is the general flow. The individual step descriptions follow.
28
Understanding the Web Server OAuth Authentication FlowIntroducing Chatter REST API
The following is a general description of the OAuth web-server flow:
1. To request authorization for a resource, the client application redirects the end-user’s browser to a web page hosted on theresource owner’s authorization server. In this case, it is the Database.com log in page.
2. The end-user logs into Database.com to authenticate themselves. Since this web page is hosted by the resource owner(Database.com) and interacted with directly by the end user, the client web application never finds out the user’s logincredentials. The end-user also grants authorization to the client application.
3. Database.com sends the authorization code back to the client application using the specified callback URL.4. After obtaining the authorization code, the client application passes back the authorization code to obtain an access token.5. After validating the authorization code, Database.com passes back a response token. If there was no error, the response
token includes an access code, a refresh token, and additional information.6. The protected resources are Chatter REST API endpoints.
Using the Web Server Flow with Chatter REST API and Database.comThe following provides specific details for the OAuth Web-server flow when used with Database.com and Chatter RESTAPI:
1. Direct the client’s web browser to the page https://login.instance_name/services/oauth2/authorize, withthe following request parameters:
29
Understanding the Web Server OAuth Authentication FlowIntroducing Chatter REST API
DescriptionParameter
Must be code for this authentication flowresponse_type
The Consumer Key value from the remote accessapplication defined for this application
client_id
The Callback URL value from the remote accessapplication defined for this application
redirect_url
You can also include the following optional request parameters:
DescriptionParameter
Specifies URL-encoded state data to be returned in thecallback URL after approval.
state
Determines whether the user should be prompted for loginand approval. Values are either true or false. Default isfalse.
immediate
• If set to true, and if the user is currently logged in andhas previously approved the application, the approvalstep is skipped.
• If set to true and the user is not logged in or has notpreviously approved the application, the session isimmediately terminated with theimmediate_unsuccessful error code.
Indicates the type of web pages that is provided. Valid valuesare:
display
• page—Full-page authorization screen. This is the defaultvalue if none is specified.
• popup—Compact dialog optimized for modern webbrowser popup windows.
• touch—mobile-optimized dialog designed for modernsmartphones such as Android and iPhone.
• mobile—mobile optimized dialog designed for lesscapable smartphones such as BlackBerry OS 5.
2. After successfully being logged in, the user is asked to authorize the application. Note that if the user has already authorizedthe application, this step is skipped.
3. Once Database.com has confirmed that the client application is authorized, the end-user’s web browser is redirected tothe callback URL specified by the redirect_url parameter, appended with the following values in its query string:
DescriptionParameter
The authorization code that is passed to get the access andrefresh tokens
code
The state value that was passed in as part of the initialrequest, if applicable.
state
It is expected that the redirect_uri web page is hosted by the client application server.
30
Understanding the Web Server OAuth Authentication FlowIntroducing Chatter REST API
4. The client application server must extract the authorization code and pass it in a request to Database.com for an accesstoken. This request should be made as a POST against this URL:https://login.instance_name/services/oauth2/token with the following query parameters:
DescriptionParameter
Value must be authorization_code for this flow.grant_type
Consumer key from the remote access application definition.client_id
Consumer secret from the remote access applicationdefinition.
client_secret
URI to redirect the user to after approval. This must matchthe value in the Callback URL field in the remote access
redirect_uri
application definition exactly, and is the same value sent bythe initial redirect.
Authorization code obtained from the callback after approval.code
Expected return format. This parameter is optional. Thedefault is json. Values are:
format
• urlencoded
• json
• xml
5. If this request is successful, the server returns a response body holding the following:
DescriptionParameters
Session ID that you can use for making Chatter REST APIrequests. This session ID cannot be used in the user interface.Treat this like a user's session and diligently protect it.
access_token
Token that can be used in the future to obtain new accesstokens (sessions).
refresh_token
Warning: This value is a secret. You should treatit like the user's password and use appropriatemeasures to protect it.
URL indicating the instance of the user's organization. Inthis example, the instance is na1:https://na1.database.com
instance_url
Identity URL that can be used to both identify the user aswell as query for more information about the user. Can be
id
used in an HTTP request to get more information aboutthe end user.
Base64-encoded HMAC-SHA256 signature signed withthe consumer's private key containing the concatenated ID
signature
and issued_at. This can be used to verify the identityURL was not modified since it was sent by the server.
When the signature was created.issued_at
31
Understanding the Web Server OAuth Authentication FlowIntroducing Chatter REST API
Understanding the User-Agent OAuth Authentication FlowTypically this flow is used by mobile apps or applications that directly access the Chatter REST API from JavaScript. In thisflow, it is assumed that the client application can’t be trusted to store client credentials, nor the user login credentials.
Warning: Because the access token is encoded into the redirection URI, it might be exposed to the end-user andother applications residing on the computer or device.
If you are authenticating using JavaScript, we recommend calling window.location.replace(); to remove thecallback from the browser’s history.
The following is the general flow. The individual step descriptions follow.
The following is a general description of the OAuth user-agent flow:
1. To request authorization for a resource, the client application redirects the end-user’s browser to a Web page hosted onthe resource owner’s authorization server. In this case, it’s the Database.com login page.
2. The end-user logs into Database.com to authenticate themselves. Since this Web page is hosted by the resource owner(Database.com) and interacted with directly by the end user, the client Web application never finds out the user’s logincredentials.
If the client application is running in the browser already, the browser can just be redirected. If the client application is amobile app, a browser must be opened (such as an UIWebView in iOS). The end-user uses this web page to authenticatethemselves and then grant authorization to the client application.
3. Once authorization has been granted, the authorization server redirects the end-user’s Web browser to a redirection URL.This URL can be used by the client application to retrieve the access and refresh tokens.
32
Understanding the User-Agent OAuth Authentication FlowIntroducing Chatter REST API
4. The protected resources are Chatter REST API resources.
Using the User-Agent Flow with Chatter REST API and Database.comThe following provides specific details for the OAuth user-agent flow when used with Database.com and Chatter REST API:
1. Direct the client’s Web browser to the page https://login.instance_name/services/oauth2/authorize, withthe following request parameters:
DescriptionParameter
Must be token for this authentication flowresponse_type
The Consumer Key value from the remote accessapplication defined for this application
client_id
The Callback URL value from the remote accessapplication defined for this application
redirect_url
You can also include the following optional request parameters:
DescriptionParameter
Indicates the type of Web page that’s provided. Valid valuesare:
display
• page—Full-page authorization screen. This is the defaultvalue if none is specified.
• popup—Compact dialog optimized for modern Webbrowser popup windows.
• touch—mobile-optimized dialog designed for modernsmartphones such as Android and iPhone.
• mobile—mobile optimized dialog designed for oldersmartphones such as BlackBerry OS 5.
Specifies what data your app can access. You do not have tospecify any value to access Chatter REST API If you specifyany values, you must include the chatter_api value.
scope
Specifies URL-encoded state data to be returned in thecallback URL after approval.
state
2. After successfully logging in, the user is asked to authorize the application. Note that if the user has already authorized theapplication, this step is skipped.
3. Once Database.com has confirmed that the client application is authorized, the end-user’s Web browser is redirected tothe callback URL specified by the redirect_uri parameter, appended with the following values after the hash sign (#).This is not a query string.
DescriptionParameters
Session ID that you can use for making Chatter REST APIrequests. This session ID cannot be used in the user interface.Treat this like a user's session and diligently protect it.
access_token
Amount of time the access token is valid, in seconds.expires_in
33
Understanding the User-Agent OAuth Authentication FlowIntroducing Chatter REST API
DescriptionParameters
Token that can be used in the future to obtain new accesstokens (sessions).
refresh_token
Warning: This value is a secret. You should treatit like the user's password and use appropriatemeasures to protect it.
The refresh token is only returned if the redirect URI ishttps://login.instance_name/services/oauth2/successor used with a custom protocol that is not HTTPS.
The following additional parameters are returned; however, they aren't used with this flow and Chatter REST API:
• instance_url
• id
• signature
• issued_at
4. If the client application is a Web app, the redirection Web page that it uses may include JavaScript that the client applicationcan manipulate in order to retrieve the access and refresh tokens.
Alternatively, a client application (native or web) may use the pagehttps://login.instance_name/services/oauth2/success as their callback URL. Instead of actually loadingthe page on redirect, they should intercept the redirection URI and extract the parameters values. Note that therefresh_token parameter values are only provided if the redirection URI is this URI or if the redirection URI uses acustom protocol.
Once the client application has retrieved the access and refresh tokens, it can use them to make requests to Chatter RESTAPI.
Using TokensAs part of both authentication flows, you will be working with access tokens and refresh tokens.
Using Access TokensTo make a successful Chatter REST API request, you must include a valid access token in the request. This can be done byusing the HTTP Authorization header:
Authorization: OAuth <access token>
If the request yields an error response due to an expired token, the refresh token can be used to get a new access token.
If the request yields an error because an access token has been revoked, the client application must be re-authorized by theuser in order to gain access.
Using Refresh TokensIf the client application has a refresh token, it can use it to send a request for a new access token.
To ask for a new access token, the client application should send a POST request tohttps://login.instance_name/services/oauth2/token with the following query parameters:
34
Using TokensIntroducing Chatter REST API
DescriptionParameters
Value must be refresh_token for this flow.grant_type
The refresh token the client application already received.refresh_token
Consumer key from the remote access application definition.client_id
You can also include the following optional parameters:
DescriptionParameters
Consumer secret from the remote access application definition.client_secret
Expected return format. The default is json. Values are:format
• urlencoded
• json
• xml
If this request is successful, the server returns a payload holding the access_token.
The following additional parameters are also returned, however, they aren't used with this flow and Chatter REST API:
• instance_url
• id
• signature
• issued_at
Requesting Static Assets and Posting Forms Directly from HTMLHTML pages that aren’t hosted on Salesforce have had difficulty displaying user and group images and posting file attachmentsin forms. The reason is that URLs for these assets require authentication, which is provided with a session cookie when pagesare hosted on Salesforce. Pages not hosted on Salesforce don't have access to the session cookie. Also, it isn’t possible to passan OAuth token from the HTML contexts <img>, <a>, and <form>.
To solve this problem, request self-authenticating bearer token URLs. A bearer token URL is a Chatter REST API resourcewith an appended bearer token that provides access to the resource. Use bearer token URLs in <img>, <a>, and <form> tagsto do the following:
• Request static Chatter REST API assets such as Chatter user profile images, files, and file and dashboard previews.• Post form requests to Chatter REST API when files are attached, for example, feed items or comments with a file
attachment, or user profile photo updates.
To request static assets or post form requests, request a resource that returns a bearer token URL. Then use the bearer tokenURL to request the resource.
1. Request a resource with a response body property that contains a bearer token URL:
• Comment Page—currentPageUrl*• Feed—feedItemsUrl*• Feed Item—photoUrl
• Feed Item Attachment-Content—downloadUrl, renditionUrl• Feed Item Attachment-Dashboard—fullSizeImageUrl, thumbnailUrl• File Detail—downloadUrl, renditionUrl, renditionUrl240By180, renditionUrl720By480• File Summary—downloadUrl, renditionUrl, renditionUrl240By180, renditionUrl720By480
35
Requesting Static Assets and Posting Forms Directly fromHTML
Introducing Chatter REST API
• File Summary Page—currentPageUrl*• Icon—url
• Mention Completion—photoUrl
• Photo—largePhotoUrl, smallPhotoUrl, url*
*Use to POST or PUT for new items that include binary files: for example, a feed item or comment with a file attachment.
2. Pass the X-Connect-Bearer-Urls request header with a value of true:
X-Connect-Bearer-Urls: true
3. Parse the bearer token URL from the response body and use it in an HTML tag to request a static asset or to post a formrequest.
Bearer token URLs have the following characteristics:
• The bearer token is good for the given URL only. Adding or reordering query parameters invalidates the URL.• The bearer token has a time-to-live (TTL) of 20 minutes. If the token expires you must request it again.• The request to the bearer token URL authenticates as the user who requested the resource that returned the bearer
token URL.
36
Requesting Static Assets and Posting Forms Directly fromHTML
Introducing Chatter REST API
Chapter 2
Quick Start
Connect to Database.com and authenticate, then make a request to ChatterREST API and look at the response.
In this chapter ...
• Prerequisites• Step One: Obtain a Database.com
Developer Edition Organization• Step Two: Set Up Authorization• Step Three: Connect to Chatter
REST API Using OAuth
37
PrerequisitesComplete these prerequisites before you begin the quick start.
Become familiar with:
• cURL, which is a command-line tool the quick start uses as the client application that makes HTTP requests toDatabase.com. cURL is pre-installed on many Linux and Mac systems. Windows users can download a version atcurl.haxx.se/. When using HTTPS on Windows, ensure that your system meets the cURL requirements for SSL.
Note: cURL is an open source tool and is not supported by salesforce.com.
• JavaScript Object Notation (JSON), which is the data format returned in this quick start.
• OAuth 2.0, which is the framework Database.com uses for authentication. The quick start provides the steps, but it wouldbe helpful to familiarize yourself with OAuth terms and concepts.
Step One: Obtain a Database.com Developer Edition OrganizationIf you are not already a member of the Force.com developer community, go to http://developer.force.com/joinand follow the instructions for signing up for a Developer Edition organization. Even if you already have Enterprise Edition,Unlimited Edition, or Performance Edition, use Developer Edition for developing, staging, and testing your solutions againstsample data to protect your organization’s live data. This is especially true for applications that insert, update, or delete data(as opposed to simply reading data).
If you already have a Developer Edition organization, verify that you have the “API Enabled” permission. This permission isenabled by default, but may have been changed by an administrator. For more information, see the help in the Database.comuser interface.
Step Two: Set Up AuthorizationCreate a connected app in a Database.com organization and enable OAuth. The client application uses the connected app toconnect to Database.com.
1. In your Developer Edition organization, from Setup, click Create > Apps, and in the Connected Apps section, click Newto create a new connected app.
Clients can use a connected app to sign in to any organization, even if the connected app isn’t defined in that organization.
2. Enter a connected app name.3. Enter the contact email, as well as any other required information.4. Select Enable OAuth Settings.5. Enter a Callback URL. It must be secure: http:// does not work, only https:// works.
For this quick start, you can simply enter https://.6. Enter an OAuth scope. Select Access and manage your Chatter feed in addition to any other scope you want
your connected app to allow access to.7. Click Save.
The Consumer Key is created and displayed, and a Consumer Secret is created (click the link to reveal it).
38
PrerequisitesQuick Start
Step Three: Connect to Chatter REST API Using OAuthUse OAuth to connect to Database.com and get an access token. Pass the access token in requests to Chatter REST API.
Complete Step Two: Set Up Authorization and create a connected app before starting this task.
This table maps the terms used in the connected app you created to the OAuth properties used in the examples. The OAuth2.0 specification uses the word “client” instead of “consumer.”
Value in ExampleConnected App Application Label
client_idConsumer Key
client_secretConsumer Secret
Note: This quick start uses the username-password OAuth authentication flow. The username-password authenticationflow passes the user’s credentials back and forth. Use this authentication flow only when necessary, such as in thisquick start. No refresh token will be issued.
To make a request to Database.com, substitute values from your organization into these examples:
1. Generate the access token.
This cURL command generates an access token:
curl --form client_id=3MVG9PhR6g6B7ps4xDycwGrI4PvjVZvK9--form client_secret=8870355475032095511--form grant_type=password--form username=admin@seattleapps.com--form password=1Lsfdc!https://login.database.com/services/oauth2/token
Tip: To paste a multi-line command into a Mac or Linux command line interface, escape each line with a backslash(“\”) to indicate that the command continues on the next line. An escaped line looks like this:
curl --form client_id=3MVG9PhR6g6B7ps4xDycwGrI4PvjVZvK9 \
To paste a multi-line command into the Windows Command Prompt, escape each line with a caret (“^”). Anescaped line looks like this:
curl --form client_id=3MVG9PhR6g6B7ps4xDycwGrI4PvjVZvK9 ^
The response includes the server instance and the access token:
{"id":"https://login.database.com/id/00DD0000000FJ6TMAW/
005D0000001B5T4IAK","issued_at":"1302907727777","instance_url":"https://na1.database.com","signature":"5jcevY5fUai0lWntuSxkwBzWcvRjd01RCOkIBZpyGv0=","access_token":"00DD0000000FJ6T!AQkAQPde_DMF2vGzddfZmBRS95GojDbtA
rKkgukAgZP0OVFYY5KkAqhLw9ejeKIlpJ3FgwGAWeRlBiWRt8mfXEuAZGbZNosk"}
39
Step Three: Connect to Chatter REST API Using OAuthQuick Start
2. To request a Chatter REST API resource, use the returned instance_url as the server instance. Pass the returnedaccess_token as a Bearer token in the Authorization request header.
curl -X GET https://na1.database.com/services/data/v30.0/chatter/users/me-H 'Authorization: Bearer 00DD0000000FJ6T!AQkAQPde_DMF2vGzddfZmBRS95GojDbtArKkgukAgZP0OVFYY5KkAqhLw9ejeKIlpJ3FgwGAWeRlBiWRt8mfXEuAZGbZNosk'
This example uses these values:
ValueProperty
na1.database.comServer instance
3MVG9PhR6g6B7ps4xDycwGrI4PvjVZvK9client_id
8870355475032095511client_secret
password
The value of grant_type depends on the OAuthauthentication flow you are using.
grant_type
admin@seattleapps.comusername
1Lsfdc!password
40
Step Three: Connect to Chatter REST API Using OAuthQuick Start
Chapter 3
Chatter REST API: How do I. . .
• Filter a response body?
• Post a feed item?
• Post a comment to feed item?
• Post a comment or feed item with an @mention?
• Post a comment or feed item with multiple @mentions?
• Get a list of @mention proposals?
• Like a feed item?
• Like a feed item and return the total number of likes?
• Share a feed item?
• Get feed items updated since the last request?
• Poll my news feed for updates?
• Get my news feed?
• Get a group feed?
• Get a feed with internal feed items only?
• Search a feed?
• Get the list of records a specific user follows?
• Get Chatter activity statistics for a user?
• Get recommendations of people to follow?
• Create a group?
• Update and crop a group photo?
• Join a group?
• Request to join a private group?
• Approve or reject a request to join a private group?
• Post to a group?
• Follow a record?
• Unfollow a record?
• Get feed items posted to a record?
• Update a user profile?
• Update and crop a user photo?
• Send a private message?
• Retrieve all the information for a list of users?
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. Whenaccessing a resource, you can use either a request body or request parameters. You cannot use both.
41
• 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
AllResource:
GETHTTP method:
NARequest body:
exclude, include, and filterGroup
Use the exclude and include query parameters to filter a response body when making arequest. The query value is a bar (|) delimited list of properties. URL encode the bar as %7C.Use a forward slash (/) before each property name.
Request parameter:
Use the filterGroup query parameter to specify whether to return a Big, Medium, orSmall response body. Every property in every response body is assigned one of these groupsizes.
This News Feed URL resource:/chatter/users/me?include=/aboutMe%7C/address
Request body example:
Returns this for the Feed response body:
{"aboutMe": "Salesforce Administrator and Citizen Developer","address": {
"city": "San Francisco","country": "US","formattedAddress": "1 Market St\nSan Francisco, CA
94105\nUS","state": "CA","street": "1 Market St","zip": "94105"
}}
For a detailed list of rules and examples, see Specifying Response Sizes.
A filtered response bodyReturns:
Post feed item
Use one of the feed resources, such as /chatter/feeds/news/userId/feed-items.Resource:
POSTHTTP method:
Feed Item InputRequest body:
textRequest parameter:
{ "body" :{
Request body example:
42
Chatter REST API: How do I. . .
"messageSegments" : [{"type": "Text","text" : "New post"
}]
}}
/services/data/v30.0/chatter/feeds/news/me/feed-items?text=New+post
Request parameterexample:
Feed ItemReturns:
Add comments
/chatter/feed-items/feedItemId/commentsResource:
POSTHTTP method:
Comment InputRequest body:
textRequest parameter:
{ "body" :{
Request body example:
"messageSegments" : [{"type": "Text","text" : "New comment"
}]
}}
/services/data/v30.0/chatter/feed-items/0D5D0000000DaSbKAK/comments?text=New+comment
Request parameterexample:
CommentReturns:
Post @mentions
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 theFeed-Items resource: /chatter/feed-items/feedItemId/comments
Resource:
POSTHTTP method:
The appropriate container input, such as comment input or feed-item input, with the messagesegment input: mention
Request body:
{ "body" :{
Request body example:
"messageSegments" : [{
43
Chatter REST API: How do I. . .
"type": "mention","id" : "005D0000001GpHp"
},{"type": "text","text" : " Did you see the new plans?"
}]
}}
Note: No spaces are added either before or after the @mention, so the text messagesegment includes a space.
Feed ItemReturns
Post multiple @mentions
To post a feed item with up to 25 mentions, use the News Feed resource, the Record Feedresource, or the User Profile Feed resource. To post a comment with up to 25 mentions,use the Feed Items Comment resource.
Resource:
POSTHTTP method:
Feed Item Input or Comment Input, with up to 25 Message Segment Input: Mentionbodies.
Request body:
{ "body" :{
Request body example:
"messageSegments" : [{
"type": "mention","id":"005D0000001LL8YIAW"
},{"type": "mention","id":"005D0000001LL8sIAG"
},{
"type": "text","text":" Did you see the new plans?"} ]
}]
}}
Note: No spaces are added either before or after the mention, so the text messagesegment includes a space.
Feed Item or CommentReturns
44
Chatter REST API: How do I. . .
Get a list of @mention proposals
Use the Mentions Completions resource to get a list of mention proposals:/chatter/mentions/completions. Use the Mentions Validations resource to determine
Resource:
which of those proposals are valid for the context user:/chatter/mentions/validations.
GETHTTP method:
contextId, page, pageSize, q, typeRequest parameters:
Mention Completion Page
Mention Validations
Returns:
Like feed items
/chatter/feed-items/feedItemId/likesResource:
POSTHTTP method:
NARequest body:
NARequest parameter:
/services/data/v30.0/chatter/feed-items/0D5D0000000DaZBKA0/likes
Example:
LikeReturns:
Like a feed item and return the total number of likes
/connect/batch/Resource:
POSTHTTP method:
NARequest parameter:
Batch InputRequest body:
{"batchRequests" : [
Request body example:
{"method" : "Post","url" : "/v30.0/chatter/feed-items/feedItemId/likes"
},{
"method" : "Get","url" : "/v30.0/chatter/feed-items/feedItemId"
}],"haltOnError" : "false"
}
Batch ResultsReturns:
45
Chatter REST API: How do I. . .
Share a feed item
Use one of the feed resources, such as/chatter/feeds/user-profile/userId/feed-items.
Resource:
POSTHTTP method:
originalFeedItemIdRequest body:
originalFeedItemIdRequest parameter:
{Request body example:
"originalFeedItemId": "0D5D0000000DaZBKA0"}
Feed ItemReturns:
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.
To get feed items that were updated since the last call to a feeds resource, make a requestto the value of the updatesUrl property of the Feed Item Page response body.
These feeds return an updatesUrl property:
Resource:
• 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 theupdatesUrl property:
{......"updatesUrl" : "/services/data/v30.0/chatter/feeds
/news/005D0000001LL8OIAW/feed-items?updatedSince=2:1384811809000"...}
A feed item is considered to be updated if it was created since the last feed request, or ifsort=LastModifiedDateDesc and a comment was added to the feed item since the lastfeed request. Adding likes and topics doesn’t update a feed item.
GETHTTP method:
NARequest body:
NARequest parameter:
NARequest body example:
46
Chatter REST API: How do I. . .
Feed Item PageReturns:
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 getinformation about the feed: /chatter/feeds/news/me/feed-items,/chatter/feeds/news/me.
The response bodies for both resources contain the isModifiedUrl property. Thisproperty contains the URL to the Is-Modified resource, which includes a since requestparameter that defines the last modified date of the feed. If the sort order of the requestto 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 thelast time you checked. Conditions under which this property is true depend on thesort order of the original request to the news feed. For example, if the feed is sortedby posts (CreatedDateDesc) and a comment was added, isModified is false.
• nextPollUrl—a string containing the URL of the Is-Modified resource. Thisproperty 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 Itemsresource to refresh the news feed.
4. If the isModified property is false, issue a GET request to the URL in thenextPollUrl property. This request also returns a Feed Modified Info response bodythat contains the isModified and nextPollUrl properties.
Note: We don’t recommend polling the news feed for updates more than once aminute.
GETHTTP method:
NARequest body:
NARequest parameter:
This News Feed URL resource:/chatter/feeds/news/005xx000001Sv1mAAB
Request body example:
Returns this for the Feed response body:
{"feedItemsUrl":
"/services/data/v30.0/chatter/feeds/news/005xx000001Sv1mAAB/feed-items",
"isModifiedUrl":"/services/data/v30.0/chatter/feeds/news/005xx000001Sv1mAAB/is-modified?since=2%3A1344352279000"
}
47
Chatter REST API: How do I. . .
The Is-Modified resource for polling this news feed is:
/chatter/feeds/news/005xx000001Sv1mAAB/is-modified?since=2%3A1344352279000
Feed Modified InfoReturns:
Get news feeds
This example gets the news feed of the current user.
/chatter/feeds/news/me/feed-itemsResource:
GETHTTP method:
NARequest body:
NARequest parameter:
/services/data/v30.0/chatter/feeds/news/me/feed-itemsExample:
Feed Item PageReturns:
Get a group feed
This example gets the feed of a group. Substitute recordId with the group ID.
/chatter/feeds/record/recordId/feed-itemsResource:
GETHTTP method:
NARequest body:
NARequest parameter:
/services/data/v30.0/chatter/feeds/record/0F9D00000000I4O/feed-itemsExample:
Feed Item PageReturns:
Get a record feed with internal feed items only
/chatter/feeds/record/recordId/feed-itemsResource:
GETHTTP method:
NARequest body:
showInternalOnlyRequest parameter:
/services/data/v30.0/chatter/feeds/record/0F9D00000000I4O/feed-items?showInternalOnly=trueExample:
Feed Item PageReturns:
48
Chatter REST API: How do I. . .
Search a feed
This example searches the record feed of the current user. Use the same q parameter to search any feed except the Topicsfeed. The search string can contain wildcards and must contain at least two characters that aren’t wildcards.
/chatter/feeds/record/me/feed-itemsResource:
GETHTTP method:
NARequest body:
qRequest parameter:
/services/data/v30.0/chatter/feeds/record/me/feed-items?q=track
Example:
Feed Item PageReturns:
Get list of what a user is following
/chatter/users/userId/followingResource:
GETHTTP method:
NARequest body:
page (optional)Request parameter:
/services/data/v30.0/chatter/users/005D0000001GLowIAB/following?page=1
Request parameterexample:
Subscription PageReturns:
Get Chatter activity statistics for a user
/chatter/users/userIdResource:
GETHTTP method:
NARequest body:
NARequest parameter:
/services/data/v30.0/chatter/users/005D0000001GLowIAB?include=/chatterActivity
Example:
User DetailReturns:
Get recommendations of users to follow
/chatter/users/me/recommendations/follow/usersResource:
GETHTTP method:
49
Chatter REST API: How do I. . .
NARequest body:
NARequest parameter:
/services/data/v30.0/chatter/users/me/recommendations/follow/users
Example:
RecommendationReturns:
Create a group
/chatter/groupsResource:
POSTHTTP method:
Group InputRequest body:
name, visibilityRequest parameters(required):
{"name" : "Chatter API",
Request body example:
"visibility" : "PublicAccess"}
/services/data/v30.0/chatter/groups?name=Chatter+API&visibility=PublicAccessRequest parameterexample:
Group DetailReturns:
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.
/chatter/group/groupId/photoResource:
POSTHTTP method:
cropSize, cropX, cropY, fileIdRequest parameters:
/services/data/v30.0/chatter/groups/0F9300000008ORJ/photo?cropSize=240&cropX=20&cropY=20&fileId=069D00000001IOh
Request parametersexample:
{ "cropSize" : "240","cropX" : "20",
Request body example:
"cropY" : "20","fileId" : "069D00000001IOh"
}
PhotoReturns:
50
Chatter REST API: How do I. . .
Join a group
/chatter/groups/groupId/membersResource:
POSTHTTP method:
Group Member InputRequest body:
userIdRequest parameter:
{"userId": "005D0000001GpHp" }Request body example:
/services/data/v30.0/chatter/groups/0F9D000000006bOKAQ/members?userId=005D0000001GpHp
Request parameterexample:
Group MemberReturns:
Request to join a private group
/chatter/groups/groupId/members/requestsResource:
POSTHTTP method:
NARequest body:
NARequest parameter:
NARequest body example:
/services/data/v30.0/chatter/groups/0F9D000000006bOKAQ/members/requests
Request parameterexample:
Group Membership RequestReturns:
Approve or reject a request to join a private group
/chatter/group-memberships-requests/requestIdResource:
PATCHHTTP method:
Group Membership Request UpdateRequest body:
status and responseMessage
The responseMessage parameter is used only if the value of status is Declined.
Request parameters:
{ "status " : "Accepted" }Request body example:
/services/data/v30.0/chatter/group-membership-requests/0I5D000000002fwKAA?status=Accepted
Request parameterexample:
Group Membership RequestReturns:
51
Chatter REST API: How do I. . .
Post to a group
/chatter/feeds/record/groupId/feed-itemsResource:
POSTHTTP method:
Feed Item InputRequest body:
TextRequest parameter:
{ "body" :{
Request body example:
"messageSegments" : [{"type": "Text","text" : "Check out the latest building proposal"
}]
}}
/feeds/record/0F9D000000006bO/feed-items?text=Has+everyone+seen+the+latest+building+proposal?
Request parameterexample:
Feed ItemReturns:
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 topicID.
/chatter/users/me/followingResource:
POSTHTTP method:
Following InputRequest body:
subjectIdRequest parameter:
{ "subjectId" : "001D000000Iyu2p" }Request body example:
/services/data/v30.0/chatter/users/me/following?subjectId=001D000000Iyu2p
Request parameterexample:
SubscriptionReturns:
Unfollow records
Note that a complete structured resource is not returned, just a return code.
/chatter/subscriptions/subscriptionIdResource:
DELETEHTTP method:
NARequest body:
NARequest parameter:
52
Chatter REST API: How do I. . .
/services/data/v30.0/chatter/subscriptions/0E8D00000001JkFKAUExample:
204: Successful DeleteReturns:
Get feed items for a record
/chatter/feeds/record/recordId/feed-itemsResource:
GETHTTP method:
NARequest body:
page (optional)Request parameter:
Note: Page tokens are returned as part of the response body, in one of the URLparameters, such as nextPageURL.
/services/data/v30.0/chatter/feeds/record/005x0000001oXx9AAE/feed-items?page=2011-03-31T20:57:24Z,0D5x0000001C2XPCA0
Request parameterexample:
Feed Item PageReturns:
Update a user profile
/chatter/users/userIdResource:
PATCHHTTP method:
aboutMeRequest parameter:
/services/data/v30.0/chatter/users/me?aboutMe=Writer+at+Salesforce
Request parametersexample:
User DetailReturns:
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.
/chatter/users/userId/photoResource:
POSTHTTP method:
cropSize, cropX, cropY, fileIdRequest parameters:
/services/data/v30.0/chatter/users/me/photo?cropSize=240&cropX=20&cropY=20&fileId=069D00000001IOh
Request parametersexample:
53
Chatter REST API: How do I. . .
{ "cropSize" : "240","cropX" : "20",
Request body example:
"cropY" : "20","fileId" : "069D00000001IOh"
}
PhotoReturns:
Send a private message
/chatter/users/me/messages/Resource:
POSTHTTP method:
User MessageRequest body:
recipients OR inReplyTo
text
Request parameter:
{ "body" : "Are we ready for next week's customer meeting?","recipients" : ["005D0000001GOYpIAO", "005D0000001GbdHIAS"]
}
Request body example:
/services/data/v30.0/chatter/users/me/messages?recipients=005D0000001GOYpIAO,005D0000001GbdHIAS&text=Are+we+ready+for+next+week's+customer+meeting?
Request parametersexample:
MessageReturns:
Return all user information for multiple users
/chatter/users/batch/user_list where user_list is a list of user Ids. Your appmay need to call Chatter REST API twice: once to get the feed items and user Ids, thesecond time to call this resource with the list of user Ids.
Resource:
GETHTTP method:
NARequest parameter:
/services/data/v30.0/chatter/users/batch/005D0000001Kl6xIAC,005D0000005J3D4HVB, . . .
Request parametersexample:
Batch ResultsReturns:
54
Chatter REST API: How do I. . .
Chapter 4
Chatter REST API Resources
Batch Resource
Create a request body with a batch of up to 25 subrequests and send them to the server in a single request to improve yourapplication’s performance. The response bodies and HTTP statuses for each subrequest in the batch are returned within asingle response body. Each subrequest counts against rate limits.
Chatter Resource
A directory of Chatter feeds, groups, and users resources.
Comments Resources
Information about the specified comment. Also used to delete a comment, or to like a comment.
Communities Moderation Resources
Information about whether a user has flagged a feed item, comment, or file as inappropriate. Also used to delete flags.
Connect Resources
Information about all /connect resources, and information about the logged-in user’s organization and settings.
Feeds Resources
Feeds are made up of feed items. There are many feed types. Each feed type has an algorithm that determines which feeditems it contains.
Feed Items Resources
Information about feed items. Access, search, delete, bookmark, and like feed items. Access and post comments. Access andvote in polls. And access, add, and remove topics.
Files Resources
Information about the specified file, including content, rendered version, and sharing.
Folders Resources
Information about a folder or the contents of a folder. Modify and delete folders and add items to folders. Folders resourcesare available through a pilot program in version 30.0.
Groups Resources
Information about groups, such as the group's members, photo, and the groups in the organization. Create and delete agroup, add members to a group, and change the group photo.
Influence Resource
List of the percentile thresholds used to categorize an organization’s users by their influence in Chatter.
Likes Resource
Information about the specified like. Also used to delete a like.
55
Mentions Resources
Information about users and groups that a user can mention in a feed item body or comment body. When a user or groupis mentioned, they receive notification.
Motifs Resources
Returns URLs for sets of small, medium, and large motif icons. Records have different sets of motif icons depending on therecord type. The motif can also include the record type’s base color.
Record View Resources
A view of records that includes both data and metadata.
Records Resources
Information about the specified record, including its followers and assigned topics. Add and remove topics from records.
Subscriptions Resource
Information about the specified subscription. Also used to delete a subscription, for example, to unfollow a record or a topic.
Topics Resources
List of topics for the organization, list of suggested topics for a specified string of text, feed item, or record, list of trendingtopics for the organization, information about a specified topic, endorsements for a specific topic, information about the filesposted recently to a specified topic, information about the groups recently contributing to a specified topic, knowledgeablepeople for a specified topic, and list of topics related to a specified topic.
User Profiles Resource
Returns details about a user’s profile. This data includes user information (such as address, manager, and phone number),some user capabilities (permissions), and a set of subtab apps, which are custom tabs on the profile page.
Users Resources
Information about the user, such as who is following the user, the user’s files or recommendations. Also used for postingfeed items and updating conversation status.
Zones Resources
Information about Chatter Answers zones.
Batch ResourceCreate a request body with a batch of up to 25 subrequests and send them to the server in a single request to improve yourapplication’s performance. The response bodies and HTTP statuses for each subrequest in the batch are returned within asingle response body. Each subrequest counts against rate limits.
Use this resource to minimize the number of round-trips between the client and the server. For example, in a mobile app,when a user taps the button to like a feed item, the response body includes information about the like, but it doesn’t includethe total number of likes on the feed item. To like the feed item, POST a request to/chatter/feed-items/feedItemId/likes. To get the like total, GET the feed item information from/chatter/feed-items/feedItemId.
Add both requests to a Batch Input request body and send them both in a single POST request to /connect/batch:
{"batchRequests" : [{
"method" : "Post","url" : "/v30.0/chatter/feed-items/feedItemId/likes"
},
56
Batch ResourceChatter REST API Resources
{"method" : "Get","url" : "/v30.0/chatter/feed-items/feedItemId"
}],"haltOnError" : "false"
}
The requests in a batch are called subrequests. All subrequests are executed in the context of the same user. Subrequests areindependent and information can’t be passed between them. Subrequests execute serially in their order in the request body.When a subrequest executes successfully, it commits its data. Commits are reflected in the output of later subrequests (as inthe previous example which liked a feed-item then got the total number of likes). If a subrequest fails, commits made byprevious subrequests are not rolled back.
To upload a binary file with a subrequest, send it as a body part in a multipart/form-data request and include informationabout the file in the richInput object in the request body. See Uploading Binary Files on page 9.
Resource
/connect/batch
Available since version28.0
HTTP methodsPOST
Request bodyBatch Input
Root XML Tag<batch>
JSON
{"batchRequests" : [{
"method" : "Get","url" : "/v28.0/chatter/feeds/news/me"
},{
"method" : "Get","url" : "/v28.0/chatter/feeds/user-profile/me"
}]
}
Properties
AvailableVersion
DescriptionTypeName
28.0Collection of Batch Request Input requestbodies containing the subrequest URLsto execute.
Batch Request Input[]batchRequests
57
Batch ResourceChatter REST API Resources
AvailableVersion
DescriptionTypeName
28.0The default value is false.
If the value is false and a subrequest inthe batch does not complete,
BooleanhaltOnError
Database.com attempts to executesubsequent subrequests in the batch.
If the value is true and a subrequest inthe batch does not complete due to anHTTP response in the 400 or 500 range,Database.com halts execution. It does notattempt to execute subsequent subrequestsin the batch, and it returns an HTTP 412status code and aBATCH_PROCESSING_HALTED errormessage for each subsequent subrequestindicating that a previous request wasunsuccessful. The top-level request to/connect/batch returns HTTP 200and the hasErrors property in theresponse is set to true.
Batch Request Input
Root XML Tag<request>
JSON
{"method" : "Get","url" : "/v28.0/chatter/feeds/news/me"
}
Properties
AvailableVersion
DescriptionTypeName
28.0The name of the binary part in themultipart request.
When there are multiple binary partsuploaded in one batch request, this value
StringbinaryPartName
is used to map a request to its binary part.To prevent name collisions, use a uniquevalue for each binaryPartName propertyin a batch request.
This property is optional. If this valueexists, a binaryPartNameAlias valuemust also exist.
58
Batch ResourceChatter REST API Resources
AvailableVersion
DescriptionTypeName
28.0The name parameter in theContent-Disposition header of the binary
StringbinaryPartNameAlias
body part. Different resources expectdifferent values. See Uploading BinaryFiles.
This property is optional. If this valueexists, a binaryPartName value mustalso exist.
28.0The HTTP method of the request. Oneof these values:
Stringmethod
• Delete• Get• Head• Patch• Post• Put
28.0The input body for the request.
The type depends on the request specifiedin the url property.
richInput
This property is optional.
28.0The Chatter API resource to request. Thisvalue is called a subrequest.
The subrequest URL can start with:
Stringurl
• /services/data/version, forexample, /services/data/v30.0/chatter/users/me.
• /version, for example,/v30.0/chatter/users/me. Theversion number must be less than orequal to the version of the requestgiven to the /connect/batchrequest URL.
Additional information about subrequests:
• The URL can include any query stringparameters that the subrequestsupports. The query string must beURL-encoded.
• You can use parameters to filterresponse bodies.
• You cannot apply headers at thesubrequest level.
59
Batch ResourceChatter REST API Resources
Request parametersNone.
ResponseBatch Results
ExampleThis simple example is a POST request made tohttps://instance_name/services/data/v30.0/connect/batch that includes the following request bodycontaining two subrequests:
{"batchRequests" : [{
"method" : "Get","url" : "/v30.0/chatter/feeds/user-profile/me"
},{
"method" : "Get","url" : "/v30.0/chatter/feeds/news/me"
}]
}
The Batch Results response body includes a Batch Result Item response body for each subrequest:
{"hasErrors": false,"results": [
{"result": {
"feedItemsUrl": "/services/data/v30.0/chatter/feeds/user-profile/005D0000001LL8OIAW/feed-items",
"isModifiedUrl": null},"statusCode": 200
},{
"result": {"feedItemsUrl": "/services/data/v30.0/chatter/feeds
/news/005D0000001LL8OIAW/feed-items","isModifiedUrl": null
},"statusCode": 200
}]
}
Example: haltOnError is trueThis example is the same as the previous example but it includes an error in the first subrequest and haltOnError isset to true. Note that the first subrequest contains a typo.
{"batchRequests" : [{
"method" : "Get","url" : "/v30.0/chatter/feeds/user-profile/men"
},{
"method" : "Get","url" : "/v30.0/chatter/feeds/news/me"
}
60
Batch ResourceChatter REST API Resources
],"haltOnError" : "true"
}
The Batch Results response body includes a Batch Result Item response body for each subrequest. The top-level requestto /connect/batch returns an HTTP 200, but the first subrequest returns an HTTP 404 because the resource can’tbe found. Because haltOnError is true, the next subrequest returns an HTTP 412. Also note that hasErrors istrue.
{"hasErrors": true,"results": [
{"result": [{
"errorCode": "NOT_FOUND","message": "The requested resource does not exist"
}],"statusCode": 404
},{
"result": [{"errorCode": "BATCH_PROCESSING_HALTED","message": "Batch processing halted per request"
}],"statusCode": 412
}]
}
Example: Uploading Binary FilesThis example is a batch request that contains two subrequests. Each subrequest creates a feed item and uploads a binaryfile attachment to it.
The POST request is made to https://instance_name/services/data/v30.0/connect/batch.
This is the multipart/form-data request body:
--123123Content-Disposition: form-data; name="json"Content-Type: application/json
{"haltOnError": "true","batchRequests": [
{"method": "Post","url": "/v30.0/chatter/feeds/news/me/feed-items","binaryPartName": "binaryPart0","binaryPartNameAlias": "feedItemFileUpload","richInput": {
"attachment": {"attachmentType": "NewFile","description": "description0","title": "contentFile0"
},"body": {
"messageSegments": [{
"type": "Text","text": "textValue0"
}]
}}
},
61
Batch ResourceChatter REST API Resources
{"method": "Post","url": "/v30.0/chatter/feeds/news/me/feed-items","binaryPartName": "binaryPart1","binaryPartNameAlias": "feedItemFileUpload","richInput": {
"attachment": {"attachmentType": "NewFile","description": "description1","title": "contentFile1"
},"body": {
"messageSegments": [{
"type": "Text","text": "textValue1"
}]
}}
}]
}--123123Content-Disposition: form-data; name="binaryPart0"; filename="file1.txt"Content-Type: application/octet-stream; charset=ISO-8859-1Content-Transfer-Encoding: binary
This is content of file 1--123123Content-Disposition: form-data; name="binaryPart1"; filename="file2.txt"Content-Type: application/octet-stream; charset=ISO-8859-1Content-Transfer-Encoding: binary
This is the content of file 2--123123--
Chatter ResourceA directory of Chatter feeds, groups, and users resources.
Resource
/chatter
Available since version23.0
HTTP methodsGET or HEAD
Response bodyChatter Directory
Example response body
{"feeds": "/services/data/v30.0/chatter/feeds","groups": "/services/data/v30.0/chatter/groups",
62
Chatter ResourceChatter REST API Resources
"users": "/services/data/v30.0/chatter/users"}
Comments ResourcesInformation about the specified comment. Also used to delete a comment, or to like a comment.
Available resources:
DescriptionResource
Returns information about the specified comment. Also usedto delete a comment.
/chatter/comments/commentId
Returns information about the likes for the specified comment.Also used to add a like to a comment.
/chatter/comments/commentId/likes
CommentReturns information about the specified comment. Also used to delete a comment.
Resource
/chatter/comments/commentId
Available since version23.0
HTTP methodsGET, DELETE or HEAD
Response body for GET or HEADComment
Example
You can find the ID for a specific comment from any feed, such as a news feed or a record feed.
Use the following resource and the HTTP method GET to return information about a comment:
/chatter/comments/0D7D00000000NtkKAE
The response is:
{"attachment": null,"body": {
"messageSegments": [{"tag": "allhands","text": "#allhands","topicUrl": "/services/data/v30.0/connect/topics?exactMatch=true&q=allhands",
"type": "Hashtag","url": "/services/data/v30.0/chatter/feed-items?q=%23allhands"
}],"text": "#allhands"
},
63
Comments ResourcesChatter REST API Resources
"clientInfo": null,"createdDate": "2013-01-16T01:06:28.000Z","feedItem": {
"id": "0D5D0000000JmV1KAK","url": "/services/data/v30.0/chatter/feed-items/0D5D0000000JmV1KAK"
},"id": "0D7D00000000PWAKA2","isDeleteRestricted": false,"likes": {
"currentPageUrl": "/services/data/v30.0/chatter/comments/0D7D00000000PWAKA2/likes",
"likes": [],"nextPageUrl": null,"previousPageUrl": null,"total": 0
},"likesMessage": null,"moderationFlags": null,"myLike": null,"parent": {
"id": "0F9D00000000I4OKAU","url": "/services/data/v30.0/chatter/groups/0F9D00000000I4OKAU"
},"relativeCreatedDate": "January 15, 2013 at 5:06 PM","type": "TextComment","url": "/services/data/v30.0/chatter/comments/0D7D00000000PWAKA2","user": {
"companyName": "Universal Containers","firstName": "Deanna","id": "005D0000001LL8OIAW","isActive": true,"isInThisCommunity": true,"lastName": "Li","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Deanna Li","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sa4idjK69Im5uTYfmFricjT",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/F","photoVersionId": "729D00000000LJFIA2","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/T","standardEmailPhotoUrl":
"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbMgjs7ldMuVclujIS-dbL9",
"url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW","userType": "Internal"
}}
Comment LikesReturns information about the likes for the specified comment. Also used to add a like to a comment.
64
Comments ResourcesChatter REST API Resources
Resource
/chatter/comments/commentId/likes
Available since version23.0
HTTP methodsGET, POST or HEAD
Request parameters for GET or HEAD
Note: POST takes no request parameters, nor a request body.
DescriptionTypeParameter Name
Specifies the number of the page youwant returned.
Integerpage
Specifies the number of items per page.Valid values are between 1 and 100. If
IntegerpageSize
you don't specify a size, the default is25.
Response body for GET or HEADLike Page
Response body for POSTLike
Communities Moderation ResourcesInformation about whether a user has flagged a feed item, comment, or file as inappropriate. Also used to delete flags.
Available resources are:
DescriptionResource
If the logged-in user is a community moderator with the“Moderate Communities Feeds” permission, returns the
/connect/communities/communityId/chatter/feed-items/feedItemId/moderation-flags
number of times a post has been flagged by communitymembers. Also flags a post for moderation and deletes all flagson a post.
If the logged-in user isn’t a community moderator, returnswhether or not the user has flagged a post. Also flags a postfor moderation and removes a flag the user previously added.
If the logged-in user is a community moderator, returns thenumber of times a comment has been flagged by community
/connect/communities/communityId/chatter/comments/commentId/moderation-flags
members. Also flags a comment for moderation and deletesall flags on a comment.
65
Communities Moderation ResourcesChatter REST API Resources
DescriptionResource
If the logged-in user isn’t a community moderator, returnswhether or not the user has flagged a comment. Also flags acomment for moderation and removes a flag the user previouslyadded.
Files that are flagged in a community.
If the logged-in user is a community moderator, returns thefiles that have been flagged by community members.
/connect/communities/communityId/chatter/files/moderation
If the logged-in user is a community moderator, returns thenumber of times a file has been flagged by community
/connect/communities/communityId/chatter/files/fileId/moderation-flags
members. Also flags a file for moderation and deletes all flagson a file.
If the logged-in user isn’t a community moderator, returnswhether or not the user has flagged a file. Also flags a file formoderation and removes a flag the user previously added.
Moderation Flags on PostsIf the logged-in user is a community moderator with the “Moderate Communities Feeds” permission, returns the number oftimes a post has been flagged by community members. Also flags a post for moderation and deletes all flags on a post.
If the logged-in user isn’t a community moderator, returns whether or not the user has flagged a post. Also flags a post formoderation and removes a flag the user previously added.
Resource
/connect/communities/communityId/chatter/feed-items/feedItemId/moderation-flags
Available since release29.0
HTTP methodsGET, DELETE, HEAD, POST
Request parameters for GET
AvailableVersion
RequiredorOptional
DescriptionTypeName
30.0OptionalSpecifies the visibility behavior of a flag for various user types.Stringvisibility
• ModeratorsOnly—The flag is visible only to users withmoderation permissions on the flagged item.
• SelfAndModerators—The flag is visible to the creatorof the flag and to users with moderation permissions onthe flagged item.
66
Communities Moderation ResourcesChatter REST API Resources
Request body for POST
Root XML tag<moderationFlag>
JSON
{"visibility" : "ModeratorsOnly"
}
Properties
Available VersionDescriptionTypeName
30.0Specifies the visibility behavior of a flag forvarious user types.
Stringvisibility
• ModeratorsOnly—The flag is visible onlyto users with moderation permissions onthe flagged item.
• SelfAndModerators—The flag is visibleto the creator of the flag and to users withmoderation permissions on the flagged item.
Request parameters for POST
AvailableVersion
RequiredorOptional
DescriptionTypeName
30.0OptionalSpecifies the visibility behavior of a flag for various user types.Stringvisibility
• ModeratorsOnly—The flag is visible only to users withmoderation permissions on the flagged item.
• SelfAndModerators—The flag is visible to the creatorof the flag and to users with moderation permissions onthe flagged item.
Request parameters for DELETE
AvailableVersion
Required orOptional
DescriptionTypeName
29.0OptionalThe ID of the logged-in user. If specified, removes the flagthe user previously added to the post. If not specified and the
StringuserId
logged-in user is a moderator for the community, all flags onthe post are removed.
Response body for GET and POSTModeration Flags
67
Communities Moderation ResourcesChatter REST API Resources
Moderation Flags on CommentsIf the logged-in user is a community moderator, returns the number of times a comment has been flagged by communitymembers. Also flags a comment for moderation and deletes all flags on a comment.
If the logged-in user isn’t a community moderator, returns whether or not the user has flagged a comment. Also flags acomment for moderation and removes a flag the user previously added.
Resource
/connect/communities/communityId/chatter/comments/commentId/moderation-flags
Available since release29.0
HTTP methodsGET, DELETE, HEAD, POST
Request parameters for GET
AvailableVersion
RequiredorOptional
DescriptionTypeName
30.0OptionalSpecifies the visibility behavior of a flag for various user types.Stringvisibility
• ModeratorsOnly—The flag is visible only to users withmoderation permissions on the flagged item.
• SelfAndModerators—The flag is visible to the creatorof the flag and to users with moderation permissions onthe flagged item.
Request body for POST
Root XML tag<moderationFlag>
JSON
{"visibility" : "ModeratorsOnly"
}
Properties
Available VersionDescriptionTypeName
30.0Specifies the visibility behavior of a flag forvarious user types.
Stringvisibility
• ModeratorsOnly—The flag is visible onlyto users with moderation permissions onthe flagged item.
68
Communities Moderation ResourcesChatter REST API Resources
Available VersionDescriptionTypeName
• SelfAndModerators—The flag is visibleto the creator of the flag and to users withmoderation permissions on the flagged item.
Request parameters for POST
AvailableVersion
RequiredorOptional
DescriptionTypeName
30.0OptionalSpecifies the visibility behavior of a flag for various user types.Stringvisibility
• ModeratorsOnly—The flag is visible only to users withmoderation permissions on the flagged item.
• SelfAndModerators—The flag is visible to the creatorof the flag and to users with moderation permissions onthe flagged item.
Request parameters for DELETE
AvailableVersion
RequiredorOptional
DescriptionTypeName
29.0OptionalThe ID of the logged-in user. If specified, removes the flagthe user previously added to the comment. If not specified
StringuserId
and the logged-in user is a moderator for the community, allflags on the comment are removed.
Response body for GET and POSTModeration Flags
Moderation Flags on FilesIf the logged-in user is a community moderator, returns the number of times a file has been flagged by community members.Also flags a file for moderation and deletes all flags on a file.
If the logged-in user isn’t a community moderator, returns whether or not the user has flagged a file. Also flags a file formoderation and removes a flag the user previously added.
Resource
/connect/communities/communityId/chatter/files/fileId/moderation-flags
Available since release30.0
69
Communities Moderation ResourcesChatter REST API Resources
HTTP methodsGET, DELETE, HEAD, POST
Request parameters for GET
AvailableVersion
RequiredorOptional
DescriptionTypeName
30.0OptionalSpecifies the visibility behavior of a flag for various user types.Stringvisibility
• ModeratorsOnly—The flag is visible only to users withmoderation permissions on the flagged item.
• SelfAndModerators—The flag is visible to the creatorof the flag and to users with moderation permissions onthe flagged item.
Request body for POST
Root XML tag<moderationFlag>
JSON
{"visibility" : "ModeratorsOnly"
}
Properties
Available VersionDescriptionTypeName
30.0Specifies the visibility behavior of a flag forvarious user types.
Stringvisibility
• ModeratorsOnly—The flag is visible onlyto users with moderation permissions onthe flagged item.
• SelfAndModerators—The flag is visibleto the creator of the flag and to users withmoderation permissions on the flagged item.
Request parameters for POST
AvailableVersion
RequiredorOptional
DescriptionTypeName
30.0OptionalSpecifies the visibility behavior of a flag for various user types.Stringvisibility
• ModeratorsOnly—The flag is visible only to users withmoderation permissions on the flagged item.
70
Communities Moderation ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeName
• SelfAndModerators—The flag is visible to the creatorof the flag and to users with moderation permissions onthe flagged item.
Request parameters for DELETE
AvailableVersion
RequiredorOptional
DescriptionTypeName
30.0OptionalThe ID of the logged-in user. If specified, removes the flagthe user previously added to the file. If not specified and the
StringuserId
logged-in user is a moderator for the community, all flags onthe file are removed.
Response body for GET and POSTModeration Flags
Flagged FilesFiles that are flagged in a community.
If the logged-in user is a community moderator, returns the files that have been flagged by community members.
Resource
/connect/communities/communityId/chatter/files/moderation
Available since release30.0
HTTP methodsGET, HEAD
Request parameters for GET
AvailableVersion
RequiredorOptional
DescriptionTypeName
30.0OptionalSpecifies the number of the page you want returned.Integerpage
30.0OptionalSpecifies the number of items per page. Valid values arebetween 1 and 100. If you don't specify a size, the default is25.
IntegerpageSize
71
Communities Moderation ResourcesChatter REST API Resources
Response bodyFile Summary
Connect ResourcesInformation about all /connect resources, and information about the logged-in user’s organization and settings.
Note: These resources have the base URL of /services/data/v30.0/connect, not/services/data/v30.0/chatter.
Available resources are:
DescriptionResource
List of all resources in the organization, as well as allcommunity resources available to the current user.
/connect
Information about the logged-in user’s organization andsettings.
/connect/organization
ConnectList of all resources in the organization, as well as all community resources available to the current user.
Resource
/connect
Available since version24.0
HTTP methodsGET and HEAD
Response bodyConnect Directory
OrganizationInformation about the logged-in user’s organization and settings.
Resource
/connect/organization
Available since version24.0
HTTP methodsGET or HEAD
Response bodyOrganization
72
Connect ResourcesChatter REST API Resources
Example response body
{"accessTimeout": 0,"features": {
"chatter": true,"chatterActivity": true,"chatterAnswers": true,"chatterGlobalInfluence": true,"chatterMessages": true,"chatterTopics": true,"communityModeration": true,"dashboardComponentSnapshots": true,"defaultCurrencyIsoCode": "USD","feedPolling": false,"files": true,"filesOnComments": true,"ideas": true,"multiCurrency": false,"publisherActions": false,"thanksAllowed": true,"trendingTopics": true,"viralInvitesAllowed": true
},"name": "Universal Containers","orgId": "00DD0000000Jhd2MAC","userSettings": {
"approvalPosts": true,"canFollow": true,"canModifyAllData": true,"canOwnGroups": true,"canViewAllData": true,"canViewAllGroups": true,"canViewAllUsers": true,"canViewFullUserProfile": true,"canViewPublicFiles": true,"currencySymbol": "$","externalUser": false,"fileSyncStorageLimit": null,"hasAccessToInternalOrg": true,"hasFileSync": false,"hasRestDataApiAccess": true,"timeZone": {
"gmtOffset": -7,"name": "Pacific Daylight Time"
},"userDefaultCurrencyIsoCode": null,"userId": "005D0000001LL8OIAW","userLocale": "en_US"
}}
See Also:News Feed Resources
Feeds ResourcesFeeds are made up of feed items. There are many feed types. Each feed type has an algorithm that determines which feeditems it contains.
The news feed, record feed, and user profile feed support GET and POST requests. All other feeds support GET requests.
73
Feeds ResourcesChatter REST API Resources
Bookmarks Feed Resources
A feed containing feed items saved as bookmarks by the logged-in user.
Communities Moderation Feed Resource
A feed containing feed items and comments that have been flagged for moderation in a community.
Company Feed Resources
A feed containing all feed-items and comments from an entire company.
Favorites Feed Resources
A feed containing favorites saved by the logged-in user.
Feeds Resource
A list of all of the feeds the logged-in user is able to view.
Files Feed Resources
A feed containing all the feed items that contain files posted by people or groups that the logged-in user follows.
Filter Feed Resources
The filter feed is the news feed filtered to contain feed items whose parent is a specified object type.
Groups Feed Resources
A feed containing all feed items from all groups the current user either owns or is a member of.
News Feed Resources
A feed containing items of interest to the logged-in user. You can post feed items to the news feed.
People Feed Resources
All feed items posted by all of the people the logged-in user follows.
Record Feed Resource
The feed of the specified record, which could be a group, person, object, file and so on. You can post feed items to the recordfeed.
To Feed Resources
A feed containing all @mentions of the logged-in user and posts others have made to the logged-in user's feed.
Topics Feed Resources
The feed of the specified topic.
User Profile Feed Resources
A feed containing actions by the current user on records that can be tracked in a feed. This feed is differentthan/chatter/feeds/news, which returns more items, including posts, group updates, and record updates. You can postfeed items to the user-profile feed.
See Also:Working with Feeds and Feed Items
Bookmarks Feed ResourcesA feed containing feed items saved as bookmarks by the logged-in user.
74
Bookmarks Feed ResourcesChatter REST API Resources
To bookmark an item, use PATCH with the Feed-Items resource and the isBookmarkedByCurrentUser parameter. Forexample:
/chatter/feed-items/0D5D0000000Ir6zKAC?isBookmarkedByCurrentUser=true
Available resources are:
DescriptionResource
Returns the URL for the bookmarks feed for the logged-inuser.
/chatter/feeds/bookmarks/me
Returns all feed items for all bookmarks for the logged-in user./chatter/feeds/bookmarks/me/feed-items
Bookmarks Feed URLReturns the URL for the bookmarks feed for the logged-in user.
Resource
/chatter/feeds/bookmarks/me
OR
/chatter/feeds/bookmarks/userId
Note: userId must be the ID of the logged-in user or the alias me.
Available since version24.0
HTTP methodsGET or HEAD
Request parameter
DescriptionTypeParameter Name
Specifies the order returned by the sort,such as by date created or last modified:
Stringsort
• CreatedDateDesc—Sorts thefeed items by most recent post date.
• LastModifiedDateDesc—Sortsthe feed items by most recentactivity, which includes new feeditems and comments.
The default value isCreatedDescDate.
Response bodyFeed
75
Bookmarks Feed ResourcesChatter REST API Resources
Bookmarks Feed ItemsReturns all feed items for all bookmarks for the logged-in user.
Resource
/chatter/feeds/bookmarks/me/feed-items
OR
/chatter/feeds/bookmarks/userId/feed-items
Note: userId must be the ID of the logged-in user or the alias me.
Available since version24.0
HTTP methodsGET or HEAD
Request parameters
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
29.0OptionalThe density of the feed. One of these values:Stringdensity
• AllUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of.
• FewerUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of, buthides system-generated posts from records thatnobody commented on.
The default value is AllUpdates.
23.0OptionalA generated token that indicates the view of feeditems in the feed. Page tokens are returned as part
Stringpage
of the response body, in one of the URLparameters, such as nextPageURL, for example:
"nextPageUrl":"/services/data/v30.0/chatter/feeds/news/005D0000001GLowIAN/feed-items?page=2011-03-30T17:34:50Z,0D5D0000000DSv4KAG"
23.0OptionalSpecifies the number of items per page. Validvalues are between 1 and 100. If you don't specifya size, the default is 25.
IntegerpageSize
76
Bookmarks Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
28.0OptionalOne or more keywords to search for in the bodyand comments of feed items in this feed.
The search string can contain wildcards and mustcontain at least two characters that aren’t wildcards.See Wildcards.
Stringq
29.0OptionalMaximum number of comments to include perfeed item. The default value is 3. The maximumvalue is 25.
IntegerrecentCommentCount
23.0OptionalSpecifies the order returned by the sort, such as bydate created or last modified:
Stringsort
• CreatedDateDesc—Sorts the feed items bymost recent post date.
• LastModifiedDateDesc—Sorts the feeditems by most recent activity, which includesnew feed items and comments.
The default value is CreatedDescDate.
Response bodyFeed Item Page
Bookmarks Feed Items FlatThis 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 commentsare at the same level. All items are returned in chronological order.
Resource
/chatter/feeds/bookmarks/me/feed-items/flat
or
/chatter/feeds/bookmarks/userId/feed-items/flat
Note: userId must be the ID of the logged-in user or the alias me.
Available since version25.0
HTTP methodsGET or HEAD
77
Bookmarks Feed ResourcesChatter REST API Resources
Request parameters
DescriptionTypeParameter Name
Specifies the number of feed itemsreturned. Valid values are between 0
IntegernumFeedItems
and 100. Default value is 25. Becausefeed items may include comments,specifying 25 flat feed items mayactually return more. For example, ifeach feed item has one comment, andrecentCommentCount is greater than1, 50 flat feed items are returned.
A generated token that indicates theview of feed items in the feed. Page
Stringpage
tokens are returned as part of theresponse body, in one of the URLparameters, such as nextPageURL.
Specifies the number of recentcomments returned. Valid values arebetween 0 and 25. Default value is 3.
IntegerrecentCommentCount
Sorts the returned feed either bycreated date in ascending order, or by
String. One of the following:sort
• CreatedDateDesclast modified date, also in ascending• LastModifiedDateDescorder. The default isLastModifiedDateDesc
Response bodyFlat Feed
See Also:Chatter REST API: How do I. . .Working with Feeds and Feed Items
Communities Moderation Feed ResourceA feed containing feed items and comments that have been flagged for moderation in a community.
Communities Moderation Feed ItemsIf the logged in user is a community moderator with the “Moderate Communities Feeds” permission, returns a list of all postsand comments in the community that have been flagged by community members. By default, returns 25 feed items per pageof results.
Resource/connect/communities/communityId/chatter/feeds/moderation/feed-items
Available since release29.0
78
Communities Moderation Feed ResourceChatter REST API Resources
HTTP methodsGET, HEAD
GET parameters
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
29.0OptionalA generated token that indicates the view of feeditems in the feed. Page tokens are returned as part
Stringpage
of the response body, in one of the URLparameters, such as nextPageURL, for example:
"nextPageUrl":"/services/data/v30.0/chatter/feeds/news/005D0000001GLowIAN/feed-items?page=2011-03-30T17:34:50Z,0D5D0000000DSv4KAG"
29.0OptionalSpecifies the number of items per page. Validvalues are between 1 and 100. If you don't specifya size, the default is 25.
IntegerpageSize
29.0OptionalOne or more keywords to search for in the bodyand comments of feed items in this feed.
The search string can contain wildcards and mustcontain at least two characters that aren’twildcards. See Wildcards.
Stringq
29.0OptionalSpecifies the order returned by the sort, such asby date created or last modified:
Stringsort
• CreatedDateDesc—Sorts the feed items bymost recent post date.
• LastModifiedDateDesc—Sorts the feeditems by most recent activity, which includesnew feed items and comments.
The default value is CreatedDescDate.
Response body for GETFeed Item Page
If a feed item has comments, the Comment Page response body contains a value in the total property to indicate thenumber of comments. However the comments property doesn’t contain a collection of comments. For example, thisexcerpt from a response shows a total of 2 comments, but no information about the comments:
"comments": {"comments": [],
"currentPageUrl": "/services/data/v30.0/connect/communities/0DBD000000002etOAA/chatter/feed-items/0D5D0000000LYi9KAG/comments",
"nextPageUrl": null,"total": 2
},
79
Communities Moderation Feed ResourceChatter REST API Resources
Example for GETThis example makes a GET request.
GET /connect/communities/0DBD000000002etOAA/chatter/feeds/moderation/feed-items
The response is a Feed Item Page response body.
{"currentPageUrl": "/services/data/v30.0/connect/communities/0DBD000000002etOAA
/chatter/feeds/moderation/feed-items","isModifiedToken": null,"isModifiedUrl": null,"items": [{
"actor": {"companyName": null,"firstName": "Abby","id": "005D0000001QdELIA0","isActive": true,"isInThisCommunity": true,"lastName": "Bass","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Abby Bass","photo": {
"fullEmailPhotoUrl":"https://instance_name/img/userprofile/default_profile_200.png?fromEmail=1",
"largePhotoUrl": "https://instance_name/profilephoto/005/F","photoVersionId": null,"smallPhotoUrl": "https://instance_name/profilephoto/005/T","standardEmailPhotoUrl":
"https://instance_name/img/userprofile/default_profile_45.png?fromEmail=1","url": "/services/data/v30.0/connect/communities/0DBD000000002etOAA
/chatter/users/005D0000001QdELIA0/photo"},"title": null,"type": "User","url": "/services/data/v30.0/connect/communities/0DBD000000002etOAA
/chatter/users/005D0000001QdELIA0","userType": "Internal"
},"attachment": null,"body": {
"messageSegments": [{"text": "All kinds of stuff is what I'm thinking about.","type": "Text"
}],"text": "All kinds of stuff is what I'm thinking about."
},"canShare": true,"clientInfo": null,"comments": {
"comments": [],"currentPageUrl": "/services/data/v30.0/connect/communities/0DBD000000002etOAA
/chatter/feed-items/0D5D0000000LYi9KAG/comments","nextPageUrl": null,"total": 2
},"createdDate": "2013-08-28T20:51:45.000Z","event": false,"id": "0D5D0000000LYi9KAG","isBookmarkedByCurrentUser": false,"isDeleteRestricted": false,
80
Communities Moderation Feed ResourceChatter REST API Resources
"isLikedByCurrentUser": false,"likes": {"currentPageUrl": "/services/data/v30.0/connect/communities/0DBD000000002etOAA
/chatter/feed-items/0D5D0000000LYi9KAG/likes","likes": [],"nextPageUrl": null,"previousPageUrl": null,"total": 0
},"likesMessage": null,"moderationFlags": {
"flagCount": 1,"flaggedByMe": false
},"modifiedDate": "2013-08-28T20:51:45.000Z","myLike": null,"originalFeedItem": null,"originalFeedItemActor": null,"parent": {
"companyName": null,"firstName": "Abby","id": "005D0000001QdELIA0","isActive": true,"isInThisCommunity": true,"lastName": "Bass","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Abby Bass","photo": {
"fullEmailPhotoUrl":"https://instance_name/img/userprofile/default_profile_200.png?fromEmail=1",
"largePhotoUrl": "https://instance_name/profilephoto/005/F","photoVersionId": null,"smallPhotoUrl": "https://instance_name/profilephoto/005/T","standardEmailPhotoUrl": "https://instance_name/img/userprofile
/default_profile_45.png?fromEmail=1","url": "/services/data/v30.0/connect/communities/0DBD000000002etOAA
/chatter/users/005D0000001QdELIA0/photo"},"title": null,"type": "User","url": "/services/data/v30.0/connect/communities/0DBD000000002etOAA
/chatter/users/005D0000001QdELIA0","userType": "Internal"
},"photoUrl": "https://instance_name/profilephoto/005/T","preamble": {
"messageSegments": [{"motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"reference": {
"id": "005D0000001QdELIA0","url": "/services/data/v30.0/connect/communities/0DBD000000002etOAA
/chatter/users/005D0000001QdELIA0"},"text": "Abby Bass","type": "EntityLink"
}],"text": "Abby Bass"
},
81
Communities Moderation Feed ResourceChatter REST API Resources
"relativeCreatedDate": "27m ago","topics": {
"canAssignTopics": true,"topics": []
},"type": "TextPost","url": "/services/data/v30.0/connect/communities/0DBD000000002etOAA
/chatter/feed-items/0D5D0000000LYi9KAG","visibility": "AllUsers"
}],"nextPageUrl": null
}
See Also:Chatter REST API: How do I. . .Working with Feeds and Feed Items
Company Feed ResourcesA feed containing all feed-items and comments from an entire company.
The company feed includes posts and comments from:
• People in the company, the ones a user follows and the ones a user doesn’t follow• Public groups, including the ones a user is not a member of• Private groups a user is a member of• Updates for records and fields that an administrator configured for feed tracking, including the ones a user is not following.
However, a user only sees updates for records they are allowed to access.
Please note the following:
• These resources are not available for communities.
Available resources are:
DescriptionResource
Returns a URL to the company feed./chatter/feeds/company
Returns the feed items of a company feed./chatter/feeds/company/feed-items
Company Feed URLReturns a URL to the company feed.
Resource
/chatter/feeds/company
Available since version23.0
HTTP methodsGET or HEAD
82
Company Feed ResourcesChatter REST API Resources
Request parameters
DescriptionTypeParameter Name
Specifies the order returned by the sort,such as by date created or last modified:
Stringsort
• CreatedDateDesc—Sorts thefeed items by most recent post date.
• LastModifiedDateDesc—Sortsthe feed items by most recentactivity, which includes new feeditems and comments.
The default value isCreatedDescDate.
Response bodyFeed
Example response body
{"feedItemsUrl": "/services/data/v30.0/chatter/feeds/company/feed-items","isModifiedUrl": null
}
Company Feed ItemsReturns the feed items of a company feed.
Resource
/chatter/feeds/company/feed-items
Available since version23.0
HTTP methodsGET or HEAD
Request parameters
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
29.0OptionalThe density of the feed. One of these values:Stringdensity
• AllUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of.
• FewerUpdates—Displays all posts andcomments from people and records the user
83
Company Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
follows and groups the user is a member of, buthides system-generated posts from records thatnobody commented on.
The default value is AllUpdates.
23.0OptionalA generated token that indicates the view of feeditems in the feed. Page tokens are returned as part
Stringpage
of the response body, in one of the URLparameters, such as nextPageURL, for example:
"nextPageUrl":"/services/data/v30.0/chatter/feeds/news/005D0000001GLowIAN/feed-items?page=2011-03-30T17:34:50Z,0D5D0000000DSv4KAG"
23.0OptionalSpecifies the number of items per page. Validvalues are between 1 and 100. If you don't specifya size, the default is 25.
IntegerpageSize
28.0OptionalOne or more keywords to search for in the bodyand comments of feed items in this feed.
The search string can contain wildcards and mustcontain at least two characters that aren’t wildcards.See Wildcards.
Stringq
29.0OptionalMaximum number of comments to include perfeed item. The default value is 3. The maximumvalue is 25.
IntegerrecentCommentCount
23.0OptionalSpecifies the order returned by the sort, such as bydate created or last modified:
Stringsort
• CreatedDateDesc—Sorts the feed items bymost recent post date.
• LastModifiedDateDesc—Sorts the feeditems by most recent activity, which includesnew feed items and comments.
The default value is CreatedDescDate.
30.0OptionalAn opaque token defining the modification timestamp of the feed and the sort order.
Do not construct this token. Retrieve this tokenfrom the updatesToken property of the FeedItem Page response body.
StringupdatedSince
84
Company Feed ResourcesChatter REST API Resources
Response bodyFeed Item Page
See Also:Chatter REST API: How do I. . .Working with Feeds and Feed Items
Favorites Feed ResourcesA feed containing favorites saved by the logged-in user.
Favorites are feed searches, list views, and topics that the logged-in user has added as a Chatter favorite.
Available resources are:
DescriptionResource
Returns all the favorites for the logged-in user. Creates afavorite of a Chatter feed search or topic.
/chatter/feeds/favorites/me
Returns the feed for the specified favorite. Deletes the specifiedfavorite. Updates the last view date of the specified favorite.
/chatter/feeds/favorites/me/favoriteId
Returns a filtered feed, only showing those feed items for thespecified favorite.
/chatter/feeds/favorites/me/favoriteId/feed-items
List of FavoritesReturns all the favorites for the logged-in user. Creates a favorite of a Chatter feed search or topic.
Resource
/chatter/feeds/favorites/me
or
/chatter/feeds/favorites/userId
Note: userId must be the ID of the logged-in user or the alias me.
Available since version24.0
HTTP methodsGET, HEAD, or POST
Request body for POST
Root XML tag<favorite>
85
Favorites Feed ResourcesChatter REST API Resources
JSON for POST
{"searchText" : "release","targetId" : "0TOD0000000099d"
}
Properties for POST
Available VersionDescriptionTypeName
24.0Text of the feed search. Usethis parameter for feedsearches only.
StringsearchText
28.0Id of the topic. Use thisparameter for topics only.
StringtargetId
Request parameters for POST
Available VersionDescriptionTypeName
24.0Text of the feed search. Usethis parameter for feedsearches only.
StringsearchText
28.0Id of the topic. Use thisparameter for topics only.
StringtargetId
Response body for GET or HEADFavorites Page
Response body for POSTFavorite
Sample response body for GET
{"favorites": [
{"community": null,"createdBy": {
"companyName": "Powell Industries","firstName": "Kristen","id": "005D0000001Gif0IAC","isActive": true,"isInThisCommunity": true,"lastName": "Powell","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Kristen Powell",
86
Favorites Feed ResourcesChatter REST API Resources
"photo": {"fullEmailPhotoUrl":
"https://instance_name/ncsphoto/g7O1xwgBO8dGwLadBRB8WWNbBNusiqjZbvaWEEu-3etqqIFpNksYLrC-v3JYOGjg",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000DbI/F",
"photoVersionId": "729D00000000DbIIAU","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000DbI/T",
"standardEmailPhotoUrl":"https://instance_name/ncsphoto/g7O1xwgBO8dGwLadBRB8WWNbBNusiqjZbvaWEEu-3esJvHV8sIzLNp4aqaFASciV",
"url": "/services/data/v30.0/chatter/users/005D0000001Gif0IAC/photo"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001Gif0IAC","userType": "Internal"
},"feedUrl":
"/services/data/v30.0/chatter/feeds/favorites/me/07FD00000000TOBMA2/feed-items","id": "07FD00000000TOBMA2","lastViewDate": "2013-02-13T18:21:47.000Z","name": "United","searchText": "united","target": null,"type": "Search","url": "/services/data/v30.0/chatter/feeds/favorites/me/07FD00000000TOBMA2","user": {
"companyName": "Powell Industries","firstName": "Kristen","id": "005D0000001Gif0IAC","isActive": true,"isInThisCommunity": true,"lastName": "Powell","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Kristen Powell","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/g7O1xwgBO8dGwLadBRB8WWNbBNusiqjZbvaWEEu-3etqqIFpNksYLrC-v3JYOGjg",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000DbI/F",
"photoVersionId": "729D00000000DbIIAU","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000DbI/T",
"standardEmailPhotoUrl":"https://instance_name/ncsphoto/g7O1xwgBO8dGwLadBRB8WWNbBNusiqjZbvaWEEu-3esJvHV8sIzLNp4aqaFASciV",
"url": "/services/data/v30.0/chatter/users/005D0000001Gif0IAC/photo"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001Gif0IAC","userType": "Internal"
}},{
"community": null,"createdBy": {
"companyName": "Powell Industries","firstName": "Kristen","id": "005D0000001Gif0IAC",
87
Favorites Feed ResourcesChatter REST API Resources
"isActive": true,"isInThisCommunity": true,"lastName": "Powell","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Kristen Powell","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/g7O1xwgBO8dGwLadBRB8WWNbBNusiqjZbvaWEEu-3etqqIFpNksYLrC-v3JYOGjg",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000DbI/F",
"photoVersionId": "729D00000000DbIIAU","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000DbI/T",
"standardEmailPhotoUrl":"https://instance_name/ncsphoto/g7O1xwgBO8dGwLadBRB8WWNbBNusiqjZbvaWEEu-3esJvHV8sIzLNp4aqaFASciV",
"url": "/services/data/v30.0/chatter/users/005D0000001Gif0IAC/photo"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001Gif0IAC","userType": "Internal"
},"feedUrl":
"/services/data/v30.0/chatter/feeds/favorites/me/07FD00000000TOAMA2/feed-items","id": "07FD00000000TOAMA2","lastViewDate": "2013-02-13T18:21:44.000Z","name": "Records list view","searchText": null,"target": null,"type": "ListView","url": "/services/data/v30.0/chatter/feeds/favorites/me/07FD00000000TOAMA2","user": {
"companyName": "Powell Industries","firstName": "Kristen","id": "005D0000001Gif0IAC","isActive": true,"isInThisCommunity": true,"lastName": "Powell","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Kristen Powell","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/g7O1xwgBO8dGwLadBRB8WWNbBNusiqjZbvaWEEu-3etqqIFpNksYLrC-v3JYOGjg",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000DbI/F",
"photoVersionId": "729D00000000DbIIAU","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000DbI/T",
"standardEmailPhotoUrl":"https://instance_name/ncsphoto/g7O1xwgBO8dGwLadBRB8WWNbBNusiqjZbvaWEEu-3esJvHV8sIzLNp4aqaFASciV",
"url": "/services/data/v30.0/chatter/users/005D0000001Gif0IAC/photo"},"title": null,
88
Favorites Feed ResourcesChatter REST API Resources
"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001Gif0IAC","userType": "Internal"
}},{
"community": null,"createdBy": {
"companyName": "Powell Industries","firstName": "Kristen","id": "005D0000001Gif0IAC","isActive": true,"isInThisCommunity": true,"lastName": "Powell","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Kristen Powell","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/g7O1xwgBO8dGwLadBRB8WWNbBNusiqjZbvaWEEu-3etqqIFpNksYLrC-v3JYOGjg",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000DbI/F",
"photoVersionId": "729D00000000DbIIAU","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000DbI/T",
"standardEmailPhotoUrl":"https://instance_name/ncsphoto/g7O1xwgBO8dGwLadBRB8WWNbBNusiqjZbvaWEEu-3esJvHV8sIzLNp4aqaFASciV",
"url": "/services/data/v30.0/chatter/users/005D0000001Gif0IAC/photo"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001Gif0IAC","userType": "Internal"
},"feedUrl":
"/services/data/v30.0/chatter/feeds/favorites/me/07FD00000000TOFMA2/feed-items","id": "07FD00000000TOFMA2","lastViewDate": "2013-02-13T18:21:35.000Z","name": "Planning meeting","searchText": null,"target": {
"id": "0TOD0000000099eOAA","url": "/services/data/v30.0/connect/topics/0TOD0000000099eOAA"
},"type": "Topic","url": "/services/data/v30.0/chatter/feeds/favorites/me/07FD00000000TOFMA2","user": {
"companyName": "Powell Industries","firstName": "Kristen","id": "005D0000001Gif0IAC","isActive": true,"isInThisCommunity": true,"lastName": "Powell","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Kristen Powell","photo": {
89
Favorites Feed ResourcesChatter REST API Resources
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/g7O1xwgBO8dGwLadBRB8WWNbBNusiqjZbvaWEEu-3etqqIFpNksYLrC-v3JYOGjg",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000DbI/F",
"photoVersionId": "729D00000000DbIIAU","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000DbI/T",
"standardEmailPhotoUrl":"https://instance_name/ncsphoto/g7O1xwgBO8dGwLadBRB8WWNbBNusiqjZbvaWEEu-3esJvHV8sIzLNp4aqaFASciV",
"url": "/services/data/v30.0/chatter/users/005D0000001Gif0IAC/photo"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001Gif0IAC","userType": "Internal"
}}
],"total": 3
}
FavoriteReturns the feed for the specified favorite. Deletes the specified favorite. Updates the last view date of the specified favorite.
Resource
/chatter/feeds/favorites/me/favoriteId
or
/chatter/feeds/favorites/userId/favoriteId
Note: userId must be the ID of the logged-in user or the alias me.
Available since version24.0
HTTP methodsGET, HEAD, PATCH, or DELETE
Request parameter for GET or HEAD
DescriptionTypeParameter Name
Specifies the order returned by the sort,such as by date created or last modified:
Stringsort
• CreatedDateDesc—Sorts thefeed items by most recent post date.
• LastModifiedDateDesc—Sortsthe feed items by most recentactivity, which includes new feeditems and comments.
90
Favorites Feed ResourcesChatter REST API Resources
DescriptionTypeParameter Name
The default value isCreatedDescDate.
Request body for PATCH
Root XML tag<favorite>
JSON for PATCH
{"updateLastViewDate" : "true"
}
Properties for PATCH
Available VersionDescriptionTypeName
24.0Sets the last view date ofthe specified feed favorite
BooleanupdateLastViewDate
to the current system time.Default value is false.
Request parameter for PATCH
DescriptionTypeParameter Name
Sets the last view date of the specifiedfeed favorite to the current system time.Default value is false.
BooleanupdateLastViewDate
Response body for GET or HEADFavorite
Response body for PATCHFavorite
Favorites Feed ItemsReturns a filtered feed, only showing those feed items for the specified favorite.
Resource
/chatter/feeds/favorites/me/favoriteId/feed-items
or
/chatter/feeds/favorites/userId/favoriteId/feed-items
91
Favorites Feed ResourcesChatter REST API Resources
Note: userId must be the ID of the logged-in user or the alias me.
Available since version24.0
HTTP methodsGET or HEAD
Request parameters
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
29.0OptionalThe density of the feed. One of these values:Stringdensity
• AllUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of.
• FewerUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of, buthides system-generated posts from records thatnobody commented on.
The default value is AllUpdates.
23.0OptionalA generated token that indicates the view of feeditems in the feed. Page tokens are returned as part
Stringpage
of the response body, in one of the URLparameters, such as nextPageURL, for example:
"nextPageUrl":"/services/data/v30.0/chatter/feeds/news/005D0000001GLowIAN/feed-items?page=2011-03-30T17:34:50Z,0D5D0000000DSv4KAG"
23.0OptionalSpecifies the number of items per page. Validvalues are between 1 and 100. If you don't specifya size, the default is 25.
IntegerpageSize
28.0OptionalOne or more keywords to search for in the bodyand comments of feed items in this feed.
The search string can contain wildcards and mustcontain at least two characters that aren’t wildcards.See Wildcards.
Stringq
29.0OptionalMaximum number of comments to include perfeed item. The default value is 3. The maximumvalue is 25.
IntegerrecentCommentCount
92
Favorites Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
23.0OptionalSpecifies the order returned by the sort, such as bydate created or last modified:
Stringsort
• CreatedDateDesc—Sorts the feed items bymost recent post date.
• LastModifiedDateDesc—Sorts the feeditems by most recent activity, which includesnew feed items and comments.
The default value is CreatedDescDate.
Response bodyFeed Item Page
See Also:Chatter REST API: How do I. . .Working with Feeds and Feed Items
Feeds ResourceA list of all of the feeds the logged-in user is able to view.
Each user may have a different set of feeds. Use this resource to determine what feeds are available. In addition, the differentfeeds may have unique labels as well as URLs. Use the given labels returned in this resource and avoid hard-coding any ofthese values.
Resource
/chatter/feeds/
Available since version23.0
HTTP methodsGET or HEAD
Response bodyFeed Directory
Example response body
{"favorites": [{
"community": null,"createdBy": {
"companyName": "SeattleApps","firstName": "Rene","id": "005D0000001LFNnIAO","isActive": true,
93
Feeds ResourceChatter REST API Resources
"lastName": "Holmes","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Rene Holmes","photo": {"fullEmailPhotoUrl":
"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZVyX4qlsJTXfOWM77RW7yt",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/F","photoVersionId": "729D00000000BDV","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/T""standardEmailPhotoUrl":
"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbktFTIf9vWhFTTALJiaFz_",
"url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo"},"title": "Senior Manager","type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LFNnIAO","userType": "Internal"
},"feedUrl":
"/services/data/v30.0/chatter/feeds/favorites/me/07FD00000000Q1CMAU/feed-items","id": "07FD00000000Q1CMAU","lastViewDate": "2012-07-17T22:52:29.000Z","name": "dreamforce","searchText": "dreamforce","type": "Search","url": "/services/data/v30.0/chatter/feeds/favorites/me/07FD00000000Q1CMAU","user": {
"companyName": "SeattleApps","firstName": "Rene","id": "005D0000001LFNnIAO","isActive": true,"lastName": "Holmes","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Rene Holmes","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZVyX4qlsJTXfOWM77RW7yt",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/F","photoVersionId": "729D00000000BDV","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/T""standardEmailPhotoUrl":
"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbktFTIf9vWhFTTALJiaFz_",
"url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LFNnIAO","userType": "Internal"
}}],"feeds": [
{"feedItemsUrl": "/services/data/v30.0/chatter/feeds/company/feed-items",
94
Feeds ResourceChatter REST API Resources
"feedUrl": "/services/data/v30.0/chatter/feeds/company","label": "All Company"
},{
"feedItemsUrl": "/services/data/v30.0/chatter/feeds/bookmarks/me/feed-items",
"feedUrl": "/services/data/v30.0/chatter/feeds/bookmarks/me","label": "Bookmarked"
},{
"feedItemsUrl": "/services/data/v30.0/chatter/feeds/files/me/feed-items","feedUrl": "/services/data/v30.0/chatter/feeds/files/me","label": "Files"
},{
"feedItemsUrl": "/services/data/v30.0/chatter/feeds/groups/me/feed-items","feedUrl": "/services/data/v30.0/chatter/feeds/groups/me","label": "Groups"
},{
"feedItemsUrl": "/services/data/v30.0/chatter/feeds/news/me/feed-items","feedUrl": "/services/data/v30.0/chatter/feeds/news/me","label": "What I Follow"
},{
"feedItemsUrl": "/services/data/v30.0/chatter/feeds/people/me/feed-items","feedUrl": "/services/data/v30.0/chatter/feeds/people/me","label": "People"
},{
"feedItemsUrl": "/services/data/v30.0/chatter/feeds/record/me/feed-items","feedUrl": "/services/data/v30.0/chatter/feeds/record/me","label": "Record"
},{
"feedItemsUrl": "/services/data/v30.0/chatter/feeds/to/me/feed-items","feedUrl": "/services/data/v30.0/chatter/feeds/to/me","label": "To Me"
},{"feedItemsUrl": "/services/data/v30.0/chatter/feeds/user-profile/me/feed-items",
"feedUrl": "/services/data/v30.0/chatter/feeds/user-profile/me","label": "User Profile"
}]
Files Feed ResourcesA feed containing all the feed items that contain files posted by people or groups that the logged-in user follows.
Available resources are:
DescriptionResource
Returns the URL to the feed-items that contain files that areposted by users or groups the logged-in user is following.
/chatter/feeds/files/me
Returns all feed items posted with files by people or groupsthat the logged-in user follows.
/chatter/feeds/files/me/feed-items
Files Feed URLReturns the URL to the feed-items that contain files that are posted by users or groups the logged-in user is following.
95
Files Feed ResourcesChatter REST API Resources
Resource
/chatter/feeds/files/me
OR
/chatter/feeds/files/userId
Note: userId must be the ID of the logged-in user or the alias me.
Available since version23.0
HTTP methodsGET or HEAD
Request parameter
DescriptionTypeParameter Name
Specifies the order returned by the sort,such as by date created or last modified:
Stringsort
• CreatedDateDesc—Sorts thefeed items by most recent post date.
• LastModifiedDateDesc—Sortsthe feed items by most recentactivity, which includes new feeditems and comments.
The default value isCreatedDescDate.
Response bodyFeed
Files Feed ItemsReturns all feed items posted with files by people or groups that the logged-in user follows.
Resource
/chatter/feeds/files/me/feed-items
or
/chatter/feeds/files/userId/feed-items
Note: userId must be the ID of the logged-in user or the alias me.
96
Files Feed ResourcesChatter REST API Resources
Available since version23.0
HTTP methodsGET or HEAD
Request parameters
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
29.0OptionalThe density of the feed. One of these values:Stringdensity
• AllUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of.
• FewerUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of, buthides system-generated posts from records thatnobody commented on.
The default value is AllUpdates.
23.0OptionalA generated token that indicates the view of feeditems in the feed. Page tokens are returned as part
Stringpage
of the response body, in one of the URLparameters, such as nextPageURL, for example:
"nextPageUrl":"/services/data/v30.0/chatter/feeds/news/005D0000001GLowIAN/feed-items?page=2011-03-30T17:34:50Z,0D5D0000000DSv4KAG"
23.0OptionalSpecifies the number of items per page. Validvalues are between 1 and 100. If you don't specifya size, the default is 25.
IntegerpageSize
28.0OptionalOne or more keywords to search for in the bodyand comments of feed items in this feed.
The search string can contain wildcards and mustcontain at least two characters that aren’t wildcards.See Wildcards.
Stringq
29.0OptionalMaximum number of comments to include perfeed item. The default value is 3. The maximumvalue is 25.
IntegerrecentCommentCount
23.0OptionalSpecifies the order returned by the sort, such as bydate created or last modified:
Stringsort
• CreatedDateDesc—Sorts the feed items bymost recent post date.
97
Files Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
• LastModifiedDateDesc—Sorts the feeditems by most recent activity, which includesnew feed items and comments.
The default value is CreatedDescDate.
30.0OptionalAn opaque token defining the modification timestamp of the feed and the sort order.
Do not construct this token. Retrieve this tokenfrom the updatesToken property of the FeedItem Page response body.
StringupdatedSince
Response bodyFeed Item Page
Response body example
{"currentPageUrl" :
"/services/data/v30.0/chatter/feeds/files/005D0000001L3zVIAS/feed-items?page=2012-04-17T18%3A13%3A57Z",
"isModifiedToken" : null,"isModifiedUrl" : null"items" : [ ],"nextPageUrl" : null,}
Files Feed Items FlatThis 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 commentsare at the same level. All items are returned in chronological order.
Resource
/chatter/feeds/files/me/feed-items/flat
or
/chatter/feeds/files/userId/feed-items/flat
Note: userId must be the ID of the logged-in user or the alias me.
Available since version25.0
98
Files Feed ResourcesChatter REST API Resources
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
Specifies the number of feed itemsreturned. Valid values are between 0
IntegernumFeedItems
and 100. Default value is 25. Becausefeed items may include comments,specifying 25 flat feed items mayactually return more. For example, ifeach feed item has one comment, andrecentCommentCount is greater than1, 50 flat feed items are returned.
A generated token that indicates theview of feed items in the feed. Page
Stringpage
tokens are returned as part of theresponse body, in one of the URLparameters, such as nextPageURL.
Specifies the number of recentcomments returned. Valid values arebetween 0 and 25. Default value is 3.
IntegerrecentCommentCount
Sorts the returned feed either bycreated date in ascending order, or by
String. One of the following:sort
• CreatedDateDesclast modified date, also in ascending• LastModifiedDateDescorder. The default isLastModifiedDateDesc
Response bodyFlat Feed
See Also:Chatter REST API: How do I. . .Working with Feeds and Feed Items
Filter Feed ResourcesThe filter feed is the news feed filtered to contain feed items whose parent is a specified object type.
Available resources are:
DescriptionResource
A collection of feed directory objects that contain informationabout filter feeds available to the logged-in user. Each object
/chatter/feeds/filter/userId
contains a URL for the filter feed, a URL for feed items in thefilter feed, and a label describing the object used to filter the feed.
99
Filter Feed ResourcesChatter REST API Resources
DescriptionResource
A feed object that contains information about a specific filter feedavailable to the logged-in user.
/chatter/feeds/filter/userId/idPrefix
Feed items from the logged-in user’s news feed whose parent hasthe specified key prefix, such as the feed items from all the groupsthe logged-in user is a member of.
/chatter/feeds/filter/userId/idPrefix/feed-items
List of Filter Feed URLsA collection of feed directory objects that contain information about filter feeds available to the logged-in user. Each objectcontains a URL for the filter feed, a URL for feed items in the filter feed, and a label describing the object used to filter thefeed. Each URL contains the first three characters of the filter object, which is called a key prefix and specifies the object type.Use this resource to return a list of the possible key prefix filter feeds that the logged-in user can apply to their news feed. SeeFilter Feed Items.
Note: The collection of feed directory objects never contains User (005) and Group (0F9) object types. However,you can use those object types to filter the feed.
Resource
/chatter/feeds/filter/me
or
/chatter/feeds/filter/userId
userId must be the ID of the logged-in user or the alias me.
Available since version23.0
HTTP methodsGET or HEAD
Response bodyFeed Directory
If the response body is empty, the user isn’t following any records.
Specific Filter Feed URLA feed object that contains information about a specific filter feed available to the logged-in user. The keyPrefix in theresource URL is the first three characters of the object ID and indicates the object type.
Resource
/chatter/feeds/filter/userId/keyPrefix
userId must be the ID of the logged-in user or the alias me.
Available since version23.0
100
Filter Feed ResourcesChatter REST API Resources
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
Specifies the order returned by the sort,such as by date created or last modified:
Stringsort
• CreatedDateDesc—Sorts thefeed items by most recent post date.
• LastModifiedDateDesc—Sortsthe feed items by most recentactivity, which includes new feeditems and comments.
The default value isCreatedDescDate.
Response bodyFeed
Example response bodyThis request returns the URL for a filter feed items resource that’s filtered by the User object (key prefix 005).
GET /chatter/feeds/filter/me/005
This is the response:
{"feedItemsUrl":
"/services/data/v30.0/chatter/feeds/filter/005D0000001Gl4rIAC/005/feed-items","isModifiedUrl": null
}
Filter Feed ItemsFeed items from the logged-in user’s news feed whose parent has the specified key prefix, such as the feed items from all thegroups the logged-in user is a member of. The key prefix specifies the object type and is the first three characters of an objectID.
To filter by feed items with a User parent object, use the key prefix 005.
To filter by feed items with a Group parent object, use the key prefix 0F9.
To filter by feed items with a parent object that the logged-in user is following (for example, Account), use the List of FilterFeed URLs resource to return the parent objects.
Suppose the logged-in user is a member of five groups. The following resource returns all of the feed items posted to all fiveof those groups:
/chatter/feeds/filter/me/0F9/feed-items
101
Filter Feed ResourcesChatter REST API Resources
Contrast that with a request to the Record Feed Items resource, which returns all of the feed items posted to a particular group:
/chatter/feeds/record/0F9XXXXXXXXX/feed-items
The filter feed returns only the feed items that are visible to the logged-in user. In the first example, the resource doesn’t returnthe feed items for groups the logged-in user is not a member of. In the second example, if the group is public, even if thelogged-in user is not a member, the resource returns all the group’s feed items.
Resource
/chatter/feeds/filter/me/keyPrefix/feed-items
or
/chatter/feeds/filter/userId/keyPrefix/feed-items
userId must be the ID of the logged-in user or the alias me.
Available since version23.0
HTTP methodsGET or HEAD
Request parameters
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
29.0OptionalThe density of the feed. One of these values:Stringdensity
• AllUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of.
• FewerUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of, buthides system-generated posts from records thatnobody commented on.
The default value is AllUpdates.
23.0OptionalA generated token that indicates the view of feeditems in the feed. Page tokens are returned as part
Stringpage
of the response body, in one of the URLparameters, such as nextPageURL, for example:
"nextPageUrl":"/services/data/v30.0/chatter/feeds/news/005D0000001GLowIAN/feed-items?page=2011-03-30T17:34:50Z,0D5D0000000DSv4KAG"
102
Filter Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
23.0OptionalSpecifies the number of items per page. Validvalues are between 1 and 100. If you don't specifya size, the default is 25.
IntegerpageSize
28.0OptionalOne or more keywords to search for in the bodyand comments of feed items in this feed.
The search string can contain wildcards and mustcontain at least two characters that aren’t wildcards.See Wildcards.
Stringq
29.0OptionalMaximum number of comments to include perfeed item. The default value is 3. The maximumvalue is 25.
IntegerrecentCommentCount
23.0OptionalSpecifies the order returned by the sort, such as bydate created or last modified:
Stringsort
• CreatedDateDesc—Sorts the feed items bymost recent post date.
• LastModifiedDateDesc—Sorts the feeditems by most recent activity, which includesnew feed items and comments.
The default value is CreatedDescDate.
30.0OptionalAn opaque token defining the modification timestamp of the feed and the sort order.
Do not construct this token. Retrieve this tokenfrom the updatesToken property of the FeedItem Page response body.
StringupdatedSince
Response bodyFeed Item Page
ExampleThis request gets all the feed items whose parent is the User object and that the logged-in user can see.
GET https://instance_name/services/data/v30.0/chatter/feeds/filter/me/005/feed-items
The response is:
{"currentPageUrl":
"/services/data/v30.0/chatter/feeds/filter/005D0000001LL8OIAW/005/feed-items","isModifiedToken": null,"isModifiedUrl": null,"items": [
{"actor": {
"companyName": "Universal Containers","firstName": "Deanna","id": "005D0000001LL8OIAW","isActive": true,
103
Filter Feed ResourcesChatter REST API Resources
"isInThisCommunity": true,"lastName": "Li","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Deanna Li","photo": {
"fullEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbKHM8BOF0F77vGAZj-E49H",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/F",
"photoVersionId": "729D00000000LJFIA2","smallPhotoUrl": "https://instance_name/profilephoto
/729D00000000LJF/T","standardEmailPhotoUrl": "https://instance_name/ncsphoto
/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sb7ZAiQf8i8QQ-eQr3mx8--","url": "/services/data/v29.0/chatter/users/005D0000001LL8OIAW/photo"
},"title": "Salesforce Administrator","type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW","userType": "Internal"
},"attachment": null,"body": {
"messageSegments": [],"text": null
},"canShare": false,"clientInfo": null,"comments": {
"comments": [],"currentPageUrl": "/services/data/v30.0/chatter
/feed-items/0D5D0000000LizgKAC/comments","nextPageUrl": null,"total": 0
},"createdDate": "2013-09-10T00:28:16.000Z","event": false,"id": "0D5D0000000LizgKAC","isBookmarkedByCurrentUser": false,"isDeleteRestricted": true,"isLikedByCurrentUser": false,"likes": {
"currentPageUrl": "/services/data/v30.0/chatter/feed-items/0D5D0000000LizgKAC/likes",
"likes": [],"nextPageUrl": null,"previousPageUrl": null,"total": 0
},"likesMessage": null,"moderationFlags": null,"modifiedDate": "2013-09-10T00:28:16.000Z","myLike": null,"originalFeedItem": null,"originalFeedItemActor": null,"parent": {
"companyName": "Universal Containers","firstName": "Deanna","id": "005D0000001LL8OIAW","isActive": true,"isInThisCommunity": true,"lastName": "Li","motif": {
104
Filter Feed ResourcesChatter REST API Resources
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Deanna Li","photo": {
"fullEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbKHM8BOF0F77vGAZj-E49H",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/F",
"photoVersionId": "729D00000000LJFIA2","smallPhotoUrl": "https://instance_name/profilephoto
/729D00000000LJF/T","standardEmailPhotoUrl": "https://instance_name/ncsphoto
/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sb7ZAiQf8i8QQ-eQr3mx8--","url": "/services/data/v30.0/chatter
/users/005D0000001LL8OIAW/photo"},"title": "Salesforce Administrator","type": "User","url": "/services/data/v30.0/chatter
/users/005D0000001LL8OIAW","userType": "Internal"
},"photoUrl": "https://instance_name/profilephoto/729D00000000LJF/T","preamble": {
"messageSegments": [{
"motif": {"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"reference": {
"id": "005D0000001LL8OIAW","url": "/services/data/v30.0/chatter
/users/005D0000001LL8OIAW"},"text": "Deanna Li","type": "EntityLink"
},{
"text": " created the public group ","type": "Text"
},{
"motif": null,"reference": {
"id": "0F9D00000000qaoKAA","url": "/services/data/v30.0/chatter
/groups/0F9D00000000qaoKAA"},"text": "Test","type": "EntityLink"
},{
"text": ".","type": "Text"
}],"text": "Deanna Li created the public group Test."
},"relativeCreatedDate": "Yesterday at 5:28 PM","topics": {
"canAssignTopics": true,"topics": []
105
Filter Feed ResourcesChatter REST API Resources
},"type": "CollaborationGroupCreated","url": "/services/data/v30.0/chatter
/feed-items/0D5D0000000LizgKAC","visibility": "AllUsers"
},{
"actor": {"companyName": "Universal Containers","firstName": "Deanna","id": "005D0000001LL8OIAW","isActive": true,"isInThisCommunity": true,"lastName": "Li","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Deanna Li","photo": {
"fullEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbKHM8BOF0F77vGAZj-E49H",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/F",
"photoVersionId": "729D00000000LJFIA2","smallPhotoUrl": "https://instance_name/profilephoto
/729D00000000LJF/T","standardEmailPhotoUrl": "https://instance_name/ncsphoto
/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sb7ZAiQf8i8QQ-eQr3mx8--","url": "/services/data/v30.0/chatter
/users/005D0000001LL8OIAW/photo"},"title": "Salesforce Administrator","type": "User","url": "/services/data/v30.0/chatter
/users/005D0000001LL8OIAW","userType": "Internal"
},"attachment": null,"body": {
"messageSegments": [],"text": null
},"canShare": false,"clientInfo": null,"comments": {
"comments": [],"currentPageUrl": "/services/data/v30.0/chatter
/feed-items/0D5D0000000Le2BKAS/comments","nextPageUrl": null,"total": 0
},"createdDate": "2013-09-04T22:38:42.000Z","event": false,"id": "0D5D0000000Le2BKAS","isBookmarkedByCurrentUser": false,"isDeleteRestricted": true,"isLikedByCurrentUser": false,"likes": {
"currentPageUrl": "/services/data/v30.0/chatter/feed-items/0D5D0000000Le2BKAS/likes",
"likes": [],"nextPageUrl": null,"previousPageUrl": null,"total": 0
},
106
Filter Feed ResourcesChatter REST API Resources
"likesMessage": null,"moderationFlags": null,"modifiedDate": "2013-09-04T22:38:42.000Z","myLike": null,"originalFeedItem": null,"originalFeedItemActor": null,"parent": {
"companyName": "Universal Containers","firstName": "Deanna","id": "005D0000001LL8OIAW","isActive": true,"isInThisCommunity": true,"lastName": "Li","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Deanna Li","photo": {
"fullEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbKHM8BOF0F77vGAZj-E49H",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/F",
"photoVersionId": "729D00000000LJFIA2","smallPhotoUrl": "https://instance_name/profilephoto
/729D00000000LJF/T","standardEmailPhotoUrl": "https://instance_name/ncsphoto
/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sb7ZAiQf8i8QQ-eQr3mx8--","url": "/services/data/v30.0/chatter
/users/005D0000001LL8OIAW/photo"},"title": "Salesforce Administrator","type": "User","url": "/services/data/v30.0/chatter
/users/005D0000001LL8OIAW","userType": "Internal"
},"photoUrl": "https://instance_name/profilephoto/729D00000000LJF/T","preamble": {
"messageSegments": [{
"motif": {"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"reference": {
"id": "005D0000001LL8OIAW","url": "/services/data/v30.0/chatter
/users/005D0000001LL8OIAW"},"text": "Deanna Li","type": "EntityLink"
},{
"text": " created the public group ","type": "Text"
},{
"motif": null,"reference": {
"id": "0F9D00000000qSzKAI","url": "/services/data/v30.0/chatter
/groups/0F9D00000000qSzKAI"},
107
Filter Feed ResourcesChatter REST API Resources
"text": "Connect","type": "EntityLink"
},{
"text": ".","type": "Text"
}],"text": "Deanna Li created the public group Connect."
},"relativeCreatedDate": "September 4, 2013 at 3:38 PM","topics": {
"canAssignTopics": true,"topics": []
},"type": "CollaborationGroupCreated","url": "/services/data/v30.0/chatter
/feed-items/0D5D0000000Le2BKAS","visibility": "AllUsers"
},],"nextPageUrl": "/services/data/v30.0/chatter/feeds/filter
/005D0000001LL8OIAW/005/feed-items?page=2013-01-25T00%3A36%3A54Z%2C0D5D0000000JnAtKAK"}
Filter Feed Items FlatThis 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 commentsare at the same level. All items are returned in chronological order.
Resource
/chatter/feeds/filter/me/feed-items/flat
or
/chatter/feeds/filter/userId/feed-items/flat
Note: userId must be the ID of the logged-in user or the alias me.
Available since version25.0
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
Specifies the number of feed itemsreturned. Valid values are between 0
IntegernumFeedItems
and 100. Default value is 25. Becausefeed items may include comments,specifying 25 flat feed items may
108
Filter Feed ResourcesChatter REST API Resources
DescriptionTypeParameter Name
actually return more. For example, ifeach feed item has one comment, andrecentCommentCount is greater than1, 50 flat feed items are returned.
A generated token that indicates theview of feed items in the feed. Page
Stringpage
tokens are returned as part of theresponse body, in one of the URLparameters, such as nextPageURL.
Specifies the number of recentcomments returned. Valid values arebetween 0 and 25. Default value is 3.
IntegerrecentCommentCount
Sorts the returned feed either bycreated date in ascending order, or by
String. One of the following:sort
• CreatedDateDesclast modified date, also in ascending• LastModifiedDateDescorder. The default isLastModifiedDateDesc
Response bodyFlat Feed
Groups Feed ResourcesA feed containing all feed items from all groups the current user either owns or is a member of.
Available resources are:
DescriptionResource
Returns a URL to the feed-items for all the groups the current,signed-in user is a member of.
/chatter/feeds/groups/me
Returns all feed items for all groups the current user eitherowns or is a member of.
/chatter/feeds/groups/me/feed-items
Groups Feed URLReturns a URL to the feed-items for all the groups the current, signed-in user is a member of.
Resource
/chatter/feeds/groups/me
or
/chatter/feeds/groups/userId
Note: userId must be the ID of the logged-in user or the alias me.
109
Groups Feed ResourcesChatter REST API Resources
Available since version23.0
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
Specifies the order returned by the sort,such as by date created or last modified:
Stringsort
• CreatedDateDesc—Sorts thefeed items by most recent post date.
• LastModifiedDateDesc—Sortsthe feed items by most recentactivity, which includes new feeditems and comments.
The default value isCreatedDescDate.
Response bodyFeed
Groups Feed ItemsReturns all feed items for all groups the current user either owns or is a member of.
To get the feed items for a specific group, use the record feed resource (/chatter/feeds/record/recordId/feed-items)and substitute the group ID for the recordId.
Resource
/chatter/feeds/groups/me/feed-items
or
/chatter/feeds/groups/userId/feed-items
Note: userId must be the ID of the logged-in user or the alias me.
Available since version23.0
HTTP methodsGET or HEAD
110
Groups Feed ResourcesChatter REST API Resources
Request parameters
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
29.0OptionalThe density of the feed. One of these values:Stringdensity
• AllUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of.
• FewerUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of, buthides system-generated posts from records thatnobody commented on.
The default value is AllUpdates.
23.0OptionalA generated token that indicates the view of feeditems in the feed. Page tokens are returned as part
Stringpage
of the response body, in one of the URLparameters, such as nextPageURL, for example:
"nextPageUrl":"/services/data/v30.0/chatter/feeds/news/005D0000001GLowIAN/feed-items?page=2011-03-30T17:34:50Z,0D5D0000000DSv4KAG"
23.0OptionalSpecifies the number of items per page. Validvalues are between 1 and 100. If you don't specifya size, the default is 25.
IntegerpageSize
28.0OptionalOne or more keywords to search for in the bodyand comments of feed items in this feed.
The search string can contain wildcards and mustcontain at least two characters that aren’t wildcards.See Wildcards.
Stringq
29.0OptionalMaximum number of comments to include perfeed item. The default value is 3. The maximumvalue is 25.
IntegerrecentCommentCount
23.0OptionalSpecifies the order returned by the sort, such as bydate created or last modified:
Stringsort
• CreatedDateDesc—Sorts the feed items bymost recent post date.
• LastModifiedDateDesc—Sorts the feeditems by most recent activity, which includesnew feed items and comments.
The default value is CreatedDescDate.
111
Groups Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
30.0OptionalAn opaque token defining the modification timestamp of the feed and the sort order.
Do not construct this token. Retrieve this tokenfrom the updatesToken property of the FeedItem Page response body.
StringupdatedSince
Response bodyFeed Item Page
Groups Feed Items FlatThis 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 commentsare at the same level. All items are returned in chronological order.
Resource
/chatter/feeds/groups/me/feed-items/flat
or
/chatter/feeds/groups/userId/feed-items/flat
Note: userId must be the ID of the logged-in user or the alias me.
Available since version25.0
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
Specifies the number of feed itemsreturned. Valid values are between 0
IntegernumFeedItems
and 100. Default value is 25. Becausefeed items may include comments,specifying 25 flat feed items mayactually return more. For example, ifeach feed item has one comment, andrecentCommentCount is greater than1, 50 flat feed items are returned.
112
Groups Feed ResourcesChatter REST API Resources
DescriptionTypeParameter Name
A generated token that indicates theview of feed items in the feed. Page
Stringpage
tokens are returned as part of theresponse body, in one of the URLparameters, such as nextPageURL.
Specifies the number of recentcomments returned. Valid values arebetween 0 and 25. Default value is 3.
IntegerrecentCommentCount
Sorts the returned feed either bycreated date in ascending order, or by
String. One of the following:sort
• CreatedDateDesclast modified date, also in ascending• LastModifiedDateDescorder. The default isLastModifiedDateDesc
Response bodyFlat Feed
See Also:Groups ResourcesRecord Feed ResourceChatter REST API: How do I. . .Working with Feeds and Feed Items
News Feed ResourcesA feed containing items of interest to the logged-in user. You can post feed items to the news feed.
Note: The composition of this feed may change between releases.
Available resources are:
DescriptionResource
Returns a URL to the feed items for all feeds for the logged-inuser. Also returns an Is-Modified resource for polling the feedfor updates.
/chatter/feeds/news/me
Returns information about whether the news feed has beenupdated or changed since the specified time and date.
/chatter/feeds/news/me/is-modified
All feed items from all groups the logged-in user either ownsor is a member of, as well as all files, records, and users the
/chatter/feeds/news/me/feed-items
logged-in user follows. Use this resource to get informationabout the feed items and to post feed items.
113
News Feed ResourcesChatter REST API Resources
News Feed URLReturns a URL to the feed items for all feeds for the logged-in user. Also returns an Is-Modified resource for polling the feedfor updates.
Resource
/chatter/feeds/news/me
or
/chatter/feeds/news/userId
Note: userId must be the ID of the logged-in user or the alias me.
Available since version23.0
HTTP methodsGET or HEAD
Request parameter
DescriptionTypeParameter Name
Specifies the order returned by the sort,such as by date created or last modified:
Stringsort
• CreatedDateDesc—Sorts thefeed items by most recent post date.
• LastModifiedDateDesc—Sortsthe feed items by most recentactivity, which includes new feeditems and comments.
The default value isCreatedDescDate.
Response bodyFeed
Example response body
{"feedItemsUrl":
"/services/data/v30.0/chatter/feeds/news/005xx000001Sv1mAAB/feed-items","isModifiedUrl":
"/services/data/v30.0/chatter/feeds/news/005xx000001Sv1mAAB/is-modified?since=2%3A1344352279000"
}
News Feed Is-ModifiedReturns information about whether the news feed has been updated or changed since the specified time and date.
114
News Feed ResourcesChatter REST API Resources
Note: Though the Is-Modified resource is generally available, your organization may not have permission to use itautomatically. If you can’t access this resource, contact your salesforce.com representative and ask about the “EnabledChatter Feed Polling” permission.
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. Inaddition, 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 tolessen your chances of reaching the rate limit and to save computing resources.
Note: If you are working with remote organizations as an ISV, use the Organization resource and the feedPollingproperty of the Feature response body to shape your polling strategy. If feedPolling is not enabled, be conservativein how often you poll for new content.
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 tothe 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. Conditionsunder 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 onlyif 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 newsfeed.
4. If the isModified property is false, issue a GET request to the URL in the nextPollUrl property. This requestalso returns a Feed Modified Info response body that contains the isModified and nextPollUrl properties.
Note: We don’t recommend exceeding one poll per minute.
Resource
/chatter/feeds/news/me/is-modified
or
/chatter/feeds/news/userId/is-modified
Note: userId must be the ID of the logged-in user or the alias me.
Available since version26.0
115
News Feed ResourcesChatter REST API Resources
HTTP methodsGET or HEAD
Request parameter
AvailableSince
Required orOptional
DescriptionTypeParameter Name
23.0RequiredAn opaque token containing information aboutthe modification time stamp of the feed and thesort order.
Do not construct this token. Retrieve this tokenfrom the isModifiedToken property of the
Stringsince
Feed Item Page or Feed Modified Info responsebody.
Response bodyFeed Modified Info
News Feed ItemsAll feed items from all groups the logged-in user either owns or is a member of, as well as all files, records, and users thelogged-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 on page 9.
For information about uploading and attaching a binary file to a feed item, see Uploading Binary Files on page 9.
GET requests for this resource return the isModifiedUrl property, which contains a News Feed Is-Modified resource forpolling the feed for updates.
As of API version 29.0, feed items can contain 5000 characters. This change is backwards compatible; all earlier API versionssupport the 5000 character limit.
Resource
/chatter/feeds/news/userId/feed-items
Note: userId must be the ID of the logged-in user or the alias me.
Available since version23.0
HTTP methodsGET, POST, HEAD
116
News Feed ResourcesChatter REST API Resources
Request parameters for GET
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
29.0OptionalThe density of the feed. One of these values:Stringdensity
• AllUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of.
• FewerUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of, buthides system-generated posts from records thatnobody commented on.
The default value is AllUpdates.
23.0OptionalA generated token that indicates the view of feeditems in the feed. Page tokens are returned as part
Stringpage
of the response body, in one of the URLparameters, such as nextPageURL, for example:
"nextPageUrl":"/services/data/v30.0/chatter/feeds/news/005D0000001GLowIAN/feed-items?page=2011-03-30T17:34:50Z,0D5D0000000DSv4KAG"
23.0OptionalSpecifies the number of items per page. Validvalues are between 1 and 100. If you don't specifya size, the default is 25.
IntegerpageSize
28.0OptionalOne or more keywords to search for in the bodyand comments of feed items in this feed.
The search string can contain wildcards and mustcontain at least two characters that aren’t wildcards.See Wildcards.
Stringq
29.0OptionalMaximum number of comments to include perfeed item. The default value is 3. The maximumvalue is 25.
IntegerrecentCommentCount
23.0OptionalSpecifies the order returned by the sort, such as bydate created or last modified:
Stringsort
• CreatedDateDesc—Sorts the feed items bymost recent post date.
• LastModifiedDateDesc—Sorts the feeditems by most recent activity, which includesnew feed items and comments.
The default value is CreatedDescDate.
117
News Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
30.0OptionalAn opaque token defining the modification timestamp of the feed and the sort order.
Do not construct this token. Retrieve this tokenfrom the updatesToken property of the FeedItem Page response body.
StringupdatedSince
Request body for POST
Root XML tag<feedItem>
JSONThe following example attaches a poll to a feed item:
{ "attachment":{
"attachmentType":"Poll","pollChoices": [
"Monday","Tuesday"
]},"body" : {
"messageSegments" : [{
"type" : "Text","text" : "When should we meet for release planning?"
}]
}}
Properties
AvailableVersion
DescriptionTypeName
Optional. You can specify only one ofthese values in the attachment parameter.Values are:
Depends on type.attachment
• 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)
118
News Feed ResourcesChatter REST API Resources
AvailableVersion
DescriptionTypeName
Note: To upload a new file,you must include it in amultipart/form–datamessage. See UploadingBinary Files.
23.0Description of message body. The bodycan contain up to 25 mentions.
If you specify originalFeedItemIdto share a feed item, use the body
Message Body Inputbody
property to add a comment to the feeditem.
If this feed item is shared, this value isthe body of the first comment.
24.0Optional. Specifies if the new feed itemshould be bookmarked for the user
BooleanisBookmarkedByCurrentUser
(true) or not (false). Default value isfalse.
24.0Optional. If this feed item is shared, thisis the original feed item 18-character ID
StringoriginalFeedItemId
Note: This parameter takesprecedence over all otherparameters. For example, if youshare a post and also try toupload a file, the generatedfeed-item only contains theshared post. You should onlyshare a post or upload a file, notboth in the same post.
26.0Optional. Who can see the post. Validvalues are:
Stringvisibility
• InternalUsers—If Communitiesis enabled, only members of thedefault, internal community can seethe feed item.
• AllUsers—If Communities isenabled, all members of thecommunity can see the feed item.
Default values:
• For external users, the default valueis AllUsers. External users mustuse this value to see their posts.
• For internal users, the default valueis InternalUsers. Internal users
119
News Feed ResourcesChatter REST API Resources
AvailableVersion
DescriptionTypeName
can accept this value or use the valueAllUsers to allow external users tosee their posts.
If the parent of the feed item is a Useror a Group, the visibility of the feeditem must be AllUsers.
Request parameters for POSTUse 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
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
27.0RequiredThe attachment type. Must contain the valueExistingContent.
StringattachmentType
23.0Required18-character ID of an existing file.StringcontentDocumentId
26.0OptionalSpecifies if the new feed item should be bookmarkedfor the user (true) or not (false). Default valueis false.
BooleanisBookmarkedByCurrentUser
23.0OptionalText of the feed item.Stringtext
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities is enabled,only members of the default, internal communitycan see the feed item.
• AllUsers—If Communities is enabled, allmembers of the community can see the feed item.
Default values:
• For external users, the default value isAllUsers. External users must use this valueto see their posts.
• For internal users, the default value isInternalUsers. Internal users can accept thisvalue or use the value AllUsers to allowexternal 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 beAllUsers.
Parameters for attaching a new file
120
News Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
27.0RequiredThe attachment type. Must contain the valueNewFile.
StringattachmentType
23.0–26.0OptionalDescription of file being posted.Stringdesc
Attention: This parameter should not beused as of version 27.0. Use descriptioninstead.
27.0OptionalDescription of file being posted.Stringdescription
23.0–24.0RequiredFile name of the file being posted.StringfileName
Attention: This parameter should not beused as of version 24.0. Use title instead.
26.0OptionalSpecifies if the new feed item should be bookmarkedfor the user (true) or not (false). Default value isfalse.
BooleanisBookmarkedByCurrentUser
23.0OptionalText of the feed item.Stringtext
24.0RequiredFile name of a file to be uploaded and posted.Stringtitle
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities is enabled,only members of the default, internal communitycan see the feed item.
• AllUsers—If Communities is enabled, allmembers 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 theirposts.
• For internal users, the default value isInternalUsers. Internal users can accept thisvalue or use the value AllUsers to allowexternal 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 beAllUsers.
Parameters for posting a link
121
News Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
27.0RequiredThe attachment type. Must contain the valueLink.
StringattachmentType
26.0OptionalSpecifies if the new feed item should bebookmarked for the user (true) or not(false). Default value is false.
BooleanisBookmarkedByCurrentUser
23.0OptionalText of the feed item.Stringtext
23.0RequiredURL of the link.Stringurl
23.0OptionalName of the URL.StringurlName
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities isenabled, only members of the default,internal community can see the feed item.
• AllUsers—If Communities is enabled,all members of the community can see thefeed item.
Default values:
• For external users, the default value isAllUsers. External users must use thisvalue to see their posts.
• For internal users, the default value isInternalUsers. Internal users can acceptthis value or use the value AllUsers toallow external users to see their posts.
If the parent of the feed item is a User or aGroup, the visibility of the feed item mustbe AllUsers.
Parameters for posting a poll
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
27.0RequiredThe attachment type. Must contain the valuePoll.
StringattachmentType
26.0OptionalSpecifies if the new feed item should bebookmarked for the user (true) or not(false). Default value is false.
BooleanisBookmarkedByCurrentUser
26.0RequiredThe choices used to create a new feed itemwith a poll. You must specify 2–10 poll choicesfor each poll.
StringpollChoice1 throughpollChoice10
23.0RequiredText of the feed item.Stringtext
122
News Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities isenabled, only members of the default,internal community can see the feed item.
• AllUsers—If Communities is enabled,all members of the community can see thefeed item.
Default values:
• For external users, the default value isAllUsers. External users must use thisvalue to see their posts.
• For internal users, the default value isInternalUsers. Internal users can acceptthis value or use the value AllUsers toallow external users to see their posts.
If the parent of the feed item is a User or aGroup, the visibility of the feed item mustbe AllUsers.
Parameters for sharing a post
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
26.0OptionalSpecifies if the new feed item should bebookmarked for the user (true) or not(false). Default value is false.
BooleanisBookmarkedByCurrentUser
24.0RequiredThe ID of the feed item you want toshare.18-character ID
StringoriginalFeedItemId
Note: Sharing a post takes precedenceover uploading a file. Do not share apost and upload a file in the samepost.
28.0OptionalA comment on the shared feed item.Stringtext
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities isenabled, only members of the default,internal community can see the feed item.
• AllUsers—If Communities is enabled,all members of the community can see thefeed item.
Default values:
123
News Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
• For external users, the default value isAllUsers. External users must use thisvalue to see their posts.
• For internal users, the default value isInternalUsers. Internal users can acceptthis value or use the value AllUsers toallow external users to see their posts.
If the parent of the feed item is a User or aGroup, the visibility of the feed item mustbe AllUsers.
Parameters for posting text only
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
26.0OptionalSpecifies if the new feed item should bebookmarked for the user (true) or not(false). Default value is false.
BooleanisBookmarkedByCurrentUser
23.0RequiredText of the feed item. The maximum numberof characters is 1000.
Stringtext
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities isenabled, only members of the default,internal community can see the feed item.
• AllUsers—If Communities is enabled,all members of the community can see thefeed item.
Default values:
• For external users, the default value isAllUsers. External users must use thisvalue to see their posts.
• For internal users, the default value isInternalUsers. Internal users can acceptthis value or use the value AllUsers toallow external users to see their posts.
If the parent of the feed item is a User or aGroup, the visibility of the feed item mustbe AllUsers.
Parameters for posting a canvas app
124
News Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
29.0RequiredThe attachment type. Must contain the valueCanvas.
StringattachmentType
29.0OptionalDescription of the canvas appStringdescription
29.0RequiredThe developer name (API name) of the canvas appStringdeveloperName
29.0OptionalThe height of the canvas app in pixels. Defaultheight is 200 pixels.
Stringheight
29.0OptionalSpecifies if the new feed item should be bookmarkedfor the user (true) or not (false). Default valueis false.
BooleanisBookmarkedByCurrentUser
29.0OptionalThe namespace prefix of the Developer Editionorganization in which the canvas app was created.
StringnamespacePrefix
29.0OptionalParameters passed to the canvas app in JSON format.The JSON must be URL-encoded:parameters={'isUpdated'='true';}"
Stringparameters
29.0OptionalText of the feed itemStringtext
29.0OptionalThe URL to a thumbnail image for the canvas app.Maximum dimensions are 120x120 pixels.
StringthumbnailUrl
29.0OptionalThe title of the link to the canvas appStringtitle
29.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities is enabled,only members of the default, internal communitycan see the feed item.
• AllUsers—If Communities is enabled, allmembers of the community can see the feed item.
Default values:
• For external users, the default value isAllUsers. External users must use this valueto see their posts.
• For internal users, the default value isInternalUsers. Internal users can accept thisvalue or use the value AllUsers to allowexternal 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 beAllUsers.
Response body for GET or HEADFeed Item Page
125
News Feed ResourcesChatter REST API Resources
Response body for POSTFeed Item
Example of file post
This example updates a news feed with a post that has a new file attachment.
curl https://instance_name/services/data/v30.0/chatter/feeds/news/me/feed-items--form "feedItemFileUpload=@Desktop/textFile.txt"--form "title=Sample"--form "description=Just a Text File"--form "text=Please review"--form "attachmentType=NewFile"--header 'Authorization: Bearer
00DD0000000Jhd2!AQIAQBgn42jbvCW2SX8JaRO2_JjX1fNKXWBrjYQPXODtDyaT6gT4DJVs4Ki7s6GoxvO8a.Z7gTHKkfqjW6S1.ujlD413PYpF'
This is an example in Java of updating a news feed with a file post.
import java.io.File;
import org.apache.commons.httpclient.*;import org.apache.commons.httpclient.methods.PostMethod;import org.apache.commons.httpclient.methods.multipart.*;
...
String oauthToken = "00Dx0000000X42V!AQgAQClp6UqGWNJUf4d3LQkVCysBIS6a";String url = "https://instance_name/services/data/v30.0/chatter/" +
"feeds/user-profile/me/feed-items";String text = "I love posting files to Chatter!";File contentFile = getFile();String description = "This is a test file that I'm posting.";String title = "contentFile";Part[] parts = {
new StringPart("description", description),new StringPart("title", fileName),new StringPart("text", text),new FilePart("feedItemFileUpload", contentFile),
};
final PostMethod postMethod = new PostMethod(url);
try {postMethod.setRequestEntity(new MultipartRequestEntity(parts,
postMethod.getParams()));postMethod.setRequestHeader("Authorization", "Bearer " + oauthToken);postMethod.setRequestHeader("Content-type", "multipart/form-data")postMethod.addRequestHeader("X-PrettyPrint", "1");
HttpClient httpClient = new HttpClient();httpClient.getParams().setSoTimeout(60000);
int returnCode = httpClient.executeMethod(postMethod);
System.out.println(postMethod.getResponseBodyAsString());
assertTrue("Expected return code of: " + HttpStatus.SC_CREATED,returnCode == HttpStatus.SC_CREATED);
} finally {postMethod.releaseConnection();
}
126
News Feed ResourcesChatter REST API Resources
Example of a link postThis request creates a link post using the request parameters:
/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:
{ "body" : {"messageSegments" : [
{"type": "Link","url" : "http://www.chatter.com"
},{
"type": "Text","text" : "Is everyone following this?"
}]
}}
This is the request body for including a link as an attachment to a feed-item post:
{ "body" : {"messageSegments" : [
{"type": "Text","text" : "Is everyone following this?"
}]
},"attachment" :{
"url" : "http://www.chatter.com","urlName" : "The Future of Social Enterprise"
}}
News Feed Items FlatThis 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 commentsare at the same level. All items are returned in chronological order.
Resource
/chatter/feeds/news/me/feed-items/flat
or
/chatter/feeds/news/userId/feed-items/flat
Note: userId must be the ID of the logged-in user or the alias me.
Available since version25.0
127
News Feed ResourcesChatter REST API Resources
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
Specifies the number of feed itemsreturned. Valid values are between 0
IntegernumFeedItems
and 100. Default value is 25. Becausefeed items may include comments,specifying 25 flat feed items mayactually return more. For example, ifeach feed item has one comment, andrecentCommentCount is greater than1, 50 flat feed items are returned.
A generated token that indicates theview of feed items in the feed. Page
Stringpage
tokens are returned as part of theresponse body, in one of the URLparameters, such as nextPageURL.
Specifies the number of recentcomments returned. Valid values arebetween 0 and 25. Default value is 3.
IntegerrecentCommentCount
Sorts the returned feed either bycreated date in ascending order, or by
String. One of the following:sort
• CreatedDateDesclast modified date, also in ascending• LastModifiedDateDescorder. The default isLastModifiedDateDesc
Response bodyFlat Feed
See Also:Chatter REST API: How do I. . .Working with Feeds and Feed Items
People Feed ResourcesAll feed items posted by all of the people the logged-in user follows.
Available resources are:
DescriptionResource
Returns a URL to the feed-items for all the people thelogged-in user is following.
/chatter/feeds/people/me
Returns all the feed items from all the people the logged-inuser follows.
/chatter/feeds/people/me/feed-items
128
People Feed ResourcesChatter REST API Resources
People Feed URLReturns a URL to the feed-items for all the people the logged-in user is following.
Resource
/chatter/feeds/people/me
or
/chatter/feeds/people/userId
Note: userId must be the ID of the logged-in user or the alias me.
Available since version23.0
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
Specifies the order returned by the sort,such as by date created or last modified:
Stringsort
• CreatedDateDesc—Sorts thefeed items by most recent post date.
• LastModifiedDateDesc—Sortsthe feed items by most recentactivity, which includes new feeditems and comments.
The default value isCreatedDescDate.
Response bodyFeed
People Feed ItemsReturns all the feed items from all the people the logged-in user follows.
Resource
/chatter/feeds/people/me/feed-items
or
/chatter/feeds/people/userId/feed-items
129
People Feed ResourcesChatter REST API Resources
Note: userId must be the ID of the logged-in user or the alias me.
Available since version23.0
HTTP methodsGET or HEAD
Request parameters
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
29.0OptionalThe density of the feed. One of these values:Stringdensity
• AllUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of.
• FewerUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of, buthides system-generated posts from records thatnobody commented on.
The default value is AllUpdates.
23.0OptionalA generated token that indicates the view of feeditems in the feed. Page tokens are returned as part
Stringpage
of the response body, in one of the URLparameters, such as nextPageURL, for example:
"nextPageUrl":"/services/data/v30.0/chatter/feeds/news/005D0000001GLowIAN/feed-items?page=2011-03-30T17:34:50Z,0D5D0000000DSv4KAG"
23.0OptionalSpecifies the number of items per page. Validvalues are between 1 and 100. If you don't specifya size, the default is 25.
IntegerpageSize
28.0OptionalOne or more keywords to search for in the bodyand comments of feed items in this feed.
The search string can contain wildcards and mustcontain at least two characters that aren’t wildcards.See Wildcards.
Stringq
29.0OptionalMaximum number of comments to include perfeed item. The default value is 3. The maximumvalue is 25.
IntegerrecentCommentCount
130
People Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
23.0OptionalSpecifies the order returned by the sort, such as bydate created or last modified:
Stringsort
• CreatedDateDesc—Sorts the feed items bymost recent post date.
• LastModifiedDateDesc—Sorts the feeditems by most recent activity, which includesnew feed items and comments.
The default value is CreatedDescDate.
30.0OptionalAn opaque token defining the modification timestamp of the feed and the sort order.
Do not construct this token. Retrieve this tokenfrom the updatesToken property of the FeedItem Page response body.
StringupdatedSince
Response bodyFeed Item Page
People Feed Items FlatThis 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 commentsare at the same level. All items are returned in chronological order.
Resource
/chatter/feeds/people/me/feed-items/flat
or
/chatter/feeds/people/userId/feed-items/flat
Note: userId must be the ID of the logged-in user or the alias me.
Available since version25.0
HTTP methodsGET or HEAD
131
People Feed ResourcesChatter REST API Resources
Request parameters
DescriptionTypeParameter Name
Specifies the number of feed itemsreturned. Valid values are between 0
IntegernumFeedItems
and 100. Default value is 25. Becausefeed items may include comments,specifying 25 flat feed items mayactually return more. For example, ifeach feed item has one comment, andrecentCommentCount is greater than1, 50 flat feed items are returned.
A generated token that indicates theview of feed items in the feed. Page
Stringpage
tokens are returned as part of theresponse body, in one of the URLparameters, such as nextPageURL.
Specifies the number of recentcomments returned. Valid values arebetween 0 and 25. Default value is 3.
IntegerrecentCommentCount
Sorts the returned feed either bycreated date in ascending order, or by
String. One of the following:sort
• CreatedDateDesclast modified date, also in ascending• LastModifiedDateDescorder. The default isLastModifiedDateDesc
Response bodyFlat Feed
See Also:Chatter REST API: How do I. . .Working with Feeds and Feed Items
Record Feed ResourceThe feed of the specified record, which could be a group, person, object, file and so on. You can post feed items to the recordfeed.
Available resources are:
DescriptionResource
Returns a URL to the feed-items for all the records the currentuser is following, or a URL to all the feed-items of thespecified recordId. Use this resource to get a group feed.
/chatter/feeds/record/recordId
Returns the feed-items for all the records the logged-in useris following, or all the feed-items of the specified recordId.
/chatter/feeds/record/recordId/feed-items
Use this resource to post a new feed item and to search a feed.
132
Record Feed ResourceChatter REST API Resources
DescriptionResource
To use this resource to get the feed items for a specific group,specify the group ID as the recordId.
Record Feed URLReturns a URL to the feed-items for all the records the current user is following, or a URL to all the feed-items of the specifiedrecordId. Use this resource to get a group feed.
Resource
/chatter/feeds/record/me
or
/chatter/feeds/record/recordId
Note: If recordId is a user ID, it must be the same as the current user or the alias me.
Available since version23.0
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
Specifies the order returned by the sort,such as by date created or last modified:
Stringsort
• CreatedDateDesc—Sorts thefeed items by most recent post date.
• LastModifiedDateDesc—Sortsthe feed items by most recentactivity, which includes new feeditems and comments.
The default value isCreatedDescDate.
Response bodyFeed
Record Feed ItemsReturns the feed-items for all the records the logged-in user is following, or all the feed-items of the specified recordId. Usethis resource to post a new feed item and to search a feed. To use this resource to get the feed items for a specific group, specifythe group ID as the recordId.
For information about posting a feed item, see Using POST, PATCH, or PUT for Input.
133
Record Feed ResourceChatter REST API Resources
For information about uploading a binary file and attaching it to a feed item, see Uploading Binary Files.
Note: You cannot post a feed item to a Record Feed if the record is of type ContentDocument.
As of API version 29.0, feed items can contain 5000 characters. This change is backwards compatible; all earlier API versionssupport the 5000 character limit.
Resource
/chatter/feeds/record/me/feed-items
or
/chatter/feeds/record/recordId/feed-items
Note: If recordId is a user ID, it must be the same as the current user or the alias me.
Available since version23.0
HTTP methodsGET, POST or HEAD
Request parameters for GET or HEAD
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
29.0OptionalThe density of the feed. One of these values:Stringdensity
• AllUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of.
• FewerUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of, buthides system-generated posts from records thatnobody commented on.
The default value is AllUpdates.
23.0OptionalA generated token that indicates the view of feeditems in the feed. Page tokens are returned as part
Stringpage
of the response body, in one of the URLparameters, such as nextPageURL, for example:
"nextPageUrl":"/services/data/v30.0/chatter/feeds/news/005D0000001GLowIAN/feed-items?page=2011-03-30T17:34:50Z,0D5D0000000DSv4KAG"
134
Record Feed ResourceChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
23.0OptionalSpecifies the number of items per page. Validvalues are between 1 and 100. If you don't specifya size, the default is 25.
IntegerpageSize
28.0OptionalOne or more keywords to search for in the bodyand comments of feed items in this feed.
The search string can contain wildcards and mustcontain at least two characters that aren’t wildcards.See Wildcards.
Stringq
29.0OptionalMaximum number of comments to include perfeed item. The default value is 3. The maximumvalue is 25.
IntegerrecentCommentCount
30.0OptionalSpecifies whether to show only feed items frominternal (non-community) users (true), or not(false). The default value is false.
BooleanshowInternalOnly
23.0OptionalSpecifies the order returned by the sort, such as bydate created or last modified:
Stringsort
• CreatedDateDesc—Sorts the feed items bymost recent post date.
• LastModifiedDateDesc—Sorts the feeditems by most recent activity, which includesnew feed items and comments.
The default value is CreatedDescDate.
30.0OptionalAn opaque token defining the modification timestamp of the feed and the sort order.
Do not construct this token. Retrieve this tokenfrom the updatesToken property of the FeedItem Page response body.
StringupdatedSince
Request body for POST
Root XML tag<feedItem>
JSONThe following example attaches a poll to a feed item:
{ "attachment":{
"attachmentType":"Poll","pollChoices": [
"Monday","Tuesday"
]},"body" : {
"messageSegments" : [{
135
Record Feed ResourceChatter REST API Resources
"type" : "Text","text" : "When should we meet for release planning?"
}]
}}
Properties
AvailableVersion
DescriptionTypeName
Optional. You can specify only one ofthese values in the attachment parameter.Values are:
Depends on type.attachment
• 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)
Note: To upload a new file,you must include it in amultipart/form–datamessage. See UploadingBinary Files.
23.0Description of message body. The bodycan contain up to 25 mentions.
If you specify originalFeedItemIdto share a feed item, use the body
Message Body Inputbody
property to add a comment to the feeditem.
If this feed item is shared, this value isthe body of the first comment.
24.0Optional. Specifies if the new feed itemshould be bookmarked for the user
BooleanisBookmarkedByCurrentUser
(true) or not (false). Default value isfalse.
24.0Optional. If this feed item is shared, thisis the original feed item 18-character ID
StringoriginalFeedItemId
Note: This parameter takesprecedence over all otherparameters. For example, if youshare a post and also try toupload a file, the generatedfeed-item only contains the
136
Record Feed ResourceChatter REST API Resources
AvailableVersion
DescriptionTypeName
shared post. You should onlyshare a post or upload a file, notboth in the same post.
26.0Optional. Who can see the post. Validvalues are:
Stringvisibility
• InternalUsers—If Communitiesis enabled, only members of thedefault, internal community can seethe feed item.
• AllUsers—If Communities isenabled, all members of thecommunity can see the feed item.
Default values:
• For external users, the default valueis AllUsers. External users mustuse this value to see their posts.
• For internal users, the default valueis InternalUsers. Internal userscan accept this value or use the valueAllUsers to allow external users tosee their posts.
If the parent of the feed item is a Useror a Group, the visibility of the feeditem must be AllUsers.
Request parameters for POSTUse 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
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
27.0RequiredThe attachment type. Must contain the valueExistingContent.
StringattachmentType
23.0Required18-character ID of an existing file.StringcontentDocumentId
26.0OptionalSpecifies if the new feed item should be bookmarkedfor the user (true) or not (false). Default valueis false.
BooleanisBookmarkedByCurrentUser
23.0OptionalText of the feed item.Stringtext
137
Record Feed ResourceChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities is enabled,only members of the default, internal communitycan see the feed item.
• AllUsers—If Communities is enabled, allmembers of the community can see the feed item.
Default values:
• For external users, the default value isAllUsers. External users must use this valueto see their posts.
• For internal users, the default value isInternalUsers. Internal users can accept thisvalue or use the value AllUsers to allowexternal 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 beAllUsers.
Parameters for attaching a new file
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
27.0RequiredThe attachment type. Must contain the valueNewFile.
StringattachmentType
23.0–26.0OptionalDescription of file being posted.Stringdesc
Attention: This parameter should not beused as of version 27.0. Use descriptioninstead.
27.0OptionalDescription of file being posted.Stringdescription
23.0–24.0RequiredFile name of the file being posted.StringfileName
Attention: This parameter should not beused as of version 24.0. Use title instead.
26.0OptionalSpecifies if the new feed item should be bookmarkedfor the user (true) or not (false). Default value isfalse.
BooleanisBookmarkedByCurrentUser
23.0OptionalText of the feed item.Stringtext
24.0RequiredFile name of a file to be uploaded and posted.Stringtitle
138
Record Feed ResourceChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities is enabled,only members of the default, internal communitycan see the feed item.
• AllUsers—If Communities is enabled, allmembers 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 theirposts.
• For internal users, the default value isInternalUsers. Internal users can accept thisvalue or use the value AllUsers to allowexternal 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 beAllUsers.
Parameters for posting a link
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
27.0RequiredThe attachment type. Must contain the valueLink.
StringattachmentType
26.0OptionalSpecifies if the new feed item should bebookmarked for the user (true) or not(false). Default value is false.
BooleanisBookmarkedByCurrentUser
23.0OptionalText of the feed item.Stringtext
23.0RequiredURL of the link.Stringurl
23.0OptionalName of the URL.StringurlName
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities isenabled, only members of the default,internal community can see the feed item.
• AllUsers—If Communities is enabled,all members of the community can see thefeed item.
Default values:
• For external users, the default value isAllUsers. External users must use thisvalue to see their posts.
139
Record Feed ResourceChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
• For internal users, the default value isInternalUsers. Internal users can acceptthis value or use the value AllUsers toallow external users to see their posts.
If the parent of the feed item is a User or aGroup, the visibility of the feed item mustbe AllUsers.
Parameters for posting a poll
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
27.0RequiredThe attachment type. Must contain the valuePoll.
StringattachmentType
26.0OptionalSpecifies if the new feed item should bebookmarked for the user (true) or not(false). Default value is false.
BooleanisBookmarkedByCurrentUser
26.0RequiredThe choices used to create a new feed itemwith a poll. You must specify 2–10 poll choicesfor each poll.
StringpollChoice1 throughpollChoice10
23.0RequiredText of the feed item.Stringtext
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities isenabled, only members of the default,internal community can see the feed item.
• AllUsers—If Communities is enabled,all members of the community can see thefeed item.
Default values:
• For external users, the default value isAllUsers. External users must use thisvalue to see their posts.
• For internal users, the default value isInternalUsers. Internal users can acceptthis value or use the value AllUsers toallow external users to see their posts.
If the parent of the feed item is a User or aGroup, the visibility of the feed item mustbe AllUsers.
Parameters for sharing a post
140
Record Feed ResourceChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
26.0OptionalSpecifies if the new feed item should bebookmarked for the user (true) or not(false). Default value is false.
BooleanisBookmarkedByCurrentUser
24.0RequiredThe ID of the feed item you want toshare.18-character ID
StringoriginalFeedItemId
Note: Sharing a post takes precedenceover uploading a file. Do not share apost and upload a file in the samepost.
28.0OptionalA comment on the shared feed item.Stringtext
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities isenabled, only members of the default,internal community can see the feed item.
• AllUsers—If Communities is enabled,all members of the community can see thefeed item.
Default values:
• For external users, the default value isAllUsers. External users must use thisvalue to see their posts.
• For internal users, the default value isInternalUsers. Internal users can acceptthis value or use the value AllUsers toallow external users to see their posts.
If the parent of the feed item is a User or aGroup, the visibility of the feed item mustbe AllUsers.
Parameters for posting text only
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
26.0OptionalSpecifies if the new feed item should bebookmarked for the user (true) or not(false). Default value is false.
BooleanisBookmarkedByCurrentUser
23.0RequiredText of the feed item. The maximum numberof characters is 1000.
Stringtext
141
Record Feed ResourceChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities isenabled, only members of the default,internal community can see the feed item.
• AllUsers—If Communities is enabled,all members of the community can see thefeed item.
Default values:
• For external users, the default value isAllUsers. External users must use thisvalue to see their posts.
• For internal users, the default value isInternalUsers. Internal users can acceptthis value or use the value AllUsers toallow external users to see their posts.
If the parent of the feed item is a User or aGroup, the visibility of the feed item mustbe AllUsers.
Parameters for posting a canvas app
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
29.0RequiredThe attachment type. Must contain the valueCanvas.
StringattachmentType
29.0OptionalDescription of the canvas appStringdescription
29.0RequiredThe developer name (API name) of the canvas appStringdeveloperName
29.0OptionalThe height of the canvas app in pixels. Defaultheight is 200 pixels.
Stringheight
29.0OptionalSpecifies if the new feed item should be bookmarkedfor the user (true) or not (false). Default valueis false.
BooleanisBookmarkedByCurrentUser
29.0OptionalThe namespace prefix of the Developer Editionorganization in which the canvas app was created.
StringnamespacePrefix
29.0OptionalParameters passed to the canvas app in JSON format.The JSON must be URL-encoded:parameters={'isUpdated'='true';}"
Stringparameters
29.0OptionalText of the feed itemStringtext
29.0OptionalThe URL to a thumbnail image for the canvas app.Maximum dimensions are 120x120 pixels.
StringthumbnailUrl
142
Record Feed ResourceChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
29.0OptionalThe title of the link to the canvas appStringtitle
29.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities is enabled,only members of the default, internal communitycan see the feed item.
• AllUsers—If Communities is enabled, allmembers of the community can see the feed item.
Default values:
• For external users, the default value isAllUsers. External users must use this valueto see their posts.
• For internal users, the default value isInternalUsers. Internal users can accept thisvalue or use the value AllUsers to allowexternal 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 beAllUsers.
Response body for GET or HEADFeed Item Page
Response body for POSTFeed Item
Example for GETThis request searches for feed items that contain the string track:
/chatter/feeds/record/me/feed-items?q=track
In the Feed Item Page response body, the string track is found in the feed-items/items/body/text property:
{"currentPageUrl":
"/services/data/v30.0/chatter/feeds/record/005D0000001LL8OIAW/feed-items","isModifiedToken": null,"isModifiedUrl": null,"items": [{
"actor": {"companyName": "Universal Containers","firstName": "Deanna","id": "005D0000001LL8OIAW","isActive": true,"isInThisCommunity": true,"lastName": "Li","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
143
Record Feed ResourceChatter REST API Resources
},"mySubscription": null,"name": "Deanna Li","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5savQXz9sPZRCJJB7fC4UIka",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/F","photoVersionId": "729D00000000LJFIA2","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/T","standardEmailPhotoUrl":
"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5saluKolvB94ZwqX5yHBSBOh",
"url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW","userType": "Internal"
},"attachment": null,"body": {
"messageSegments": [{"text": "I'm building an app to track "floater" holidays.
Does anyone have any feature requests?","type": "Text"
}],"text": "I'm building an app to track "floater" holidays.
Does anyone have any feature requests?"},"canShare": true,"clientInfo": null,"comments": {
"comments": [],"currentPageUrl":
"/services/data/v30.0/chatter/feed-items/0D5D0000000HwkyKAC/comments","nextPageUrl": null,"total": 4
},"createdDate": "2012-09-12T00:54:27.000Z","event": false,"id": "0D5D0000000HwkyKAC","isBookmarkedByCurrentUser": false,"isDeleteRestricted": false,"isLikedByCurrentUser": false,"likes": {
"currentPageUrl":"/services/data/v30.0/chatter/feed-items/0D5D0000000HwkyKAC/likes",
"likes": [],"nextPageUrl": null,"previousPageUrl": null,"total": 0
},"likesMessage": null,"modifiedDate": "2012-09-12T01:01:42.000Z","moderationFlags": null,"myLike": null,"originalFeedItem": null,"originalFeedItemActor": null,"parent": {
"companyName": "Universal Containers","firstName": "Deanna","id": "005D0000001LL8OIAW","isActive": true,"isInThisCommunity": true,"lastName": "Li","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png",
144
Record Feed ResourceChatter REST API Resources
"mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Deanna Li","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5savQXz9sPZRCJJB7fC4UIka",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/F","photoVersionId": "729D00000000LJFIA2","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/T","standardEmailPhotoUrl":
"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5saluKolvB94ZwqX5yHBSBOh",
"url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW","userType": "Internal"
},"photoUrl": "https://instance_name/profilephoto/729D00000000LJF/T","preamble": {
"messageSegments": [{"motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"reference": {
"id": "005D0000001LL8OIAW","url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW"
},"text": "Deanna Li","type": "EntityLink"
}],"text": "Deanna Li"
},"topics": null,"type": "TextPost","url": "/services/data/v30.0/chatter/feed-items/0D5D0000000HwkyKAC","visibility": "AllUsers"
}],"nextPageUrl": null
}
Record Feed Items FlatThis 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 commentsare at the same level. All items are returned in chronological order.
Resource
/chatter/feeds/record/me/feed-items/flat
or
/chatter/feeds/record/userId/feed-items/flat
145
Record Feed ResourceChatter REST API Resources
Note: userId must be the ID of the logged-in user or the alias me.
Available since version25.0
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
Specifies the number of feed itemsreturned. Valid values are between 0
IntegernumFeedItems
and 100. Default value is 25. Becausefeed items may include comments,specifying 25 flat feed items mayactually return more. For example, ifeach feed item has one comment, andrecentCommentCount is greater than1, 50 flat feed items are returned.
A generated token that indicates theview of feed items in the feed. Page
Stringpage
tokens are returned as part of theresponse body, in one of the URLparameters, such as nextPageURL.
Specifies the number of recentcomments returned. Valid values arebetween 0 and 25. Default value is 3.
IntegerrecentCommentCount
Sorts the returned feed either bycreated date in ascending order, or by
String. One of the following:sort
• CreatedDateDesclast modified date, also in ascending• LastModifiedDateDescorder. The default isLastModifiedDateDesc
Response bodyFlat Feed
See Also:Records ResourcesChatter REST API: How do I. . .Working with Feeds and Feed Items
To Feed ResourcesA feed containing all @mentions of the logged-in user and posts others have made to the logged-in user's feed.
146
To Feed ResourcesChatter REST API Resources
Available resources are:
DescriptionResource
Returns a URL to the feed-items for the feed of the logged-inuser.
/chatter/feeds/to/me
Returns the feed-items for all @mentions of the logged-inuser, and all posts made to the user's feed.
/chatter/feeds/to/me/feed-items
To Feed URLReturns a URL to the feed-items for the feed of the logged-in user.
Resource
/chatter/feeds/to/me
OR
/chatter/feeds/to/userId
Note: userId must be the ID of the logged-in user or the alias me.
Available since version23.0
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
Specifies the order returned by the sort,such as by date created or last modified:
Stringsort
• CreatedDateDesc—Sorts thefeed items by most recent post date.
• LastModifiedDateDesc—Sortsthe feed items by most recentactivity, which includes new feeditems and comments.
The default value isCreatedDescDate.
Response bodyFeed
147
To Feed ResourcesChatter REST API Resources
To Feed ItemsReturns the feed-items for all @mentions of the logged-in user, and all posts made to the user's feed. The To Feed includesposts that mention you and posts that other users make to your wall. Your own posts are included only if they have a comment.The comment can be from you or from another user.
Resource
/chatter/feeds/to/me/feed-items
OR
/chatter/feeds/to/userId/feed-items
Note: userId must be the ID of the logged-in user or the alias me.
Available since version23.0
HTTP methodsGET or HEAD
Request parameters
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
29.0OptionalThe density of the feed. One of these values:Stringdensity
• AllUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of.
• FewerUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of, buthides system-generated posts from records thatnobody commented on.
The default value is AllUpdates.
23.0OptionalA generated token that indicates the view of feeditems in the feed. Page tokens are returned as part
Stringpage
of the response body, in one of the URLparameters, such as nextPageURL, for example:
"nextPageUrl":"/services/data/v30.0/chatter/feeds/news/005D0000001GLowIAN/feed-items?page=2011-03-30T17:34:50Z,0D5D0000000DSv4KAG"
148
To Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
23.0OptionalSpecifies the number of items per page. Validvalues are between 1 and 100. If you don't specifya size, the default is 25.
IntegerpageSize
28.0OptionalOne or more keywords to search for in the bodyand comments of feed items in this feed.
The search string can contain wildcards and mustcontain at least two characters that aren’t wildcards.See Wildcards.
Stringq
29.0OptionalMaximum number of comments to include perfeed item. The default value is 3. The maximumvalue is 25.
IntegerrecentCommentCount
23.0OptionalSpecifies the order returned by the sort, such as bydate created or last modified:
Stringsort
• CreatedDateDesc—Sorts the feed items bymost recent post date.
• LastModifiedDateDesc—Sorts the feeditems by most recent activity, which includesnew feed items and comments.
The default value is CreatedDescDate.
Response body for GET or HEADFeed Item Page
To Feed Items FlatThis 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 commentsare at the same level. All items are returned in chronological order.
Resource
/chatter/feeds/to/me/feed-items/flat
or
/chatter/feeds/to/userId/feed-items/flat
Note: userId must be the ID of the logged-in user or the alias me.
Available since version25.0
149
To Feed ResourcesChatter REST API Resources
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
Specifies the number of feed itemsreturned. Valid values are between 0
IntegernumFeedItems
and 100. Default value is 25. Becausefeed items may include comments,specifying 25 flat feed items mayactually return more. For example, ifeach feed item has one comment, andrecentCommentCount is greater than1, 50 flat feed items are returned.
A generated token that indicates theview of feed items in the feed. Page
Stringpage
tokens are returned as part of theresponse body, in one of the URLparameters, such as nextPageURL.
Specifies the number of recentcomments returned. Valid values arebetween 0 and 25. Default value is 3.
IntegerrecentCommentCount
Sorts the returned feed either bycreated date in ascending order, or by
String. One of the following:sort
• CreatedDateDesclast modified date, also in ascending• LastModifiedDateDescorder. The default isLastModifiedDateDesc
Response bodyFlat Feed
See Also:Chatter REST API: How do I. . .Working with Feeds and Feed Items
Topics Feed ResourcesThe feed of the specified topic.
Available resources are:
DescriptionResource
Returns a URL to the feed items for the specified topic./chatter/feeds/topics/topicId
Returns all feed items for the specified topic./chatter/feeds/topics/topicId/feed-items
150
Topics Feed ResourcesChatter REST API Resources
Topics Feed URLReturns a URL to the feed items for the specified topic.
Resource
/chatter/feeds/topics/topicId
Available since version28.0
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
Specifies the order returned by the sort,such as by date created or last modified:
Stringsort
• CreatedDateDesc—Sorts thefeed items by most recent post date.
• LastModifiedDateDesc—Sortsthe feed items by most recentactivity, which includes new feeditems and comments.
The default value isCreatedDescDate.
Response bodyFeed
Topics Feed ItemsReturns all feed items for the specified topic. To post a topic, use the Feed-Items Topics resource.
Resource
/chatter/feeds/topics/topicId/feed-items
Available since version28.0
HTTP methodsGET or HEAD
151
Topics Feed ResourcesChatter REST API Resources
Request parameters
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
28.0OptionalA generated token that indicates the view of feeditems in the feed. Page tokens are returned as part
Stringpage
of the response body, in one of the URLparameters, such as nextPageURL.
28.0OptionalSpecifies the number of items per page. Validvalues are between 1 and 100. If you don't specifya size, the default is 25.
IntegerpageSize
28.0OptionalSpecifies the order returned by the sort, such as bydate created or last modified:
Stringsort
• CreatedDateDesc—Sorts the feed items bymost recent post date.
• LastModifiedDateDesc—Sorts the feeditems by most recent activity, which includesnew feed items and comments.
The default value is CreatedDescDate.
Response bodyFeed Item Page
See Also:Chatter REST API: How do I. . .Working with Feeds and Feed Items
User Profile Feed ResourcesA feed containing actions by the current user on records that can be tracked in a feed. This feed is differentthan/chatter/feeds/news, which returns more items, including posts, group updates, and record updates. You can postfeed items to the user-profile feed.
Note: The composition of this feed may change between releases.
Available resources are:
DescriptionResource
Returns a URL to the feed-items for the user-profile feed./chatter/feeds/user-profile/me
Returns the feed-items for all actions on all records that canbe tracked in a feed. You can also use this resource to post anew feed item.
/chatter/feeds/user-profile/me/feed-items
152
User Profile Feed ResourcesChatter REST API Resources
User Profile Feed URLReturns a URL to the feed-items for the user-profile feed.
Resource
/chatter/feeds/user-profile/me
or
/chatter/feeds/user-profile/userId
Available since version23.0
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
Specifies the order returned by the sort,such as by date created or last modified:
Stringsort
• CreatedDateDesc—Sorts thefeed items by most recent post date.
• LastModifiedDateDesc—Sortsthe feed items by most recentactivity, which includes new feeditems and comments.
The default value isCreatedDescDate.
Response bodyFeed
User Profile Feed ItemsReturns the feed-items for all actions on all records that can be tracked in a feed. You can also use this resource to post a newfeed item.
For information about posting a feed item, see Using POST, PATCH, or PUT for Input.
To upload a binary file, you must send it as a body part in a multipart/form-data request. You can send information such asthe text of a post or comment as a JSON or XML rich input body part in the same multipart/form-data request. Alternately,you can choose to send that information in request parameters. If you pass both a rich input request body and request parameters,the request parameters are ignored. For information about how to create the multipart/form-data message, see UploadingBinary Files.As of API version 29.0, feed items can contain 5000 characters. This change is backwards compatible; all earlier API versionssupport the 5000 character limit. In API versions 23.0 and 24.0, posts to the User Profile Feed Items resource created userstatus updates; they didn’t create feed items. Therefore, the character limit for the User Profile Feed Items resource for thoseAPI versions is still 1000 characters.
153
User Profile Feed ResourcesChatter REST API Resources
Resource
/chatter/feeds/user-profile/me/feed-items
or
/chatter/feeds/user-profile/userId/feed-items
Available since version23.0
HTTP methodsGET, POST or HEAD
Request body for POST
Root XML tag<feedItem>
JSONThe following example attaches a poll to a feed item:
{ "attachment":{
"attachmentType":"Poll","pollChoices": [
"Monday","Tuesday"
]},"body" : {
"messageSegments" : [{
"type" : "Text","text" : "When should we meet for release planning?"
}]
}}
Properties
AvailableVersion
DescriptionTypeName
Optional. You can specify only one ofthese values in the attachment parameter.Values are:
Depends on type.attachment
• Attachment Input: Canvas App(v29.0)
• Attachment Input: Existing Content(v23.0)
• Attachment Input: Feed Poll (v26.0)• Attachment Input: Link (v23.0)
154
User Profile Feed ResourcesChatter REST API Resources
AvailableVersion
DescriptionTypeName
• Attachment Input: New File Upload(v23.0)
Note: To upload a new file,you must include it in amultipart/form–datamessage. See UploadingBinary Files.
23.0Description of message body. The bodycan contain up to 25 mentions.
If you specify originalFeedItemIdto share a feed item, use the body
Message Body Inputbody
property to add a comment to the feeditem.
If this feed item is shared, this value isthe body of the first comment.
24.0Optional. Specifies if the new feed itemshould be bookmarked for the user
BooleanisBookmarkedByCurrentUser
(true) or not (false). Default value isfalse.
24.0Optional. If this feed item is shared, thisis the original feed item 18-character ID
StringoriginalFeedItemId
Note: This parameter takesprecedence over all otherparameters. For example, if youshare a post and also try toupload a file, the generatedfeed-item only contains theshared post. You should onlyshare a post or upload a file, notboth in the same post.
26.0Optional. Who can see the post. Validvalues are:
Stringvisibility
• InternalUsers—If Communitiesis enabled, only members of thedefault, internal community can seethe feed item.
• AllUsers—If Communities isenabled, all members of thecommunity can see the feed item.
Default values:
155
User Profile Feed ResourcesChatter REST API Resources
AvailableVersion
DescriptionTypeName
• For external users, the default valueis AllUsers. External users mustuse this value to see their posts.
• For internal users, the default valueis InternalUsers. Internal userscan accept this value or use the valueAllUsers to allow external users tosee their posts.
If the parent of the feed item is a Useror a Group, the visibility of the feeditem must be AllUsers.
Request parameters for POSTUse 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
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
27.0RequiredThe attachment type. Must contain the valueExistingContent.
StringattachmentType
23.0Required18-character ID of an existing file.StringcontentDocumentId
26.0OptionalSpecifies if the new feed item should be bookmarkedfor the user (true) or not (false). Default valueis false.
BooleanisBookmarkedByCurrentUser
23.0OptionalText of the feed item.Stringtext
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities is enabled,only members of the default, internal communitycan see the feed item.
• AllUsers—If Communities is enabled, allmembers of the community can see the feed item.
Default values:
• For external users, the default value isAllUsers. External users must use this valueto see their posts.
• For internal users, the default value isInternalUsers. Internal users can accept thisvalue or use the value AllUsers to allowexternal 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 beAllUsers.
156
User Profile Feed ResourcesChatter REST API Resources
Parameters for attaching a new file
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
27.0RequiredThe attachment type. Must contain the valueNewFile.
StringattachmentType
23.0–26.0OptionalDescription of file being posted.Stringdesc
Attention: This parameter should not beused as of version 27.0. Use descriptioninstead.
27.0OptionalDescription of file being posted.Stringdescription
23.0–24.0RequiredFile name of the file being posted.StringfileName
Attention: This parameter should not beused as of version 24.0. Use title instead.
26.0OptionalSpecifies if the new feed item should be bookmarkedfor the user (true) or not (false). Default value isfalse.
BooleanisBookmarkedByCurrentUser
23.0OptionalText of the feed item.Stringtext
24.0RequiredFile name of a file to be uploaded and posted.Stringtitle
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities is enabled,only members of the default, internal communitycan see the feed item.
• AllUsers—If Communities is enabled, allmembers 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 theirposts.
• For internal users, the default value isInternalUsers. Internal users can accept thisvalue or use the value AllUsers to allowexternal 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 beAllUsers.
Parameters for posting a link
157
User Profile Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
27.0RequiredThe attachment type. Must contain the valueLink.
StringattachmentType
26.0OptionalSpecifies if the new feed item should bebookmarked for the user (true) or not(false). Default value is false.
BooleanisBookmarkedByCurrentUser
23.0OptionalText of the feed item.Stringtext
23.0RequiredURL of the link.Stringurl
23.0OptionalName of the URL.StringurlName
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities isenabled, only members of the default,internal community can see the feed item.
• AllUsers—If Communities is enabled,all members of the community can see thefeed item.
Default values:
• For external users, the default value isAllUsers. External users must use thisvalue to see their posts.
• For internal users, the default value isInternalUsers. Internal users can acceptthis value or use the value AllUsers toallow external users to see their posts.
If the parent of the feed item is a User or aGroup, the visibility of the feed item mustbe AllUsers.
Parameters for posting a poll
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
27.0RequiredThe attachment type. Must contain the valuePoll.
StringattachmentType
26.0OptionalSpecifies if the new feed item should bebookmarked for the user (true) or not(false). Default value is false.
BooleanisBookmarkedByCurrentUser
26.0RequiredThe choices used to create a new feed itemwith a poll. You must specify 2–10 poll choicesfor each poll.
StringpollChoice1 throughpollChoice10
23.0RequiredText of the feed item.Stringtext
158
User Profile Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities isenabled, only members of the default,internal community can see the feed item.
• AllUsers—If Communities is enabled,all members of the community can see thefeed item.
Default values:
• For external users, the default value isAllUsers. External users must use thisvalue to see their posts.
• For internal users, the default value isInternalUsers. Internal users can acceptthis value or use the value AllUsers toallow external users to see their posts.
If the parent of the feed item is a User or aGroup, the visibility of the feed item mustbe AllUsers.
Parameters for sharing a post
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
26.0OptionalSpecifies if the new feed item should bebookmarked for the user (true) or not(false). Default value is false.
BooleanisBookmarkedByCurrentUser
24.0RequiredThe ID of the feed item you want toshare.18-character ID
StringoriginalFeedItemId
Note: Sharing a post takes precedenceover uploading a file. Do not share apost and upload a file in the samepost.
28.0OptionalA comment on the shared feed item.Stringtext
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities isenabled, only members of the default,internal community can see the feed item.
• AllUsers—If Communities is enabled,all members of the community can see thefeed item.
Default values:
159
User Profile Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
• For external users, the default value isAllUsers. External users must use thisvalue to see their posts.
• For internal users, the default value isInternalUsers. Internal users can acceptthis value or use the value AllUsers toallow external users to see their posts.
If the parent of the feed item is a User or aGroup, the visibility of the feed item mustbe AllUsers.
Parameters for posting text only
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
26.0OptionalSpecifies if the new feed item should bebookmarked for the user (true) or not(false). Default value is false.
BooleanisBookmarkedByCurrentUser
23.0RequiredText of the feed item. The maximum numberof characters is 1000.
Stringtext
26.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities isenabled, only members of the default,internal community can see the feed item.
• AllUsers—If Communities is enabled,all members of the community can see thefeed item.
Default values:
• For external users, the default value isAllUsers. External users must use thisvalue to see their posts.
• For internal users, the default value isInternalUsers. Internal users can acceptthis value or use the value AllUsers toallow external users to see their posts.
If the parent of the feed item is a User or aGroup, the visibility of the feed item mustbe AllUsers.
Parameters for posting a canvas app
160
User Profile Feed ResourcesChatter REST API Resources
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
29.0RequiredThe attachment type. Must contain the valueCanvas.
StringattachmentType
29.0OptionalDescription of the canvas appStringdescription
29.0RequiredThe developer name (API name) of the canvas appStringdeveloperName
29.0OptionalThe height of the canvas app in pixels. Defaultheight is 200 pixels.
Stringheight
29.0OptionalSpecifies if the new feed item should be bookmarkedfor the user (true) or not (false). Default valueis false.
BooleanisBookmarkedByCurrentUser
29.0OptionalThe namespace prefix of the Developer Editionorganization in which the canvas app was created.
StringnamespacePrefix
29.0OptionalParameters passed to the canvas app in JSON format.The JSON must be URL-encoded:parameters={'isUpdated'='true';}"
Stringparameters
29.0OptionalText of the feed itemStringtext
29.0OptionalThe URL to a thumbnail image for the canvas app.Maximum dimensions are 120x120 pixels.
StringthumbnailUrl
29.0OptionalThe title of the link to the canvas appStringtitle
29.0OptionalWho can see the post. Valid values are:Stringvisibility
• InternalUsers—If Communities is enabled,only members of the default, internal communitycan see the feed item.
• AllUsers—If Communities is enabled, allmembers of the community can see the feed item.
Default values:
• For external users, the default value isAllUsers. External users must use this valueto see their posts.
• For internal users, the default value isInternalUsers. Internal users can accept thisvalue or use the value AllUsers to allowexternal 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 beAllUsers.
161
User Profile Feed ResourcesChatter REST API Resources
Request parameters for GET or HEAD
AvailableVersion
RequiredorOptional
DescriptionTypeParameter Name
29.0OptionalThe density of the feed. One of these values:Stringdensity
• AllUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of.
• FewerUpdates—Displays all posts andcomments from people and records the userfollows and groups the user is a member of, buthides system-generated posts from records thatnobody commented on.
The default value is AllUpdates.
23.0OptionalA generated token that indicates the view of feeditems in the feed. Page tokens are returned as part
Stringpage
of the response body, in one of the URLparameters, such as nextPageURL, , for example:
"nextPageUrl":"/services/data/v30.0/chatter/feeds/news/005D0000001GLowIAN/feed-items?page=2011-03-30T17:34:50Z,0D5D0000000DSv4KAG"
23.0OptionalSpecifies the number of items per page. Validvalues are between 1 and 100. If you don't specifya size, the default is 25.
IntegerpageSize
28.0OptionalOne or more keywords to search for in the bodyand comments of feed items in this feed.
The search string can contain wildcards and mustcontain at least two characters that aren’t wildcards.See Wildcards.
Stringq
29.0OptionalMaximum number of comments to include perfeed item. The default value is 3. The maximumvalue is 25.
IntegerrecentCommentCount
23.0OptionalSpecifies the order returned by the sort, such as bydate created or last modified:
Stringsort
• CreatedDateDesc—Sorts the feed items bymost recent post date.
• LastModifiedDateDesc—Sorts the feeditems by most recent activity, which includesnew feed items and comments.
The default value is CreatedDescDate.
162
User Profile Feed ResourcesChatter REST API Resources
Response body for GET or HEADFeed Item Page
Response body for POSTFeed Item
User-Profile Feed Items FlatThis 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 commentsare at the same level. All items are returned in chronological order.
Resource
/chatter/feeds/user-profile/me/feed-items/flat
or
/chatter/feeds/user-profile/userId/feed-items/flat
Available since version25.0
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
Specifies the number of feed itemsreturned. Valid values are between 0
IntegernumFeedItems
and 100. Default value is 25. Becausefeed items may include comments,specifying 25 flat feed items mayactually return more. For example, ifeach feed item has one comment, andrecentCommentCount is greater than1, 50 flat feed items are returned.
A generated token that indicates theview of feed items in the feed. Page
Stringpage
tokens are returned as part of theresponse body, in one of the URLparameters, such as nextPageURL.
Specifies the number of recentcomments returned. Valid values arebetween 0 and 25. Default value is 3.
IntegerrecentCommentCount
Sorts the returned feed either bycreated date in ascending order, or by
String. One of the following:sort
• CreatedDateDesclast modified date, also in ascending• LastModifiedDateDescorder. The default isLastModifiedDateDesc
163
User Profile Feed ResourcesChatter REST API Resources
Response bodyFlat Feed
See Also:Chatter REST API: How do I. . .Working with Feeds and Feed Items
Feed Items ResourcesInformation about feed items. Access, search, delete, bookmark, and like feed items. Access and post comments. Access andvote in polls. And access, add, and remove topics.
Available resources:
DescriptionResource
A batch of feed items. Get informationabout multiple feed items in one request.
/chatter/feed-items/batch/feedItemIds
A paginated collection of feed items. Usethis resource to search for feed items. The
/chatter/feed-items?q=searchTerm
query parameter (q) is required. All typesof feed items are searched, includingtracked changes. A search returns feeditems with the search term in the feeditem body, as well as feed items that havecomments that contain the search term.You can also use wildcards with the queryparameter.
Access, delete, or bookmark a specificfeed item.
/chatter/feed-items/feedItemId
Access comments for a specific feed itemor post a comment.
/chatter/feed-items/feedItemId/comments
Used to access likes for a specific feeditem, or to add a like to a specific feeditem.
/chatter/feed-items/feedItemId/likes
The topics associated with a specific feeditem. Associate a new or existing topic
/chatter/feed-items/feedItemId/topics
with a specific feed item. Remove a topicfrom a specific feed item.
Feed-Items BatchA batch of feed items. Get information about multiple feed items in one request.
Get information about the comma-separated list of feed items. Errors for feed items that couldn’t be loaded are returned inthe results.
164
Feed Items ResourcesChatter REST API Resources
Resource
/chatter/feed-items/batch/feedItemIds
Available since version29.0
HTTP methodsGET, HEAD
Response body for GETBatch Results
Feed-Items QueryA paginated collection of feed items. Use this resource to search for feed items. The query parameter (q) is required. All typesof feed items are searched, including tracked changes. A search returns feed items with the search term in the feed item body,as well as feed items that have comments that contain the search term. You can also use wildcards with the query parameter.
Resource
/chatter/feed-items?q=searchTerm
Available since version23.0
HTTP methodsGET, HEAD
Request parameters
AvailableSince
RequiredorOptional
DescriptionTypeParameter Name
23.0OptionalA generated token that indicates the view of feed items in the feed.Stringpage
23.0OptionalSpecifies the number of items per page. Valid values are between 1and 100. If you don't specify a size, the default is 25.
IntegerpageSize
23.0RequiredSpecifies the string to search. The search string must contain at leasttwo characters, not including any wildcards. For more informationabout wildcards, see Wildcards.
The query parameter searches all types of feed items, including trackedchanges. The search returns feed items with the search term in the
Stringq
feed item body, as well as feed items that have comments that containthe search term.
29.0OptionalMaximum number of comments to include per feed item. The defaultvalue is 3.
IntegerrecentCommentCount
28.0OptionalThe sort order of the results. Values are:Stringsort
• CreatedDateDesc
165
Feed-Items QueryChatter REST API Resources
AvailableSince
RequiredorOptional
DescriptionTypeParameter Name
• LastModifiedDateDesc
The default value is CreatedDateDesc.
Response bodyFeed Item Page
Feed-Items, Specific Feed ItemAccess, delete, or bookmark a specific feed item.
Resource
/chatter/feed-items/feedItemId
Available since version23.0
HTTP methodsGET, DELETE, PATCH, or HEAD
Request body for PATCHThe root XML tag is <feedItem>.
DescriptionTypeParameter Name
Specify true to add the current feeditem to the list of bookmarked feed
BooleanisBookmarkedByCurrentUser
items for the current user. Specifyfalse to remove this feed item fromthe list of bookmarked feed items forthe current user.
Request parameter for PATCH
DescriptionTypeParameter Name
Specify true to add the current feeditem to the list of bookmarked feed
BooleanisBookmarkedByCurrentUser
items for the current user. Specifyfalse to remove this feed item fromthe list of bookmarked feed items forthe current user.
Response body for GET, PATCH, or HEADFeed Item
166
Feed-Items, Specific Feed ItemChatter REST API Resources
ExampleThis PATCH request bookmarks a feed item:
/chatter/feed-items/0D5D0000000JvckKAC?isBookmarkedByCurrentUser=true
Feed Items CommentsAccess comments for a specific feed item or post a comment.
The default number of comments to retrieve is 3. To retrieve more comments increase the size of the pageSize parameter.
For additional information about posting a comment, see Using POST, PATCH, or PUT for Input.
To upload a binary file to attach to a comment, you must send it in a multipart/form-data request. To send the text of thecomment, you can choose to include a JSON or XML rich input body part in the multipart/form-data request. Alternately,you can choose to pass the information in request parameter parts. For information about how to create the multipart/form-datamessage, see Uploading Binary Files.
Comments can contain up to 5000 characters.
Resource
/chatter/feed-items/feedItemId/comments
Available since version23.0
HTTP methodsGET, POST or HEAD
Request body for POST
Root XML tag<comment>
Properties
AvailableVersion
DescriptionTypeName
24.0Optional. Values are:Depends on type.attachment
• Attachment Input: Existing Content• Attachment Input: New File Upload
Note: To upload a new file,you must include it in amultipart/form–data message.See Uploading Binary Files.
23.0Description of message bodyMessage Body Inputbody
167
Feed Items CommentsChatter REST API Resources
Request parameters for POSTParameters for attaching an existing file
Available VersionRequired or OptionalDescriptionTypeParameter Name
27.0RequiredThe type of attachment. Must containthe value ExistingContent.
StringattachmentType
24.0RequiredID of an existing file to be posted.StringcontentDocumentId
23.0OptionalText of the comment.Stringtext
Parameters for posting text
Available VersionRequired or OptionalDescriptionTypeParameter Name
23.0RequiredThe comment text.Stringtext
Request parameters for GET or HEAD
Available VersionRequired or OptionalDescriptionTypeParameter Name
23.0OptionalA generated token thatindicates the view of
Stringpage
feed items in the feed.Page tokens arereturned as part of theresponse body, in oneof the URLparameters, such asnextPageURL.
23.0OptionalSpecifies the numberof items per page.
IntegerpageSize
Valid values arebetween 1 and 100. Ifyou don't specify asize, the default is 25.
This parameterspecifies the number ofcomments per page.
Response body for GET or HEADComment Page
Response body for POSTComment
Example: Posting a CommentThis POST request uses a request parameter to post a comment to a feed item:
/chatter/feed-items/0D5D0000000JvckKAC/comments?text=I+completely+agree
168
Feed Items CommentsChatter REST API Resources
Example: Posting a Comment and Attaching an Existing FileThis POST request posts a comment and attaches a file that has already been uploaded to the user’s organization:
/chatter/feed-items/0D5D0000000JvckKAC/comments?text=yes&attachmentType=ExistingContent&contentDocumentId=069D00000001FHF
Example: Posting a Comment and Uploading and Attaching a New FileSee Uploading Binary Files on page 9.
Feed-Items LikesUsed to access likes for a specific feed item, or to add a like to a specific feed item.
Resource
/chatter/feed-items/feedItemId/likes
Available since version23.0
HTTP methodsGET, POST or HEAD
Request parameters for GET or HEAD
Note: There aren’t any request parameters for POST.
DescriptionTypeParameter Name
Specifies the number of the page youwant returned.
Integerpage
Specifies the number of items per page.Valid values are between 1 and 100. If
IntegerpageSize
you don't specify a size, the default is25.
Response body for GET or HEADLike Page
Response body for POSTLike
Example response body with GET
{"currentPageUrl": "/services/data/v30.0/chatter/feed-items/0D5D0000000IPZuKAO/likes",
"likes": [{"id": "0I0D000000003KeKAI","likedItem": {
"id": "0D5D0000000IPZuKAO",
169
Feed-Items LikesChatter REST API Resources
"url": "/services/data/v30.0/chatter/feed-items/0D5D0000000IPZuKAO"},"url": "/services/data/v30.0/chatter/likes/0I0D000000003KeKAI","user": {
"companyName": "Universal Containers","firstName": "Deanna","id": "005D0000001LL8OIAW","isActive": true,"lastName": "Li","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Deanna Li","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5saBc65JKjmm4DaxyLRr1XQK",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/F","photoVersionId": "729D00000000LJFIA2","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/T","standardEmailPhotoUrl":
"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZNDZe0BfzuOg1WyB6Vo-DB",
"url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW","userType": "Internal"
}}],"nextPageUrl": null,"previousPageUrl": null,"total": 1
}
Feed-Items PollsUsed to access or vote in an existing poll.
Resource
/chatter/feed-items/feedItemId/poll
The feedItemId must have the type PollPost.
Available since version26.0
HTTP methodsGET, PATCH or HEAD
Use PATCH to either vote in an existing poll, or change the current user’s vote.
170
Feed-Items PollsChatter REST API Resources
Request body for PATCH
Root XML tag<feedPoll>
Properties
Available VersionDescriptionTypeName
26.0ID of an existing choice onthe feed poll. Used to
StringmyChoiceId
specify the ID of the pollchoice that the current useris voting on.
Request parameters for PATCH
Available VersionDescriptionTypeName
26.0ID of an existing choice onthe feed poll. Used to specify
StringmyChoiceId
the ID of the poll choice thatthe current user is voting on.
Response bodyFeed Item Attachment: Poll
Feed-Items TopicsThe topics associated with a specific feed item. Associate a new or existing topic with a specific feed item. Remove a topicfrom a specific feed item. Only users with the “Assign Topics” permission can add or remove existing topics from feed items.Only users with the “Create Topics” permission can add new topics to feed items.
Resource
/chatter/feed-items/feedItemId/topics
Available since version28.0
HTTP methodsDELETE, POST
Request parameter for DELETE
Available VersionRequired or OptionalDescriptionTypeParameter Name
28.0RequiredID of an existing topicStringtopicId
171
Feed-Items TopicsChatter REST API Resources
Request body for POST
Root XML tag<feedItemTopic>
JSONThe following example attaches a new topic to a feed item:
{ "topicName": "W3C"}
Properties
AvailableVersion
Required or OptionalDescriptionTypeName
29.0Required for existing topicsif the topicName propertyisn’t used
ID of an existing topicStringtopicId
29.0Required for new topics;required for existing topics if
Name of a new or existingtopic, up to 150 characters
StringtopicName
the topicId property isn’tused
Request parameters for POST
Available VersionRequired or OptionalDescriptionTypeParameter Name
28.0Required for existingtopics if the
ID of an existing topicStringtopicId
topicName parameterisn’t used
28.0Required for newtopics; required for
Name of a new orexisting topic, up to150 characters
StringtopicName
existing topics if thetopicId parameterisn’t used
Response body for DELETE204: Successful Delete
Response body for POSTTopic
Example for POSTThis example passes the ID of an existing topic in the topidId parameter to associate it with a feed item:
/chatter/feed-items/0D5D0000000JmiB/topics?topicId=0TOD0000000090r
172
Feed-Items TopicsChatter REST API Resources
This is the JSON response:
{"createdDate": "2013-02-25T18:24:31.000Z","id": "0TOD0000000090rOAA","description": "Test topic description.","talkingAbout": 9,"name": "Test","url": "/services/data/v30.0/connect/topics/0TOD0000000090rOAA"
}
Files ResourcesInformation about the specified file, including content, rendered version, and sharing.
Available resources are:
DescriptionResource
Returns details about the specified file. Can also be used torename a file, upload a new version of an existing file, movea file to a different folder, and delete a file.
/chatter/files/fileId
Returns the content of the file. The content is streamed as thebody of the response.
/chatter/files/fileId/content
Returns information about the objects with which the specifiedfile has been shared. Objects can be users, groups, or records.Can also be used to share the specified file with users.
/chatter/files/fileId/file-shares
A description of a file shared as a link. Create, access, anddelete a file’s share link.
/chatter/files/fileId/file-shares/link
A rendition of the file. A rendition is a binary preview of thefile. The format of the binary depends on the format specifiedin the request.
/chatter/files/fileId/rendition
Information about a list of files, specified by file IDs. Getinformation about a list of files and delete a list of files.
/chatter/files/batch/fileIds
File InformationReturns details about the specified file. Can also be used to rename a file, upload a new version of an existing file, move a fileto a different folder, and delete a file.
To upload a new version of an existing file, make a POST request. You must upload the new version as a binary part in amultipart/form-data request. See Uploading Binary Files on page 9. To upload a new file to the Files tab, use/chatter/users/me/files on page 248.
Resource
/chatter/files/fileId
Available since version24.0
173
Files ResourcesChatter REST API Resources
HTTP methodsGET, POST, PATCH, DELETE, or HEAD
Note: POST, PATCH, and DELETE available since version 26.0.
Request body for POST
Root XML tag<fileInput>
JSON
{"desc" : "Employee Survey Results","title" : "emp_surv_results"
}
Properties
Available VersionDescriptionTypeName
24.0Description of the file to beuploaded.
Stringdesc
30.0 (pilot only)true if the file is includedin the user’s Salesforce Files
BooleanisInMyFileSync
folder, and is syncedbetween that folder andChatter; false otherwise.
30.0 (pilot only)ID of the containing folder.StringparentFolderId
24.0Title of the file.Stringtitle
Request parameters for POST
AvailableVersion
DescriptionTypeName
26.0Description of the file to be uploaded.Stringdesc
30.0 (pilot only)The request is automatically generated by an automatedclient.
BooleanisDataSync
30.0 (pilot only)true if the file is included in the user’s Salesforce Filesfolder, and is synced between that folder and Chatter; falseotherwise.
BooleanisInMyFileSync
26.0Title of the file.Stringtitle
Request parameters for GET and HEAD
Get information about the specified file.
174
Files ResourcesChatter REST API Resources
AvailableVersion
DescriptionTypeName
23.0Specify an existing version number for the file. If notspecified, the latest version is returned.
IntegerversionNumber
Request parameters for PATCH
Update the title or sync state of a file or move a file to a different folder.
AvailableVersion
DescriptionTypeName
26.0A new title for the fileStringtitle
30.0 (pilot only)true if the file is included in the user’s Salesforce Filesfolder, and is synced between that folder and Chatter;false otherwise.
BooleanisInMyFileSync
30.0 (pilot only)ID of the containing folderStringparentFolderId
Response body for GET, POST, PATCH, and HEADFile Detail
Response body for DELETEReturns a status code of 204.
ExampleThis PATCH request updates the title of a file:
/chatter/files/069D00000001FHF?title=A+New+Title
File ContentReturns the content of the file. The content is streamed as the body of the response.
Resource
/chatter/files/fileId/content
Available since version24.0
HTTP methodsGET
175
Files ResourcesChatter REST API Resources
Request parameters
AvailableVersion
DescriptionTypeName
23.0Specify an existing version number for the file. If notspecified, the latest version is returned.
IntegerversionNumber
Response bodyBinary stream of the file content.
File SharesReturns information about the objects with which the specified file has been shared. Objects can be users, groups, or records.Can also be used to share the specified file with users.
Resource
/chatter/files/fileId/file-shares
Available since version24.0
HTTP methodsGET, HEAD, POST
POST is available in versions 30.0 and later.
Request parameters for GETIn versions 30.0 and later, the first share returned in a GET request is the organization record share. In communities,the first share returned is the network record share.
Available SinceRequired or OptionalDescriptionTypeName
24.0OptionalAn integer greater than 0specifying a page of topics. Thedefault value is zero.
Integerpage
24.0OptionalSpecifies the number of items perpage. Valid values are between 1and 100. The default value is 25.
IntegerpageSize
Request body for POST
Root XML tag<fileShares>
JSON example
{"message": "I shared a document with you.","shares": [
{ "id": "005D0000001Az4l", "sharingType": "V" },
176
Files ResourcesChatter REST API Resources
{ "id": "005D0000001B2ny", "sharingType": "C" }]
}
Properties
AvailableVersion
DescriptionTypeName
30.0Private message body that’s sent to the recipients.If Salesforce Communities is enabled, an emailis sent instead of a private message.
Stringmessage
30.0Collection of Share Input request bodiesShare Input[]shares
Request parameters for POSTParameters for sharing a file with users
Available SinceRequired or OptionalDescriptionTypeName
30.0RequiredList of up to 9 user IDs to sharethis file with. This list must matchthe list of sharing types.
Stringid(1–9)
30.0OptionalPrivate message body that’s sent tothe recipients. If Salesforce
Stringmessage
Communities is enabled, an emailis sent instead of a private message.
30.0RequiredList of sharing types, either C forcollaborator or V for viewer. Thislist must match the list of user IDs.
StringsharingType(1–9)
Response body for GET and POSTFile Shares Page
Example for POSTThis example uses request parameters to share a file with two users.
POST /chatter/files/069D00000001JDU/file-shares?id1=005D0000001LL8O&id2=005D0000001QdEL&sharingType1=C&sharingType2=V
This example uses a request body to share the same file with the same users.
POST /chatter/files/069D00000001JDU/file-shares
{"shares": [
{ "id": "005D0000001LL8O", "sharingType": "C" },{ "id": "005D0000001QdEL", "sharingType": "V" }
]}
177
Files ResourcesChatter REST API Resources
Files Shares LinkA description of a file shared as a link. Create, access, and delete a file’s share link.
Resource
/chatter/files/fileId/file-shares/link
Available since version30.0
HTTP methodsGET, HEAD, PUT, DELETE
Response body for GET or PUTFile Share Link
Response body for DELETEReturns a status code of 204.
File RenditionA rendition of the file. A rendition is a binary preview of the file. The format of the binary depends on the format specifiedin the request.
Note: Renditions are processed asynchronously and might not be available immediately after the file has beenuploaded.
Resource
/chatter/files/fileId/rendition
Available since version24.0
HTTP methodsGET
Request parameters
DescriptionTypeName
Specify a rendition of a specific page.The first page is 0. If you don’t specify
Integerpage
a specific page, a rendition of the firstpage is returned.
For a PDF file rendition, the renditionis for the entire document. The onlyvalid value is 0: you can’t get therendition of a single page.
178
Files ResourcesChatter REST API Resources
DescriptionTypeName
Specify the type of rendition to bereturned. Default value isTHUMB120BY90. Valid values are:
Stringtype
• FLASH
• THUMB120BY90
• THUMB240BY180
• THUMB720BY480
Response bodyBinary stream of the rendition.
File Information, BatchInformation about a list of files, specified by file IDs. Get information about a list of files and delete a list of files. The numberof file IDs you can specify is limited by the length of the URL. In general, you can specify up to 100 file IDs in acomma-separated list.
Resource
/chatter/files/batch/fileIds
Available since version26.0
HTTP methodsGET, DELETE
Response bodyBatch Result Item
Folders ResourcesInformation about a folder or the contents of a folder. Modify and delete folders and add items to folders. Folders resourcesare available through a pilot program in version 30.0.
Available resources:
DescriptionResource
Get information about the specified folder. You can also move,rename, and delete a folder. Folders resources are availablethrough a pilot program in version 30.0.
/chatter/folders/folderId
Get information about the contents of a folder. You can alsoadd a file to a folder and create a folder. Folders resources areavailable through a pilot program in version 30.0.
/chatter/folders/folderId/items
179
Folders ResourcesChatter REST API Resources
Folder InformationGet information about the specified folder. You can also move, rename, and delete a folder. Folders resources are availablethrough a pilot program in version 30.0. When you delete a folder, you delete all the folders within that folder and remove allfiles from the deleted folders so they are no longer synced.
Resource
/chatter/folders/folderId
Available since version30.0
HTTP methodsGET, HEAD, PATCH, DELETE
Request body for PATCHFolder Input
Request parameters for PATCHMove a folder
AvailableVersion
Required or OptionalDescriptionTypeParameter
30.0RequiredThe ID of the new parent folder. If null, thefolder will be removed from its current folder. If
StringparentFolderId
the specified ID is root, the folder is moved tothe root of the user’s folder hierarchy.
Rename a folder
AvailableVersion
Required or OptionalDescriptionTypeParameter
30.0RequiredThe new name for the folderStringname
Response body for GET and PATCHFolder
Folder ContentsGet information about the contents of a folder. You can also add a file to a folder and create a folder. Folders resources areavailable through a pilot program in version 30.0.
To create a folder, you can use a request body or request parameters in a POST request.
To create a file, you must send it as a body part in a multipart/form-data POST request. You can send the description andtitle information in a JSON or XML rich input body in a part of the multipart/form-data request. Alternately, you can sendthe description, title, and type in request parameters. See Uploading Binary Files on page 9. To add a file to the Files tab,use /chatter/users/me/files.
180
Folders ResourcesChatter REST API Resources
Resource
/chatter/folders/folderId/items
Available since version30.0
HTTP methodsGET, HEAD, POST
Request parameters for GET
AvailableVersion
Required or OptionalDescriptionTypeParameter
30.0OptionalAn integer specifying a page of items. The defaultvalue is 0, which returns the first page.
Integerpage
30.0OptionalSpecifies the number of items per page. Validvalues are between 1 and 100. If you don't specifya size, the default is 25.
IntegerpageSize
Response body for GETFolder Item Page
Request body for POST
Folder Item Input
Request parameters for POSTAdd a file to a folder
AvailableVersion
Required or OptionalDescriptionTypeParameter
30.0OptionalThe description of the fileStringdesc
30.0OptionalThe title of the fileStringtitle
30.0RequiredThe item type. To add a file to a folder, the valuemust be File.
Stringtype
Create a folder
AvailableVersion
Required or OptionalDescriptionTypeParameter
30.0RequiredThe path to the folderStringfolderPath
30.0RequiredThe item type. To create a folder, the value mustbe Folder.
Stringtype
181
Folders ResourcesChatter REST API Resources
Response body for POSTFolder Item
Example for adding a file to a folder
{"file" :
{"description" : "Yearly Report for Universal Containers Box Division","title" : "Yearly.txt"
},"type" : "File"
}
Example for creating a folder
{"folder" :
{"path" : "my_documents/my_folder"
},"type" : "Folder"
}
Groups ResourcesInformation about groups, such as the group's members, photo, and the groups in the organization. Create and delete a group,add members to a group, and change the group photo.
Note: The groups resource is not a feed. To view the feed for a group, or post to it, use the record feed resource witha groupId.
Available resources:
DescriptionResource
Update the status of a request by a user to join a private groupor get information about a request to join a private group.
/chatter/group-membership-requests/requestId
Access information about a member of a group, remove amember from a group, and update a group member’s role.
/chatter/group-memberships/membershipId
Access information about a list of group members./chatter/group-memberships/batch/membershipIds
A list of all the groups in the organization. Get informationabout groups or create a group.
/chatter/groups/
Returns information about more than one group at the sametime.
/chatter/groups/batch/group_list
Information about a group./chatter/groups/groupId
Returns information about the files posted to the specifiedgroup.
/chatter/groups/groupID/files
Members of a specified group. Get the members and add amember to a group.
/chatter/groups/groupId/members
182
Groups ResourcesChatter REST API Resources
DescriptionResource
Request membership in a private group or get the status ofrequests to a join a private group.
/chatter/groups/groupId/members/requests
Information about the context user’s Chatter settings for thespecified group.
/chatter/groups/groupId/my-settings
The photo for the specified group. Get, post, crop, and deletethe photo.
/chatter/groups/groupId/photo
Returns up to five topics most recently used in the specifiedgroup.
/chatter/groups/groupId/topics
See Also:Groups Feed Resources
List of GroupsA list of all the groups in the organization. Get information about groups or create a group.
Resource
/chatter/groups/
Available version23.0
POST available in 29.0
HTTP methodsGET, HEAD, POST
Request parameters for GET
AvailableDescriptionTypeParameter Name
29.0Returns the list of groups filtered by thearchive status you specify:
StringarchiveStatus
• All—All groups, including groupsthat are archived and groups that arenot archived.
• Archived—Only groups that arearchived.
• NotArchived—Only groups thatare not archived.
The default value is NotArchived.
23.0An integer specifying a page of items.The default value is 0, which returns thefirst page.
Integerpage
183
List of GroupsChatter REST API Resources
AvailableDescriptionTypeParameter Name
23.0Specifies the number of items per page.Valid values are between 1 and 250. Thedefault value is 25.
IntegerpageSize
23.0Specifies the string to search. The searchstring must contain at least two
Stringq
characters, not including any wildcards.For more information about wildcards,see Wildcards.
Request body for POST
AvailableVersion
DescriptionTypeName
29.0true if this group allows Chattercustomers, false otherwise. After this
BooleancanHaveChatterGuests
property is set to true, it cannot be setto false.
29.0The “Description” section of the groupStringdescription
28.0The “Information” section of the groupIf the group is private, the “Information”
Group Information Inputinformation
section is visible only to members. The“Description” section is visible toeveryone.
29.0true if the group is archived, falseotherwise. Defaults to false.
BooleanisArchived
29.0true if automatic archiving is turnedoff for the group, false otherwise.Defaults to false.
BooleanisAutoArchiveDisabled
29.0The name of the groupStringname
29.0The ID of the group owner. Thisproperty is available for PATCHrequests only.
Stringowner
29.0The visibility of the group. One of thefollowing values:
Stringvisibility
• PublicAccess
• PrivateAccess
184
List of GroupsChatter REST API Resources
Request parameters for POST
AvailableRequired orOptional
DescriptionTypeParameter Name
29.0Optionaltrue if this group allows Chatter customers, falseotherwise. After this property is set to true, itcannot be set to false.
BooleancanHaveChatterGuests
29.0OptionalThe “Description” section of the groupStringdescription
29.0OptionalThe text in the “Information” section of the groupStringinformationText
29.0OptionalThe title of the “Information” section of the groupStringinformationTitle
29.0Optionaltrue if the group is archived, false otherwise.Defaults to false.
BooleanisArchived
29.0Optionaltrue if automatic archiving is turned off for thegroup, false otherwise. Defaults to false.
BooleanisAutoArchiveDisabled
29.0RequiredThe name of the groupStringname
29.0RequiredThe visibility of the group. One of the following:Stringvisibility
• PublicAccess
• PrivateAccess
Response body for GETGroup Page
Response body for POSTGroup Detail
Example for POSTThis request creates a public group:
POST /chatter/groups?name=New+Group&visibility=PublicAccess
Example response body for POST
{"canHaveChatterGuests": false,"community": null,"description": null,"emailToChatterAddress":
0F9D00000000HRRKA3@post.t-dpvcmac.instance_name.chatter.salesforce.com,"fileCount": 0,"id": "0F9D00000000mb9KAA","information": {
"text": null,"title": null
},"isArchived": false,"isAutoArchiveDisabled": false,"lastFeedItemPostDate": "2013-05-17T05:51:52.000Z","memberCount": 1,"motif": {
"color": "1797C0","largeIconUrl": "/img/icon/groups64.png",
185
List of GroupsChatter REST API Resources
"mediumIconUrl": "/img/icon/groups32.png","smallIconUrl": "/img/icon/groups16.png"
},"myRole": "GroupOwner","mySubscription": {
"id": "0FBD00000003KaVOAU","url": "/services/data/v30.0/chatter/group-memberships/0FBD00000003KaVOAU"
},"name": "New Group2","owner": {
"companyName": "Universal Containers","firstName": "Deanna","id": "005D0000001LL8OIAW","isActive": true,"isInThisCommunity": true,"lastName": "Li","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Deanna Li","photo": {
"fullEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sanJJq16bcKA-9fqZj1svK3",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/F","photoVersionId": "729D00000000LJFIA2","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/T","standardEmailPhotoUrl": "https://instance_name/ncsphoto/
SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sYVo6fntPnCQ_-xIH-GU3vI","url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo"
},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW","userType": "Internal"
},"pendingRequests": null,"photo": {
"fullEmailPhotoUrl": "https://instance_name/img/userprofile/default_group_profile_200.png?fromEmail=1",
"largePhotoUrl": "https://instance_name/profilephoto/0F9/F","photoVersionId": null,"smallPhotoUrl": "https://instance_name/profilephoto/0F9/T","standardEmailPhotoUrl": "https://instance_name/img/userprofile/
default_group_profile_45.png?fromEmail=1","url": "/services/data/v30.0/chatter/groups/0F9D00000000mb9KAA/photo"
},"type": "CollaborationGroup","url": "/services/data/v30.0/chatter/groups/0F9D00000000mb9KAA","visibility": "PublicAccess"
}
Example response for GET
"currentPageUrl": "/services/data/v30.0/chatter/groups","groups": [
{"canHaveChatterGuests": false,"community": null"description": "Get company announcements and other important updates","emailToChatterAddress":
0F9D00000000HRRKA3@post.t-dpvcmac.instance_name.chatter.salesforce.com,"fileCount": 0,"id": "0F9D00000000FG0KAM",
186
List of GroupsChatter REST API Resources
"information": {"text": null,"title": null
},"isArchived": false,"isAutoArchiveDisabled": false,"lastFeedItemPostDate": "2011-09-21T19:58:58.000Z","memberCount": 2,"motif": {
"color": "1797C0","largeIconUrl": "/img/icon/groups64.png","mediumIconUrl": "/img/icon/groups32.png","smallIconUrl": "/img/icon/groups16.png"
},"myRole": "GroupOwner","mySubscription": {
"id": "0FBD00000002oJVOAY","url": "/services/data/v30.0/chatter/group-memberships/0FBD00000002oJVOAY"
},"name": "All Seattle Apps","owner": {
"companyName": "Seattle Apps","firstName": "Marion","id": "005D0000001Kl6xIAC","isActive": true,"isInThisCommunity": true,"lastName": "Raven","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Marion Raven","photo": {
"fullEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZVyX4qlsJTXfOWM77RW7yt",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/F",
"photoVersionId": "729D00000000BDV","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/T"
"standardEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbktFTIf9vWhFTTALJiaFz_",
"url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001Kl6xIAC","userType: "Internal"
},"pendingRequests": 0,"photo": {
"fullEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZVyX4qlsJTXfOWM77RW7yt",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000BDQ/F","photoVersionId": "729D00000000BDQ","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000BDQ/T","standardEmailPhotoUrl": "https://instance_name/ncsphoto/
SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbktFTIf9vWhFTTALJiaFz_","url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo"
},"type": "CollaborationGroup","url": "/services/data/v30.0/chatter/groups/0F9D00000000FG0KAM","visibility": "PublicAccess"
}],"nextPageUrl": null,
187
List of GroupsChatter REST API Resources
"previousPageUrl": null}
Group InformationInformation about a group.
Resource
/chatter/groups/groupId
Available version23.0
PATCH is available in 28.0
HTTP methodsGET, DELETE, HEAD, PATCH
DELETE is supported in 29.0
PATCH is supported in 28.0
Request body for PATCHGroup Input
Root XML Tag
<group>
JSON
{"canHaveChatterGuests" : "true","description" : "This group is building a powerful API.","information" : {
"text" : "Read this section before you post to the group.","title" : "Information"
},"isArchived" : "false","isAutoArchiveDisabled" : "false","name" : "Chatter API","owner" : "00590000000DmPw","visibility" : "PublicAccess"
}
Properties
AvailableVersion
DescriptionTypeName
29.0true if this group allows Chattercustomers, false otherwise. After
BooleancanHaveChatterGuests
this property is set to true, it cannotbe set to false.
188
Group InformationChatter REST API Resources
AvailableVersion
DescriptionTypeName
29.0The “Description” section of the groupStringdescription
28.0The “Information” section of thegroup If the group is private, the
Group Information Inputinformation
“Information” section is visible only tomembers. The “Description” sectionis visible to everyone.
29.0true if the group is archived, falseotherwise. Defaults to false.
BooleanisArchived
29.0true if automatic archiving is turnedoff for the group, false otherwise.Defaults to false.
BooleanisAutoArchiveDisabled
29.0The name of the groupStringname
29.0The ID of the group owner. Thisproperty is available for PATCHrequests only.
Stringowner
29.0The visibility of the group. One of thefollowing values:
Stringvisibility
• PublicAccess
• PrivateAccess
Group Information Input
JSON
{"text" : "Post questions about the API.","title" : "API Questions"
}
Properties
AvailableVersion
DescriptionTypeName
28.0The text in the “Information” sectionof the group. HTML is not supported.
Stringtext
The maximum length is 4000characters (bytes).
28.0The title in the “Information” sectionof the group. The maximum length is240 characters (bytes).
Stringtitle
189
Group InformationChatter REST API Resources
Request parameters for PATCH
AvailableVersion
Required orOptional
DescriptionTypeProperty
29.0Optionaltrue if this group allows Chatter customers, falseotherwise. After this property is set to true, it cannot beset to false.
BooleancanHaveChatterGuests
29.0OptionalThe “Description” section of the groupStringdescription
28.0OptionalThe “Information” section of the group. If the group isprivate, the “Information” section is visible only tomembers. The “Description” section is visible to everyone.
StringinformationText
28.0OptionalThe title of the “Information” section of the groupStringinformationTitle
29.0Optionaltrue if the group is archived, false otherwise. Defaultsto false.
StringisArchived
29.0Optionaltrue if automatic archiving is turned off for the group,false otherwise. Defaults to false.
BooleanisAutoArchiveDisabled
29.0OptionalThe name of the groupStringname
29.0OptionalThe ID of the group owner. This property is available forPATCH requests only.
Stringowner
29.0OptionalThe visibility of the group. One of the following values:Stringvisibility
• PublicAccess
• PrivateAccess
Response body for GET and PATCHGroup Detail
Example for PATCHThis request body updates the text and title of the “Information” section of a group:
{"information" : {
"text" : "Post questions about the API to this group. If you have the answer toa question, please post it. This is a private R&D group.",
"title" : "API Questions Group"}
}
Here is the same example using request parameters:
https://instance_name/services/data/30.0/chatter/groups/groupId?informationText=Post+questions+about+the+API+to+this+group.+If+you+have+the+answer+to+a+question%2C%20+please+post+it.+This+is+a+private+R%26amp%3Bamp%3BD+group.&informationTitle=API+Questions+Group
The response is a Group Detail response body:
{"canHaveChatterGuests": false,"community": null,"description": "A group for people building Force.com apps.",
190
Group InformationChatter REST API Resources
"emailToChatterAddress":0F9D00000000HRRKA3@post.t-dpvcmac.instance_name.chatter.salesforce.com,
"fileCount": 1,"id": "0F9D00000000I4OKAU","information": {
"text": "Post questions about the API to this group. If you have the answer to aquestion, please post it.",
"title": "API Questions Group"},"isArchived": "false","isAutoArchiveDisabled": "false","lastFeedItemPostDate": "2013-04-02T23:18:08.000Z","memberCount": 2,"motif": {
"color": "1797C0","largeIconUrl": "/img/icon/groups64.png","mediumIconUrl": "/img/icon/groups32.png","smallIconUrl": "/img/icon/groups16.png"
},"myRole": "GroupOwner","mySubscription": {
"id": "0FBD00000002vOVOAY","url": "/services/data/v30.0/chatter/group-memberships/0FBD00000002vOVOAY"
},"name": "App Builders","owner": {
"companyName": "Universal Containers","firstName": "Deanna","id": "005D0000001LL8OIAW","isActive": true,"isInThisCommunity": true,"lastName": "Li","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Deanna Li","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sa4idjK69Im5uTYfmFricjT",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/F","photoVersionId": "729D00000000LJFIA2","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/T","standardEmailPhotoUrl":
"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbMgjs7ldMuVclujIS-dbL9",
"url": "/services/data/v28.0/chatter/users/005D0000001LL8OIAW/photo"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW","userType": "Internal"
},"pendingRequests": null,"photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/0_6z_M1zlQXy0iICaZWfdyMkZkpEttUCohuRK3CoTiDvqyRW3xtIe1cq90Bj3lH7",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJK/F","photoVersionId": "729D00000000LJKIA2","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000LJK/T","standardEmailPhotoUrl":
"https://instance_name/ncsphoto/0_6z_M1zlQXy0iICaZWfdyMkZkpEttUCohuRK3CoTiDd9pTChyCnpBYx0vfH0Pi9",
"url": "/services/data/v30.0/chatter/groups/0F9D00000000I4OKAU/photo"
191
Group InformationChatter REST API Resources
},"type": "CollaborationGroup","url": "/services/data/v30.0/chatter/groups/0F9D00000000I4OKAU","visibility": "PublicAccess"
}
Batch Group InformationReturns information about more than one group at the same time.
Resource
/chatter/groups/batch/group_list
Where group_list is a comma separated list of group IDs.
Available since version23.0
HTTP methodsGET or HEAD
Response bodyBatch Results
Group FilesReturns information about the files posted to the specified group.
Resource
/chatter/groups/groupID/files
Available since version24.0
HTTP methodsGET or HEAD
Request parameters
Available SinceDescriptionTypeParameter Name
24.0An integer specifying a pageof items. The default value
Integerpage
is 0, which returns the firstpage.
24.0Specifies the number ofitems per page. Valid values
IntegerpageSize
are between 1 and 100. Ifyou don't specify a size, thedefault is 25.
192
Batch Group InformationChatter REST API Resources
Available SinceDescriptionTypeParameter Name
27.0A query string to filter theresults. The string must
Stringq
contain at least twocharacters, not includingwildcards. For informationabout wildcards, seeWildcards.
Response bodyFile Summary Page
Group MembersMembers of a specified group. Get the members and add a member to a group.
Resource
/chatter/groups/groupId/members
Available since version23.0
HTTP methodsGET, POST or HEAD
Request body for POST
Root XML tag<member>
Properties
Available VersionDescriptionTypeName
29.0The role of the member.One of these values:
Stringrole
• GroupManager
• StandardMember
23.0The user ID of the memberto be added to the group.
StringuserId
193
Group MembersChatter REST API Resources
Request parameter for POST
Available VersionDescriptionTypeParameter Name
29.0The role of the member. One of thesevalues:
Stringrole
• GroupManager
• StandardMember
23.0ID of the user to add to the group.StringuserId
Request parameters for GET or HEAD
Available VersionDescriptionTypeParameter Name
23.0An integer specifying a pageof items. The default value
Integerpage
is 0, which returns the firstpage.
23.0Specifies the number ofitems per page. Valid values
IntegerpageSize
are between 1 and 1000. Ifyou don’t specify a size, thedefault is 25.
Response body for GET or HEADGroup Member Page
Response body for POSTGroup Member
Example: Add a member to a groupThis POST request adds a member to a group:
/chatter/groups/0F9D00000000I4O/members?userId=005D0000001LLO1
The response is a Group Member response body:
{"id": "0FBD00000003LRxOAM","role": "StandardMember","url": "/services/data/v30.0/chatter/group-memberships/0FBD00000003LRxOAM","user": {
"companyName": "Universal Containers","firstName": "Gordon","id": "005D0000001LLO1IAO","isActive": true,"isInThisCommunity": true,"lastName": "Johnson","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},
194
Group MembersChatter REST API Resources
"mySubscription": {"id": "0E8D0000000T5ZUKA0","url": "/services/data/v30.0/chatter/subscriptions/0E8D0000000T5ZUKA0"
},"name": "Gordon Johnson","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cPhKrC7plNhUw5eOz7Aj1u-oFL0K-ff2oe04ZAmT2MqC",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJL/F","photoVersionId": "729D00000000LJLIA2","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000LJL/T","standardEmailPhotoUrl":
"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cPhKrC7plNhUw5eOz7Aj1u-6d5rE2mNaMaBZfGnFX65O",
"url": "/services/data/v30.0/chatter/users/005D0000001LLO1IAO/photo"},"title": "VP Sales","type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LLO1IAO","userType": "Internal"
}}
Note:
If the group is private, the response is 403. To request to join the group, send a POST request to the GroupMembers—Private resource (/chatter/groups/groupId/members/requests).
Group Members—PrivateRequest membership in a private group or get the status of requests to a join a private group.
Note: To request membership in a public group use the Group Members resource.
Resource
/chatter/groups/groupId/members/requests
Available since version27.0
HTTP methodsGET, HEAD, and POST
Request parameter for GET
Available SinceDescriptionTypeParameter Name
27.0Optional. If you include thisparameter, results are filtered
Stringstatus
to include those that matchthe specified status. Validvalues:• Accepted
195
Group Members—PrivateChatter REST API Resources
Available SinceDescriptionTypeParameter Name
• Declined
• Pending
Response body for GET or HEADGroup Membership Request Collection
Response body for POSTGroup Membership Request
This table lists HTTP response code descriptions that are unique to this resource. For descriptions of other HTTPresponse codes, see Status Codes and Error Responses.
DescriptionHTTP Response Code
One of the following:201• Success• User already has a membership request for this group
User is already a member of this group.204
One of the following:403• Group is private: INSUFFICIENT_ACCESS_OR_READONLY• User is an external user: INSUFFICIENT_ACCESS
Example for GETThis example gets information about all the requests to join that have been accepted for this private group:
/chatter/groups/0F9D00000000izfKAA/members/requests?status=Accepted
The JSON Group Membership Request Collection response body includes one request from the user Gordon Johnson:
{"requests": [{
"createdDate": "2012-10-19T00:23:23.000Z","id": "0I5D000000002fmKAA","lastUpdateDate": "2012-10-19T00:24:06.000Z","requestedGroup": {
"id": "0F9D00000000izfKAA","url": "/services/data/v30.0/chatter/groups/0F9D00000000izfKAA"
},"responseMessage": null,"status": "Accepted","url": "/services/data/v30.0/chatter/group-membership-requests/0I5D000000002fmKAA",
"user": {"companyName": "Universal Containers","firstName": "Gordon","id": "005D0000001LLO1IAO","isActive": true,"lastName": "Johnson","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png",
196
Group Members—PrivateChatter REST API Resources
"smallIconUrl": "/img/icon/profile16.png"},"mySubscription": {
"id": "0E8D0000000T5ZUKA0","url": "/services/data/v30.0/chatter/subscriptions/0E8D0000000T5ZUKA0"
},"name": "Gordon Johnson","photo": {"fullEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cPhK
rC7plNhUw5eOz7Aj1u-zWLMxsSybO7lwUPg5_Xne","largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJL/F","photoVersionId": "729D00000000LJLIA2","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000LJL/T",
"standardEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cPhKrC7plNhUw5eOz7Aj1u_2Vnyzx4jZ2zFiKBz_sTt2",
"url": "/services/data/v30.0/chatter/users/005D0000001LLO1IAO/photo"},"title": "VP Sales","type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LLO1IAO","userType": "Internal"
}}],"total": 1
}
Example for POSTThis example requests membership in a private group with the ID 0F9D00000000lpK:
/chatter/groups/0F9D00000000lpK/members/requests
The Group Membership Request response body is in JSON format:
{"createdDate": "2013-04-02T23:44:25.000Z","id": "0I5D000000002kOKAQ","lastUpdateDate": "2013-04-02T23:44:25.000Z","requestedGroup": {
"id": "0F9D00000000lpKKAQ","url": "/services/data/v30.0/chatter/groups/0F9D00000000lpKKAQ"
},"responseMessage": null,"status": "Pending","url": "/services/data/v30.0/chatter/group-membership-requests/0I5D000000002kOKAQ",
"user": {"companyName": "Universal Containers","firstName": "Gordon","id": "005D0000001LLO1IAO","isActive": true,"isInThisCommunity": true,"lastName": "Johnson","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Gordon Johnson","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cPhKrC7plNhUw5eOz7Aj1u-oFL0K-ff2oe04ZAmT2MqC",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJL/F",
197
Group Members—PrivateChatter REST API Resources
"photoVersionId": "729D00000000LJLIA2","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000LJL/T","standardEmailPhotoUrl":
"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cPhKrC7plNhUw5eOz7Aj1u-6d5rE2mNaMaBZfGnFX65O",
"url": "/services/data/v30.0/chatter/users/005D0000001LLO1IAO/photo"},"title": "VP Sales","type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LLO1IAO","userType": "Internal"
}}
Group Membership Requests—PrivateUpdate the status of a request by a user to join a private group or get information about a request to join a private group. Getthe value of requestId from the Group Membership Request response from a POST request to/chatter/groups/groupId/members/requests.
Resource
/chatter/group-membership-requests/requestId
Available since version27.0
HTTP methodsGET, HEAD, and PATCH
Request body for PATCHGroup Membership Request Update
Request parameters for PATCH
Available SinceDescriptionTypeParameter Name
27.0Use this property to provide a message to theuser if their membership request is declined.
StringresponseMessage
The value of this property is used only whenthe value of the status property isDeclined.
The maximum length is 756 characters.
27.0Valid values:Stringstatus
• Accepted
• Declined
Response body for PATCHGroup Membership Request
198
Group Membership Requests—PrivateChatter REST API Resources
Response body for GET or HEADGroup Membership Request
Example for PATCHThis example updates a request to join a private group from Pending to Accepted:
/chatter/group-membership-requests/0I5D000000002fwKAA?status=Accepted
This is the JSON Group Membership Request response body:
{"createdDate": "2012-10-24T16:36:36.000Z","id": "0I5D000000002fwKAA","lastUpdateDate": "2012-10-24T16:43:57.000Z","requestedGroup": {
"id": "0F9D00000000j46KAA","url": "/services/data/v30.0/chatter/groups/0F9D00000000j46KAA"
},"responseMessage": null,"status": "Accepted","url": "/services/data/v30.0/chatter/group-membership-requests/0I5D000000002fwKAA",
"user": {"companyName": "Universal Containers","firstName": "Deanna","id": "005D0000001LL8OIAW","isActive": true,"lastName": "Li","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Deanna Li","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5saBc65JKjmm4DaxyLRr1XQK",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/F","photoVersionId": "729D00000000LJFIA2","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/T","standardEmailPhotoUrl":
"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZNDZe0BfzuOg1WyB6Vo-DB"
},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW","userType": "Internal"
}}
Group Memberships ResourcesInformation about memberships in Chatter groups.
Available resources are:
199
Group Memberships ResourcesChatter REST API Resources
DescriptionResource
Access information about a member of a group, remove amember from a group, and update a group member’s role.
/chatter/group-memberships/membershipId
Access information about a list of group members./chatter/group-memberships/batch/membershipIds
Group Memberships InformationAccess information about a member of a group, remove a member from a group, and update a group member’s role.
Membership IDs are returned from the /chatter/groups/groupId/memberships resource.
Resource
/chatter/group-memberships/membershipId
Available since version23.0
HTTP methodsGET, DELETE, HEAD, PATCH
PATCH is supported in version 29.0.
Request body for PATCH
Root XML tag<member>
JSON example
{"role" : "GroupManager","userId" : "005B0000000Ge16"
}
Properties
Available VersionDescriptionTypeName
29.0The role of the member.One of these values:
Stringrole
• GroupManager
• StandardMember
23.0The user ID of the memberto be added to the group.
StringuserId
Note: To update a group member’s role in a PATCH request, pass only the role property, don’t pass theuserId property.
200
Group Memberships ResourcesChatter REST API Resources
Request parameters for PATCH
Available VersionDescriptionTypeName
29.0The role of the member.One of these values:
Stringrole
• GroupManager
• StandardMember
Response body for GET or PATCHGroup Member
Batch Group MembershipsAccess information about a list of group members. The members don’t have to belong to the same group. Each membershipID is associated with a specific group.
Membership IDs are returned in the response bodies of several groups resources.
The following groups resource lists every member of a group in its own Group Member response body. The id property ofevery Group Member response body contains a membership Id:
/chatter/groups/groupId/members
Resource
/chatter/group-memberships/batch/membershipIds
Where membershipIds is a comma separated list of membership IDs.
Available since version27.0
HTTP methodsGET, HEAD
Response body for GET or HEADBatch Results
Example for GET
This request gets the group membership information for two users:
/chatter/group-memberships/batch/0FBD00000003GAPOA2,0FBD00000003GAKOA
This is the Batch Results response body, which contains nested User Summary response bodies:
{"hasErrors": true,"results": [
{"result": {
"id": "0FBD00000003GAPOA2","role": "StandardMember",
"url": "/services/data/v30.0/chatter/group-memberships/0FBD00000003GAPOA2",
201
Group Memberships ResourcesChatter REST API Resources
"user": {"companyName": "Universal Containers","firstName": "Gordon","id": "005D0000001LLO1IAO","isActive": true,"isInThisCommunity": true,"lastName": "Johnson","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": {
"id": "0E8D0000000T5ZUKA0","url": "/services/data/v30.0/chatter/subscriptions/0E8D0000000T5ZUKA0"
},"name": "Gordon Johnson","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cPhKrC7plNhUw5eOz7Aj1u-oFL0K-ff2oe04ZAmT2MqC",
"largePhotoUrl": "https:/instance_name/profilephoto/729D00000000LJL/F",
"photoVersionId": "729D00000000LJLIA2","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000LJL/T",
"standardEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cPhKrC7plNhUw5eOz7Aj1u-6d5rE2mNaMaBZfGnFX65O",
"url": "/services/data/v30.0/chatter/users/005D0000001LLO1IAO/photo"
},"title": "VP Sales","type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LLO1IAO","userType": "Internal"
}},"statusCode": 200
},{
"result": [{"errorCode": "NOT_FOUND","message": "The requested resource does not exist"
}],"statusCode": 404
}]
}
Note that the second group membership wasn’t found. Batch requests return a status code for each subrequest.
Group PhotoThe photo for the specified group. Get, post, crop, and delete the photo.
To use an image from the Files page as a group photo (existing content), pass the file ID in the fileId property of the requestbody or in the fileId request parameter. Images uploaded on the Group page don’t have a file ID and can’t be used as thefileId.
To upload a binary file as a group photo, you must send it in a multipart/form-data message. For information about how tocreate the multipart/form-data message, see Uploading Binary Files.
202
Group PhotoChatter REST API Resources
Resource
/chatter/groups/groupId/photo
Available since version23.0
HTTP methodsGET, POST, DELETE, or HEAD
Request body for POST
Root XML tag<photo>
JSON example
{ "cropSize" : "120","cropX" : "0","cropY" : "0","fileId" : "069D00000001IOh"
}
Properties
AvailableVersion
Required or OptionalDescriptionTypeName
29.0Required to crop an uploadedfile or an existing file.
The length, in pixels, of any edgeof the crop square.
IntegercropSize
29.0Required to crop an uploadedfile or an existing file.
The position X, in pixels, fromthe left edge of the image to thestart of the crop square. Top leftis position (0,0).
IntegercropX
29.0Required to crop an uploadedfile or an existing file.
The position Y, in pixels, fromthe top edge of the image to thestart of the crop square. Top leftis position (0,0).
IntegercropY
25.0Required to choose anexisting file.
18–character ID of an existingfile. The key prefix must be 069and the file size must be less than2 MB.
StringfileId
Note: Images uploadedon the Group page andon the User page don’thave file IDs andtherefore can’t be used.
25.0OptionalVersion number of an existingfile. If not provided, the latestversion is used.
IntegerversionNumber
203
Group PhotoChatter REST API Resources
Request parameters for POST
Available VersionRequired or OptionalDescriptionTypeParameter Name
29.0Required to crop anuploaded file or anexisting file.
The length, in pixels,of any edge of the cropsquare.
IntegercropSize
29.0Required to crop anuploaded file or anexisting file.
The position X, inpixels, from the leftedge of the image tothe start of the crop
IntegercropX
square. Top left isposition (0,0).
29.0Required to crop anuploaded file or anexisting file.
The position Y, inpixels, from the topedge of the image tothe start of the crop
IntegercropY
square. Top left isposition (0,0).
25.0Required to choose anexisting file.
18 character ID of anexisting file. The keyprefix must be 069 and
StringfileId
the file size must beless than 2 MB.
Note: Filesuploaded onthe Grouppage and onthe UserProfile pagedon’t have afile ID andcan’t beposted orcropped. Filesuploaded onthe Files pagehave a file IDand can beposted andcropped.
25.0OptionalVersion number of theexisting content. If not
IntegerversionNumber
provided, the latestversion is used.
Note: Photos are processed asynchronously and may not be visible right away.
204
Group PhotoChatter REST API Resources
Response body for GET or HEADPhoto
Response body for POSTPhoto
Group SettingsInformation about the context user’s Chatter settings for the specified group.
Resource
/chatter/groups/groupId/my-settings
Available since version27.0
HTTP methodsGET, HEAD, or PATCH
Request body for PATCH
Root XML tag<groupChatterSettings>
Properties
A user’s Chatter settings.
AvailableVersion
DescriptionTypeName
27.0The frequency with which a groupmember receives email from a group.Valid values are:
StringemailFrequency
• EachPost
• DailyDigest
• WeeklyDigest
• Never
In Communities, the Email on EachPost option is disabled once a groupexceeds 10,000 members. All memberswho had this option selected areautomatically switched to DailyDigest.
205
Group SettingsChatter REST API Resources
Request parameter for PATCH
Available SinceDescriptionTypeParameter Name
27.0The frequency with which agroup member receives email
StringemailFrequency
from a group. Valid valuesare:• EachPost
• DailyDigest
• WeeklyDigest
• Never
Response body for GET, HEAD, or PATCHGroup Chatter Settings
Group TopicsReturns up to five topics most recently used in the specified group.
Resource
/chatter/groups/groupID/topics
Available since version28.0
HTTP methodsGET or HEAD
Response bodyTopic Collection
Influence ResourceList of the percentile thresholds used to categorize an organization’s users by their influence in Chatter.
Users are ranked based on the number of posts and comments made, and comments and likes received. The percentile associatedwith a category represents the bottom threshold for that influencer category. For example: 0.25 defines the cutoff for theActive Influencer category, which means it includes users with an influence rank equal to or greater than the 25thpercentile (25%) and less than the next highest category threshold.
Influence ThresholdsResource
/chatter/influence/thresholds
206
Group TopicsChatter REST API Resources
Available since version24.0
HTTP methodGET or HEAD
Response bodyInfluence Thresholds
Example response body
{"thresholds": [{
"name": "Top Influencer","threshold": "0.8",
}{
"name": "Active Influencer","threshold": "0.25",
}{
"name": "Observer","threshold": "0.0",
}]}
Likes ResourceInformation about the specified like. Also used to delete a like.
You can find the ID for a specific like from any feed, such as a news feed or a record feed.
LikeResource
/chatter/likes/likeId
Available since version23.0
HTTP methodsGET, DELETE or HEAD
Response body for GET or HEADLike
Example response body
{"id": "0I0D000000003KeKAI","likedItem": {
"id": "0D5D0000000IPZuKAO","url": "/services/data/v30.0/chatter/feed-items/0D5D0000000IPZuKAO"
},"url": "/services/data/v30.0/chatter/likes/0I0D000000003KeKAI","user": {
207
Likes ResourceChatter REST API Resources
"companyName": "Universal Containers","firstName": "Deanna","id": "005D0000001LL8OIAW","isActive": true,"lastName": "Li","motif": {
"largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Deanna Li","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5saBc65JKjmm4DaxyLRr1XQK",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/F","photoVersionId": "729D00000000LJFIA2","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000LJF/T","standardEmailPhotoUrl":
"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZNDZe0BfzuOg1WyB6Vo-DB",
"url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW","userType": "Internal"
}}
Mentions ResourcesInformation about users and groups that a user can mention in a feed item body or comment body. When a user or group ismentioned, they receive notification.
Use the Mentions Completions resource to get a list of mention proposals. Use the Mentions Validations resource to determinewhich of those proposals are valid for the context user.
Mentions Completions
Information about users and groups to mention in a feed item body or comment body. Use this resource to generate a list ofproposed mentions that a user can choose from. A mention is an “@” character followed by a user or group name. When auser or group is mentioned, they receive a notification.
Mentions Validations
Information about whether the specified mentions are valid for the context user. For example, the context user can’t mentionprivate groups he doesn’t belong to. If such a group were included in the list of mention validations, the hasErrors propertyof the Mention Validations response body would be true and the group would have a validationStatus of Disallowedin its mention validation.
Mentions CompletionsInformation about users and groups to mention in a feed item body or comment body. Use this resource to generate a list ofproposed mentions that a user can choose from. A mention is an “@” character followed by a user or group name. When auser or group is mentioned, they receive a notification.
208
Mentions ResourcesChatter REST API Resources
Resource
/chatter/mentions/completions
Available since version29.0
HTTP methodsGET, HEAD
Request parameters for GET
AvailableSince
Required or OptionalDescriptionTypeParameter Name
29.0OptionalA feed item ID (for a mention in a comment)or a feed subject ID (for a mention in a feed
StringcontextId
item) that narrows search results, with moreuseful results listed first.
29.0OptionalThe number of the page you want returned.Numbering starts at 0. If you pass 0 or omitthe property, the first page is returned.
Attempting to page beyond 500 results returnsan empty response.
Integerpage
29.0OptionalThe number of items per page. Valid valuesare between 1 and 100. The default size is 25.
Attempting to retrieve more than 500 resultsreturns an empty response.
IntegerpageSize
29.0RequiredA search term. Searches for matching userand group names. To search for a user, a
Stringq
minimum of 1 character is required. To searchfor a group, a minimum of 2 characters isrequired. This parameter does not supportwildcards.
29.0OptionalThe type of mention completion. One of thesevalues:
Stringtype
• All—All mention completions, regardlessof the type of record to which the mentionrefers.
• Group—Mention completions for groups.• User—Mention completions for users.
The default value is All.
Response body for GETMention Completion Page
209
Mentions CompletionsChatter REST API Resources
Example for GETThis example specifies a feed item ID in the contextId parameter to request mention completions for a comment onthe feed item:
GET /chatter/mentions/completions?contextId=0D5D0000000Hwky&q=g
This is the response body:
{"currentPageUrl":
"/services/data/v30.0/chatter/mentions/completions?contextId=0D5D0000000Hwky&q=g","mentionCompletions": [
{"additionalLabel": null,"description": "VP Sales","name": "Gordon Johnson","photoUrl": "https://instance_name/profilephoto/729D00000000LJL/T","recordId": "005D0000001LLO1IAO"
},{
"additionalLabel": null,"description": "A place for constructive cr...","name": "Airing of Grievances","photoUrl": "https://instance_name/profilephoto/0F9/T","recordId": "0F9D00000000izfKAA"
}],"nextPageUrl": null,"previousPageUrl": null
}
Mentions ValidationsInformation about whether the specified mentions are valid for the context user. For example, the context user can’t mentionprivate groups he doesn’t belong to. If such a group were included in the list of mention validations, the hasErrors propertyof the Mention Validations response body would be true and the group would have a validationStatus of Disallowedin its mention validation.
Resource
/chatter/mentions/validations
Available since version29.0
HTTP methodsGET, HEAD
Request parameters for GET
AvailableSince
Required or OptionalDescriptionTypeParameter Name
29.0RequiredThe feed item parent ID (for new feed items)or feed item ID (for comments).
StringparentId
210
Mentions ValidationsChatter REST API Resources
AvailableSince
Required or OptionalDescriptionTypeParameter Name
29.0RequiredA comma separated list of IDs to bementioned. The maximum value is 25.
String[]recordIds
29.0RequiredSpecifies the type of users who can see a feeditem.
Stringvisibility
• AllUsers—Visibility is not limited tointernal users.
• InternalUsers—Visibility is limitedto internal users.
Response body for GETMention Validation
UsageFirst make a request to Mentions Completions to get a list of proposed mentions. Pass those proposed mentions to theMentions Validations resource to determine whether the mentions are valid for the logged-in user.
Motifs ResourcesReturns URLs for sets of small, medium, and large motif icons. Records have different sets of motif icons depending on therecord type. The motif can also include the record type’s base color.
Available resources are:
DescriptionResource
Returns a set of small, medium, and large motif icons for thespecified record. Can also return the base color for the specifiedrecord.
/connect/motifs/idOrPrefix
Returns a set of small, medium, and large motif icons for thespecified records. Can also contain the base color for eachspecified record.
/connect/motifs/batch/idOrPrefixList
Motifs ResourceReturns a set of small, medium, and large motif icons for the specified record. Can also return the base color for the specifiedrecord.
Specify either an ID or key prefix for idOrPrefix.
Resource
/connect/motifs/idOrPrefix
Available since release27.0
211
Motifs ResourcesChatter REST API Resources
HTTP methodsGET or HEAD
Response bodyMotif
Example of GETRequest for user motifs: /connect/motifs/005D0000001LLO1
Response:
{"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
}
Batch Motifs ResourceReturns a set of small, medium, and large motif icons for the specified records. Can also contain the base color for each specifiedrecord.
Specify a comma-separated list of IDs and key prefixes for idOrPrefixList. You can mix IDs and key prefixes in the samerequest.
Resource
/connect/motifs/batch/idOrPrefixList
Available since release27.0
HTTP methodsGET or HEAD
Response bodyBatch Results
Example of GETRequest for motifs for a user and a file: /connect/motifs/batch/005D0000001LLO1,069D00000001FHF
Response:
{"results": [{
"result": {"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"statusCode": 200
},{
"result": {"color": "993333","largeIconUrl": "/img/content/content64.png","mediumIconUrl": "/img/content/content32.png",
212
Motifs ResourcesChatter REST API Resources
"smallIconUrl": "/img/icon/files16.png"},"statusCode": 200
}]}
Record View ResourcesA view of records that includes both data and metadata.
Use the Records View resources to get a view of records that includes data and metadata that you can use to lay out the record.
Record View Information
Data and page layout information (metadata) about the specified record. The metadata describes how to lay out the record’sdetail page, including sections and related lists. The metadata is defined in the page layout editor.
Record View Search
Search for a record and get a collection of list view objects grouped by record type. Results include record data and metadatadescribing the search list view.
Record View InformationData and page layout information (metadata) about the specified record. The metadata describes how to lay out the record’sdetail page, including sections and related lists. The metadata is defined in the page layout editor.
Available in: Unlimited, Enterprise, and Developer Editions
Resource
/connect/records/recordId
Available since version30.0
HTTP methodsGET or HEAD
Response bodyRecord View
UsageThis resource uses a whitelist. If the object type requested is not in the whitelist, the request returns a 400 response withan "INVALID_TYPE" error code. These are the supported objects:
AvailableObject Type
30.0Custom objects
30.0Account
30.0Campaign
213
Record View ResourcesChatter REST API Resources
AvailableObject Type
30.0Case
30.0CollaborationGroup
30.0Contact
30.0ContentDocument
30.0ContentVersion
30.0Contract
30.0Dashboard
30.0Event
30.0Lead
30.0LiveChatTranscript
30.0Opportunity
30.0OpportunityLineItem
30.0Product
30.0ServiceContract
30.0Solution
30.0Task
30.0User
Record View SearchSearch for a record and get a collection of list view objects grouped by record type. Results include record data and metadatadescribing the search list view.
Available in: Unlimited, Enterprise, and Developer Editions
Resource
/connect/records
Available since version30.0
HTTP methodsGET or HEAD
214
Record View SearchChatter REST API Resources
Request parameters for GET
AvailableVersion
Required orOptional
DescriptionTypeProperty
30.0OptionalThe maximum number of rows to return for each list view(each list view contains one object). The minimum valueis 1. The maximum value is 25. The default value is 5.
IntegermaxRecordsPerType
30.0RequiredSpecifies the string to search. The search string mustcontain at least two characters, not including wildcards.See Wildcards.
Stringq
Response bodyRecord Search Results
UsageThis resource uses a whitelist. If the object type requested is not in the whitelist, the request returns a 400 response withan "INVALID_TYPE" error code. These are the supported objects:
AvailableObject Type
30.0Custom objects
30.0Account
30.0Campaign
30.0Case
30.0CollaborationGroup
30.0Contact
30.0ContentDocument
30.0ContentVersion
30.0Contract
30.0Dashboard
30.0Event
30.0Lead
30.0LiveChatTranscript
30.0Opportunity
30.0OpportunityLineItem
30.0Product
30.0ServiceContract
30.0Solution
30.0Task
30.0User
215
Record View SearchChatter REST API Resources
ExampleThis GET request searches for any records whose fields contain the characters “th” plus any additional characters:
GET /connect/records?q=th*
This is the response:
{"resultGroups" : [ {"definition" : {"columns" : [ {"dataType" : "Name","fieldId" : "Name","label" : "Account Name","name" : "Name"
}, {"dataType" : "Text","fieldId" : "Site","label" : "Account Site","name" : "Site"
}, {"dataType" : "Phone","fieldId" : "Phone","label" : "Account Phone","name" : "Phone"
}, {"dataType" : "Reference","fieldId" : "OwnerId","label" : "Owner ID","name" : "OwnerId"
} ],"label" : "Accounts","objectType" : {"fieldId" : null,"type" : "Account"
},"rowLimit" : 5,"sortColumns" : [ ]
},"foundMoreRecords" : false,"minRecordsFound" : 3,"records" : [ {"fields" : [ {"fields" : [ {"label" : "Account Name","text" : "Baghdad Theater","type" : "Text"
} ],"label" : "Account Name","text" : "Baghdad Theater","type" : "Name"
}, {"label" : "Account Site","text" : null,"type" : "Text"
}, {"label" : "Phone","text" : null,"type" : "Phone"
}, {"label" : "Account Owner","reference" : {"id" : "005D0000001LL8OIAW","motif" : {"color" : "20aeb8","largeIconUrl" : "/img/icon/profile64.png","mediumIconUrl" : "/img/icon/profile32.png",
216
Record View SearchChatter REST API Resources
"smallIconUrl" : "/img/icon/profile16.png"},"mySubscription" : null,"name" : "Deanna Li","recordViewUrl" : "/services/data/v30.0/connect/records/005D0000001LL8OIAW",
"type" : "User","url" : "/services/data/v30.0/chatter/users/005D0000001LL8OIAW"
},"text" : "Deanna Li","type" : "Reference"
} ],"id" : "001D000000I8elzIAB","motif" : {"color" : "236FBD","largeIconUrl" : "/img/icon/accounts64.png","mediumIconUrl" : "/img/icon/accounts32.png","smallIconUrl" : "/img/icon/accounts16.png"
},"mySubscription" : null,"name" : "Baghdad Theater","recordViewUrl" : "/services/data/v30.0/connect/records/001D000000I8elzIAB","type" : "Account","url" : "/services/data/v30.0/connect/records/001D000000I8elzIAB"
}, {"fields" : [ {"fields" : [ {"label" : "Account Name","text" : "Hawthorne Theater","type" : "Text"
} ],"label" : "Account Name","text" : "Hawthorne Theater","type" : "Name"
}, {"label" : "Account Site","text" : null,"type" : "Text"
}, {"label" : "Phone","text" : null,"type" : "Phone"
}, {"label" : "Account Owner","reference" : {"id" : "005D0000001LL8OIAW","motif" : {"color" : "20aeb8","largeIconUrl" : "/img/icon/profile64.png","mediumIconUrl" : "/img/icon/profile32.png","smallIconUrl" : "/img/icon/profile16.png"
},"mySubscription" : null,"name" : "Deanna Li","recordViewUrl" : "/services/data/v30.0/connect/records/005D0000001LL8OIAW",
"type" : "User","url" : "/services/data/v30.0/chatter/users/005D0000001LL8OIAW"
},"text" : "Deanna Li","type" : "Reference"
} ],"id" : "001D000000I8eltIAB","motif" : {"color" : "236FBD","largeIconUrl" : "/img/icon/accounts64.png","mediumIconUrl" : "/img/icon/accounts32.png","smallIconUrl" : "/img/icon/accounts16.png"
},
217
Record View SearchChatter REST API Resources
"mySubscription" : null,"name" : "Hawthorne Theater","recordViewUrl" : "/services/data/v30.0/connect/records/001D000000I8eltIAB","type" : "Account","url" : "/services/data/v30.0/connect/records/001D000000I8eltIAB"
}, {"fields" : [ {"fields" : [ {"label" : "Account Name","text" : "The Whole Bowl","type" : "Text"
} ],"label" : "Account Name","text" : "The Whole Bowl","type" : "Name"
}, {"label" : "Account Site","text" : null,"type" : "Text"
}, {"label" : "Phone","text" : null,"type" : "Phone"
}, {"label" : "Account Owner","reference" : {"id" : "005D0000001LL8OIAW","motif" : {"color" : "20aeb8","largeIconUrl" : "/img/icon/profile64.png","mediumIconUrl" : "/img/icon/profile32.png","smallIconUrl" : "/img/icon/profile16.png"
},"mySubscription" : null,"name" : "Deanna Li","recordViewUrl" : "/services/data/v30.0/connect/records/005D0000001LL8OIAW",
"type" : "User","url" : "/services/data/v30.0/chatter/users/005D0000001LL8OIAW"
},"text" : "Deanna Li","type" : "Reference"
} ],"id" : "001D000000I8eloIAB","motif" : {"color" : "236FBD","largeIconUrl" : "/img/icon/accounts64.png","mediumIconUrl" : "/img/icon/accounts32.png","smallIconUrl" : "/img/icon/accounts16.png"
},"mySubscription" : null,"name" : "The Whole Bowl","recordViewUrl" : "/services/data/v30.0/connect/records/001D000000I8eloIAB","type" : "Account","url" : "/services/data/v30.0/connect/records/001D000000I8eloIAB"
} ]}, {"definition" : {"columns" : [ {"dataType" : "Name","fieldId" : "Name","label" : "Full Name","name" : "Name"
}, {"dataType" : "Text","fieldId" : "Title","label" : "Title","name" : "Title"
}, {
218
Record View SearchChatter REST API Resources
"dataType" : "Phone","fieldId" : "Phone","label" : "Phone","name" : "Phone"
}, {"dataType" : "Text","fieldId" : "Company","label" : "Company","name" : "Company"
}, {"dataType" : "Email","fieldId" : "Email","label" : "Email","name" : "Email"
}, {"dataType" : "Picklist","fieldId" : "Status","label" : "Status","name" : "Status"
} ],"label" : "Leads","objectType" : {"fieldId" : null,"type" : "Lead"
},"rowLimit" : 5,"sortColumns" : [ ]
},"foundMoreRecords" : false,"minRecordsFound" : 1,"records" : [ {"fields" : [ {"fields" : [ {"label" : "Salutation","text" : null,"type" : "Picklist"
}, {"label" : "First Name","text" : null,"type" : "Text"
}, {"label" : "Last Name","text" : null,"type" : "Text"
} ],"label" : "Name","text" : "Thea","type" : "Name"
}, {"label" : "Title","text" : null,"type" : "Text"
}, {"label" : "Phone","text" : null,"type" : "Phone"
}, {"label" : "Company","text" : "Key Shoppe","type" : "Text"
}, {"label" : "Email","text" : null,"type" : "Email"
}, {"label" : "Lead Status","text" : "Open - Not Contacted","type" : "Picklist"
} ],
219
Record View SearchChatter REST API Resources
"id" : "00QD000000GGUyqMAH","motif" : {"color" : "E39321","largeIconUrl" : "/img/icon/leads64.png","mediumIconUrl" : "/img/icon/leads32.png","smallIconUrl" : "/img/icon/leads16.png"
},"mySubscription" : null,"name" : "Thea, Key Shoppe","recordViewUrl" : "/services/data/v30.0/connect/records/00QD000000GGUyqMAH","type" : "Lead","url" : "/services/data/v30.0/connect/records/00QD000000GGUyqMAH"
} ]} ],"url" : "/services/data/v30.0/connect/records?q=th*"
}
Records ResourcesInformation about the specified record, including its followers and assigned topics. Add and remove topics from records.
Note: This is not a feed. To obtain a feed for a record, use the Record Feed Resource.
Available resources are:
DescriptionResource
A specified record. Get information about the specified record,such as the name of the record, the record type, a URL to thefeed-items for the record, and so on.
/chatter/records/recordId
The followers of a specified record. Get information aboutthe followers of the specified record.
/chatter/records/recordId/followers
The topics assigned to the specified record. Get informationabout topics assigned to the specified record, and add andremove topics from the specified record.
/connect/records/recordId/topics
Record InformationA specified record. Get information about the specified record, such as the name of the record, the record type, a URL to thefeed-items for the record, and so on.
Resource
/chatter/records/recordId
Available since version23.0
HTTP methodsGET or HEAD
Response bodyRecord Summary
220
Records ResourcesChatter REST API Resources
Example response body
{"id": "069D00000001FHFIA2","motif": {
"largeIconUrl": "/img/content/content64.png","mediumIconUrl": "/img/content/content32.png","smallIconUrl": "/img/icon/files16.png"
},"mySubscription": {
"id": "0E8D0000000T5fwKAC","url": "/services/data/v30.0/chatter/subscriptions/0E8D0000000T5fwKAC"
},"name": "sales","type": "ContentDocument","url": "/services/data/v27.0/chatter/files/069D00000001FHFIA2"
}
Record FollowersThe followers of a specified record. Get information about the followers of the specified record.
Resource
/chatter/records/recordId/followers
Available since version23.0
As of version 29.0, you can use a topic ID for the recordId.
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
An integer specifying a page of items.The default value is 0, which returnsthe first page.
Integerpage
Specifies the number of items per page.Valid values are between 1 and 1000.
IntegerpageSize
If you don't specify a size, the defaultis 25.
Response bodySubscription Page
See Also:Record Feed Resource
221
Records ResourcesChatter REST API Resources
Topics on Records ResourceThe topics assigned to the specified record. Get information about topics assigned to the specified record, and add and removetopics from the specified record. Administrators must enable topics for objects before users can add topics to records of thatobject type.
Resource
/connect/records/recordId/topics
Available since version30.0
HTTP methodsGET, DELETE, POST
Request parameters for DELETE
Available VersionRequired or OptionalDescriptionTypeParameter Name
30.0RequiredID of an existing topicStringtopicId
Response body for DELETE204: Successful Delete
Request body for POST
Root XML tag<topicAssignment>
JSONThe following example assigns a topic to a record:
{ "topicId": "0TOD0000000090r"}
Properties
AvailableVersion
Required or OptionalDescriptionTypeName
30.0Required for existing topicsif the topicName propertyisn’t used.
ID of an existing topic.StringtopicId
30.0Required for new topics;required for existing topics if
Name of a new or existingtopic.
StringtopicName
the topicId property isn’tused.
222
Topics on Records ResourceChatter REST API Resources
Request parameters for POST
Available VersionRequired or OptionalDescriptionTypeParameter Name
30.0Required for existingtopics if the
ID of an existing topicStringtopicId
topicName parameterisn’t used
30.0Required for newtopics; required for
Name of a new orexisting topic
StringtopicName
existing topics if thetopicId parameterisn’t used
Response body for POSTTopic
Example for POSTThis example passes the ID of an existing topic in the topidId parameter to associate it with an opportunity record:
POST /connect/records/006D000000CtYBc/topics?topicId=0TOD0000000090r
This is the JSON response:
{"createdDate": "2013-02-25T18:24:31.000Z","id": "0TOD0000000090rOAA","description": "Test topic description.","talkingAbout": 9,"name": "Test","url": "/services/data/v30.0/chatter/topics/0TOD0000000090rOAA"
}
Subscriptions ResourceInformation about the specified subscription. Also used to delete a subscription, for example, to unfollow a record or a topic.
A subscription ID is returned as part of the response body for follower and following resources, for example,/records/recordId/followers. In addition, subscriptions IDs are also returned in many summary response bodies, suchas group summary or user summary.
Resource
/chatter/subscriptions/subscriptionId
Available since version23.0
HTTP methodsGET, DELETE, or HEAD
223
Subscriptions ResourceChatter REST API Resources
Response body for GET or HEADSubscription
Topics ResourcesList of topics for the organization, list of suggested topics for a specified string of text, feed item, or record, list of trendingtopics for the organization, information about a specified topic, endorsements for a specific topic, information about the filesposted recently to a specified topic, information about the groups recently contributing to a specified topic, knowledgeablepeople for a specified topic, and list of topics related to a specified topic.
Available resources:
DescriptionResource
List of topics for the organization./connect/topics
List of suggested topics for a specified string of text, feed item,or record.
/connect/topics/suggestions
List of the top five trending topics for the organization./connect/topics/trending
Information about the specified topic. Get information abouta topic, change the capitalization or spacing of a topic’s name,
/connect/topics/topicId
and update a topic’s description. Users with the “DeleteTopics” or “Modify All Data” permission can use this resourceto delete topics.
Endorsements on knowledgeable people for the specified topic.Get endorsements for a specified topic and endorse a user forthe specified topic.
/connect/topics/topicId/endorsements
An endorsement. Get information about an endorsement andremove an endorsement.
/connect/topic-endorsements/endorsementId
Returns information about the five files most recently postedto the specified topic.
/connect/topics/topicId/files
Returns information about the five groups that most recentlycontributed to the specified topic.
/connect/topics/topicId/groups
People who are knowledgeable about topics. Get a list ofknowledgeable people for the specified topic.
/connect/topics/topicId/knowledgeable-users
List of five topics most closely related to the specified topic./connect/topics/topicId/related-topics
Topic opt outs. Get a list of topic opt outs for the specifiedtopic. Hide yourself from the Knowledgeable People list forthe specified topic.
/connect/topics/topicId/topic-opt-outs
Topic opt out. After hiding yourself from the KnowledgeablePeople list, show yourself again.
/connect/topic-opt-outs/topicOptOutId
List of TopicsList of topics for the organization.
224
Topics ResourcesChatter REST API Resources
Resource
/connect/topics
Available since version29.0
In version 28.0, use /chatter/topics.
HTTP methodsGET or HEAD
Request parameters
Available VersionRequired or OptionalDescriptionValuesParameter Name
28.0OptionalUse with the qparameter and specify
BooleanexactMatch
true to find a topic byits exact,case-insensitive name.Default value isfalse.
28.0OptionalAn integer greaterthan 0 specifying a
Integerpage
page of topics. Thedefault value is zero.
28.0OptionalSpecifies the numberof items per page.
IntegerpageSize
Valid values arebetween 1 and 100.The default value is25.
28.0OptionalA query string to filterthe results. The string
Stringq
must contain at leasttwo characters, notincluding wildcards.
28.0OptionalOne of the followingvalues:
Stringsort
• popularDesc—Sortstopics bypopularity with themost popular first.This value is thedefault.
• alphaAsc—Sortstopicsalphabetically.
225
List of TopicsChatter REST API Resources
Response bodyTopic Collection
Example for GETThis example requests a list of topics sorted alphabetically:
/connect/topics?sort=alphaAsc
This is the JSON Topic Collection response body:
{"currentPageUrl" : "/services/data/v30.0/connect/topics?sort=alphaAsc","nextPageUrl" : "/services/data/v30.0/connect/topics?sort=alphaAsc&page=1","topics" : [
{"createdDate": "2013-01-01T20:43:31.000Z","id" : "0TOD0000000090qOAA","description" : "Application Programming Interface","talkingAbout" : 27,"name" : "API","url": "/services/data/v30.0/connect/topics/0TOD0000000090qOAA"
},{
"createdDate": "2012-11-14T05:24:23.000Z","id" : "0TOD000000006RxOAI","description" : "The cloud computing event of the year.","talkingAbout" : 424,"name" : "Dreamforce","url": "/services/data/v30.0/connect/topics/0TOD000000006RxOAI"
},{
"createdDate": "2013-02-25T10:47:51.000Z","id" : "0TOD0000000090rOAA","description" : "All things related to mobile.","talkingAbout" : 87,"name" : "Mobile","url": "/services/data/v30.0/connect/topics/0TOD0000000090rOAA"
},{
"createdDate": "2012-10-09T12:49:17.000Z","id" : "0TOD000000007PXOAY","description" : "Promotion announcements.","talkingAbout" : 43,"name" : "Promotion","url": "/services/data/v30.0/connect/topics/0TOD000000007PXOAY"
},{
"createdDate": "2013-02-13T23:19:32.000Z","id" : "0TOD000000006RwOAI","description" : "Workbench provides the user with a graphical interface to work
with file systems and launch applications.","talkingAbout" : 9,"name" : "Workbench","url": "/services/data/v30.0/connect/topics/0TOD000000006RwOAI"
}]}
Topics SuggestionsList of suggested topics for a specified string of text, feed item, or record.
226
Topics SuggestionsChatter REST API Resources
Resource
/connect/topics/suggestions
Available since version29.0
In version 28.0, use /chatter/topics/suggestions.
HTTP methodsGET or HEAD
Request parameters
Required or OptionalDescriptionValuesParameter Name
OptionalMaximum number of topicsuggestions that get
IntegermaxResults
returned. The default is 5.Value must be greater than0 and less than or equal to25.
Required if the textparameter isn’t used
18-character ID of a feeditem or record from which toextract topics.
StringrecordId
Administrators must enabletopics for objects to see topicsuggestions for records ofthat object type. Topics forobjects is available in version30.0.
Required if the recordIdparameter isn’t used
Text from which to extracttopics.
Stringtext
Response bodyTopic Suggestion Collection
Example for GETThis example gets topic suggestions for the text “Working on the planning meeting for our new initiative.”
/connect/topics/suggestions?text=Working+on+the+planning+meeting+for+our+new+initiative.
The following is the response body:
{"topicSuggestions" : [{
"existingTopic" :{
"createdDate": "2013-01-01T20:43:31.000Z","description" : "Our new initiative for hiring in 2013.""id" : "0TOD0000000099dOAA""talkingAbout" : 5,"name" : "New initiative","url": "/services/data/v30.0/connect/topics/0TOD0000000099dOAA"
227
Topics SuggestionsChatter REST API Resources
}"name" : "New initiative"
},{
"existingTopic" :{
"createdDate": "2012-11-14T05:24:23.000Z","description" : "One place to keep track of all of our planning meetings across
all of our initiatives.""id" : "0TOD0000000099eOAA""talkingAbout" : 28,"name" : "planning meeting","url": "/services/data/v30.0/connect/topics/0TOD0000000099eOAA"
}"name" : "planning meeting"
},{
"existingTopic" : null"name" : "New"
},{
"existingTopic" : null"name" : "Initiative"
},]}
Trending TopicsList of the top five trending topics for the organization. The more frequently people add a specific topic to their posts andcomments and comment on or like posts with the same topic over a short period of time, the more likely it is to become atrending topic. For example, if your coworkers are attending the upcoming Dreamforce conference and have started discussingit in Chatter, you may see a trending topic for Dreamforce. A trending topic is not solely based on popularity and usuallyrelates to a one-time or infrequent event that has a spike in activity, such as a conference or a project deadline.
Note: In API versions earlier than 28.0, topics began with a hashtag (#).
Resource
/connect/topics/trending
Available since version29.0
In versions 24.0–28.0, use /chatter/topics/trending.
HTTP methodsGET or HEAD
Request parameters
DescriptionValuesParameter Name
Maximum number of trending topicsthat get returned. The default is 5.
IntegermaxResults
Value must be greater than 0 and lessthan 100.
228
Trending TopicsChatter REST API Resources
Response bodyTopic Collection
Example response body (version 28.0 and later)
{"currentPageUrl" : "/services/data/v30.0/connect/topics/trending?maxResults=5","nextPageUrl" : null,"topics" : [
{"createdDate": "2013-01-01T20:43:31.000Z","id" : "0TOD0000000090qOAA","description" : "Application Programming Interface","talkingAbout" : 527,"name" : "API","url": "/services/data/v30.0/connect/topics/0TOD0000000090qOAA"
},{
"createdDate": "2012-11-14T05:24:23.000Z","id" : "0TOD000000006RxOAI","description" : "The cloud computing event of the year.","talkingAbout" : 424,"name" : "Dreamforce","url": "/services/data/v30.0/connect/topics/0TOD000000006RxOAI"
},{
"createdDate": "2013-02-25T10:47:51.000Z","id" : "0TOD0000000090rOAA","description" : "All things related to mobile.","talkingAbout" : 87,"name" : "Mobile","url": "/services/data/v30.0/connect/topics/0TOD0000000090rOAA"
}]}
Example response body (version 24.0–27.0)
{"topics" : [{
"name" : "#API"},{
"name" : "#Dreamforce"},{
"name" : "#Mobile"}
]}
TopicInformation about the specified topic. Get information about a topic, change the capitalization or spacing of a topic’s name,and update a topic’s description. Users with the “Delete Topics” or “Modify All Data” permission can use this resource todelete topics. Users with the “Edit Topics” permission can edit topic names and descriptions.
Resource
/connect/topics/topicId
229
TopicChatter REST API Resources
Available since version29.0
In version 28.0, use /chatter/topics/topicId.
HTTP methodsGET, PATCH, DELETE, and HEAD
Request body for PATCH
Root XML tag<topic>
JSON
{"description" : "World Wide Web Consortium (W3C) is the main international
standards organization for the Web.""name" : "W3C"}
Properties
Available VersionDescriptionTypeName
28.0Text description of thetopic
Stringdescription
28.0Name of the topic. Use thisproperty to change only the
Stringname
capitalization and spacingof the topic name.
Request parameters for PATCH
Available SinceDescriptionTypeParameter Name
28.0Text description of the topicStringdescription
28.0Name of the topic. Use this parameter tochange only the capitalization and spacingof the topic name.
Stringname
Response body for GET, HEAD, or PATCHTopic
Response body for DELETE204: Successful Delete
Example for PATCHThis example uses request parameters to update the description of a topic:
/connect/topics/0TOD000000006RxOAI?description=Edit+requests
230
TopicChatter REST API Resources
This is the same request using a JSON request body:
/connect/topics/0TOD000000006RxOAI
{"description" : "Edit requests"
}
This is the response body:
{"createdDate": "2012-03-22T13:58:30.000Z","description": "Edit requests","id": "0TOD000000006RxOAI","talkingAbout": 1,"name": "edits","url": "/services/data/v30.0/connect/topics/0TOD000000006RxOAI"
}
Topics, Endorse PeopleEndorsements on knowledgeable people for the specified topic. Get endorsements for a specified topic and endorse a user forthe specified topic.
Resource
/connect/topics/topicId/endorsements
Available since version30.0
HTTP methodsGET, HEAD, POST
Request parameters for GET
Available SinceRequired or OptionalDescriptionTypeParameter Name
30.0OptionalAn integer greaterthan 0 specifying a
Integerpage
page of endorsements.The default value iszero.
30.0OptionalSpecifies the numberof items per page.
IntegerpageSize
Valid values arebetween 1 and 100.The default value is25.
231
Topics, Endorse PeopleChatter REST API Resources
Request body for POST
Root XML tag<topicEndorsement>
JSON
{"userId" : "005B0000000Ge16"
}
Properties
Available VersionRequired orOptional
DescriptionTypeName
30.0RequiredID of the user to beendorsed for thespecified topic.
StringuserId
Request parameters for POST
Available SinceDescriptionTypeParameter Name
30.0ID of the user to endorseStringuserId
Response body for GETTopic Endorsement Collection
Response body for POSTTopic Endorsement
Topic EndorsementsAn endorsement. Get information about an endorsement and remove an endorsement.
Resource
/connect/topic-endorsements/endorsementId
Available since version30.0
HTTP methodsGET, HEAD, DELETE
Response body for GETTopic Endorsement
232
Topic EndorsementsChatter REST API Resources
Response body for DELETE204: Successful Delete
Example for DELETEWhen you endorse someone for a topic, an endorsement record is created with the key prefix 0en. To remove anendorsement, delete the endorsement record.
DELETE /connect/topic-endorsements/0enD0000000003UIAQ
This is the response:
HTTP 204
Topic FilesReturns information about the five files most recently posted to the specified topic.
Resource
/connect/topics/topicId/files
Available since version29.0
In version 28.0, use /chatter/topics/topicId/files.
HTTP methodsGET or HEAD
Response bodyFile Summary Page
Example response bodyThis GET request returns information about every file in the specified topic:
/connect/topics/0TOD000000009Q2/files
The response is:
{"currentPageUrl": null,"files": [{
"checksum": "a65b71bc6a31fa95dd0a9232c9f58c86","contentSize": 100377,"contentUrl": null,"description": null,"downloadUrl":
"/services/data/v30.0/chatter/files/069D00000001E32IAE/content?versionNumber=1","fileExtension": "png","fileType": "Png","flashRenditionStatus": "Na","id": "069D00000001E32IAE","isInMyFileSync": false,"mimeType": "image/png","modifiedDate": "2012-07-17T21:47:27.000Z",
233
Topic FilesChatter REST API Resources
"motif": {"color": "993333","largeIconUrl": "/img/content/content64.png","mediumIconUrl": "/img/content/content32.png","smallIconUrl": "/img/icon/files16.png"
},"mySubscription": {
"id": "0E8D0000000T5JrKAK","url": "/services/data/v30.0/chatter/subscriptions/0E8D0000000T5JrKAK"
},"name": "Recruitment Poster","origin": "Chatter","owner": {
"companyName": "SeattleApps","firstName": "Rene","id": "005D0000001LFNnIAO","isActive": true,"lastName": "Holmes","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile.png","smallIconUrl": "/img/icon/profile.png"
},"mySubscription": null,"name": "Rene Holmes","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZVyX4qlsJTXfOWM77RW7yt",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/F","photoVersionId": "729D00000000BDV","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/T","standardEmailPhotoUrl":
"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbktFTIf9vWhFTTALJiaFz_",
"url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LFNnIAO","userType": "Internal"
},"parentFolder" : "null","pdfRenditionStatus": "Na","renditionUrl": "/services/data/v30.0/chatter/files/069D00000001E32IAE/rendition",
"thumb120By90RenditionStatus": "Success","thumb240By180RenditionStatus": "Success","thumb720By480RenditionStatus": "Success","title": "Recruitment Poster","type": "ContentDocument","url": "/services/data/v30.0/chatter/files/069D00000001E32IAE?versionNumber=1","versionNumber": "1"
}],"nextPageUrl": null,"previousPageUrl": null
}
Topic GroupsReturns information about the five groups that most recently contributed to the specified topic.
234
Topic GroupsChatter REST API Resources
Resource
/connect/topics/topicId/groups
Available since version29.0
In version 28.0, use /chatter/topics/topicId/groups.
HTTP methodsGET or HEAD
Response bodyGroup Page
Example response body
"currentPageUrl": "/services/data/v30.0/chatter/groups","groups": [
{"canHaveChatterGuests": false,"community": null"description": "Get company announcements and other important updates","emailToChatterAddress":
0F9D00000000HRRKA3@post.t-dpvcmac.instance_name.chatter.salesforce.com,"fileCount": 0,"id": "0F9D00000000FG0KAM","information": {
"text": null,"title": null
},"isArchived": false,"isAutoArchiveDisabled": false,"lastFeedItemPostDate": "2011-09-21T19:58:58.000Z","memberCount": 2,"motif": {
"color": "1797C0","largeIconUrl": "/img/icon/groups64.png","mediumIconUrl": "/img/icon/groups32.png","smallIconUrl": "/img/icon/groups16.png"
},"myRole": "GroupOwner","mySubscription": {
"id": "0FBD00000002oJVOAY","url": "/services/data/v30.0/chatter/group-memberships/0FBD00000002oJVOAY"
},"name": "All Seattle Apps","owner": {
"companyName": "Seattle Apps","firstName": "Marion","id": "005D0000001Kl6xIAC","isActive": true,"isInThisCommunity": true,"lastName": "Raven","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Marion Raven","photo": {
235
Topic GroupsChatter REST API Resources
"fullEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZVyX4qlsJTXfOWM77RW7yt",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/F",
"photoVersionId": "729D00000000BDV","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/T"
"standardEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbktFTIf9vWhFTTALJiaFz_",
"url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001Kl6xIAC","userType: "Internal"
},"pendingRequests": 0,"photo": {
"fullEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZVyX4qlsJTXfOWM77RW7yt",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000BDQ/F","photoVersionId": "729D00000000BDQ","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000BDQ/T","standardEmailPhotoUrl": "https://instance_name/ncsphoto/
SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbktFTIf9vWhFTTALJiaFz_","url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo"
},"type": "CollaborationGroup","url": "/services/data/v30.0/chatter/groups/0F9D00000000FG0KAM","visibility": "PublicAccess"
}],"nextPageUrl": null,"previousPageUrl": null
}
Topics, Knowledgeable People ListPeople who are knowledgeable about topics. Get a list of knowledgeable people for the specified topic.
Resource
/connect/topics/topicId/knowledgeable-users
Available since version30.0
HTTP methodsGET or HEAD
Request parameters
Available VersionRequired or OptionalDescriptionValuesParameter Name
30.0OptionalAn integer greaterthan 0 specifying a
Integerpage
page of topics. Thedefault value is zero.
236
Topics, Knowledgeable People ListChatter REST API Resources
Available VersionRequired or OptionalDescriptionValuesParameter Name
30.0OptionalSpecifies the numberof items per page.
IntegerpageSize
Valid values arebetween 1 and 100.The default value is25.
Response bodyKnowledgeable People Collection
Related TopicsList of five topics most closely related to the specified topic.
Resource
/connect/topics/topicId/related-topics
Available since version29.0
In version 28.0, use /chatter/topics/topicId/relatedtopics.
HTTP methodsGET or HEAD
Response bodyTopic Collection
Topics, Opt Outs from Knowledgeable People ListTopic opt outs. Get a list of topic opt outs for the specified topic. Hide yourself from the Knowledgeable People list for thespecified topic.
Resource
/connect/topics/topicId/topic-opt-outs
Available since version30.0
HTTP methodsGET, HEAD, POST
Response body for GETTopic Opt Out Collection
237
Related TopicsChatter REST API Resources
Response body for POSTTopic Opt Out
Topics, Opt Out from Knowledgeable People ListTopic opt out. After hiding yourself from the Knowledgeable People list, show yourself again.
Resource
/connect/topic-opt-outs/topicOptOutId
Available since version30.0
HTTP methodsGET, HEAD, DELETE
Response body for GETTopic Opt Out
Response body for DELETE204: Successful Delete
Example for DELETEWhen you opt out of the knowledgeable people list for a topic, a topic opt out record is created with the key prefix 0eb.To show yourself in the knowledgeable people list after you’ve opted out, delete the topic opt out record.
DELETE /connect/topic-opt-outs/0ebD0000000003oIAA
This is the response:
HTTP 204
User Profiles ResourceReturns details about a user’s profile. This data includes user information (such as address, manager, and phone number),some user capabilities (permissions), and a set of subtab apps, which are custom tabs on the profile page.
For information about subtab apps, search for “subtab apps” at help.salesforce.com.
The capabilities information provides some information about the logged-in user’s capabilities in relation to another user,called the subject user. For example, the capabilities information indicates whether the logged-in user can chat with the subjectuser and whether the logged-in user can direct message the subject user. Specify the subject user as the userID.
Resource
connect/user-profiles/userID
Available since version29.0
238
Topics, Opt Out from Knowledgeable People ListChatter REST API Resources
HTTP methodsGET or HEAD
Parameters
Available SinceDescriptionTypeParameter Name
29.0ID of the userStringuserId
29.0ID of the communityStringcommunityId
Response body for GETUser Profile
Users ResourcesInformation about the user, such as who is following the user, the user’s files or recommendations. Also used for posting feeditems and updating conversation status.
Available resources are:
DescriptionResource
Returns information about all users in anorganization.
/chatter/users
Information about the logged-in or specifieduser's profile.
/chatter/users/me
Returns information about the specified users’profiles.
/chatter/users/batch/user_list
Returns all private conversations for thelogged–in user. Also used to search across allconversations.
/chatter/users/me/conversations
Returns information about the specified privateconversation for the logged-in user. Also usedto search within a specific conversation.
/chatter/users/me/conversations/conversationId
Changes the status of the specified conversation./chatter/users/me/conversations/conversationId/mark-read
Returns the number of conversations that haveunread messages for the logged-in or specifieduser.
/chatter/users/me/conversations/unread-count
Post a file or get information about files a userowns. These files don’t include files shared with
/chatter/users/me/files/
a user, files a user follows, or generalorganization files.
Returns information about files posted togroups that the specified user is a member of.
/chatter/users/me/files/filter/groups
Returns information about files that have beenshared with the specified user.
/chatter/users/me/files/filter/sharedwithme
239
Users ResourcesChatter REST API Resources
DescriptionResource
Returns information about the followers for thespecified user.
/chatter/users/me/followers
Returns a list of people, groups, records, topics,and files that the specified user is following.Also used to follow records.
/chatter/users/me/following
The groups the specified user is a member of./chatter/users/me/groups
Topics that the specified user is knowledgeableabout. Get a list of topics for the specified user.
/chatter/users/me/knowledgeable-about-topics
Returns all the messages for all the privateconversations for the logged-in user. Also usedto search across all messages and post a message.
/chatter/users/me/messages
Returns the specified Chatter private message./chatter/users/me/messages/messageId
The user photo. Get, post, and crop the photo./chatter/users/me/photo
Returns the user, group, file, and recordrecommendations for the logged-in user.
/chatter/users/me/recommendations
Returns the recommendations of the specifiedaction for the logged-in user. For example, usethis resource to get a list of records to follow.
/chatter/users/me/recommendations/action
Returns the recommendations of the specifiedaction and object category for the logged-inuser. Also used to delete recommendations.
/chatter/users/me/recommendations/action/objectCategory
Returns the recommendations of the specifiedaction and key prefix for the logged-in user.
/chatter/users/me/recommendations/action/idPrefix
Returns the recommendation of the specifiedaction and object ID for the logged-in user.Also used to delete a recommendation.
/chatter/users/me/recommendations/action/objectID
A list of the records the logged-in user hasrecently added, edited, or viewed.
/chatter/users/me/records/recent
Information about the context user’s globalChatter settings.
/chatter/users/me/settings
Returns the most recent user status feed item.Also used to update or delete user status.
/chatter/users/me/status
Topics recently used by the specified user. Getup to five topics most recently used by thespecified user.
/chatter/users/me/topics
User InformationReturns information about all users in an organization.
Resource
/chatter/users
240
User InformationChatter REST API Resources
Available since version23.0
HTTP methodsGET or HEAD
Request parameters
AvailableVersion
DescriptionTypeParameter
23.0An integer specifying a page of items. The default value is 0, whichreturns the first page.
Integerpage
23.0The number of items per page. Valid values are between 1 and250. The default value is 25.
IntegerpageSize
23.0Specifies the string to search. The search string must contain atleast two characters, not including any wildcards. For moreinformation about wildcards, see Wildcards.
This parameter searches user names, not email addresses, titles,and so on.
Stringq
28.0Specify a feed item ID that provides context for the search results.
Use this parameter for @mention completion. Passing a feed itemID for searchContextId matches users already mentioned inthe thread earlier in the returned collection.
StringsearchContextId
When using this parameter, you can’t query more than 500 resultsand you can’t use wildcards in the search term.
Response bodyUser Page
In versions earlier than 28.0, the user property in the User Page response body can contain a User Summary or a UserDetail response body. In version 28.0 and later, it always contains User Detail. The fields that the context user is notallowed to see are set to null.
User Profile InformationInformation about the logged-in or specified user's profile.
Resource
/chatter/users/me
or
/chatter/users/userId
Available version23.0
241
User Profile InformationChatter REST API Resources
PATCH available in 29.0
HTTP methodsGET, HEAD, PATCH
Request body for PATCH
Root XML tag<user>
Properties
Available VersionDescriptionTypeName
29.0The aboutMe property ofa User Detail response
StringaboutMe
body. The maximumlength is 1000 characters.
JSON example
{"aboutMe": "Staff Technical Writer responsible for the Connect API and Connect
in Apex documentation."}
Request parameters for PATCH
Available VersionDescriptionTypeName
29.0The aboutMe property of aUser Detail response body.
StringaboutMe
The maximum length is1000 characters.
Response body for GET and HEAD
• User Summary—If the user is an external user or a portal user, or if the version is 25.0 or earlier.• User Detail—If the user is an internal user (including the logged-in user) and the version is greater than 25.0.
Response body for PATCHUser Detail
Example request parameters for PATCHThis example uses a parameter to update the aboutMe property.
/chatter/users/me?aboutMe=Staff+Technical+Writer+at+Seattle+Apps
242
User Profile InformationChatter REST API Resources
Example request body for PATCHThis example uses a request body to update the aboutMe property.
/chatter/users/me
Request body:
{"aboutMe": "Staff Technical Writer at Seattle Apps"
}
Example response body for PATCH
{"aboutMe": "Staff Technical Writer at Seattle Apps",
"address": {"city": "Seattle","country": "US","formattedAdress": "2001 8th Ave\nSeattle, WA 98121\nUS""state": "WA","street": "2001 8th Ave","zip": "98121"
},"chatterActivity": {
"commentCount": 0,"commentReceivedCount": 1,"likeReceivedCount": 0,"postCount": 4
},"chatterInfluence": {
"percentile": "0.5","rank": 1
},"companyName": "Seattle Apps","email": "mraven@seattleapps.com","firstName": "Marion","followersCount": 1,"followingCounts": {
"people": 5,"records": 2,"total": 7
},"groupCount": 3,"id": "005D0000001Kl6xIAC","isActive": true,"isInThisCommunity": true,"lastName": "Raven","managerId": "000000000000000AAA","managerName": null,"motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Marion Raven","phoneNumbers": [{
"phoneNumber": "(206) 999-2846","type": "Work"
}],"photo": {
"fullEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZVyX4qlsJTXfOWM77RW7yt",
243
User Profile InformationChatter REST API Resources
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/F","photoVersionId": "729D00000000BDV","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/T","standardEmailPhotoUrl": "https://instance_name/ncsphoto/
SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbktFTIf9vWhFTTALJiaFz_","url": "/services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo"
},"thanksReceived": null,"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001Kl6xIAC","userType": "Internal","username": "mraven@seattleapps.com"
}
Batch User InformationReturns information about the specified users’ profiles.
Resource
/chatter/users/batch/user_list
Where user_list is a comma separated list of user IDs.
Available since version23.0
HTTP methodsGET or HEAD
Response bodyBatch Results
User Conversations, GeneralReturns all private conversations for the logged–in user. Also used to search across all conversations. See User Conversations,Specific on page 245 and User Messages, General on page 256.
Resource
/chatter/users/me/conversations
or
/chatter/users/userId/conversations
Note: userId must be the ID of the logged-in user or the alias me.
Available since version23.0
244
Batch User InformationChatter REST API Resources
HTTP methodsGET or HEAD
Request parameters for GET
Available VersionDescriptionRequired or OptionalTypeParameter Name
23.0A page token thatindicates where
OptionalStringpage
retrieval begins. Getthis token from theNextPageUrlproperty in theresponse body.
23.0Specifies the numberof items per page.
OptionalIntegerpageSize
Valid values arebetween 1 and 100. Ifyou don't specify asize, the default is 25.
24.0Specifies the string tosearch. The search
OptionalStringq
string must contain atleast two characters,not including anywildcards. For moreinformation aboutwildcards, seeWildcards. Thisparameter is optional.
Note: Thequeryparameteronly searchesmessage textbodies, notuser names,titles, and soon.
Response bodyConversation Summary Collection
User Conversations, SpecificReturns information about the specified private conversation for the logged-in user. Also used to search within a specificconversation.
Note: You can also use the Conversations resource to change the status of a specified conversation. See ChangeStatus of Conversations on page 247.
245
User Conversations, SpecificChatter REST API Resources
Resource
/chatter/users/me/conversations/conversationId
or
/chatter/users/userId/conversations/conversationId
Note: userId must be the ID of the logged-in user or the alias me.
Available since version23.0
HTTP methodsGET, PATCH, or HEAD
Request parameter for GET
Available VersionDescriptionRequired or OptionalTypeParameter Name
24.0Specifies the string tosearch. The search
OptionalStringq
string must contain atleast two characters,not including anywildcards. For moreinformation aboutwildcards, seeWildcards. Thisparameter is optional.
Note: Thequeryparameteronly searchesmessage textbodies, notuser names,titles, and soon.
Request body for PATCH
Root XML tag<conversation>
246
User Conversations, SpecificChatter REST API Resources
Properties
Available VersionDescriptionTypeName
24.0Changes the conversationstatus to unread (false)or read (true).
Booleanread
Request parameters for PATCH
DescriptionTypeParameter Name
Changes the conversation status tounread (false) or read (true).
Booleanread
Response body for GET or HEADConversation Detail
Change Status of ConversationsChanges the status of the specified conversation. Also see Using POST, PATCH, or PUT for Input. You can also use PATCHon the conversations resource to change the status of a specified conversation.
Resource
/chatter/users/me/conversations/conversationId/mark-read
Available versions23.0–29.0
HTTP methodsPOST or PUT
Request body
Root XML tag<conversation>
Properties
Available VersionDescriptionTypeName
24.0Changes the conversationstatus to unread (false)or read (true).
Booleanread
247
Change Status of ConversationsChatter REST API Resources
Request parameters
DescriptionTypeParameter Name
Changes the conversation status tounread (false) or read (true).
Booleanread
Get Unread Count for ConversationsReturns the number of conversations that have unread messages for the logged-in or specified user.
Resource
/chatter/users/me/conversations/unread-count
OR
/chatter/users/userId/conversations/unread-count
Available since version23.0
HTTP methodsGET or HEAD
Request bodyConversation Unread Count
Users Files, GeneralPost a file or get information about files a user owns. These files don’t include files shared with a user, files a user follows, orgeneral organization files.
When you post a file, it is uploaded to the Files tab as a private file and is available only to the file owner.
To upload a file, you must send it in a multipart/form-data request. You can include the description and title of the file in themultipart/form-data request as a JSON or XML request body. You can also send the information as request parameters. Forinformation about how to create the multipart/form-data message, see Uploading Binary Files.
Important: Be aware that this resource may return a large amount of data and may take a while to process.
Resource
/chatter/users/me/files/
or
/chatter/users/userId/files/
248
Get Unread Count for ConversationsChatter REST API Resources
Available since version24.0
HTTP methodsGET, POST, or HEAD
Request body for POST
Describes a new file input. To upload a file, provide the binary file in a multipart/form-data body part wherename="fileData". See Uploading Binary Files.
Root XML tag<fileInput>
JSON
{"desc":"Employee Survey Results","title":"emp_surv_results"
}
Properties
Available VersionDescriptionTypeName
24.0Description of the file to beuploaded.
Stringdesc
30.0 (pilot only)true if the file is includedin the user’s Salesforce Files
BooleanisInMyFileSync
folder, and is syncedbetween that folder andChatter; false otherwise.
30.0 (pilot only)ID of the containing folder.StringparentFolderId
24.0Title of the file.Stringtitle
Request parameters for POST
Since versionDescriptionTypeName
24.0Description of the fileStringdesc
30.0 (pilot only)The request is automatically generatedby an automated client
BooleanisDataSync
30.0 (pilot only)true if the file is included in the user’sSalesforce Files folder, and is synced
BooleanisInMyFileSync
between that folder and Chatter; falseotherwise.
24.0Title of the fileStringtitle
249
Users Files, GeneralChatter REST API Resources
Request parameters for GET or HEAD
Available SinceDescriptionTypeParameter Name
24.0An integer specifying a pageof items. The default value
Integerpage
is 0, which returns the firstpage.
24.0Specifies the number ofitems per page. Valid values
IntegerpageSize
are between 1 and 100. Ifyou don't specify a size, thedefault is 25.
27.0A query string to filter theresults. The string must
Stringq
contain at least twocharacters, not includingwildcards. For informationabout wildcards, seeWildcards.
Response body for GETFile Summary Page
Response body for POSTFile Summary
Example POST requestThe following are the body parts, including a File Input request body, in a multipart/form-data request. For moreinformation, see Uploading Binary Files.
--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgqContent-Type: application/json; charset=UTF-8Content-Disposition: form-data; name="json"
{"desc":"A new file","title":"a_new_file"
}
--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgqContent-Disposition: form-data; name="fileData"; filename="foo"Content-Type: application/octet-stream; charset=ISO-8859-1
This is the content of the file.
--a7V4kRcFA8E79pivMuV2tukQ85cmNKeoEgJgq--
User Files, Filtered by GroupReturns information about files posted to groups that the specified user is a member of.
250
User Files, Filtered by GroupChatter REST API Resources
Resource
/chatter/users/me/files/filter/groups
or
/chatter/users/userId/files/filter/groups
Available since version24.0
HTTP methodsGET or HEAD
Request parameters
Available SinceDescriptionTypeParameter Name
24.0An integer specifying a pageof items. The default value
Integerpage
is 0, which returns the firstpage.
24.0Specifies the number ofitems per page. Valid values
IntegerpageSize
are between 1 and 100. Ifyou don't specify a size, thedefault is 25.
27.0A query string to filter theresults. The string must
Stringq
contain at least twocharacters, not includingwildcards. For informationabout wildcards, seeWildcards.
Response bodyFile Summary Page
User Files, Filtered by SharingReturns information about files that have been shared with the specified user.
Resource
/chatter/users/me/files/filter/shared-with-me
OR
/chatter/users/userId/files/filter/shared-with-me
251
User Files, Filtered by SharingChatter REST API Resources
Note: The resource can also be accessed with the final keyword as one word:
/chatter/users/me | userid/files/filter/sharedwithme
Available since version24.0
HTTP methodsGET or HEAD
Request parameters
Available SinceDescriptionTypeParameter Name
24.0An integer specifying a pageof items. The default value
Integerpage
is 0, which returns the firstpage.
24.0Specifies the number ofitems per page. Valid values
IntegerpageSize
are between 1 and 100. Ifyou don't specify a size, thedefault is 25.
27.0A query string to filter theresults. The string must
Stringq
contain at least twocharacters, not includingwildcards. For informationabout wildcards, seeWildcards.
Response bodyFile Summary Page
User FollowersReturns information about the followers for the specified user.
Resource
/chatter/users/me/followers
or
/chatter/users/userId/followers
Available since version23.0
252
User FollowersChatter REST API Resources
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
An integer specifying a page of items.The default value is 0, which returnsthe first page.
Integerpage
Specifies the number of items per page.Valid values are between 1 and 1000.
IntegerpageSize
If you don't specify a size, the defaultis 25.
Response bodyFollower Page
FollowingReturns a list of people, groups, records, topics, and files that the specified user is following. Also used to follow records. SeeUsing POST, PATCH, or PUT for Input.
Note: You can't use the users resource to add a user to a group. Use the groups resource instead.
Resource
/chatter/users/me/following
or
/chatter/users/userId/following
Available since version23.0
Following topics is available since version 29.0.
HTTP methodsGET, POST, or HEAD
Request body for POST
Root XML tag<following>
253
FollowingChatter REST API Resources
Properties
Available VersionDescriptionTypeName
23.0
Topic IDs are available in29.0
The ID of what to follow,for example, a user ID, arecord ID, a file ID, a topicID, and so on.
StringsubjectId
Note: Use GroupMember Input foradding membersto groups.
Request parameter for POST
AvailableDescriptionTypeParameter Name
23.0
Topic IDs are available in29.0
This request enables the userto follow the specifiedrecord. This could be a userID, a file ID, a topic ID, andso on.
StringsubjectId
Request parameters for GET or HEADAll parameters are optional.
DescriptionTypeParameter Name
Specifies the key prefix to filter the typeof objects returned. The key prefix is
StringfilterType
the three-character prefix code in theobject ID. Object IDs are prefixed withthree-character codes that specify thetype of the object. For example, Userobjects have a prefix of 005 and Groupobjects have a prefix of 0F9.
You don’t need to generate the keyprefixes yourself. Use the List of FilterFeed URLs to see the available keyprefixes.
An integer specifying a page of items.The default value is 0, which returnsthe first page.
Integerpage
Specifies the number of items per page.Valid values are between 1 and 1000.
IntegerpageSize
If you don't specify a size, the defaultis 25.
254
FollowingChatter REST API Resources
Response body for GET or HEADFollowing Page
Response body for POSTSubscription
User GroupsThe groups the specified user is a member of.
Resource
/chatter/users/me/groups
OR
/chatter/users/userId/groups
Available since version23.0
HTTP methodsGET, HEAD
Request parameters
AvailableVersion
Required orOptional
DescriptionTypeParameter Name
23.0OptionalA generated token that indicates the view of feed items.Page tokens are returned as part of the response body,in one of the URL parameters, such as nextPageURL.
Tokenpage
23.0OptionalSpecifies the number of items per page. Valid values arebetween 1 and 250. If you don’t specify a size, the defaultis 25.
IntegerpageSize
30.0OptionalSpecifies the string to search. The search string mustcontain at least two characters, not including wildcards.See Wildcards.
Stringq
Response bodyUser Group Page
ExampleThis GET request returns information about all groups the logged-in user is a member of whose names or descriptionscontain the letters co.
/chatter/users/me/groups?q=co
255
User GroupsChatter REST API Resources
Topics a User is Knowledgeable AboutTopics that the specified user is knowledgeable about. Get a list of topics for the specified user.
Resource
/chatter/users/me/knowledgeable-about-topics
OR
/chatter/users/userId/knowledgeable-about-topics
Available since version30.0
HTTP methodsGET or HEAD
Request parameters
Available VersionRequired or OptionalDescriptionValuesParameter Name
30.0OptionalAn integer greaterthan 0 specifying a
Integerpage
page of topics. Thedefault value is zero.
30.0OptionalSpecifies the numberof items per page.
IntegerpageSize
Valid values arebetween 1 and 100.The default value is25.
Response bodyTopics People Are Knowledgeable About Collection
User Messages, GeneralReturns all the messages for all the private conversations for the logged-in user. Also used to search across all messages andpost a message. See Using POST, PATCH, or PUT for Input. See also User Conversations, General on page 244.
Resource
/chatter/users/me/messages
or
/chatter/users/userId/messages
256
Topics a User is Knowledgeable AboutChatter REST API Resources
Note: userId must be the ID of the logged-in user or the alias me.
Available since version23.0
HTTP methodsGET, HEAD, POST
Request body for POST
Root XML tag<message>
Properties
Available VersionDescriptionTypeName
23.0Text of the message bodyStringbody
23.0ID of an existing messagethat identifies which
StringinReplyTo
conversation this messageis part of.You must specifyeither recipients orinReplyTo. You mustspecify one or the other,not both.
23.0List of users who are theintended message
User Message RecipientList Input
recipients
recipients, up to 9.Comma-separated list ofuser IDs.You must specifyeither recipients orinReplyTo. You mustspecify one or the other,not both.
Example XML format:
<message><body>Text of the message</body><recipients>
<recipient>userID</recipient><recipient>userID</recipient>
</recipients><inReplyTo>messageID</inReplyTo>
</message>
Example JSON format:
{"body": "Text of the message","recipients": ["userID","userID"],
257
User Messages, GeneralChatter REST API Resources
"inReplyTo": "messageID"}
Request parameters for POST
Available VersionDescriptionRequired or OptionalTypeParameter Name
23.0ID of an existingmessage that identifies
You must specifyeither recipients or
StringinReplyTo
which conversationthis message is part of
inReplyTo. Youcannot specify both.
23.0List of users who arethe intended message
You must specifyeither recipients or
Stringrecipients
recipients, up to 9.inReplyTo. Youcannot specify both. Comma-separated list
of user IDs.
23.0The text of themessage, up to 10,000characters
RequiredStringtext
Request parameters for GET
Available VersionDescriptionRequired or OptionalTypeParameter Name
23.0A page token thatindicates where
OptionalStringpage
retrieval begins. Getthis token from theNextPageUrlproperty in theresponse body.
23.0Specifies the numberof items per page.
OptionalIntegerpageSize
Valid values arebetween 1 and 100. Ifyou don't specify asize, the default is 25.
24.0Specifies the string tosearch. The search
OptionalStringq
string must contain atleast two characters,not including anywildcards. For moreinformation aboutwildcards, seeWildcards. Thisparameter is optional.
Note: Thequeryparameter
258
User Messages, GeneralChatter REST API Resources
Available VersionDescriptionRequired or OptionalTypeParameter Name
only searchesmessage textbodies, notuser names,titles, and soon.
Response body for GET or HEADMessage Collection
Response body for POSTMessage
Example response body for GET or HEAD
{"currentPageUrl": "/services/data/v30.0/chatter/users/me/messages","messages": [
{"body": {
"messageSegments": [],"text": "Will you be able to meet about your Dreamforce presentation this
week?"},"conversationId": "03MD000000002LTMAY","conversationUrl":
"/services/data/v30.0/chatter/users/me/conversations/03MD000000002LTMAY","id": "03JD000000003XGMAY","recipients": [
{"companyName": "SeattleApps","firstName": "Rene","id": "005D0000001LFNnIAO","isActive": true,"lastName": "Holmes","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Rene Holmes","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZVyX4qlsJTXfOWM77RW7yt",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000XA5/F",
"photoVersionId": "729D00000000XA5","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000XA5/T",
"standardEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbktFTIf9vWhFTTALJiaFz_",
"url": "/services/data/v30.0/chatter/users/005D0000001LLO6IAO/photo"
},"title": "Senior Manager",
259
User Messages, GeneralChatter REST API Resources
"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LFNnIAO","userType": "Internal"
},{
"companyName": null,"firstName": "Desmond","id": "005D0000001LJvOIAW","isActive": true,"lastName": "Catillo","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Desmond Catillo","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZVyX4qlsJTXfOWM77RW7yt",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000XA5/F",
"photoVersionId": "729D00000000XA5","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000XA5/T",
"standardEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbktFTIf9vWhFTTALJiaFz_",
"url": "/services/data/v30.0/chatter/users/005D0000001LLO1IAO/photo"
},"title": "Senior Manager","type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LJvOIAW","userType": "Internal"
}],"sender": {
"companyName": "SeattleApps","firstName": "Rene","id": "005D0000001LFNnIAO","isActive": true,"lastName": "Holmes","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Rene Holmes","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZVyX4qlsJTXfOWM77RW7yt",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000XA5/F",
"photoVersionId": "729D00000000XA5","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000XA5/T",
"standardEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbktFTIf9vWhFTTALJiaFz_",
"url": "/services/data/v30.0/chatter/users/005D0000001LLO6IAO/photo"},"title": "Senior Manager","type": "User",
260
User Messages, GeneralChatter REST API Resources
"url": "/services/data/v30.0/chatter/users/005D0000001LFNnIAO","userType": "Internal"
},"sentDate": "2012-07-20T21:27:07.000Z","url": "/services/data/v30.0/chatter/users/me/messages/03JD000000003XGMAY"
},{
"body": {"messageSegments": [],"text": "Rene Holmes has shared Recruitment Poster.png with you on
Chatter.\n\nPlease review.\n\nTo view the file, go to:https://na1-blitz01.soma.salesforce.com/069D00000001E32"
},"conversationId": "03MD000000002LTMAY","conversationUrl":
"/services/data/v30.0/chatter/users/me/conversations/03MD000000002LTMAY","id": "03JD000000003VAMAY","recipients": [
{"companyName": "SeattleApps","firstName": "Rene","id": "005D0000001LFNnIAO","isActive": true,"lastName": "Holmes","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Rene Holmes","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZVyX4qlsJTXfOWM77RW7yt",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000XA5/F",
"photoVersionId": "729D00000000XA5","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000XA5/T",
"standardEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbktFTIf9vWhFTTALJiaFz_",
"url": "/services/data/v30.0/chatter/users/005D0000001LLO6IAO/photo"
},"title": "Senior Manager","type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LFNnIAO","userType": "Internal"
},{
"companyName": null,"firstName": "Desmond","id": "005D0000001LJvOIAW","isActive": true,"lastName": "Catillo","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Desmond Catillo","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZVyX4qlsJTXfOWM77RW7yt",
261
User Messages, GeneralChatter REST API Resources
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000XA5/F",
"photoVersionId": "729D00000000XA5","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000XA5/T",
"standardEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbktFTIf9vWhFTTALJiaFz_",
"url": "/services/data/v30.0/chatter/users/005D0000001LLO1IAO/photo"
},"title": "Senior Manager","type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LJvOIAW","userType": "Internal"
}],"sender": {
"companyName": "SeattleApps","firstName": "Rene","id": "005D0000001LFNnIAO","isActive": true,"lastName": "Holmes","motif": {
"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},"mySubscription": null,"name": "Rene Holmes","photo": {
"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZVyX4qlsJTXfOWM77RW7yt",
"largePhotoUrl": "https://instance_name/profilephoto/729D00000000XA5/F",
"photoVersionId": "729D00000000XA5","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000XA5/T",
"standardEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbktFTIf9vWhFTTALJiaFz_",
"url": "/services/data/v30.0/chatter/users/005D0000001LLO6IAO/photo"},"title": "Senior Manager","type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LFNnIAO","userType": "Internal"
},"sentDate": "2012-07-18T19:01:51.000Z","url": "/services/data/v30.0/chatter/users/me/messages/03JD000000003VAMAY"
},"nextPageUrl": null
}
User Messages, SpecificReturns the specified Chatter private message.
Resource
/chatter/users/me/messages/messageId
262
User Messages, SpecificChatter REST API Resources
or
/chatter/users/userId/messages/messageId
Note: userId must be the ID of the logged-in user or the alias me.
Available since version23.0
HTTP methodsGET or HEAD
Response bodyMessage
User PhotoThe user photo. Get, post, and crop the photo.
To use an image from the Files page as a user photo, pass the file ID in the fileId property of the request body or in thefileId request parameter. Images uploaded on the User page don’t have a file ID and can’t be used as the fileId.
To upload a binary file as the user photo, you must send it in a multipart/form-data message. For information about how tocreate the multipart/form-data message, see Uploading Binary Files.
To display user profile photos in a feed, cache the user photos. Then use the photoVersionId to determine when you needto update a photo. This technique helps you avoid running over limits and may improve mobile client performance.
Resource
/chatter/users/me/photo
OR
/chatter/users/userId/photo
Available since version23.0
HTTP methodsGET, POST or HEAD
Request body for POST
Root XML tag<photo>
JSON example
{ "cropSize" : "120","cropX" : "0","cropY" : "0",
263
User PhotoChatter REST API Resources
"fileId" : "069D00000001IOh"}
Properties
AvailableVersion
Required or OptionalDescriptionTypeName
29.0Required to crop an uploadedfile or an existing file.
The length, in pixels, of any edgeof the crop square.
IntegercropSize
29.0Required to crop an uploadedfile or an existing file.
The position X, in pixels, fromthe left edge of the image to thestart of the crop square. Top leftis position (0,0).
IntegercropX
29.0Required to crop an uploadedfile or an existing file.
The position Y, in pixels, fromthe top edge of the image to thestart of the crop square. Top leftis position (0,0).
IntegercropY
25.0Required to choose anexisting file.
18–character ID of an existingfile. The key prefix must be 069and the file size must be less than2 MB.
StringfileId
Note: Images uploadedon the Group page andon the User page don’thave file IDs andtherefore can’t be used.
25.0OptionalVersion number of an existingfile. If not provided, the latestversion is used.
IntegerversionNumber
Request parameters for POST
Available VersionRequired or OptionalDescriptionTypeParameter Name
29.0Required to crop anuploaded file or anexisting file.
The length, in pixels,of any edge of the cropsquare.
IntegercropSize
29.0Required to crop anuploaded file or anexisting file.
The position X, inpixels, from the leftedge of the image tothe start of the crop
IntegercropX
square. Top left isposition (0,0).
29.0Required to crop anuploaded file or anexisting file.
The position Y, inpixels, from the topedge of the image tothe start of the crop
IntegercropY
264
User PhotoChatter REST API Resources
Available VersionRequired or OptionalDescriptionTypeParameter Name
square. Top left isposition (0,0).
25.0Required to choose anexisting file.
18 character ID of anexisting file. The keyprefix must be 069 and
StringfileId
the file size must beless than 2 MB.
Note: Filesuploaded onthe Grouppage and onthe UserProfile pagedon’t have afile ID andcan’t beposted orcropped. Filesuploaded onthe Files pagehave a file IDand can beposted andcropped.
25.0OptionalVersion number of theexisting content. If not
IntegerversionNumber
provided, the latestversion is used.
Note: Photos are processed asynchronously and may not be visible right away.
Response body for GET or HEADPhoto
Response body for POSTPhoto
User Recommendations, GeneralReturns the user, group, file, and record recommendations for the logged-in user.
Resource
/chatter/users/me/recommendations
265
User Recommendations, GeneralChatter REST API Resources
OR
/chatter/users/userId/recommendations
Note: userId must be the ID of the logged-in user or the alias me.
Available since version24.0
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
Maximum number of recommendationresults; default is 10. Value must begreater than 0.
IntegermaxResults
Response bodyZero or more Recommendation responses
User Recommendations for a Specific ActionReturns the recommendations of the specified action for the logged-in user. For example, use this resource to get a list ofrecords to follow.
Resource
/chatter/users/me/recommendations/action
or
/chatter/users/userId/recommendations/action
Note: userId must be the ID of the logged-in user or the alias me.
Valid values for action and resulting recommendations:
• follow returns recommendations to follow users, files, and records.• join returns recommendations to join groups.• view returns recommendations to view users, files, groups, and records. Available in versions 25.0 and later.
Available since version24.0
266
User Recommendations for a Specific ActionChatter REST API Resources
HTTP methodsGET or HEAD
Request parameters
DescriptionTypeParameter Name
Maximum number of recommendationresults; default is 10. Value must begreater than 0.
IntegermaxResults
Response bodyZero or more Recommendation responses
User Recommendations for a Specific Action and Object CategoryReturns the recommendations of the specified action and object category for the logged-in user. Also used to deleterecommendations.
Resource
/chatter/users/me/recommendations/action/objectCategory
or
/chatter/users/userId/recommendations/action/objectCategory
Note: userId must be the ID of the logged-in user or the alias me.
• Valid values for action:
◊ follow
◊ join
◊ view (Available in versions 25.0 and later.)
• Valid values for object category:
◊ If action is follow, object category is users, files, or records.◊ If action is join, object category is groups.◊ If action is view, object category is users, files, groups, or records.
Available since version23.0
HTTP methodsGET, DELETE, or HEAD
DELETE is available as of version 24.0. DELETE is used to remove a recommendation and is only valid for thefollowing resources:
• /chatter/users/me | userId/recommendations/follow/recommendedUserId
267
User Recommendations for a Specific Action and ObjectCategory
Chatter REST API Resources
• /chatter/users/me | userId/recommendations/follow/recommendedFileId
• /chatter/users/me | userId/recommendations/follow/recommendedRecordId
• /chatter/users/me | userId/recommendations/join/recommendedGroupId
Note: userId must be the ID of the logged-in user or the alias me.
Request parameters for GET or HEAD
Since VersionDescriptionTypeParameter Name
23.0Maximum number of recommendationresults; default is 10. Value must begreater than 0.
IntegermaxResults
24.0ID of a user. Provides newrecommendations based on the contextof this user ID.
Stringfollowed
25.0ID of a file. Provides newrecommendations based on the contextof this file ID.
Stringviewed
Example request URL with followed request parameter
/chatter/users/me/recommendations/follow/users?followed=005D0000001GLowIAB
Response body for GET with followed request parameterZero or one user Recommendation response
Response body for GET or HEAD without request parametersZero or more Recommendation responses
Response body for DELETE204: Successful Delete
User Recommendations for a Specific Action and Key PrefixReturns the recommendations of the specified action and key prefix for the logged-in user. The keyPrefix in the resourceURL is the first three characters of the object ID and indicates the object type.
Resource
/chatter/users/me/recommendations/action/idPrefix
or
/chatter/users/userId/recommendations/action/idPrefix
268
User Recommendations for a Specific Action and Key PrefixChatter REST API Resources
Note: userId must be the ID of the logged-in user or the alias me.
• Valid values for action:
◊ follow
◊ join
◊ view
• Valid values for idPrefix:
◊ If action is follow, idPrefix is the key prefix for users (005), files (069), or records (such as 001 or 003).◊ If action is join, idPrefix is the key prefix for groups (0F9).◊ If action is view, idPrefix is the key prefix for users (005), files (069), groups (0F9), or records (such as 001
or 003).
Available since version26.0
HTTP methodsGET or HEAD
Request parameters for GET or HEAD
DescriptionTypeParameter Name
Maximum number of recommendationresults; default is 10. Value must begreater than 0.
IntegermaxResults
ID of a user. Provides newrecommendations based on the contextof this user ID.
Stringfollowed
ID of a file. Provides newrecommendations based on the contextof this file ID.
Stringviewed
Example request URL
/chatter/users/me/recommendations/view/001
Response body for GET or HEAD without request parametersZero or more account Recommendation responses
User Recommendations for a Specific Action and Object IDReturns the recommendation of the specified action and object ID for the logged-in user. Also used to delete a recommendation.
Resource
/chatter/users/me/recommendations/action/objectID
269
User Recommendations for a Specific Action and Object IDChatter REST API Resources
or
/chatter/users/userId/recommendations/action/objectID
Note: userId must be the ID of the logged-in user or the alias me.
• Valid values for action:
◊ follow
◊ join
◊ view (Available in versions 25.0 and later.)
• Valid values for object ID:
◊ If action is follow, object ID is a user ID, file ID, or record ID.◊ If action is join, object ID is a group ID.◊ If action is view, object ID is a user ID, file ID, group ID, or record ID.
Available since version24.0
HTTP methodsGET, DELETE, or HEAD
DELETE is used to remove a recommendation and is only valid for the following resources:
• /chatter/users/me | userId/recommendations/follow/recommendedUserId
• /chatter/users/me | userId/recommendations/follow/recommendedFileId
• /chatter/users/me | userId/recommendations/follow/recommendedRecordId
• /chatter/users/me | userId/recommendations/join/recommendedGroupId
Note: userId must be the ID of the logged-in user or the alias me.
Request parameters for GET or HEAD
DescriptionTypeParameter Name
Maximum number of recommendationresults; default is 10. Value must begreater than 0.
IntegermaxResults
ID of a user. Provides newrecommendations based on the contextof this user ID.
Stringfollowed
Response body for GET or HEAD without request parametersZero or one Recommendation response
Response body for DELETE204: Successful Delete
270
User Recommendations for a Specific Action and Object IDChatter REST API Resources
User Records, Recently UsedA list of the records the logged-in user has recently added, edited, or viewed.
Resource
/chatter/users/me/records/recent
or
/chatter/users/userId/records/recent
Note: The userId must be the ID of the logged-in user or the alias me.
Available since version30.0
HTTP methodsGET, HEAD
Request parameter for GET
Available SinceDescriptionTypeParameter Name
30.0The maximum number of recently used objects toreturn between 1–150. The default value is 10.
Integersize
Response body for GETRecord Summary List
User SettingsInformation about the context user’s global Chatter settings.
Resource
/chatter/users/me/settings
or
/chatter/users/userId/settings
Note: The userId must be the ID of the logged-in user or the alias me.
Available since version27.0
271
User Records, Recently UsedChatter REST API Resources
HTTP methodsGET, HEAD, or PATCH
Request body for PATCH
Root XML tag<userChatterSettings>
Properties
AvailableVersion
DescriptionTypeName
27.0The default frequency with which a userreceives email from a group when theyjoin. Valid values are:
StringdefaultGroupEmailFrequency
• EachPost
• DailyDigest
• WeeklyDigest
• Never
In Communities, the Email on Each Postoption is disabled once a group exceeds10,000 members. All members who hadthis option selected are automaticallyswitched to Daily Digest.
Request parameter for PATCH
Available SinceDescriptionTypeParameter Name
27.0The default frequency withwhich a user receives email
StringdefaultGroupEmailFrequency
from a group when they join.This setting does not affectgroups a user is already amember of. Valid values are:• EachPost
• DailyDigest
• WeeklyDigest
• Never
Response body for GET, HEAD, or PATCHUser Chatter Settings
Response body example for GET
{"defaultGroupEmailFrequency": "Never"}
272
User SettingsChatter REST API Resources
User StatusNote: This resource is no longer available as of version 25.0. Instead, use any feed resource, with the feed-item, suchas /chatter/feeds/news/me/feed-items.
Returns the most recent user status feed item. Also used to update or delete user status. See Using POST, PATCH, or PUTfor Input.
Resource
/chatter/users/me/status
or
/chatter/users/userId/status
Available in versions23.0–24.0
HTTP methodsGET, DELETE, POST or HEAD
Request body for POST
Root XML tag<userStatus>
Properties
Available VersionDescriptionTypeName
23.0–24.0Description of messagebody.
Message Body Inputbody
Request parameter for POST
DescriptionTypeName
Text of the item to be posted to theuser's status
String Text to posttext
Response body for GET or POSTUser Status
Example response body
<?xml version="1.0" encoding="UTF-8"?><currentStatus><body><messageSegments><segment>
273
User StatusChatter REST API Resources
<text>Will send you latest updates tonight</text><type>Text</type>
</segment></messageSegments><text>Will send you latest updates tonight</text>
</body><parentId>005D0000001GLbn</parentId><url>/services/data/v30.0/chatter/users/005D0000001GLbn/status</url>
</currentStatus>
Topics Recently UsedTopics recently used by the specified user. Get up to five topics most recently used by the specified user.
Resource
/chatter/users/me/topics
OR
/chatter/users/userId/topics
Available since version28.0
HTTP methodsGET or HEAD
Response bodyTopic Collection
Zones ResourcesInformation about Chatter Answers zones.
Available resources:
DescriptionResource
A list of Chatter Answers zones in the organization. Getinformation about zones available to the context user.
/connect/zones
Information about the specified Chatter Answers zone./connect/zones/zoneId
Search results from a search in a Chatter Answers zone./connect/zones/zoneId/searchResults
List of ZonesA list of Chatter Answers zones in the organization. Get information about zones available to the context user.
274
Topics Recently UsedChatter REST API Resources
Resource
/connect/zones/
Available version29.0
HTTP methodsGET
Request parameters for GET
Available VersionDescriptionTypeParameter Name
29.0An integer specifying a page of items. The defaultvalue is 0, which returns the first page.
Integerpage
29.0Specifies the number of items per page. Valid valuesare between 1 and 250. The default value is 25.
IntegerpageSize
Response body for GETZone Page
Zone InformationInformation about the specified Chatter Answers zone.
Resource
/connect/zones/zoneId
Available version29.0
HTTP methodsGET
Response body for GETZone
Zone Search ResultsSearch results from a search in a Chatter Answers zone.
Resource
/connect/zones/zoneId/search-results
Available version29.0
275
Zone InformationChatter REST API Resources
HTTP methodsGET
Request parameters for GET
Available VersionDescriptionTypeParameter Name
29.0An integer specifying a page of items. The defaultvalue is 0, which returns the first page.
Integerpage
29.0Specifies the number of items per page. Valid valuesare between 1 and 100. The default value is 20.
IntegerpageSize
Response body for GETZone Search Result
276
Zone Search ResultsChatter REST API Resources
Chapter 5
Chatter REST API Request Bodies
To perform a POST, PATCH, or PUT request, pass query parameters or create a request body formatted in either XML orJSON. This chapter lists the request bodies. The query parameters are listed with each resource.
To create a JSON request body, specify the properties of the request body in JSON format.
This is an example of a Comment request body.
{"body" : "Let's look for a new solution."}
If a request body is top-level, it has a root XML tag listed. To create an XML request body, nest the properties as XML tagsinside the root XML tag.
This is the same Connect request body in XML format:
<comment><body>Let's look for a new solution.</body></comment>
Attachment Input: Canvas AppXML
In XML request bodies, attachmentType is an attribute of the <attachment> element.
<attachment attachmentType="Canvas"><developerName>TravelApp</developerName>
</attachment>
JSON
{"attachment" :{"attachmentType" : "Canvas","developerName" : "TravelApp","namespacePrefix" : "dev_org","parameters" : "{"itinerary":"123"}","height" : "250px","title" : "TravelItinerary",
}}
277
Properties
AvailableVersion
DescriptionTypeName
29.0The attachment type. Must contain the value Canvas.StringattachmentType
29.0Optional. The description of the canvas app.Stringdescription
29.0The developer name (API name) of the canvas appStringdeveloperName
29.0Optional. The height of the canvas app in pixels. Defaultheight is 200 pixels.
Stringheight
29.0Optional. The namespace prefix of the Developer Editionorganization in which the canvas app was created.
StringnamespacePrefix
29.0Optional. Parameters passed to the canvas app in JSONformat. The JSON must be escaped.
Stringparameters
29.0Optional. The URL to a thumbnail image for the canvas app.Maximum dimensions are 120x120 pixels.
StringthumbnailUrl
29.0Optional. The title of the link used to call the canvas app.Stringtitle
Attachment Input: Existing ContentXML
In XML request bodies, attachmentType is an attribute of the <attachment> element.
<attachment attachmentType="ExistingContent"><contentDocumentId>069...</contentDocumentId>
</attachment>
JSON
{ "attachment":{
"attachmentType":"ExistingContent","contentDocumentId": "069D00000001FHF"
}}
Properties
Available VersionDescriptionTypeName
27.0The attachment type. Mustcontain the valueExistingContent.
StringattachmentType
23.0ID of the existing contentStringcontentDocumentId
278
Attachment Input: Existing ContentChatter REST API Request Bodies
Attachment Input: Feed PollXML
Note that in XML, the choices for the poll are each wrapped in a <choice> element and attachmentType is anattribute of the <attachment> element. For example:
<attachment attachmentType="Poll"><pollChoices>
<choice>One</choice><choice>Two</choice>
</pollChoices></attachment>
JSON
{ "attachment":{
"attachmentType":"Poll","pollChoices": [
"Monday","Tuesday"
]}
}
Properties
Available VersionDescriptionTypeName
27.0The attachment type. Mustcontain the value Poll.
StringattachmentType
26.0A list of choices used in thefeed poll.
String []pollChoices
Attachment Input: LinkXML
The attachmentType property is an attribute of the <attachment> element. For example:
<attachment attachmentType="Link"><url>http://www.google.com</url><urlName>A search engine</urlName>
</attachment>
JSON
{ "attachment":{
"attachmentType":"Link","url": "http://www.salesforce.com","urlName": "Salesforce"
279
Attachment Input: Feed PollChatter REST API Request Bodies
}}
Properties
Available VersionDescriptionTypeName
27.0The attachment type. Mustcontain the value Link.
StringattachmentType
23.0URL included in theattachment.
Stringurl
23.0Optional. Name of the URL.If not provided, a name is
StringurlName
generated from the domainname of the URL.
Attachment Input: New File UploadTo upload a new file, provide the binary file in a multipart/form-data body part where name="feedItemFileUpload".See Uploading Binary Files.
XMLThe attachmentType property is an attribute of the <attachment> element. For example:
<attachment attachmentType="NewFile"><description>TPS Report (with cover)</description>
<title>TPS.txt</title></attachment>
JSON
{ "attachment":{
"attachmentType":"NewFile","description":"TPS Report (with cover)","title":"TPS.txt"
}}
Properties
Available VersionDescriptionTypeName
27.0The attachment type. Must contain thevalue NewFile.
StringattachmentType
23.0–26.0Description of the file.Stringdesc
Attention: This parametershould not be used as of
280
Attachment Input: New File UploadChatter REST API Request Bodies
Available VersionDescriptionTypeName
version 27.0. Usedescription instead.
27.0Optional. Description of the file.Stringdescription
24.0Title of the file.Stringtitle
Batch InputRoot XML Tag
<batch>
JSON
{"batchRequests" : [{
"method" : "Get","url" : "/v28.0/chatter/feeds/news/me"
},{
"method" : "Get","url" : "/v28.0/chatter/feeds/user-profile/me"
}]
}
Properties
AvailableVersion
DescriptionTypeName
28.0Collection of Batch Request Input requestbodies containing the subrequest URLs toexecute.
Batch Request Input[]batchRequests
28.0The default value is false.
If the value is false and a subrequest in thebatch does not complete, Database.com
BooleanhaltOnError
attempts to execute subsequent subrequestsin the batch.
If the value is true and a subrequest in thebatch does not complete due to an HTTPresponse in the 400 or 500 range,Database.com halts execution. It does notattempt to execute subsequent subrequestsin the batch, and it returns an HTTP 412status code and aBATCH_PROCESSING_HALTED errormessage for each subsequent subrequestindicating that a previous request was
281
Batch InputChatter REST API Request Bodies
AvailableVersion
DescriptionTypeName
unsuccessful. The top-level request to/connect/batch returns HTTP 200 andthe hasErrors property in the response isset to true.
Batch Request InputRoot XML Tag
<request>
JSON
{"method" : "Get","url" : "/v28.0/chatter/feeds/news/me"
}
Properties
AvailableVersion
DescriptionTypeName
28.0The name of the binary part in the multipartrequest.
When there are multiple binary partsuploaded in one batch request, this value is
StringbinaryPartName
used to map a request to its binary part. Toprevent name collisions, use a unique valuefor each binaryPartName property in abatch request.
This property is optional. If this value exists,a binaryPartNameAlias value must alsoexist.
28.0The name parameter in theContent-Disposition header of the binary
StringbinaryPartNameAlias
body part. Different resources expectdifferent values. See Uploading Binary Files.
This property is optional. If this value exists,a binaryPartName value must also exist.
28.0The HTTP method of the request. One ofthese values:
Stringmethod
• Delete• Get• Head• Patch
282
Batch Request InputChatter REST API Request Bodies
AvailableVersion
DescriptionTypeName
• Post• Put
28.0The input body for the request.
The type depends on the request specifiedin the url property.
richInput
This property is optional.
28.0The Chatter API resource to request. Thisvalue is called a subrequest.
The subrequest URL can start with:
Stringurl
• /services/data/version, forexample, /services/data/v30.0/chatter/users/me.
• /version, for example,/v30.0/chatter/users/me. Theversion number must be less than orequal to the version of the request givento the /connect/batch request URL.
Additional information about subrequests:
• The URL can include any query stringparameters that the subrequest supports.The query string must be URL-encoded.
• You can use parameters to filter responsebodies.
• You cannot apply headers at thesubrequest level.
Comment InputRoot XML tag
<comment>
JSONThe following example attaches an existing file to a comment:
{"attachment": {
"attachmentType":"ExistingContent","contentDocumentId":"069D00000001FHF"
},"body" : {
"messageSegments" : [{
"text" : "FY14 Sales Projections","type" : "Text"
}
283
Comment InputChatter REST API Request Bodies
]}
}
Properties
AvailableVersion
DescriptionTypeName
24.0Optional. Values are:Depends on type.attachment
• Attachment Input: Existing Content• Attachment Input: New File Upload
Note: To upload a new file,you must include it in amultipart/form–data message.See Uploading Binary Files.
23.0Description of message bodyMessage Body Inputbody
Dashboard Component Snapshot InputRoot XML tag
<dashboardComponentSnapshot>
JSON
{"parentId" : "0F9D00000000I4O","feedItemBody" : {
"messageSegments" : [{
"text" : "Sales Heat","type" : "Text"
}]
}}
Properties
Available VersionDescriptionTypeName
25.0A user, group, or dashboard ID towhich you are posting thesnapshot.
StringparentId
25.0Optional. A dashboard filter itemID.
StringfilterId1
25.0Optional. A second dashboardfilter item ID.
StringfilterId2
284
Dashboard Component Snapshot InputChatter REST API Request Bodies
Available VersionDescriptionTypeName
25.0Optional. A third dashboard filteritem ID.
StringfilterId3
25.0Contains the text thataccompanies the feed item
Message BodyInput
feedItemBody
associated with the dashboardcomponent snapshot.
25.0Optional. A user ID from whichthe view of the dashboard will becreated, if other than the creator.
StringrunningUserId
Feed Favorite InputRoot XML tag
<favorite>
JSON for POST
{"searchText" : "release","targetId" : "0TOD0000000099d"
}
Properties for POST
Available VersionDescriptionTypeName
24.0Text of the feed search. Usethis parameter for feedsearches only.
StringsearchText
28.0Id of the topic. Use thisparameter for topics only.
StringtargetId
JSON for PATCH
{"updateLastViewDate" : "true"
}
Properties for PATCH
Available VersionDescriptionTypeName
24.0Sets the last view date of thespecified feed favorite to the
BooleanupdateLastViewDate
current system time. Defaultvalue is false.
285
Feed Favorite InputChatter REST API Request Bodies
Feed Item InputRoot XML tag
<feedItem>
JSONThe following example attaches a poll to a feed item:
{ "attachment":{
"attachmentType":"Poll","pollChoices": [
"Monday","Tuesday"
]},"body" : {
"messageSegments" : [{
"type" : "Text","text" : "When should we meet for release planning?"
}]
}}
Properties
AvailableVersion
DescriptionTypeName
Optional. You can specify only one of thesevalues in the attachment parameter. Valuesare:
Depends on type.attachment
• 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)
Note: To upload a new file,you must include it in amultipart/form–data message.See Uploading Binary Files.
23.0Description of message body. The bodycan contain up to 25 mentions.
If you specify originalFeedItemId toshare a feed item, use the body propertyto add a comment to the feed item.
Message Body Inputbody
286
Feed Item InputChatter REST API Request Bodies
AvailableVersion
DescriptionTypeName
If this feed item is shared, this value is thebody of the first comment.
24.0Optional. Specifies if the new feed itemshould be bookmarked for the user (true)or not (false). Default value is false.
BooleanisBookmarkedByCurrentUser
24.0Optional. If this feed item is shared, thisis the original feed item 18-character ID
StringoriginalFeedItemId
Note: This parameter takesprecedence over all otherparameters. For example, if youshare a post and also try to uploada file, the generated feed-itemonly contains the shared post. Youshould only share a post or uploada file, not both in the same post.
26.0Optional. Who can see the post. Validvalues are:
Stringvisibility
• InternalUsers—If Communities isenabled, only members of the default,internal community can see the feeditem.
• AllUsers—If Communities isenabled, all members of the communitycan see the feed item.
Default values:
• For external users, the default value isAllUsers. External users must usethis value to see their posts.
• For internal users, the default value isInternalUsers. Internal users canaccept this value or use the valueAllUsers to allow external users tosee their posts.
If the parent of the feed item is a User ora Group, the visibility of the feed itemmust be AllUsers.
Feed Item Topic InputRoot XML tag
<feedItemTopic>
287
Feed Item Topic InputChatter REST API Request Bodies
JSONThe following example attaches a new topic to a feed item:
{ "topicName": "W3C"}
Properties
AvailableVersion
Required or OptionalDescriptionTypeName
29.0Required for existing topics ifthe topicName property isn’tused
ID of an existing topicStringtopicId
29.0Required for new topics;required for existing topics if
Name of a new or existingtopic, up to 150 characters
StringtopicName
the topicId property isn’tused
Feed Poll InputRoot XML tag
<feedPoll>
Properties
Available VersionDescriptionTypeName
26.0ID of an existing choice onthe feed poll. Used to specify
StringmyChoiceId
the ID of the poll choice thatthe current user is voting on.
File InputDescribes a new file input. To upload a file, provide the binary file in a multipart/form-data body part wherename="fileData". See Uploading Binary Files.
Root XML tag<fileInput>
JSON
{"desc":"Employee Survey Results","title":"emp_surv_results"
}
288
Feed Poll InputChatter REST API Request Bodies
Properties
Available VersionDescriptionTypeName
24.0Description of the file to beuploaded.
Stringdesc
30.0 (pilot only)true if the file is includedin the user’s Salesforce Files
BooleanisInMyFileSync
folder, and is synced betweenthat folder and Chatter;false otherwise.
30.0 (pilot only)ID of the containing folder.StringparentFolderId
24.0Title of the file.Stringtitle
File Shares InputRoot XML tag
<fileShares>
JSON example
{"message": "I shared a document with you.","shares": [
{ "id": "005D0000001Az4l", "sharingType": "V" },{ "id": "005D0000001B2ny", "sharingType": "C" }
]}
Properties
Available VersionDescriptionTypeName
30.0Private message body that’s sent to the recipients.If Salesforce Communities is enabled, an email issent instead of a private message.
Stringmessage
30.0Collection of Share Input request bodiesShare Input[]shares
Folder InputRoot XML tag
<folderInput>
JSON example
{"path" : "my_documents/my_folder"
}
289
File Shares InputChatter REST API Request Bodies
Properties
Available VersionDescriptionTypeName
30.0The name of the folder.
Either path or name is required. If you specifyboth, path is used and name is ignored.
Stringname
30.0The ID of the parent folder.
Either parentFolderId or path is required.You can’t include both.
StringparentFolderId
30.0The path of the folder. For example, mydocuments/folder.
Stringpath
Folder Item InputRoot XML tag
<folderItem>
JSON example
{"file" :
{"desc" : "Yearly Report for Universal Containers Box Division","title" : "Yearly.txt"
},"type" : "File"
}
Properties
AvailableVersion
Required or OptionalDescriptionTypeName
30.0Required to POST a FileA file in a folderFile Inputfile
30.0Required to POST a FolderA folder in a folderFolder Inputfolder
30.0RequiredThe item type. One ofthese values:
Stringtype
• File
• Folder
Following InputRoot XML tag
<following>
290
Folder Item InputChatter REST API Request Bodies
Properties
Available VersionDescriptionTypeName
23.0
Topic IDs are available in29.0
The ID of what to follow,for example, a user ID, arecord ID, a file ID, a topicID, and so on.
StringsubjectId
Note: Use GroupMember Input foradding members togroups.
Group Chatter Settings InputRoot XML tag
<groupChatterSettings>
Properties
A user’s Chatter settings.
AvailableVersion
DescriptionTypeName
27.0The frequency with which a groupmember receives email from a group.Valid values are:
StringemailFrequency
• EachPost
• DailyDigest
• WeeklyDigest
• Never
In Communities, the Email on EachPost option is disabled once a groupexceeds 10,000 members. All memberswho had this option selected areautomatically switched to Daily Digest.
Group Information InputJSON
{"text" : "Post questions about the API.","title" : "API Questions"
}
291
Group Chatter Settings InputChatter REST API Request Bodies
Properties
AvailableVersion
DescriptionTypeName
28.0The text in the “Information” section ofthe group. HTML is not supported. The
Stringtext
maximum length is 4000 characters(bytes).
28.0The title in the “Information” section ofthe group. The maximum length is 240characters (bytes).
Stringtitle
Group InputRoot XML Tag
<group>
JSON
{"canHaveChatterGuests" : "true","description" : "This group is building a powerful API.","information" : {
"text" : "Read this section before you post to the group.","title" : "Information"
},"isArchived" : "false","isAutoArchiveDisabled" : "false","name" : "Chatter API","owner" : "00590000000DmPw","visibility" : "PublicAccess"
}
Properties
AvailableVersion
DescriptionTypeName
29.0true if this group allows Chattercustomers, false otherwise. After this
BooleancanHaveChatterGuests
property is set to true, it cannot be setto false.
29.0The “Description” section of the groupStringdescription
28.0The “Information” section of the groupIf the group is private, the “Information”
Group Information Inputinformation
section is visible only to members. The“Description” section is visible toeveryone.
292
Group InputChatter REST API Request Bodies
AvailableVersion
DescriptionTypeName
29.0true if the group is archived, falseotherwise. Defaults to false.
BooleanisArchived
29.0true if automatic archiving is turnedoff for the group, false otherwise.Defaults to false.
BooleanisAutoArchiveDisabled
29.0The name of the groupStringname
29.0The ID of the group owner. Thisproperty is available for PATCHrequests only.
Stringowner
29.0The visibility of the group. One of thefollowing values:
Stringvisibility
• PublicAccess
• PrivateAccess
Group Member InputRoot XML tag
<member>
JSON example
{"role" : "GroupManager","userId" : "005B0000000Ge16"
}
Properties
Available VersionDescriptionTypeName
29.0The role of the member.One of these values:
Stringrole
• GroupManager
• StandardMember
23.0The user ID of the memberto be added to the group.
StringuserId
Group Membership Request UpdateRoot XML tag
<groupMembershipRequestUpdate>
293
Group Member InputChatter REST API Request Bodies
Properties
Available VersionDescriptionTypeName
27.0Use this property to provide a message to theuser if their membership request is declined.
StringresponseMessage
The value of this property is used only whenthe value of the status property isDeclined.
The maximum length is 756 characters.
27.0Valid values:Stringstatus
• Accepted
• Declined
Message Body Input
Available VersionDescriptionTypeName
23.0Collection of messagesegments, based on type.
Segments[]messageSegments
Segments can be one of thefollowing:• Message Segment Input:
Hash Tag• Message Segment Input:
Link• Message Segment Input:
Mention• Message Segment Input:
Text
Message Segment Input: Hash TagRepresents an inline hash tag. The use of this segment is optional because hash tags are also parsed out of Text segments.
Available VersionDescriptionTypeName
23.0
Multiple word hash tags areavailable in version 28.0.
Text of the hash tag withoutthe hash tag.
Stringtag
Note: Closingsquare brackets ( ] )are not supported inhash tag text. If thetext contains aclosing squarebracket ( ] ), the hash
294
Message Body InputChatter REST API Request Bodies
Available VersionDescriptionTypeName
tag ends at thebracket.
23.0Value is Hashtag.Stringtype
Message Segment Input: LinkRepresents an inline link to a URL. If a link is provided as input without whitespace text before it, a space is inserted. If a linkis provided as input without whitespace text after it, a space is inserted. The use of this segment is optional because links arealso parsed out of Text segments.
Available VersionDescriptionTypeName
23.0Value is Link.Stringtype
23.0URL to be used for the link.URLurl
Message Segment Input: MentionRepresents an inline mention of a user or group. You must provide a user or group ID. No spaces are added. When creatinga feed item or a comment, you can include up to 25 mentions.
Available VersionDescriptionTypeName
23.0
Groups are available in 29.0
ID of the user or group to bementioned.
Stringid
23.0Value is MentionStringtype
Message Segment Input: TextRepresents plain inline text. Text that looks like a link and is surrounded by space is converted into a link segment. Textprefixed with a hash and surrounded by square brackets ([]) is converted into a hash tag segment. Multiple word hash tags areavailable in version 28.0 and higher.
Available VersionDescriptionTypeName
23.0Plain text for this segment.Stringtext
23.0Only value is Text.Stringtype
295
Message Segment Input: LinkChatter REST API Request Bodies
Moderation Flag InputRoot XML tag
<moderationFlag>
JSON
{"visibility" : "ModeratorsOnly"
}
Properties
Available VersionDescriptionTypeName
30.0Specifies the visibility behavior of a flag for varioususer types.
Stringvisibility
• ModeratorsOnly—The flag is visible onlyto users with moderation permissions on theflagged item.
• SelfAndModerators—The flag is visibleto the creator of the flag and to users withmoderation permissions on the flagged item.
Photo InputDescribes a photo input.
Root XML tag<photo>
JSON example
{ "cropSize" : "120","cropX" : "0","cropY" : "0","fileId" : "069D00000001IOh"
}
Properties
AvailableVersion
Required or OptionalDescriptionTypeName
29.0Required to crop an uploadedfile or an existing file.
The length, in pixels, of any edgeof the crop square.
IntegercropSize
296
Moderation Flag InputChatter REST API Request Bodies
AvailableVersion
Required or OptionalDescriptionTypeName
29.0Required to crop an uploadedfile or an existing file.
The position X, in pixels, from theleft edge of the image to the startof the crop square. Top left isposition (0,0).
IntegercropX
29.0Required to crop an uploadedfile or an existing file.
The position Y, in pixels, from thetop edge of the image to the startof the crop square. Top left isposition (0,0).
IntegercropY
25.0Required to choose an existingfile.
18–character ID of an existing file.The key prefix must be 069 and thefile size must be less than 2 MB.
StringfileId
Note: Images uploadedon the Group page and onthe User page don’t havefile IDs and thereforecan’t be used.
25.0OptionalVersion number of an existing file.If not provided, the latest versionis used.
IntegerversionNumber
Share InputJSON example
{"id": "005D0000001Az4l","sharingType": "V"
}
Properties
Available VersionDescriptionTypeName
30.0User ID to share a file withStringid
30.0Either C for collaborator or V for viewerStringsharingType
Topic Assignment InputRepresents a topic to assign to a feed item or record. Administrators must enable topics for objects before users can add topicsto records of that object type.
Root XML tag<topicAssignment>
297
Share InputChatter REST API Request Bodies
JSONThe following example assigns a topic to a record:
{ "topicId": "0TOD0000000090r"}
Properties
AvailableVersion
Required or OptionalDescriptionTypeName
30.0Required for existing topics ifthe topicName property isn’tused.
ID of an existing topic.StringtopicId
30.0Required for new topics;required for existing topics if
Name of a new or existingtopic.
StringtopicName
the topicId property isn’tused.
Topic Endorsement InputEndorse a user who’s knowledgeable about a topic.
Root XML tag<topicEndorsement>
JSON
{"userId" : "005B0000000Ge16"
}
Properties
Available VersionRequired or OptionalDescriptionTypeName
30.0RequiredID of the user to beendorsed for thespecified topic.
StringuserId
Topic InputRoot XML tag
<topic>
JSON
{"description" : "World Wide Web Consortium (W3C) is the main international standards
298
Topic Endorsement InputChatter REST API Request Bodies
organization for the Web.""name" : "W3C"}
Properties
Available VersionDescriptionTypeName
28.0Text description of the topicStringdescription
28.0Name of the topic. Use thisproperty to change only the
Stringname
capitalization and spacing ofthe topic name.
User Chatter Settings InputA user’s global Chatter settings.
Root XML tag<userChatterSettings>
Properties
AvailableVersion
DescriptionTypeName
27.0The default frequency with which a userreceives email from a group when they join.Valid values are:
StringdefaultGroupEmailFrequency
• EachPost
• DailyDigest
• WeeklyDigest
• Never
In Communities, the Email on Each Postoption is disabled once a group exceeds10,000 members. All members who hadthis option selected are automaticallyswitched to Daily Digest.
User InputRoot XML tag
<user>
299
User Chatter Settings InputChatter REST API Request Bodies
Properties
Available VersionDescriptionTypeName
29.0The aboutMe property of aUser Detail response body.
StringaboutMe
The maximum length is1000 characters.
JSON example
{"aboutMe": "Staff Technical Writer responsible for the Connect API and Connect in
Apex documentation."}
User MessageRoot XML tag
<message>
Properties
Available VersionDescriptionTypeName
23.0Text of the message bodyStringbody
23.0ID of an existing messagethat identifies which
StringinReplyTo
conversation this message ispart of.You must specifyeither recipients orinReplyTo. You mustspecify one or the other, notboth.
23.0List of users who are theintended message recipients,
User Message Recipient ListInput
recipients
up to 9. Comma-separatedlist of user IDs.You mustspecify either recipientsor inReplyTo. You mustspecify one or the other, notboth.
Example XML format:
<message><body>Text of the message</body><recipients>
<recipient>userID</recipient><recipient>userID</recipient>
</recipients>
300
User MessageChatter REST API Request Bodies
<inReplyTo>messageID</inReplyTo></message>
Example JSON format:
{"body": "Text of the message","recipients": ["userID","userID"],"inReplyTo": "messageID"
}
User Message Recipient InputRoot XML tag
<recipient>
Properties
Available VersionDescriptionTypeName
23.018-character ID of the userwho receives the message.
Stringrecipient
User Message Recipient List InputRoot XML tag
<message>
Properties
Available VersionDescriptionTypeName
23.0Collection of recipients whoreceive the message.
User Message RecipientInput[]
recipients
User Status InputNote: Setting a user status is no longer available as of version 25.0. Post feed items to the feed instead, using FeedItem Input.
Root XML tag<userStatus>
Properties
Available VersionDescriptionTypeName
23.0–24.0Description of message body.Message Body Inputbody
301
User Message Recipient InputChatter REST API Request Bodies
User Stream (Conversation) InputRoot XML tag
<conversation>
Properties
Available VersionDescriptionTypeName
24.0Changes the conversationstatus to unread (false) orread (true).
Booleanread
302
User Stream (Conversation) InputChatter REST API Request Bodies
Chapter 6
Chatter REST API Response Bodies
The successful execution of a request to a Chatter REST API resource can return a response body in either JSON or XMLformat.
A request to a Chatter REST API resource always returns an HTTP response code, whether the request was successful ornot.
Address
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Name of the cityStringcity
23.0Small, 29.0Name of the countryStringcountry
25.0Small, 29.0Address formatted by localeStringformattedAddress
23.0Small, 29.0Name of the state, province, or so onStringstate
23.0Small, 29.0Street numberStringstreet
23.0Small, 29.0Zip or postal codeStringzip
Batch Results
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
28.0Small, 29.0true if at least one of the results in the result setis an HTTP status code in the 400 or 500 range;false otherwise
BooleanhasErrors
23.0Small, 29.0Collection of batch result itemsBatch Result Item[]results
303
Batch Result Item
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
Small, 29.0Dependent on the type of batch. Value could beone of the following:
Variousresult
• For /connect/batch, the value can be anyresponse body depending on the sub-request inthe batch. (v28.0)
• Error Message (v23.0)
• File Summary for
/chatter/files/batch/fileIds
(v26.0)• Group Member for
/chatter/group-memberships/batch/membershipIds
(v27.0)• Group for
/chatter/groups/batch/groupIds
(v23.0)• Motif for
/connect/motifs/batch/idOrPrefixList
(v27.0)• User Detail for
/chatter/users/batch/userIds
(v23.0)
23.0Small, 29.0An HTTP status code indicating the status of thisindividual request in the batch
IntegerstatusCode
304
Batch Result ItemChatter REST API Response Bodies
Chatter Activity
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Total number of comments in the organization orcommunity made by the user
IntegercommentCount
23.0Small, 29.0Total number of comments in the organization orcommunity received by the user
IntegercommentReceivedCount
23.0Small, 29.0Total number of likes on posts and comments inthe organization or community received by the user
IntegerlikeReceivedCount
23.0Small, 29.0Total number of posts in the organization orcommunity made by the user
IntegerpostCount
Chatter Directory
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Small, 29.0Returns a URL to the general feeds resource for theorganization
Stringfeeds
24.0Small, 29.0Returns a URL to the general groups resource forthe organization
Stringgroups
24.0–26.0StringorganizationNote: This property is no longer availableas of version 26.0. Use the organizationproperty in the Connect Directory instead.
Returns a URL to the general connect organizationresource
24.0Small, 29.0Returns a URL to the general users resource for theorganization
Stringusers
Chatter Influence
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Small, 29.0Percentile value for the user’s influence rank withinthe organization or community
Stringpercentile
305
Chatter ActivityChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Small, 29.0Number indicating the user’s influence rank, relativeto all other users within the organization orcommunity
Integerrank
ClientInfo
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Name of the Connected App used forauthentication. For more information, seeUnderstanding Connected Apps.
StringapplicationName
23.0Small, 29.0Value from the Info URL field of the ConnectedApp used for authentication
StringapplicationUrl
Comment
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Medium, 29.0If the comment does not contain an attachment orif the attachment, returns null. Otherwise, returnsFeed Item Attachment: Content.
Depends on type ofcomment
attachment
23.0Small, 29.0Message body for the commentFeed Bodybody
23.0Medium, 29.0Information about the Connected App used toauthenticate the connection
ClientInfoclientInfo
23.0Small, 29.0ISO8601 date string, for example,2011-02-25T18:24:31.000Z
StringcreatedDate
23.0Medium, 29.0Information about the feed item for the commentReferencefeedItem
23.0Small, 29.018-character ID of the commentStringid
23.0–24.0BooleanisDeletableNote: This property is no longer availableas of version 25.0. Use theisDeleteRestricted property instead.
Specifies if the context user can delete the comment
25.0Medium, 29.0Returns true if a comment cannot be deleted bythe logged-in user. If it returns false, possibly thelogged-in user can delete the comment.
BooleanisDeleteRestricted
24.0Medium, 29.0Page of likes associated with the commentLike Pagelikes
306
ClientInfoChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
27.0Medium, 29.0A message body that describes who likes thecomment.
Like Message BodylikesMessage
23.0Medium, 29.0If the logged-in user has liked the comment, returnsa reference to that like or returns null
ReferencemyLike
23.0Big, 29.0Information about the parent of the feed-itemassociated with this comment
Referenceparent
28.0Medium, 29.0The created date formatted as a relative, localizedstring, for example, “17m ago” or “Yesterday.”
StringrelativeCreatedDate
24.0Small, 29.0Indicates the type of comment. Valid values are:Stringtype
• ContentComment—the comment contains anattachment
• TextComment—the comment contains onlytext
23.0Small, 29.0URL to this commentStringurl
23.0Small, 29.0Information about the comment authorUser Summaryuser
Comment Page
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Collection of commentsComment[]comments
23.0Medium, 29.0URL for the current page of comments, that is, themost recent comments. The default is 25 commentsper page.
StringcurrentPageUrl
23.0Small, 29.0URL to the next page of comments, that is, oldercomments. The default is 25 comments per page.
StringnextPageUrl
23.0Small, 29.0Total number of comments across all pages for theparent feed item
Integertotal
Community
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Small, 30.0Specifies whether members of the community canflag content
BooleanallowMembersToFlag
26.0Small, 29.0Community’s descriptionStringdescription
307
Comment PageChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
26.0Small, 29.018-character ID of the communityStringid
26.0Small, 29.0Specifies whether members of the community caninvite other members to the community, true ifthey can, false otherwise
BooleaninvitationsEnabled
30.0Small, 30.0Specifies whether knowledgeable people andendorsements are available for topics (true), or not(false).
BooleanknowledgeableEnabled
26.0Small, 29.0Community nameStringname
30.0Small, 30.0Specifies whether members of the community cansend and receive private messages to and from othermembers of the community, (true) or not (false).
BooleanprivateMessagesEnabled
26.0Small, 29.0Specifies whether a welcome email is automaticallygenerated and sent to any new member. true ifemail is sent, false otherwise
BooleansendWelcomeEmail
26.0Small, 29.0Specifies whether a welcome email is automaticallygenerated and sent to any new member. true ifemail is sent, false otherwise
BooleansendWelcomeEmail
30.0Small, 30.0Site URL for the community, which is the customdomain plus a URL prefix
StringsiteUrl
28.0Small, 29.0Community’s status. Values are:Stringstatus
• Live
• Inactive
• UnderConstruction
26.0Small, 29.0Community-specific URL prefixStringurlPathPrefix
26.0Small, 29.0Full URL to communityStringurl
Community Page
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
26.0Small, 29.0List of communities available to the current userCommunity[]communities
26.0Small, 29.0Total number of communitiesIntegertotal
308
Community PageChatter REST API Response Bodies
Connect Directory
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
26.0Small, 29.0List of communities in the current organizationCommunity[]communities
25.0Small, 29.0URL to the Chatter organizationStringorganization
Conversation Detail
AvailableVersion
Filter Group and VersionDescriptionTypeProperty
23.0Medium, 29.018-character ID of the conversationStringconversationId
23.0Small, 29.0URL to the conversation detail pageStringconversationUrl
23.0Small, 29.0Collection of users participating in thisconversation
UserSummary[]
members
23.0Small, 29.0Messages in this conversationMessageCollection
messages
23.0Small, 29.0Does the context user have unread messagesin this conversation?
Booleanread
Conversation Summary
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.018-character ID of the conversationStringid
23.0Small, 29.0The most recent message in this conversationMessagelatestMessage
23.0Small, 29.0Collection of users participating in the conversationUser Summary[]members
23.0Small, 29.0Does the context user have unread messages in thisconversation?
Booleanread
23.0Small, 29.0URL to the conversation detail pageStringurl
309
Connect DirectoryChatter REST API Response Bodies
Conversation Summary Collection
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Collection of zero or more conversationsConversationSummary[]
conversations
23.0Medium, 29.0URL to the first page of conversations, that is, theconversations with the most recent messages
StringcurrentPageUrl
23.0Small, 29.0URL to the next page of messages, that is, olderconversations
StringnextPageUrl
Conversation Unread Count
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0true if the actual number of unread conversationsis greater than 50, false otherwise
BooleanhasMore
23.0Small, 29.0Number of unread conversations, that is,conversations that have unread messages. Is an exact
IntegerunreadCount
value up to the maximum of 50, and is capped at50 if the value is greater.
Email AddressAn email address for an email message sent from a case record in Case Feed.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0Display name for an email addressStringdisplayName
29.0Small, 29.0Email addressStringemailAddress
Error Message
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0An error code with information about the error, forexample, INSUFFICIENT_PRIVILEDGES
StringerrorCode
23.0Small, 29.0Description of errorStringmessage
310
Conversation Summary CollectionChatter REST API Response Bodies
Error with Output
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
27.0Small, 29.0Description of the errorStringmessage
27.0Small, 29.0The response body described in the requestedresource. For example, if a successful request returns
Any response bodyoutput
a Like response body but an error triggers the Errorwith Output response body, the value of theoutput property is a Like response body.
Explanation Details
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Small, 29.0More information about the recommendation.What is returned depends on the type.
Variousdata
• UserFollowsSameUsers–people that boththe user and recommended person are following.See User Summary.
• GroupMembersFollowed–people that the useris following and that are members of therecommended group. See User Summary.
• UserViewingSameRecords—records thatthe user and the recommended person haverecently viewed. See Record Summary.
• RecordParentOfFollowed—records thatthe user is following and that are child recordsof the recommended record. See RecordSummary.
24.0Small, 29.0Explanation of recommendationStringsummary
24.0Small, 29.0Type of recommendation explanation. Values are:Stringtype
• UserFollowsSameUsers
• GroupMembersFollowed
• UserViewingSameRecords
• RecordParentOfFollowed
311
Error with OutputChatter REST API Response Bodies
Explanation Summary
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Small, 29.0URL for explanation details. If the recommendationdoesn’t have a detailed explanation, the string “null”.
StringdetailsUrl
23.0Small, 29.0Explanation of recommendationStringsummary
24.0Small, 29.0Type of recommendation explanation, such asUserFollowsSameUsers
Stringtype
Favorite
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
26.0Medium, 29.0Information about the community. Returns nullif favorite exists in default community orcommunities aren’t enabled.
Referencecommunity
24.0Medium, 29.0Information about the original creator of thefavorite
User SummarycreatedBy
24.0Small, 29.0URL to the feed item for this favoriteStringfeedUrl
24.0Small, 29.018-character ID of the favoriteStringid
24.0Medium, 29.0ISO8601 date string, for example,2011-02-25T18:24:31.000Z
StringlastViewDate
24.0Small, 29.0Name of the favoriteStringname
24.0Medium, 29.0If the favorite is from a search, contains the searchtext, if not, contains null.
StringsearchText
28.0Small, 29.0A reference to the topic if applicable, nullotherwise
Referencetarget
24.0Small, 29.0One of the following values:Stringtype
• ListView
• Search
• Topic
24.0Small, 29.0URL to this favoriteStringurl
24.0Medium, 29.0Information about the user who saved this favoriteUser Summaryuser
312
Explanation SummaryChatter REST API Response Bodies
Favorites Page
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Small, 29.0Collection of one or more favoritesFavorite[]favorites
24.0Small, 29.0Total number of favoritesIntegertotal
FeaturesFeatures that are available to the logged-in user. If a feature is disabled, the resources associated with that feature are unavailableand some feature-related properties on objects are set to null.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
27.0Small, 29.0Specifies whether Chatter is enabled for anorganization or not
Booleanchatter
24.0Small, 29.0Specifies whether the user details includeinformation about Chatter activity
BooleanchatterActivity
29.0Small, 29.0Specifies whether Chatter Answers is enabledBooleanchatterAnswers
24.0Small, 29.0Specifies whether the user details include globalChatter activity
BooleanchatterGlobalInfluence
24.0Small, 29.0Specifies whether Chatter messages are enabled forthe organization
BooleanchatterMessages
28.0Small, 29.0Specifies whether Chatter topics are enabledBooleanchatterTopics
29.0Small, 29.0Specifies whether Community moderation isenabled for this organization
BooleancommunityModeration
29.0Small, 29.0Reserved for future useBooleanconnectRecords
24.0Small, 29.0Specifies whether the user can post dashboardcomponent snapshots
BooleandashboardComponentSnapshots
28.0Small, 29.0The ISO code of the default currency. Applicableonly when multiCurrency is false.
StringdefaultCurrencyIsoCode
24.0Small, 29.0Specifies whether the is-modified resource isenabled for the Chatter REST API
BooleanfeedPolling
24.0Small, 29.0Specifies whether files can act as resources forChatter REST API
Booleanfiles
24.0Small, 29.0Specifies whether files can be attached to commentsBooleanfilesOnComments
28.0–29.0Small, 29.0Reserved for future useBooleangroupsCanFollow
313
Favorites PageChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0Specifies whether Ideas is enabledBooleanideas
29.0Small, 29.0Reserved for future useBooleanmobileNotificationsEnabled
28.0Small, 29.0Indicates whether the user’s organization usesmultiple currencies (true) or not (false). When
BooleanmultiCurrency
false, the defaultCurrencyIsoCode indicatesthe ISO code of the default currency.
28.0Small, 29.0Indicates whether publisher actions are enabledBooleanpublisherActions
24.0Small, 29.0Specifies whether trending topics are enabledBooleantrendingTopics
24.0Small, 29.0Specifies whether existing Chatter users can invitepeople in their company to use Chatter
BooleanviralInvitesAllowed
Feed
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0URL of feed itemsStringfeedItemsUrl
23.0Small, 29.0A News Feed Is-Modified resource with a sincerequest parameter that contains an opaque token
StringisModifiedUrl
that describes when the feed was last modified.Returns null if feed is not a news feed.
Feed Body
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Medium, 29.0Collection of message segments, based on type.Segments can be one or more of the following:
Segment[]messageSegments
• Message Segment: Entity Link
• Message Segment: Field Change
• Message Segment: Field Change Name
• Message Segment: Field Change Value
• Message Segment: Hashtag
• Message Segment: Link
• Message Segment: Mention
• Message Segment: More Changes
• Message Segment: Text
314
FeedChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Display–ready text of the message. Use this text ifyou don’t want to process the message segments.
In API versions 29.0 and later, the text propertyof the Feed Body response body can be null, which
Stringtext
means you can’t use it as the default case forrendering text. Instead, use the text property ofthe Feed Item Preamble Message Body responsebody because it can’t be null.
Feed Directory
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Small, 29.0Collection of favorites that the logged-in user hassaved.
Favorite[]favorites
23.0Small, 29.0Collection of feed directory items that the logged-inuser is allowed to view
Feed DirectoryItem[]
feeds
Feed Directory ItemThe definition of a feed.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0URL to the resource of the feed items for a specificfeed. For example:/services/data/v30.0/chatter/feeds/files/me/feed-items
StringfeedItemsUrl
30.0Big, 30.0The feed type. One of these values:StringfeedType
• Bookmarks—Contains all feed items saved asbookmarks by the logged-in user.
• Company—Contains all feed items except feeditems of type TrackedChange. To see the feeditem, the user must have sharing access to itsparent.
• Files—Contains all feed items that containfiles posted by people or groups that thelogged-in user follows.
315
Feed DirectoryChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
• Filter—Contains the news feed filtered tocontain feed items whose parent is a specifiedobject type.
• Groups—Contains all feed items from allgroups the logged-in user either owns or is amember of.
• Moderation—Contains all feed items thathave been flagged for moderation. TheCommunities Moderation feed is available onlyto users with “Moderate Community Feeds”permissions.
• News—Contains all updates for people thelogged-in user follows, groups the user is amember of, files and records the user isfollowing, all updates for records whose parentis the logged-in user, and every feed item andcomment that mentions the logged-in user orthat mentions a group the logged-in user is amember of.
• People—Contains all feed items posted by allpeople the logged-in user follows.
• Record—Contains all feed items whose parentis a specified record, which could be a group,user, object, file, or any other standard or customobject. When the record is a group, the feed alsocontains feed items that mention the group.
• To—Contains all feed items with mentions ofthe logged-in user, feed items the logged-in usercommented on, and feed items created by thelogged-in user that are commented on.
• Topics—Contains all feed items that includethe specified topic.
• UserProfile—Contains feed items createdwhen a user changes records that can be trackedin a feed, feed items whose parent is the user,and feed items that @mention the user. Thisfeed is different than the news feed, whichreturns more feed items, including groupupdates.
23.0Small, 29.0URL to the resource of a specific feed. For example:/services/data/v30.0/chatter/feeds/files/me
StringfeedUrl
30.0Big, 30.0For filter feeds, this value is the key prefix associatedwith the entity type used to filter this feed. All feed
StringkeyPrefix
items in this feed have a parent whose entity type
316
Feed Directory ItemChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
matches this key prefix value. For non-filter feeds,this value is null.
A key prefix is the first three characters of a recordID, which specifies the entity type.
23.0Small, 29.0Name of the feed, such as, Groups, People,Company, and so on
Stringlabel
Feed ItemThe type property always returns all types, regardless of version. However, not all types are valid with all versions. Use theattachment property to verify the type of feed item. For example, for a type of PollPost, if the version is earlier than26.0, attachment is null. Use the text property to properly render any unknown feed item types.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
Small, 29.0The entity that created the feed item. Values are:Depends on parentactor
• Record Summary—if a record (V23.0)
• User Summary—if a user (V23.0)
Note: If the actor is a user, a UserSummary response body is returned, nota Record Summary of type user.
Medium, 29.0Depends on the type value of the attachment.Values include:
Depends on typeattachment
• BasicTemplate—Feed Item Attachment:Basic Template (v27.0)
• Canvas—Feed Item Attachment: CanvasTemplate (v29.0)
• Content—Feed Item Attachment: Content ornull if the content is unavailable (v23.0)
• Link—Feed Item Attachment: Link (v23.0)
• Poll—Feed Item Attachment: Poll (v26.0)
• RecordSnapshot—Feed Item Attachment:Record Snapshot (v29.0)
• TrackedChange—Feed Item Attachment:Tracked Change (v29.0)
23.0Small, 29.0Information about the feed item.
In API versions 29.0 and later, the text propertyof the Feed Body response body can be null, which
Feed Bodybody
means you can’t use it as the default case forrendering text. Instead, use the text property of
317
Feed ItemChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
the Feed Item Preamble Message Body responsebody because it can’t be null.
27.0Medium, 29.0true if feed item can be shared, false otherwiseBooleancanShare
23.0Medium, 29.0Information about the Connected App used toauthenticate the connection
ClientInfoclientInfo
23.0Small, 29.0Comments for this feed itemComment Pagecomments
23.0Small, 29.0ISO8601 date string, for example,2011-02-25T18:24:31.000Z
StringcreatedDate
23.0–24.0ReferencecurrentUserLikeNote: This property is no longer availableas of version 24.0. Use the myLikeproperty instead.
A reference to a like object if applicable, nullotherwise.
23.0Medium, 29.0true if feed item created due to an event change,false otherwise
Booleanevent
23.0Small, 29.018-character ID of the feed itemStringid
24.0Medium, 29.0true if the current user has bookmarked this feeditem, false otherwise
BooleanisBookmarkedByCurrentUser
25.0Medium, 29.0Returns true if a feed item cannot be deleted bythe logged in user. If it returns false, possibly thelogged in users can delete the feed item.
BooleanisDeleteRestricted
23.0Medium, 29.0true if the current user has liked this feed item,false otherwise
BooleanisLikedByCurrentUser
23.0Medium, 29.0Likes for this feed itemLike Pagelikes
27.0Small, 29.0A message body that describes who likes the feeditem
Like Message BodylikesMessage
23.0Medium, 29.0If the logged-in user has liked the comment, thisproperty is a reference to the specific like, nullotherwise
ReferencemyLike
23.0Small, 29.0ISO8601 date string, for example,2011-02-25T18:24:31.000Z
StringmodifiedDate
29.0Big, 29.0Flags for this feed item. Community moderatorscan view and take action on flagged items.
If the communityModeration property of theFeatures response body is false, this property isnull.
Moderation FlagsmoderationFlags
24.0Small, 29.0A reference to the original feed item if this feeditem is a shared feed item, null otherwise
ReferenceoriginalFeedItem
318
Feed ItemChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Medium, 29.0Value depends on type of original feed item. Valuesare:
Depends on typeoriginalFeedItemActor
• Record Summary–if original feed item is arecord
• User Summary–if original feed item is a user
• null if this feed item is not a shared feed item
23.0Medium, 29.0Value depends on type of parent. Values are:Depends on typeparent
• File Summary–if parent is a file
• Group–if parent is a group
• Record Summary–if parent is a record
• User Summary–if parent is a user
Note: If the parent is a user, a UserSummary response body is returned, nota Record Summary of type user. The sameapplies for both groups and files.
23.0Medium, 29.0URL of the photo associated with the feed itemStringphotoUrl
27.0Medium, 29.0The preamble is the title of the post. This propertycontains renderable plain text for all the segments
Feed ItemPreamble MessageBody
preamble
of the message, for example, “App Builders - PamJones”.
In API versions 29.0 and later, the text propertyof the Feed Body response body can be null, whichmeans you can’t use it as the default case forrendering text. Instead, use the text property ofthe Feed Item Preamble Message Body responsebody because it can’t be null.
28.0Small, 29.0ISO8601 date string, for example,2011-02-25T18:24:31.000Z
StringrelativeCreatedDate
28.0Medium, 29.0Topics for this feed itemFeed Item Topicstopics
23.0Small, 29.0Values are:Stringtype
• ActivityEvent—Feed item generated inCase Feed when an event or task associated witha parent record with a feed enabled is createdor updated.
• ApprovalPost—Feed item with an approvalaction attachment. Approvers can act on thefeed item parent.
• AttachArticleEvent—Feed item generatedwhen an article is attached to a case in CaseFeed.
319
Feed ItemChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
• BasicTemplateFeedItem—Feed item witha standard rendering containing an attachmentwith an image, link, and title.
• CanvasPost—Feed item generated by a canvasapp in the publisher or from Chatter REST APIor Chatter in Apex. The post itself is a link toa canvas app.
• CollaborationGroupCreated—Feed itemgenerated when a new group is created.Contains a link to the new group.
• CollaborationGroupUnarchived—Donot use. Feed item generated when an archivedgroup is activated.
• ContentPost—Feed item with a fileattachment.
• LinkPost—Feed item with a hyperlinkattachment
• PollPost—Feed item with an actionable pollattachment. Viewers of the feed item are allowedto vote on the options in the poll.
• ReplyPost—Feed item generated by a ChatterAnswers reply.
• RypplePost—Feed item generated when aThanks badge is created.
• TextPost—Feed item without an attachment.
• TrackedChange—Feed item created whenone or more fields on a record have beenchanged.
• SocialPost—Feed item generated when asocial post is created from a case in Case Feed.
• UserStatus—
Deprecated. A user's post to their own profile.
23.0Small, 29.0URL to this feed itemStringurl
26.0Small, 29.0Who can see this feed item. Values are:Stringvisibility
• InternalUsers—If Communities is enabled,only members of the default, internalcommunity can see the feed item.
• AllUsers—If Communities is enabled, allmembers of the community can see the feeditem.
320
Feed ItemChatter REST API Response Bodies
Feed Item Attachment: Basic Template
AvailableVersion
Filter Typeand Version
DescriptionTypeProperty
27.0Small, 29.0An optional description with a 500 character limitStringdescription
27.0Small, 29.0An optional iconIconicon
28.0Small, 29.0If linkURL refers to a Database.com record,linkRecordId contains the ID of the record.
StringlinkRecordId
27.0Small, 29.0An optional link URL to a detail page if availablecontent can’t display inline
StringlinkUrl
27.0 only
This propertyis deprecated
Big, 29.0The subtype associated with the basic template feeditem. Value is:
Stringsubtype
• CollaborationGroupCreated
in 28.0 andalways returnsNone forclients witholder versions.
27.0Small, 29.0An optional title to a detail pageStringtitle
27.0Small, 29.0BasicTemplateStringtype
Feed Item Attachment: Canvas Template
AvailableVersion
Filter Typeand Version
DescriptionTypeProperty
29.0Small, 29.0Optional. Description of the canvas app. Themaximum length of this field is 500 characters.
Stringdescription
29.0Small, 29.0The developer name (API name) of the canvas appStringdeveloperName
29.0Small, 29.0Optional. The height of the canvas app in pixels.Default height is 200 pixels.
Stringheight
29.0Small, 29.0The canvas app iconIconicon
29.0Small, 29.0Optional. The namespace prefix of the DeveloperEdition organization in which the canvas app wascreated.
StringnamespacePrefix
29.0Small, 29.0Optional. Parameters passed to the canvas app inJSON format. Example:{'isUpdated'='true'}
Stringparameters
321
Feed Item Attachment: Basic TemplateChatter REST API Response Bodies
AvailableVersion
Filter Typeand Version
DescriptionTypeProperty
29.0Small, 29.0Optional. The URL to a thumbnail image for thecanvas app. Maximum dimensions are 120x120pixels.
StringthumbnailUrl
29.0Small, 29.0The title of the link used to call the canvas appStringtitle
29.0Small, 29.0CanvasStringtype
Feed Item Attachment: ContentDescription of a feed item content attachment.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
26.0Small, 29.0MD5 checksum for the fileStringcheckSum
23.0Small, 29.0Description of the attachmentStringdescription
23.0Small, 29.0URL to the contentStringdownloadUrl
26.0Small, 29.0Extension of the fileStringfileExtension
23.0Small, 29.0Size of the file in bytes. If size cannot bedetermined, returns unknown.
StringfileSize
23.0Small, 29.0Type of fileStringfileType
23.0–29.0Small, 29.0true if the file has a preview image available,false otherwise
BooleanhasImagePreview
23.0Small, 29.0true if the file has a PDF preview available, falseotherwise
BooleanhasPdfPreview
23.0Small, 29.018-character ID of the contentStringid
26.0Small, 29.0true if the file is included in the user’s SalesforceFiles folder, and is synced between that folder andChatter; false otherwise.
BooleanisInMyFileSync
23.0Small, 29.0MIME type content of the fileStringmimeType
26.0Small, 29.0URL to the rendition resource for the file.Renditions are processed asynchronously and might
StringrenditionUrl
not be available immediately after the file has beenuploaded.
30.0Small, 30.0URL to the 240 x 180 rendition resource for thefile. Renditions are processed asynchronously and
StringrenditionUrl240By180
might not be available immediately after the file hasbeen uploaded.
30.0Small, 30.0URL to the 720 x 480 rendition resource for thefile. Renditions are processed asynchronously and
StringrenditionUrl720By480
322
Feed Item Attachment: ContentChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
might not be available immediately after the file hasbeen uploaded.
30.0Big, 30.0Text preview of the file if available, null otherwise.StringtextPreview
30.0Medium, 30.0Specifies the rendering status of the 120 x 90preview image of the file. One of these values:
Stringthumb120By90RenditionStatus
• Processing—Image is being rendered.
• Failed—Rendering process failed.
• Success—Rendering process was successful.
• Na—Rendering is not available for this image.
30.0Medium, 30.0Specifies the rendering status of the 240 x 180preview image of the file. One of these values:
Stringthumb240By180RenditionStatus
• Processing—Image is being rendered.
• Failed—Rendering process failed.
• Success—Rendering process was successful.
• Na—Rendering is not available for this image.
30.0Medium, 30.0Specifies the rendering status of the 720 x 480preview image of the file. One of these values:
Stringthumb720By480RenditionStatus
• Processing—Image is being rendered.
• Failed—Rendering process failed.
• Success—Rendering process was successful.
• Na—Rendering is not available for this image.
23.0Small, 29.0Title of the fileStringtitle
27.0Small, 29.0ContentStringtype
23.0Medium, 29.0Version Id of the fileStringversionId
Feed Item Attachment: Link
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Description of the linkStringtitle
27.0Small, 29.0LinkStringtype
23.0Small, 29.0URL attached to the feed item (could be external)Stringurl
323
Feed Item Attachment: LinkChatter REST API Response Bodies
Feed Item Attachment: Poll
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
26.0Small, 29.0Collection of feed poll choices that make up thepoll
Feed Poll Choice[]choices
26.0Small, 29.018-character ID of the poll choice that the currentuser has voted for in this poll. Returns null if thecurrent user hasn’t voted.
StringmyChoiceId
26.0Small, 29.0Total number of votes cast on the feed poll itemIntegertotalVoteCount
27.0Small, 29.0PollStringtype
Feed Item Attachment: Record Snapshot
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0A representation of a record.Record ViewrecordView
29.0Small, 29.0RecordSnapshotStringtype
Feed Item Attachment: Tracked Change
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0Collection of feed tracked changes.Feed TrackedChange[]
changes
29.0Small, 29.0TrackedChangeStringtype
Feed Item Page
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Medium, 29.0URL to the current page of feed itemsStringcurrentPageUrl
27.0Medium, 29.0An opaque polling token that describes when a newsfeed was last modified. Use this value as the since
StringisModifiedToken
request parameter of the News Feed Is-Modifiedresource.
324
Feed Item Attachment: PollChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Medium, 29.0A News Feed Is-Modified resource with a sincerequest parameter that contains an opaque token
StringisModifiedUrl
that describes when the feed was last modified.Returns null if feed is not a news feed.
23.0Small, 29.0Collection of one or more feed itemsFeed Item[]items
23.0Small, 29.0URL to the next page of feed itemsStringnextPageUrl
30.0Big, 30.0Token to use in an updatedSince parameter, ornull if not available.
StringupdatesToken
30.0Big, 30.0A Chatter REST API resource with a query stringcontaining the value of the updatesToken
StringupdatesUrl
property. The resource returns the feed items thathave been updated since the last request. Propertyis null if not available.
Feed Item Preamble Message Body
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
27.0Medium, 29.0Collection of message segments, based on type.Segments can be one or more of the following:
Segments[]messageSegments
• Message Segment: Entity Link
• Message Segment: Text
27.0Small, 29.0The preamble is the title of the post. This propertycontains renderable plain text for all the segments
Stringtext
of the message, for example, “App Builders - PamJones”.
In API versions 29.0 and later, the text propertyof the Feed Body response body can be null, whichmeans you can’t use it as the default case forrendering text. Instead, use the text property ofthe Feed Item Preamble Message Body responsebody because it can’t be null.
325
Feed Item Preamble Message BodyChatter REST API Response Bodies
Feed Item Topics
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
28.0Small, 29.0true if a topic can be assigned to the feed item,false otherwise
BooleancanAssignTopics
28.0Small, 29.0Collection of topicsTopic[]topics
Feed Modified Info
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0true if a news feed and has been modified sincethe last time it was polled, false otherwise.Returns null if the feed is not a news feed.
BooleanisModified
27.0Small, 29.0An opaque polling token that describes when a newsfeed was last modified. Use this value as the since
StringisModifiedToken
request parameter of the News Feed Is-Modifiedresource.
23.0Small, 29.0A News Feed Is-Modified resource with a sincerequest parameter that contains an opaque token
StringnextPollUrl
that describes when the feed was last modified.Returns null if feed is not a news feed. Make arequest to this resource after making a request tothe isModifiedUrl resource in the Feed or FeedItem Page response bodies.
Feed Poll Choice
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
26.0Small, 29.018-character ID of the poll choiceStringid
26.0Small, 29.0The location in the poll where this poll choiceexists. The first poll choice starts at 1.
Integerposition
26.0Small, 29.0Label text associated with the poll choiceStringtext
26.0Small, 29.0Total number of votes for this poll choiceIntegervoteCount
26.0Small, 29.0The ratio of total number of votes for this pollchoice to all votes cast in the poll. Multiply the ratio
DoublevoteCountRatio
326
Feed Item TopicsChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
by 100 to get the percentage of votes cast for thispoll choice.
Feed Tracked Change
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0The name of the field that was updated.StringfieldName
29.0Small, 29.0The new value of the field or null if the fieldlength is long or empty.
StringnewValue
29.0Small, 29.0The old value of the field or null if the field lengthis long or empty.
StringoldValue
File DetailIncludes all of the File Summary response body with the additional item:
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Medium, 29.0Number of pages for documents that support flashrenditions, or the number of slides in a presentation.
IntegerpageCount
Returns 0 if the flash rendition fails, or if it isn’tsupported for the file type.
File Share LinkDescription of a file shared as a link.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Small, 30.0URL where the file can be viewed and downloaded.This value is also called the file share link.
StringfileViewUrl
30.0Small, 30.0The permission level of sharing. Values are:StringsharingType
• C—Collaborator
• I—Sharing permission is determined bylocation. This generally occurs when the sharingpermission is not set on the file, but on thelibrary. This value is also used when thelogged-in user is the owner of the file.
327
Feed Tracked ChangeChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
• N—No access
• V—Viewer
File Shares Page
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Medium, 29.0URL for the current page of file sharesStringcurrentPageUrl
30.0Small, 30.0URL of the file share linkFile Share LinklinkShare
24.0Small, 29.0Collection of one or more file sharesShares[]shares
24.0Small, 29.0URL for the next page of file sharesStringnextPageUrl
24.0Medium, 29.0URL for the previous page of file sharesStringpreviousPageUrl
File SummaryDescription of a file.
For all rendition properties, note the following: Renditions are processed asynchronously and might not be available immediatelyafter the file has been uploaded.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
26.0Big, 29.0MD5 checksum for the fileStringcheckSum
24.0Small, 29.0Size of the file in bytesIntegercontentSize
24.0Small, 29.0If the file is a link, returns the URL, otherwise thestring “null”
StringcontentUrl
24.0Medium, 29.0Description of the fileStringdescription
26.0Small, 29.0URL to the fileStringdownloadUrl
24.0Big, 29.0Specifies if a flash preview version of the file hasbeen rendered
StringflashRenditionStatus
26.0Small, 29.0Extension of the fileStringfileExtension
24.0Medium, 29.0Type of file, such as PDF, PowerPoint, and so onStringfileType
24.0Small, 29.018-character ID of the fileStringid
26.0Medium, 29.0true if the file is included in the user’s SalesforceFiles folder, and is synced between that folder andChatter; false otherwise.
BooleanisInMyFileSync
328
File Shares PageChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
26.0Medium, 29.0MIME type of the fileStringmimeType
30.0Big, 30.0Flags for this file. Community moderators can viewand take action on flagged items.
If the communityModeration property of theFeatures response body is false, this property isnull.
Moderation FlagsmoderationFlags
24.0Small, 29.0ISO8601 date string, for example,2011-02-25T18:24:31.000Z
StringmodifiedDate
27.0Small, 29.0Small, medium, and large icons indicating that theobject is a file. The motif can also contain theobject’s base color.
The icon is not a preview of the file.
Motifmotif
23.0Medium, 29.0If the logged in user is following this file, thiscontains information about the subscription,otherwise returns null
ReferencemySubscription
24.0Small, 29.0Name of the fileStringname
24.0Big, 29.0Specifies the file source. Valid values are:Stringorigin
• Chatter—file came from Chatter
• Content—file came from content
• FileField—file came from a record or otherform
24.0Small, 29.0Owner of the fileUser Summaryowner
28.0Small, 29.0A reference to the parent folder.ReferenceparentFolder
24.0Big, 29.0Specifies if a PDF preview version of the file hasbeen rendered
StringpdfRenditionStatus
29.0Small, 29.0The publish status of the file. One of these values:StringpublishStatus
• PendingAccess—File is pending publishing.
• PrivateAccess—File is private.
• PublicAccess—File is public.
30.0Small, 30.0The URL of the Chatter REST API record viewresource for this record, or null if this record does
StringrecordViewUrl
not have a record view layout, or if “ConnectRecords API” is not enabled for this organization,or if the record type isn’t supported.
26.0Medium, 29.0URL to the rendition resource for the file.Renditions are processed asynchronously and might
StringrenditionUrl
not be available immediately after the file has beenuploaded.
329
File SummaryChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Medium, 29.0URL to the 240px by 180px rendition for the file,if available. Renditions are processed asynchronously
StringrenditionUrl240By180
and might not be available immediately after thefile has been uploaded.
29.0Medium, 29.0URL to the 720px by 480px rendition for the file,if available. Renditions are processed asynchronously
StringrenditionUrl720By480
and might not be available immediately after thefile has been uploaded.
29.0Medium, 29.0The sharing role of the file. One of these values:StringsharingRole
• Admin—Owner permission, but doesn’t ownthe file.
• Collaborator—Viewer permission, and canedit, change permissions, and upload a newversion of a file.
• Owner—Collaborator permission, and can makea file private, and delete a file.
• Viewer—Can view, download, and share a file.
• WorkspaceManaged—Permission controlledby the library.
30.0Big, 30.0Text preview of the file if available, null otherwise.StringtextPreview
24.0Small, 29.0Specifies the rendering status of the 120 x 90preview image of the file. One of these values:
Stringthumb120By90RenditionStatus
• Processing—Image is being rendered.
• Failed—Rendering process failed.
• Success—Rendering process was successful.
• Na—Rendering is not available for this image.
24.0Small, 29.0Specifies the rendering status of the 240 x 180preview image of the file. One of these values:
Stringthumb240By180RenditionStatus
• Processing—Image is being rendered.
• Failed—Rendering process failed.
• Success—Rendering process was successful.
• Na—Rendering is not available for this image.
24.0Small, 29.0Specifies the rendering status of the 720 x 480preview image of the file. One of these values:
Stringthumb720By480RenditionStatus
• Processing—Image is being rendered.
• Failed—Rendering process failed.
• Success—Rendering process was successful.
• Na—Rendering is not available for this image.
24.0Small, 29.0Title of the fileStringtitle
24.0Small, 29.0ContentDocumentStringtype
330
File SummaryChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Small, 29.0URL for the fileStringurl
24.0Medium, 29.0Version number of the fileStringversionNumber
File Summary Page
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Medium, 29.0URL for the current page of filesStringcurrentPageUrl
24.0Small, 29.0Collection of one or more filesFile Summary[]files
24.0Small, 29.0URL for the next page of filesStringnextPageUrl
24.0Medium, 29.0URL for the previous page of filesStringpreviousPageUrl
Flat Feed
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
25.0–26.0Medium, 29.0URL for the current page of itemsStringcurrentPageUrl
25.0–26.0Small, 29.0Collection of one or more flat feed itemsFlat Feed Item[]items
25.0–26.0Small, 29.0URL for the next page of itemsStringnextPageUrl
Flat Feed Item
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
25.0–26.0Small, 29.0The flat feed item, depending on the value of type.Valid values are:
Depends on typeitem
• If type is Comment—Comment
• If type is FeedItem—Feed Item
25.0–26.0Small, 29.0The type of item. Valid values are:Stringtype
• Comment
• FeedItem
331
File Summary PageChatter REST API Response Bodies
FolderDescription of a folder.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Small, 30.0An ISO-8601 formatted date string specifying thecreation date of the folder.
DatecreatedDate
30.0Small, 30.018-character ID of the folder.Stringid
30.0Small, 30.0An ISO-8601 formatted date string specifying thelast modified date of the folder.
DatemodifiedDate
30.0Small, 30.0A small, medium, and large icon indicating therecord’s type. The motif can also contain the recordtype’s base color.
Motifmotif
30.0Medium, 30.0If the logged-in user is following this record, thisproperty contains information about thesubscription; otherwise this property is null.
ReferencemySubscription
30.0Small, 30.0The folder name.Stringname
30.0Small, 30.0A reference to the parent folder.ReferenceparentFolder
30.0Small, 30.0The path to the folder.Stringpath
30.0Small, 30.0The URL of the Chatter REST API record viewresource for this record, or null if this record does
StringrecordViewUrl
not have a record view layout, or if “ConnectRecords API” is not enabled for this organization,or if the record type isn’t supported.
30.0Small, 30.0FolderStringtype
30.0Small, 30.0A Chatter REST API URL to this resource.Stringurl
Folder ItemDescription of an item (file or folder) in a folder.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Small, 30.0A file representationFile Summaryfile
30.0Small, 30.0A folder representationFolderfolder
30.0Small, 30.0The type of item. Valid values are:Stringtype
• File
• Folder
332
FolderChatter REST API Response Bodies
Folder Item PageA paged collection of Folder Item response bodies.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Medium, 30.0Chatter REST API URL identifying the currentpage.
StringcurrentPageUrl
30.0Small, 30.0A collection of folder items.Folder Item[]items
30.0Small, 30.0Chatter REST API URL identifying the next pageor null if there isn’t a next page.
StringnextPageUrl
30.0Medium, 30.0Chatter REST API URL identifying the previouspage or null if there isn’t a previous page.
StringpreviousPageUrl
Follower Page
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Medium, 29.0URL of the current pageStringcurrentPageUrl
23.0Small, 29.0Collection of one or more subscriptions of thosethat follow a record
Subscription[]followers
23.0–24.0ReferencemySubscriptionNote: This field is no longer available asof version 24.0.
If the logged-in user is following this user, thiscontains information about the subscription, elsereturns null
23.0Small, 29.0Chatter REST API URL identifying the next pageor null if there isn’t a next page.
StringnextPageUrl
23.0Medium, 29.0Chatter REST API URL identifying the previouspage or null if there isn’t a previous page.
StringpreviousPageUrl
23.0Small, 29.0Total number of followersIntegertotal
Following Counts
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Number of people the user is followingIntegerpeople
333
Folder Item PageChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Number of records the user is following
Topics are a type of record that can be followed asof version 29.0.
Integerrecords
23.0Small, 29.0Total number of items the user is followingIntegertotal
Following Page
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Medium, 29.0URL to the current pageStringcurrentPageUrl
23.0Small, 29.0Collection of one or more subscriptionsSubscription[]following
23.0Small, 29.0URL of the next pageStringnextPageUrl
23.0Medium, 29.0URL of the previous pageStringpreviousPageUrl
23.0Small, 29.0Total number of records being followedIntegertotal
Group
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Small, 30.0An additional label for the group, for example,“Archived,” “Private,” or “Private With Customers.”If there isn’t an additional label, the value is null.
StringadditionalLabel
23.0Small, 29.0true if this group allows Chatter customers, falseotherwise
BooleancanHaveChatterGuests
26.0Medium, 29.0Information about the community. Returns nullif group exists in the default community orcommunities aren’t enabled.
Referencecommunity
23.0Big, 29.0Text-only description of the groupStringdescription
30.0Medium, 30.0Group’s email address for posting to this group byemail.
Returns null if Chatter emails and posting toChatter by email aren’t both enabled in yourorganization.
StringemailToChatterAddress
29.0Big, 29.0Specifies whether the group is archived (true) ornot (false).
BooleanisArchived
334
Following PageChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Big, 29.0Specifies whether automatic archiving is disabledfor the group (true) or not (false).
BooleanisAutoArchiveDisabled
24.0–27.0
ThefileCount
Big, 29.0Number of files posted to this groupIntegerfileCount
property is inthe GroupDetailresponsebody.
23.0Small, 29.018-character ID of the groupStringid
24.0Big, 29.0Date of the most recent feed item posted to thegroup
StringlastFeedItemPostDate
23.0Small, 29.0Total number of group membersIntegermemberCount
27.0Small, 29.0Small, medium, and large icons indicating that theobject is a group. The motif can also contain therecord type’s base color.
The icon is not the group photo.
Motifmotif
23.0Small, 29.0Values are:StringmyRole
• GroupOwner
• GroupManager
• NotAMember
• NotAMemberPrivateRequested
• StandardMember
23.0Medium, 29.0If the logged-in user is a member of this group, thiscontains information about that subscription, orreturns null otherwise
ReferencemySubscription
23.0Small, 29.0Name of the groupStringname
24.0Medium, 29.0Information about the owner of the groupUser Summaryowner
23.0Small, 29.0Information about the group photoPhotophoto
30.0Small, 30.0The URL of the Chatter REST API record viewresource for this record, or null if this record does
StringrecordViewUrl
not have a record view layout, or if “ConnectRecords API” is not enabled for this organization,or if the record type isn’t supported.
23.0Small, 29.0CollaborationGroupStringtype
23.0Small, 29.0Relative URL string to the groupStringurl
335
GroupChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Values are:Stringvisibility
• PrivateAccess
• PublicAccess
Group Chatter SettingsA user’s Chatter settings for a specific group.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
27.0Small, 29.0The frequency with which a group member receivesemail from a group. One of the following values:
StringemailFrequency
• EachPost
• DailyDigest
• WeeklyDigest
• Never
• UseDefault
The value UseDefault uses the user’s defaultglobal setting defined in User Chatter Settings. InCommunities, the Email on Each Post option isdisabled once a group exceeds 10,000 members. Allmembers who had this option selected areautomatically switched to Daily Digest.
Group Detail
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Small, 30.0An additional label for the group, for example,“Archived,” “Private,” or “Private With Customers.”If there isn’t an additional label, the value is null.
StringadditionalLabel
23.0Small, 29.0true if this group allows Chatter customers, falseotherwise
BooleancanHaveChatterGuests
26.0Medium, 29.0Information about the community. Returns nullif group exists in the default community orcommunities aren’t enabled.
Referencecommunity
23.0Big, 29.0Text-only description of the groupStringdescription
336
Group Chatter SettingsChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Medium, 30.0Group’s email address for posting to this group byemail.
Returns null if Chatter emails and posting toChatter by email aren’t both enabled in yourorganization.
StringemailToChatterAddress
28.0Big, 29.0Number of files posted to this groupIntegerfileCount
23.0Small, 29.018-character ID of the groupStringid
28.0Big, 29.0The “Information” section of the group. If the groupis private, this section is visible only to members. If
Group Informationinformation
the logged-in user is not a member of the group ordoes not have “Modify All Data” or “View All Data”permission, the value is null.
24.0Big, 29.0Date of the most recent feed item posted to thegroup
StringlastFeedItemPostDate
23.0Small, 29.0Total number of group membersIntegermemberCount
27.0Small, 29.0Small, medium, and large icons indicating that theobject is a group. The motif can also contain therecord type’s base color.
The icon is not the group photo.
Motifmotif
23.0Small, 29.0Values are:StringmyRole
• GroupOwner
• GroupManager
• NotAMember
• NotAMemberPrivateRequested
• StandardMember
23.0Medium, 29.0If the logged-in user is a member of this group, thiscontains information about that subscription, orreturns null otherwise
ReferencemySubscription
23.0Small, 29.0Name of the groupStringname
24.0Medium, 29.0Information about the owner of the groupUser Summaryowner
29.0Medium, 29.0The number of pending requests to join a privategroup. For public groups, the value is null.
IntegerpendingRequests
23.0Small, 29.0Information about the group photoPhotophoto
30.0Small, 30.0The URL of the Chatter REST API record viewresource for this record, or null if this record does
StringrecordViewUrl
not have a record view layout, or if “ConnectRecords API” is not enabled for this organization,or if the record type isn’t supported.
337
Group DetailChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0CollaborationGroupStringtype
23.0Small, 29.0Relative URL string to the groupStringurl
23.0Small, 29.0Values are:Stringvisibility
• PrivateAccess
• PublicAccess
Group InformationDescribes the “Information” section of a group. Information about groups, such as the group's members, photo, and the groupsin the organization. Create and delete a group, add members to a group, and change the group photo.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
28.0Small, 29.0The text of the “Information” section of a groupStringtext
28.0Small, 29.0The title of the “Information” section of a groupStringtitle
Group Member
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.018-character ID of the group membershipStringid
23.0Small, 29.0Values are:Stringrole
• GroupOwner
• GroupManager
• NotAMember
• NotAMemberPrivateRequested
• StandardMember
23.0Small, 29.0URL to this membershipStringurl
23.0Small, 29.0Information about the user who is subscribed tothis group
User Summaryuser
338
Group InformationChatter REST API Response Bodies
Group Member Page
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Medium, 29.0URL to this page of membersStringcurrentPageUrl
23.0Small, 29.0Collection of group membersGroup Member[]members
23.0Medium, 29.0If the logged-in user is a member of this group,returns information about that membership, orreturns null otherwise
ReferencemyMembership
23.0Small, 29.0URL to the next page of membersStringnextPageUrl
23.0Medium, 29.0URL to the previous page of membersStringpreviousPageUrl
23.0Small, 29.0Total number of group membersIntegertotalMemberCount
Group Membership Request
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
27.0Big, 29.0An ISO formatted date string specifying the dateof the membership request
StringcreatedDate
27.0Small, 29.0ID for the group membership request objectStringid
27.0Small, 29.0An ISO formatted date string specifying the lasttime the request was updated
StringlastUpdateDate
27.0Big, 29.0Information about the group the user is requestingto join
ReferencerequestedGroup
27.0Big, 29.0A message to display to the user if their membershiprequest is declined. The value of this property is
StringresponseMessage
used only when the value of the status propertyis Declined.
The maximum length is 756 characters.
27.0Small, 29.0The status of the request to join a private group.Values are:
Stringstatus
• Accepted
• Declined
• Pending
27.0Small, 29.0URL to this group membership request objectStringurl
27.0Small, 29.0Information about the user requesting membershipin a group
User Summaryuser
339
Group Member PageChatter REST API Response Bodies
Group Membership Request Collection
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
27.0Small, 29.0Information about all requests to join a privategroup
GroupMembershipRequest
requests
27.0Small, 29.0The total number of requests to join a private groupIntegertotal
Group Page
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Medium, 29.0URL to this page of groupsStringcurrentPageUrl
23.0Small, 29.0Collection of group detailsGroup Detail[]groups
23.0Small, 29.0URL to the next page of groupsStringnextPageUrl
23.0Medium, 29.0URL to the previous page of groupsStringpreviousPageUrl
Icon
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
27.0Small, 29.0The height of the icon, in pixelsIntegerheight
27.0Small, 29.0The width of the icon, in pixelsIntegerwidth
27.0Small, 29.0The URL of the icon. This URL is available tounauthenticated users. The URL doesn’t expire.
Stringurl
Influence Thresholds
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Small, 29.0Description of this influencer category. For example:Active Influencer
Stringname
24.0Small, 29.0Number expressed as a raw percentile that definesthe bottom threshold for this influencer category.
Doublethreshold
For example: 0.25 defines the cutoff for the
340
Group Membership Request CollectionChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
Active Influencer category, which means itincludes users with an influence rank equal to orgreater than the 25th percentile (25%) and less thanthe next highest category threshold.
Knowledgeable PeopleRepresents a user that is knowledgeable about a specified topic.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Small, 30.0Specifies if the knowledgeable user is endorsed forthe topic by the context user, true if so, falseotherwise
BooleanisEndorsedByMe
30.0Small, 30.0ID of the knowledgeable recordStringknowledgeableId
30.0Medium, 30.0Number of endorsements received by theknowledgeable user for the topic
IntegernumEndorsements
30.0Medium, 30.0Specifies the reasons why the user is consideredknowledgeable about the topic. Valid values are:
Stringreasons
• Influential—User was mentioned in postsor in comments on posts with the topic orreceived likes on comments on posts with thetopic.
• Endorsed—User received endorsement fromanother user for the topic.
30.0Small, 30.0User that is knowledgeable about the topicUser Summaryuser
Knowledgeable People CollectionA collection of knowledgeable people response bodies.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Medium, 30.0Chatter REST API URL identifying the currentpage.
StringcurrentPageUrl
30.0Small, 30.0Collection of knowledgeable people response bodiesKnowledgeablePeople[]
knowledgeableUsers
30.0Small, 30.0Chatter REST API URL identifying the next pageor null if there isn’t a next page.
StringnextPageUrl
341
Knowledgeable PeopleChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Medium, 30.0Chatter REST API URL identifying the previouspage or null if there isn’t a previous page.
StringpreviousPageUrl
Like
AvailableVersion
Filter Groupor Version
DescriptionTypeProperty
23.0Small, 29.018-character ID of the like on either a comment ora feed item
Stringid
27.0Medium, 29.0A reference to the liked comment or feed itemReferencelikedItem
23.0Small, 29.0URL to this likeStringurl
23.0Small, 29.0Information about the user who liked this commentor feed item
User Summaryuser
Like Message Body
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
27.0Medium, 29.0Collection of message segments, based on type.Segments can be one or more of the following:
Segments[]messageSegments
• Message Segment: Entity Link
• Message Segment: Resource Link
• Message Segment: Text
27.0Small, 29.0Text summary of the users who like the feed itemor comment. For example, “You like this.” or
Stringtext
“Renee Moreau, Gordon Johnson, and Pam Joneslike this.”
Like Page
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Medium, 29.0URL to the current page of likesStringcurrentPageUrl
23.0Small, 29.0Collection of likesLike[]likes
342
LikeChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0–24.0ReferencemyLikeNote: This field is no longer available asof version 24.0.
Either returns a reference to the specific like orreturns null
23.0Small, 29.0URL to the next page of likesStringnextPageUrl
23.0Medium, 29.0URL to the previous page of likesStringpreviousPageUrl
23.0Small, 29.0Total number of likes for the itemIntegertotal
List View DefinitionDefines a related list structure or a search list structure on a record view. There is no data in the list.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Big, 29.0The columns of fields shown in this list view.List ViewColumn[]
columns
29.0Small, 29.0The localized label of this list view.Stringlabel
29.0Medium, 29.0The definition of the type of the objects in this listview.
List View ObjectobjectType
29.0Medium, 29.0The maximum number of objects per page in thislist view. To view all objects in this related list, page
IntegerrowLimit
through the data in pages no larger than this size.To build a SOQL statement from this describe, theSOQL statement must include a LIMIT value equalto this value or an error is thrown on execution.
29.0Medium, 29.0The columns in which to sort this list view. Thesort columns are given in the order of their priority
List View Sort[]sortColumns
(for example, primary sort, secondary sort, and soon).
List View ColumnDescribes a single column of a record’s related list. Describes how to lay out the column; doesn’t contain the column’s data.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Medium, 29.0The object type for this column’s field. This is theobject type used in REST API and SOAP API.
StringdataType
343
List View DefinitionChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Big, 29.0The fully qualified API field ID, for example,Contact.Name.
StringfieldId
29.0Small, 29.0The localized label of this column.Stringlabel
29.0Medium, 29.0The short name of the API field, for example,Name.
Stringname
List View ObjectDefines the type of record displayed in the rows of a related list.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Big, 29.0The API field ID that refers to the parent record.For example, if an Account record has a related list
StringfieldId
of Contact records, then in the Contact related listdefinition on the Account this value might be"Account".
29.0Small, 29.0The object type name for this object. This is theobject type used in REST API and SOAP API.
Stringtype
List View RecordThe list view of a record.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Medium, 30.0The fields and values for the record displayed inthis list. A collection of any of these:
fields
• Record Field
• Record Field: Blank
• Record Field: Compound
• Record Field: Currency
• Record Field: Date
• Record Field: Percent
• Record Field: Picklist
• Record Field: Reference
• Record Field: Reference with Date
23.0Small, 29.018-character ID of the objectStringid
344
List View ObjectChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
27.0Small, 29.0Small, medium, and large icons indicating the typeof the object. The motif can also contain the object’sbase color.
The icon is not a preview of the file.
Motifmotif
23.0Medium, 29.0If the logged-in user is following this file, thiscontains information about the subscription;otherwise returns null.
ReferencemySubscription
23.0Small, 29.0The localized name of this record.Stringname
30.0Small, 30.0The URL of the Chatter REST API record viewresource for this record, or null if this record does
StringrecordViewUrl
not have a record view layout, or if “ConnectRecords API” is not enabled for this organization,or if the record type isn’t supported.
23.0Small, 29.0A fixed type name for this object. Check this valueto determine the shape of a response body.
Stringtype
23.0Small, 29.0The Chatter REST API URL resource for thisobject.
Stringurl
List View SortDefines an ordinal of a sort order in a related list.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0The field ID on the related list column to sort.Stringcolumn
29.0Small, 29.0The order in which to sort the column. One of thesevalues:
Stringorder
• Ascending—Ascending order (A-Z).
• Descending—Descending order (Z-A).
Mention CompletionInformation about a record that could be used to @mention a user or group.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Big, 29.0An additional label (if one exists) for the recordrepresented by this completion, for example,“(Customer)” or “(Acme Corporation)”.
StringadditionalLabel
345
List View SortChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Medium, 29.0Description for the record represented by thiscompletion
Stringdescription
29.0Small, 29.0Name for the record represented by this completionStringname
29.0Medium, 29.0URL to the photo or icon for the record representedby this completion
StringphotoUrl
29.0Small, 29.018-character ID for the record represented by thiscompletion
StringrecordId
30.0Medium, 30.0If the record represented by this completion is auser, this value is the user type associated with thatuser; otherwise the value is null.
One of these values:
StringuserType
• ChatterGuest—User is a Chatter customerin an external group
• ChatterOnly—User is a Chatter Freecustomer
• Guest—Unauthenticated users
• Internal—User is a standard organizationmember
• Portal—User is a Customer Portal User, acommunities user, and so on.
• System—User is Chatter Expert or a systemuser
• Undefined—User is a user type that is acustom object.
Mention Completion PageA paginated list of Mention Completion response bodies.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Medium, 29.0URL of the current pageStringcurrentPageUrl
29.0Small, 29.0Collection of Mention Completion response bodiesto use in a mention.
MentionCompletion[]
mentionCompletions
29.0Small, 29.0Chatter REST API URL identifying the next pageor null if there isn’t a next page.
StringnextPageUrl
29.0Medium, 29.0Chatter REST API URL identifying the previouspage or null if there isn’t a previous page.
StringpreviousPageUrl
346
Mention Completion PageChatter REST API Response Bodies
Mention ValidationInformation about whether a proposed mention is valid for the context user.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0The ID of the mentioned record.StringrecordId
29.0Small, 29.0Specifies the type of validation error for a proposedmention, if any. One of these values:
StringvalidationStatus
• Disallowed—The proposed mention is invalidand will be rejected because the context user istrying to mention something that is not allowed.For example a user who is not a member of aprivate group is trying to mention the privategroup.
• Inaccessible—The proposed mention isallowed but the user or record being mentionedwill not be notified because they don't haveaccess to the parent record being discussed.
• Ok—There is no validation error for thisproposed mention.
Mention ValidationsInformation about whether a set of mentions is valid for the context user.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0Indicates whether at least one of the proposedmentions has an error (true), or not (false). For
BooleanhasErrors
example, the context user can’t mention privategroups he doesn’t belong to. If such a group wereincluded in the list of mention validations,hasErrors would be true and the group wouldhave a validationStatus of Disallowed inits mention validation.
29.0Medium, 29.0Information about whether a set of mentions is validfor the context user.
MentionValidation[]
mentionValidations
347
Mention ValidationChatter REST API Response Bodies
Message
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Text of this messageFeed Bodybody
23.0Big, 29.018-character ID of the conversation this messageis part of
StringconversationId
23.0Small, 29.0URL to the conversation this message is part ofStringconversationUrl
23.0Small, 29.018-character ID of the messageStringid
23.0Small, 29.0Collection of one or more message recipientsUser Summary[]recipients
Note: The collection of recipients is emptyfor the following resources because theconversation participants are alreadyidentified in the conversation’s membersproperty in Conversation Detail andConversation Summary.
• /chatter/users/me/conversations
• /chatter/users/me/conversations/conversationId
23.0Small, 29.0ISO8601 date string, for example,2011-02-25T18:24:31.000Z
StringsentDate
23.0Small, 29.0Information about the user who sent this messageUser Summarysender
23.0Small, 29.0URL to this messageStringurl
Message Collection
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Medium, 29.0Chatter REST API URL identifying the currentpage.
StringcurrentPageUrl
23.0Small, 29.0Collection of one or more messagesMessage[]messages
23.0Small, 29.0Chatter REST API URL identifying the next pageor null if there isn’t a next page.
StringnextPageUrl
348
MessageChatter REST API Response Bodies
Message Segment: Entity LinkRepresents an entity, such as a user or a group.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
27.0Small, 29.0A set of small, medium, and large icons thatcorrespond to the entity type. The motif can alsocontain the entity type’s base color.
Motifmotif
25.0Small, 29.0Information about the entityReferencereference
25.0Small, 29.0Plain text output for this segmentStringtext
25.0Small, 29.0EntityLinkStringtype
Message Segment: Field ChangeRepresents an inline field change.
An example of an inline field change is "First Name from Bob to Joe". This example segment consists of multiplesegments.
[Text("Owner from "),FieldChangeValue("Bob Smith"),Text(" to "),FieldChangeValue("Dave Jones")
]
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Medium, 29.0Collection of message segments, based on type.Segments can be one or more of the following:
Segments[]segments
• Message Segment: Entity Link
• Message Segment: Field Change
• Message Segment: Field Change Name
• Message Segment: Field Change Value
• Message Segment: Hashtag
• Message Segment: Link
• Message Segment: Mention
• Message Segment: More Changes
• Message Segment: Text
23.0Small, 29.0Formatted text of the change. For example:"City from San Francisco toNew Orleans"
Stringtext
23.0Small, 29.0Value is FieldChangeStringtype
349
Message Segment: Entity LinkChatter REST API Response Bodies
Message Segment: Field Change NameRepresents an inline name of a field change, like “Name” or “Description.” Making this a separate segment makes it possibleto give special user interface treatments to field names, for example, making a name field bold.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Formatted text of the change. Possible valuesinclude:
Stringtext
• Old name of the field
• New name of the field
23.0Small, 29.0Value is FieldChangeNameStringtype
Message Segment: Field Change ValueRepresents an inline value of a field change, like "1" or "Bob Smith.” Making this a separate segment makes it possible to addspecial coding, for example, to wrap values in anchor tags.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Big, 29.0The value type. One of these values:StringvalueType
• NewValue—The new value of the field change.
• OldValue—The old value of the field change.
23.0Small, 29.0Formatted text of the change. Possible valuesinclude:
Stringtext
• the words a blank value
Note: This text is also localized.
• the old value of the field
• the new value of the field
23.0Small, 29.0Value is FieldChangeValueStringtype
23.0Small, 29.0URL value if the field change is to a URL field(such as a web address)
Stringurl
Message Segment: HashtagRepresents an inline hashtag.
350
Message Segment: Field Change NameChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Text of the hashtag without the hash symbol (#)Stringtag
23.0Small, 29.0Text of the hashtag with the hash symbol (#)Stringtext
28.0Small, 29.0URL for the topic in this format:/services/data/.../topics?exactMatch=true&q=tag
StringtopicUrl
23.0Small, 29.0Value is HashtagStringtype
23.0Small, 29.0URL search for the tag in this format:services/data/.../feed-items?q=tag
Stringurl
Message Segment: LinkRepresents an inline link to a URL
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Formatted text of the feed item of this segmentStringtext
23.0Small, 29.0Value is LinkStringtype
23.0Small, 29.0URL value of the linkStringurl
Message Segment: MentionRepresents an inline @mention.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Specifies whether the mentioned user or group cansee the mention (true) or not (false).
Booleanaccessible
23.0Small, 29.0Name of the mentioned user or groupStringname
23.0Small, 29.0Formatted text of the feed item of this segmentStringtext
23.0Small, 29.0Value is MentionStringtype
29.0Small, 29.0Information about the mentioned user or group.One of these response bodies:
record
• Group
• User Detail
• User Summary
351
Message Segment: LinkChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0–28.0
In versionsbefore 29.0, if
Small, 29.0Information about the mentioned user, null if thelogged-in user doesn’t have access.
User Summaryuser
the mention isnot a user, themention is ina MessageSegment:Text responsebody.
Message Segment: More Changes
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Big, 29.0The complete collection of tracked changes for afeed item.
Message Segment:Field Change[]
moreChanges
23.0Small, 29.0Number of changesIntegermoreChangesCount
23.0Small, 29.0Formatted text of the number of changes. Forexample: "2 other changes"
Stringtext
Note: This value is localized.
23.0Small, 29.0Value is MoreChangesStringtype
Message Segment: Resource Link
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Formatted text of this segmentStringtext
23.0Small, 29.0Value is "ResourceLink"Stringtype
27.0Small, 29.0URL value of the resource linkStringurl
Message Segment: TextRepresents plain inline text.
352
Message Segment: More ChangesChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0Formatted text associated with the item. Possiblevalues include:
Stringtext
• formatted text of a comment
• the name of the field that has been changed withthe word from
23.0Small, 29.0Value is TextStringtype
Moderation FlagsModeration flags are available if Salesforce Communities is enabled in an organization and the community administratorselected “Allow members to flag content” during community setup.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0If the logged in user is a community moderator,shows the total number of flags on the post,
IntegerflagCount
comment, or file. If the logged in user isn’t acommunity moderator, value is null.
Flags on files is available starting in version 30.0.
29.0Small, 29.0Indicates whether the post, comment, or file wasflagged by the logged-in user (true) or not(false).
Flags on files is available starting in version 30.0.
BooleanflaggedByMe
MotifThe motif properties contain URLs for small, medium, and large icons that indicate the Database.com record type. Commonrecord types are files, users, and groups, but all record types have a set of motif icons. Custom object records use their tab styleicon. All icons are available to unauthenticated users so that, for example, you can display the motif icons in an email. Themotif can also contain the record type’s base color.
Note: The motif images are icons, not user uploaded images or photos. For example, every user has the same set ofmotif icons.
Custom object records use their tab style icon, for example, the following custom object uses the “boat” tab style:
"motif": {"color": "8C004C","largeIconUrl": "/img/icon/custom51_100/boat64.png","mediumIconUrl": "/img/icon/custom51_100/boat32.png","smallIconUrl": "/img/icon/custom51_100/boat16.png"
},
353
Moderation FlagsChatter REST API Response Bodies
Users use the following icons:
"motif": {"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"
},
Groups use the following icons:
"motif": {"color": "1797C0","largeIconUrl": "/img/icon/groups64.png","mediumIconUrl": "/img/icon/groups32.png","smallIconUrl": "/img/icon/groups16.png"
},
Files use the following icons:
"motif": {"color": "1797C0","largeIconUrl": "/img/content/content64.png","mediumIconUrl": "/img/content/content32.png","smallIconUrl": "/img/icon/files16.png"
},
Note: To view the icons in the previous examples, preface the URL with https://instance_name. For example,https://instance_name/img/icon/profile64.png.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0A hex value representing the base color of the recordtype, or null.
Stringcolor
27.0Small, 29.0A large icon indicating the record type.StringlargeIconUrl
27.0Small, 29.0A medium icon indicating the record type.StringmediumIconUrl
27.0Small, 29.0A small icon indicating the record type.StringsmallIconUrl
Organization
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Small, 29.0Amount of time after which the system promptsusers who have been inactive to log out or continueworking
IntegeraccessTimeout
24.0Small, 29.0Information about features available in theorganization or community
Featuresfeatures
26.0Small, 29.0Organization nameStringname
354
OrganizationChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Small, 29.018-character ID for the organizationStringorgId
24.0Small, 29.0Information about the organization permissions forthe user
User SettingsuserSettings
Phone NumberA phone number.
AvailableVersion
Filter Groupand Name
DescriptionTypeProperty
30.0Small, 30.0Localized string indicating the phone typeStringlabel
23.0–26.0NAStringnumberNote: This property is not available afterversion 26.0. Use the phoneNumberproperty instead.
Phone number
27.0Small, 29.0Phone numberStringphoneNumber
30.0Small, 30.0Phone type. One of these values:StringphoneType
• Fax
• Mobile
• Work
These values are not localized.
23.0–29.0Small, 29.0StringtypeNote: This property is not available afterversion 29.0. Use the phoneType propertyinstead.
Values are:• Fax
• Mobile
• Work
355
Phone NumberChatter REST API Response Bodies
Photo
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
27.0Medium, 29.0A temporary URL to the large profile picture thatexpires after 30 days. This URL is available tounauthenticated users.
StringfullEmailPhotoUrl
23.0Medium, 29.0URL to the large profile picture. The default widthis 200 pixels, while the length is scaled so theoriginal image proportions are maintained.
StringlargePhotoUrl
24.0Small, 29.018-character ID to that version of the photo.StringphotoVersionId
23.0Small, 29.0URL to the small profile picture. The default sizeis 64x64 pixels.
StringsmallPhotoUrl
27.0Small, 29.0A temporary URL to the small profile picture thatexpires after 30 days. This URL is available tounauthenticated users.
StringstandardEmailPhotoUrl
27.0Small, 29.0URL to a resource that returns a Photo responsebody: for example, /services/data/v30.0/chatter/users/005D0000001LL8OIAW/photo.
Stringurl
Recommendation
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
Small, 29.0The recommended action. Values are:Stringaction
• follow (V23.0)
• join (V23.0)
• view (V25.0)
23.0Small, 29.0URL that can be used with an HTTP methodPOST request to follow a recommended user, file,
StringactOnUrl
or record, or join a recommended group. Forexample:/users/me/following/?subjectId=001D000000Iyu2p
23.0Big, 29.0The recommendation explanationExplanationSummary
explanation
Small, 29.0The object with which the receiver is recommendedto take action. Possible objects are:
Variousobject
• File Summary (V24.0)
• Group (V23.0)
356
PhotoChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
• Record Summary (V23.0)
• User Summary (V23.0)
23.0–24.0No longer available as of version 24.0Stringtype
Record FieldA generic record field containing a label and text value.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0A localized string describing the record field.Stringlabel
29.0Small, 29.0The text value of the record field. All record fieldshave a text value. To ensure that all clients can
Stringtext
consume new content, inspect the record field’stype property and if it isn’t recognized, render thetext value as the default case.
29.0Small, 29.0Valid values are:Stringtype
• Boolean
• Number
• Phone
• Text
Record Field: BlankA record field displayed as a place holder in a grid of fields.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0BlankStringtype
Record Field: CompoundA record field that is a composite of sub-fields.
357
Record FieldChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Big, 29.0A collection of sub-fields that make up thecompound field. A collection of these responsebodies:
fields
• Record Field
• Record Field: Blank
• Record Field: Compound
• Record Field: Currency
• Record Field: Date
• Record Field: Percent
• Record Field: Picklist
• Record Field: Reference
• Record Field: Reference with Date
29.0Small, 29.0A localized string describing the record field.Stringlabel
29.0Small, 29.0The text value of the record field. All record fieldshave a text value. To ensure that all clients can
Stringtext
consume new content, inspect the record field’stype property and if it isn’t recognized, render thetext value as the default case.
29.0Small, 29.0Valid values are:Stringtype
• Address
• Compound
• Location
• Name
Record Field: CurrencyA record field containing a currency value.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0A localized string describing the record field.Stringlabel
29.0Small, 29.0The text value of the record field. All record fieldshave a text value. To ensure that all clients can
Stringtext
consume new content, inspect the record field’stype property and if it isn’t recognized, render thetext value as the default case.
Currency is formatted in the default currency of theorganization.
29.0Small, 29.0CurrencyStringtype
358
Record Field: CurrencyChatter REST API Response Bodies
Record Field: DateA record field containing a date.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Medium, 29.0A date that a machine can read.DatedateValue
29.0Small, 29.0A localized string describing the record field.Stringlabel
29.0Small, 29.0The text value of the record field. All record fieldshave a text value. To ensure that all clients can
Stringtext
consume new content, inspect the record field’stype property and if it isn’t recognized, render thetext value as the default case.
29.0Small, 29.0Valid values are:Stringtype
• Date
• DateTime
• Time
Record Field: PercentA record field containing a percentage value.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Medium, 29.0The value of the percentage.Doublevalue
29.0Small, 29.0A localized string describing the record field.Stringlabel
29.0Small, 29.0The text value of the record field. All record fieldshave a text value. To ensure that all clients can
Stringtext
consume new content, inspect the record field’stype property and if it isn’t recognized, render thetext value as the default case.
29.0Small, 29.0PercentStringtype
Record Field: PicklistA record field containing an enumerated value.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0A localized string describing the record field.Stringlabel
359
Record Field: DateChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0The text value of the record field. All record fieldshave a text value. To ensure that all clients can
Stringtext
consume new content, inspect the record field’stype property and if it isn’t recognized, render thetext value as the default case.
29.0Small, 29.0PicklistStringtype
Record Field: ReferenceA record field containing a reference to another object.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0A localized string describing the record field.Stringlabel
29.0Medium, 29.0The object referenced by the record field.Referencereference
29.0Small, 29.0The text value of the record field. All record fieldshave a text value. To ensure that all clients can
Stringtext
consume new content, inspect the record field’stype property and if it isn’t recognized, render thetext value as the default case.
29.0Small, 29.0ReferenceStringtype
Record Field: Reference with DateA record field containing a referenced object that acted at a specific time, for example, “Created By...”.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Medium, 29.0A time at which the referenced object acted.DatedateValue
29.0Small, 29.0A localized string describing the record field.Stringlabel
29.0Medium, 29.0The object referenced by the record field.Referencereference
29.0Small, 29.0The text value of the record field. All record fieldshave a text value. To ensure that all clients can
Stringtext
consume new content, inspect the record field’stype property and if it isn’t recognized, render thetext value as the default case.
29.0Small, 29.0Valid values are:Stringtype
• CreatedBy
• LastModifiedBy
360
Record Field: ReferenceChatter REST API Response Bodies
Record Search List ViewA list view structure visible after searching for records.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Medium, 30.0Defines the columns available in this list view.List ViewDefinition
definition
30.0Small, 30.0Specifies whether more than minRecordsFoundrecords were found for this search (true) or not(false).
BooleanfoundMoreRecords
30.0Small, 30.0The number of records found up to the value specifiedin the maxRecordsPerType parameter of the request.
IntegerminRecordsFound
If more than maxRecordsPerType records are found,this value is maxRecordsPerType andfoundMoreRecords is true.
30.0Small, 30.0The record data to show in this list view.List ViewRecord[]
records
Record Search ResultsThe results of a record search.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Small, 30.0A collection of record search list view objects thatmatch the search, grouped by object type.
Record Search ListView[]
resultGroups
30.0Small, 30.0The Chatter REST API URL to this set of searchresults.
Stringurl
Record Summary
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.018-character ID of the recordStringid
27.0Small, 29.0Small, medium, and large icons indicating the tabstyle of the record. The motif can also contain therecord type’s base color.
Motifmotif
24.0Medium, 29.0If the logged in user is following this record, thiscontains information about the subscription;otherwise returns null.
ReferencemySubscription
361
Record Search List ViewChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.0The localized nameStringname
30.0Small, 30.0The URL of the Chatter REST API record viewresource for this record, or null if this record does
StringrecordViewUrl
not have a record view layout, or if “ConnectRecords API” is not enabled for this organization,or if the record type isn’t supported.
23.0Small, 29.0Type of record, such as CustomObject orContentDocument
Stringtype
23.0Small, 29.0Relative URL to this recordStringurl
Record Summary ListSummary information about a collection of records in the organization, including custom objects.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Small, 30.0A collection of records. The collection can containany of these response bodies:
records
• File Summary
• Group
• Record Summary
• User Summary
30.0Small, 30.0The URL to this collection of records.Stringurl
Record ViewA view of any record in the organization, including a custom object record. This object is used if a specialized object, such asUser or ChatterGroup, is not available for the record type. Contains data and metadata so you can render a record with oneresponse.
AvailableVersion
FilterGroup andVersion
DescriptionTypeProperty
23.0Small, 29.018-character ID of the objectStringid
27.0Small, 29.0Small, medium, and large icons indicating thetype of the object. The motif can also containthe object’s base color.
The icon is not a preview of the file.
Motifmotif
362
Record Summary ListChatter REST API Response Bodies
AvailableVersion
FilterGroup andVersion
DescriptionTypeProperty
23.0Medium,29.0
If the logged in user is following this file, thiscontains information about the subscription,otherwise returns null.
ReferencemySubscription
29.0Small, 29.0The localized nameStringname
30.0Small, 30.0The Chatter REST API URL to the recordview resource for this record. This property is
StringrecordViewUrl
null if this record doesn’t have a record viewlayout, if the “Connect Records API” is notenabled for this organization, or if the recordtype isn’t in the whitelist.
29.0Medium,29.0
The related list definitions (metadata) for thisobject. These list definitions do not includethe related list data. .
List View Definition[]relatedListDefinitions
29.0Small, 29.0A list of record view sections.Record View Section[]sections
23.0Small, 29.0A fixed type name for this object. Check thisvalue to determine the shape of a responsebody.
Stringtype
23.0Small, 29.0The Chatter REST API URL resource for thisobject.
Stringurl
Record View SectionA section of record fields and values on a record detail.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0The number of columns to use to lay out the fieldsin a record section.
StringcolumnCount
29.0Small, 29.0The order of the fields to use in the fieldsproperty to lay out the fields in a record section.
StringcolumnOrder
• LeftRight—Fields are rendered from left toright.
• TopDown—Fields are rendered from the topdown.
29.0Small, 29.0The fields and values for the record contained inthis section. A collection of these response bodies:
fields
• Record Field
• Record Field: Blank
• Record Field: Compound
363
Record View SectionChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
• Record Field: Currency
• Record Field: Date
• Record Field: Percent
• Record Field: Picklist
• Record Field: Reference
• Record Field: Reference with Date
29.0Small, 29.0A localized label to display when rendering thissection of fields.
Stringheading
29.0Small, 29.0Indicates whether the section can be collapsed tohide all the fields (true) or not (false).
BooleanisCollapsible
Reference
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Small, 29.018-character ID of the object being referencedStringid
23.0Small, 29.0URL to the resource endpointStringurl
Shares
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Small, 29.0Returns information about the user, record, or groupthe file is shared with. Value is one of the following:
Depends on sharingentity
• Group
• Record Summary
• User Summary
24.0Small, 29.0The permission level of sharing. Values are:StringsharingType
• C—collaborator
• I—sharing permission is determined bylocation. This generally occurs when the sharingpermission is not set on the file, but on thelibrary instead. This value is also used when thelogged-in user is the same as owner of the file.
• N—no access
• V—viewer
364
ReferenceChatter REST API Response Bodies
Subscription
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
26.0Medium, 29.0Information about the community. Returns nullif subscription exists in default community orcommunities aren’t enabled.
Referencecommunity
23.0Small, 29.018-character ID of the subscriptionStringid
Small, 29.0Information about the parent, that is, the thing orperson being followed. Valid values are:
Dependssubject
• Group (23.0)
• Record Summary (23.0)
• Topic (29.0)
• User Summary (23.0)
23.0Small, 29.0Information about the subscriber, that is, the personfollowing this item. Valid values are:
Dependssubscriber
• Group
• User Summary
23.0Small, 29.0Relative URL to this specific subscriptionStringurl
Subscription Page
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Medium, 29.0Returns the current page of subscriptionsStringcurrentPageUrl
23.0Small, 29.0Returns the next page of subscriptions. If there isno next page, returns the string “null”
StringnextPageUrl
23.0Medium, 29.0Returns information about the subscription, ornull the logged-in user is not subscribed.
ReferencemySubscription
23.0Medium, 29.0Returns the previous page of subscriptions. If thereis no previous page, returns the string “null”
StringpreviousPageUrl
23.0Small, 29.0Collection of subscriptionsSubscription[]subscriptions
23.0Small, 29.0Total number of subscriptionsIntegertotal
Time ZoneThe user's time zone as selected in My Settings in Database.com. This value does not reflect a device's current location.
365
SubscriptionChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Small, 30.0Signed offset, in hours, from GMTDoublegmtOffset
30.0Small, 30.0Display name of this time zoneStringname
Topic
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
28.0Big, 29.0ISO8601 date string, for example,2011-02-25T18:24:31.000Z
StringcreatedDate
28.0Big, 29.0Description of the topicStringdescription
28.0Small, 29.018-character ID of the topicStringid
24.0Small, 29.0Name of the topicStringname
28.0Medium, 29.0Number of people talking about this topic over thelast two months, based on factors such as topicadditions and comments on posts with the topic
IntegertalkingAbout
29.0Small, 29.0URL to the topic detail pageStringurl
Topic Collection
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Medium, 29.0Returns the current page of topicsStringcurrentPageUrl
29.0Small, 29.0Returns the next page of topics. If there is no nextpage, returns the string “null”
StringnextPageUrl
24.0Small, 29.0Collection of topicsTopic[]topics
Topic EndorsementRepresents one user endorsing another user for a single topic.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Small, 30.0User being endorsedUser Summaryendorsee
30.0Small, 30.0ID of the endorsement recordStringendorsementId
30.0Small, 30.0User performing the endorsementUser Summaryendorser
366
TopicChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Small, 30.0Topic the user is being endorsed forTopictopic
30.0Small, 30.0Chatter REST API resource URL for theendorsement record
Stringurl
Topic Endorsement CollectionA collection of topic endorsement response bodies.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Medium, 30.0Chatter REST API URL identifying the currentpage.
StringcurrentPageUrl
30.0Small, 30.0Collection of topic endorsement response bodiesTopicEndorsement[]
topicEndorsements
30.0Small, 30.0Chatter REST API URL identifying the next pageor null if there isn’t a next page.
StringnextPageUrl
30.0Medium, 30.0Chatter REST API URL identifying the previouspage or null if there isn’t a previous page.
StringpreviousPageUrl
Topic Opt OutAn “opt out” from a topic. Indicates that a user doesn’t want to be identified as knowledgeable about a topic.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Small, 30.0ID of the topic opt out recordStringid
30.0Small, 30.0The reason the user is opting out of the topic.
The only valid value is topicInfluenceHide.
Stringreason
30.0Small, 30.0Topic the user opted out ofTopictopic
30.0Small, 30.0Chatter REST API resource URL for the topic optout
Stringurl
30.0Small, 30.0User that opted out of the topicUser Summaryuser
Topic Opt Out CollectionA collection of topic opt out response bodies.
367
Topic Endorsement CollectionChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Medium, 30.0Chatter REST API URL identifying the currentpage.
StringcurrentPageUrl
30.0Small, 30.0Collection of topic opt out response bodies.Topic Opt Out[]topicOptOuts
Topics People Are Knowledgeable AboutRepresents a topic that a specified user is knowledgeable about.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Small, 30.0Specifies if the knowledgeable user is endorsed forthe topic by the context user, true if so, falseotherwise
BooleanisEndorsedByMe
30.0Small, 30.0ID of the knowledgeable recordStringknowledgeableId
30.0Medium, 30.0Number of endorsements received by theknowledgeable user for the topic
IntegernumEndorsements
30.0Medium, 30.0Specifies the reasons why the user is consideredknowledgeable about the topic. Valid values are:
Stringreasons
• Influential—User was mentioned in postsor in comments on posts with the topic orreceived likes on comments on posts with thetopic.
• Endorsed—User received endorsement fromanother user for the topic.
30.0Small, 30.0Topic that the user is knowledgeable aboutTopictopic
Topics People Are Knowledgeable About CollectionA collection of topics people are knowledgeable about response bodies.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Medium, 30.0Chatter REST API URL identifying the currentpage.
StringcurrentPageUrl
30.0Small, 30.0Collection of topics people are knowledgeable aboutresponse bodies
Topics People AreKnowledgeableAbout[]
knowledgeableAboutTopic
30.0Small, 30.0Chatter REST API URL identifying the next pageor null if there isn’t a next page.
StringnextPageUrl
368
Topics People Are Knowledgeable AboutChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Medium, 30.0Chatter REST API URL identifying the previouspage or null if there isn’t a previous page.
StringpreviousPageUrl
Topic Suggestion
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
28.0Small, 29.0Topic that already exists or null for a new topicTopicexistingTopic
28.0Small, 29.0Name of the topicStringname
Topic Suggestion Collection
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
28.0Small, 29.0Collection of topic suggestion response bodiesTopic Suggestion[]topicSuggestions
User Capabilities
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0Specifies if the context user can use ChatterMessenger with the subject user (true) or not(false)
BooleancanChat
29.0Small, 29.0Specifies if the context user can direct message thesubject user (true) or not (false)
BooleancanDirectMessage
29.0Small, 29.0Specifies if the context user can edit the subjectuser’s account (true) or not (false)
BooleancanEdit
29.0Small, 29.0Specifies if the context user can follow the subjectuser’s feed (true) or not (false)
BooleancanFollow
29.0Small, 29.0Specifies if the context user can view the feed of thesubject user (true) or not (false)
BooleancanViewFeed
29.0Small, 29.0Specifies if the context user can view the full profileof the subject user (true) or only the limited profile(false)
BooleancanViewFullProfile
369
Topic SuggestionChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0Specifies if the subject user is a Chatter moderatoror admin (true) or not (false)
BooleanisModerator
User Chatter SettingsA user’s global Chatter settings.
AvailableSince
Filter Groupand Version
DescriptionTypeProperty
27.0Small, 29.0The default frequency with which a user receivesemail from a group when they join it. Values are:
StringdefaultGroupEmailFrequency
• EachPost
• DailyDigest
• WeeklyDigest
• Never
In Communities, the Email on Each Post optionis disabled once a group exceeds 10,000 members.All members who had this option selected areautomatically switched to Daily Digest.
User DetailIf a context user doesn’t have permission to see a property, the property is set to null.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Big, 29.0Text from user's profileStringaboutMe
30.0Small, 30.0An additional label for the user, for example,“Customer,” “Partner,” or “Acme Corporation.” If
StringadditionalLabel
the user doesn’t have an additional label, the valueis null.
23.0Big, 29.0AddressAddressaddress
23.0Big, 29.0Chatter activity statisticsChatter ActivitychatterActivity
23.0Big, 29.0User’s influence rankChatter InfluencechatterInfluence
23.0Small, 29.0Company nameStringcompanyName
23.0–25.0User StatuscurrentStatusNote: This property is no longer availableas of version 25.0.
370
User Chatter SettingsChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
User's current status
23.0Medium, 29.0User's email addressStringemail
23.0Small, 29.0User's first nameStringfirstName
23.0Big, 29.0Number of users following this userIntegerfollowersCount
23.0Big, 29.0Information about items the user is followingFollowing CountsfollowingCounts
23.0Big, 29.0Number of groups user is followingIntegergroupCount
23.0Small, 29.018-character ID of the userStringid
23.0Small, 29.0true if user is active, false otherwiseBooleanisActive
23.0–25.0BooleanisChatterGuestNote: This property is no longer availableas of version 26.0. Use the userTypeproperty instead.
true if user is a Chatter customer, falseotherwise
28.0Small, 29.0true if user is in the same community as thecontext user; false otherwise. Can be false for
BooleanisInThisCommunity
record feed @mentions on posts with the scope “AllUsers.”
23.0Small, 29.0User's last nameStringlastName
23.0Big, 29.018-character ID of the user’s managerStringmanagerId
23.0Big, 29.0Locale-based concatenation of manager's first andlast names
StringmanagerName
27.0Small, 29.0Small, medium, and large icons indicating that theobject is a user. The motif can also contain theobject’s base color.
The motif icon is not the user’s profile picture.
Motifmotif
23.0Medium, 29.0If the logged-in user is following this user, thiscontains information about the subscription, elsereturns null
ReferencemySubscription
23.0Small, 29.0Locale-based concatenation of user's first and lastnames
Stringname
23.0Big, 29.0Collection of user's phone numbersPhone Number[]phoneNumbers
23.0Small, 29.0Information about the user's photosPhotophoto
30.0Small, 30.0The URL of the Chatter REST API record viewresource for this record, or null if this record does
StringrecordViewUrl
not have a record view layout, or if “ConnectRecords API” is not enabled for this organization,or if the record type isn’t supported.
371
User DetailChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Big, 29.0Number of thanks the user has receivedIntegerthanksReceived
23.0Small, 29.0Title of the userStringtitle
23.0Small, 29.0UserStringtype
23.0Small, 29.0URL to the user's profileStringurl
24.0Small, 29.0User name of the user, such asAdmin@mycompany.com
Stringusername
26.0Medium, 29.0Type of user. Values are:StringuserType
• ChatterGuest—User is a Chattercustomerin an external group
• ChatterOnly—User is a Chatter Freecustomer
• Guest—Unauthenticated users
• Internal—User is a standard organizationmember
• Portal—User is a Customer Portal User, acommunities user, and so on.
• System—User is Chatter Expert or a systemuser
• Undefined—User is a user type that is acustom object.
User Group PageA paginated collection of groups a user is a member of.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Medium, 29.0URL to the current pageStringcurrentPageUrl
23.0Small, 29.0Collection of groups for a userGroup[]groups
23.0Small, 29.0URL to the next page, if there is no next page,returns the string “null”
StringnextPageUrl
23.0Medium, 29.0URL to the previous page, if there is no previouspage, returns the string “null”
StringpreviousPageUrl
23.0Small, 29.0Total number of groups a user is a member of.
This number is always the total number of groupsa user is a member of, even when the request is a
Integertotal
search and the response contains a subset of thattotal.
372
User Group PageChatter REST API Response Bodies
User Page
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0Medium, 29.0URL to the current pageStringcurrentPageUrl
23.0Small, 29.0URL to the next page, if there is no next page,returns null
StringnextPageUrl
23.0Medium, 29.0URL to the previous page, if there is no previouspage, returns null
StringpreviousPageUrl
24.0Small, 29.0Collection of user detail information.User Detail[]users
User Profile
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Medium, 29.0The context user’s capabilities specific to the subjectuser’s profile
User Capabilitiescapabilities
29.0Small, 29.0The ID of the user attached to the profileStringid
29.0Big, 29.0The tabs visible to the context user for that usertype
User Profile Tab[]tabs
29.0Small, 29.0The URL of the user’s profileStringurl
29.0Small, 29.0The details about the user attached to the profileUser DetailuserDetail
User Profile Tab
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0The tab’s unique identifier or 18–character IdStringid
29.0Small, 29.0Specifies if the tab appears first when clicking theuser profile (true) or not (false)
BooleanisDefault
29.0Small, 29.0Specifies the type of user profile tab:StringtabType
• CustomVisualForce—Tab that displays datafrom a Visualforce page.
• CustomWeb—Tab that displays data from anyexternal Web-based application or Web page.
• Feed—Tab that displays the Chatter feed.
• Overview—Tab that displays user details.
373
User PageChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0The current tab’s content URL (for non built-intab types)
StringtabUrl
User SettingsSettings specific to a user.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
27.0Small, 29.0User can approve workflows from Chatter posts.BooleanapprovalPosts
24.0Small, 29.0The logged-in user is allowed to follow things.BooleancanFollow
24.0Small, 29.0User has “Modify all Data” permissionBooleancanModifyAllData
24.0Small, 29.0User can own groupsBooleancanOwnGroups
24.0Small, 29.0User has “View all Data” permissionBooleancanViewAllData
24.0Small, 29.0User has “View all Groups” permissionBooleancanViewAllGroups
24.0Small, 29.0User has “View all Users” permissionBooleancanViewAllUsers
24.0Small, 29.0User can see of other user’s Chatter profilesBooleancanViewFullUserProfile
24.0Small, 29.0User can see all files marked as publicBooleancanViewPublicFiles
28.0Small, 29.0Currency symbol to use for displaying currencyvalues. Applicable only when the multiCurrencyproperty of the Features response body is false.
StringcurrencySymbol
24.0Small, 29.0User is a ChattercustomerBooleanexternalUser
29.0Small, 29.0Maximum storage for synced files, in megabytes(MB)
IntegerfileSyncStorageLimit
26.0Small, 29.0User is a member of the internal organizationBooleanhasAccessToInternalOrg
26.0Small, 29.0User has “Sync Files” permissionBooleanhasFileSync
29.0Small, 29.0User has access to REST API.BooleanhasRestDataApiAccess
30.0Small, 30.0The user's time zone as selected in My Settings inDatabase.com. This value does not reflect a device'scurrent location.
Time ZonetimeZone
28.0Small, 29.0The ISO code for the default currency. Applicableonly when the multiCurrency property of theFeatures response body is true.
StringuserDefaultCurrencyIsoCode
374
User SettingsChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
24.0Small, 29.018-character ID of the userStringuserId
24.0Small, 29.0Locale of userStringuserLocale
User Status
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
23.0–25.0Small, 29.0Body of the postFeed Body[]body
23.0–25.0Small, 29.018-character IDStringparentId
23.0–25.0Small, 29.0URL to this user status postStringurl
User Summary
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
30.0Small, 30.0An additional label for the user, for example,“Customer,” “Partner,” or “Acme Corporation.” If
StringadditionalLabel
the user doesn’t have an additional label, the valueis null.
23.0Small, 29.0Name of the companyStringcompanyName
23.0Small, 29.0User's first nameStringfirstName
23.0Small, 29.018-character IDStringid
25.0Small, 29.0true if user is active, false otherwise.BooleanisActive
23.0–26.0BooleanisChatterGuestNote: This property is no longer availableas of version 26.0. Use the userTypeproperty instead.
true if user is a Chatter customer, falseotherwise
28.0Small, 29.0true if user is in the same community as thecontext user; false otherwise. Can be false for
BooleanisInThisCommunity
record feed @mentions on posts with the scope “AllUsers.”
23.0Small, 29.0User's last nameStringlastName
375
User StatusChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
27.0Small, 29.0Small, medium, and large icons indicating that theobject is a user. The motif can also contain theobject’s base color.
The motif icon is not the user’s profile photo.
Motifmotif
23.0Medium, 29.0If the logged-in user is following this user, thiscontains information about the subscription, elsereturns null
ReferencemySubscription
23.0Small, 29.0Locale-based concatenation of first and last namesStringname
23.0Small, 29.0Information about the user's photoPhotophoto
30.0Small, 30.0The URL of the Chatter REST API record viewresource for this record, or null if this record does
StringrecordViewUrl
not have a record view layout, or if “ConnectRecords API” is not enabled for this organization,or if the record type isn’t supported.
23.0Small, 29.0Title of the userStringtitle
23.0Small, 29.0UserStringtype
23.0Small, 29.0URL to the user's profileStringurl
26.0Medium, 29.0Type of user. Valid values are:StringuserType
• ChatterGuest—User is a Chattercustomerin an external group
• ChatterOnly—User is a Chatter Freecustomer
• Guest—Unauthenticated users
• Internal—User is a standard organizationmember
• Portal—User is a Customer Portal User, acommunities user, and so on.
• System—User is Chatter Expert or a systemuser
• Undefined—User is a user type that is acustom object.
ZoneA Chatter Answers zone.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Big, 29.0The description of the zoneStringdescription
376
ZoneChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0The zone IDStringid
29.0Small, 29.0Indicates that the zone is activeBooleanisActive
29.0Small, 29.0Indicates that the zone is available for ChatterAnswers
BooleanisChatterAnswers
29.0Small, 29.0Name of the zoneStringname
30.0Small, 30.0Chatter REST API resource URL for the zoneStringurl
29.0Small, 29.0Zone visibility type. One of these values:Stringvisibility
• Community—Available in a community.
• Internal—Available internally only.
• Portal—Available in a portal.
29.0Small, 29.0If the zone is available in a portal or a community,this property contains the ID of the portal or
StringvisibilityId
community. If the zone is available to all portals,this property contains the value All.
Zone PageA page of Chatter Answers zones.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0Collection of one or more zonesZone[]zones
29.0Medium, 29.0Chatter REST API URL identifying the currentpage.
StringcurrentPageUrl
29.0Small, 29.0Chatter REST API URL identifying the next pageor null if there isn’t a next page.
StringnextPageUrl
Zone Search PageA page of results from a search within a Chatter Answers zone.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Medium, 29.0Token identifying the current page.StringcurrentPageToken
29.0Medium, 29.0Chatter REST API URL identifying the currentpage.
StringcurrentPageUrl
377
Zone PageChatter REST API Response Bodies
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0Collection of search resultsZone SearchResult[]
items
29.0Small, 29.0Token identifying the next page or null if thereisn’t a next page.
StringcurrentPageToken
29.0Small, 29.0Chatter REST API URL identifying the next pageor null if there isn’t a next page.
StringnextPageUrl
Zone Search ResultThe result of a search within a Chatter Answers zone.
AvailableVersion
Filter Groupand Version
DescriptionTypeProperty
29.0Small, 29.0Indicates whether or not the search result has a bestanswer
BooleanhasBestAnswer
29.0Small, 29.0ID of the search result. The search result can be aquestion or an article.
Stringid
29.0Small, 29.0Title of the search resultStringtitle
29.0Small, 29.0Type of the search result. One of these values:Stringtype
• Article—Search results contain only articles.
• Question—Search results contain onlyquestions.
29.0Small, 29.0Number of votes given to the search resultStringvoteCount
378
Zone Search ResultChatter REST API Response Bodies
Index
@ me resources 146
A
Access tokens 34Adding member to a group 193Adding photo
group 202user 263
Address response body 303Attach input
canvas app 277existing content 278feed poll 279link 279new file upload 280
Authentication 3
B
Batch feed items 164Batch information
group-memberships resource 199Batch requests
batch input 281batch request input 282
Batch resource 56Batch Result Item response body 304Batch Results response body 303Batching information
groups 192users 244
Bearer token 35Bookmarks
feed items 76feed URL 75flat feed 77resources 74
C
Canvas appsattachment input 277
Chatter Activity response body 305Chatter API
wildcards 19Chatter Directory response body 305Chatter feed items 12Chatter feeds 12Chatter Influence response body 305Chatter resource 62Chatter REST API
cURL 5differences with other APIs 2
Chatter REST API (continued)how to example 41named resources 4quick reference 41resources 5rich input 9selecting the right API 2URLs 4using 2
ClientInfo response body 306Comment Page response body 307Comment response body 306Comments
access 63delete 63input 283likes 64on feed items 167resources 63
Communitiesbuilding URL 4
Communities Moderation Feedresources 78
Communities Moderation resources 65Community Page response body 308Community response body 307Company feed
feed items 83getting updated feed items example 46resources 82URL 82
Connectresource 72
Connect Directory response body 309Conversation Detail response body 309Conversation Summary Collection response body 310Conversation Summary response body 309Conversation Unread Count response body 310Conversations
change status 247input 302unread count 248
D
Dashboard component snapshotinput 284
Data format 3Deleting photo
group 202user 263
379
Index
E
Email Address response body 310Encoding 3Error Message response body 310Error responses 25Error with Output response body 311Examples
@mentions proposals 45activity status 49add comments 43batch 54create group 50filter a response body 42follow record 52following list 49get a feed with internal feed items only 48get a group feed 48get feed items for a record 53get the news feed 48get updated feed items 46Java 126join group 51join private group 51like a feed item, batch 45like feed items 45link post 127poll news feed for updates 47post @mentions 43post multiple @mentions 44post to group 52recommendations 49request to join private group 51search a group feed 49search a record feed 49send private message 54share a feed item 46unfollow record 52updating group photo 50updating user photo 53updating user profile 53uploading binary files 9
Explanation Details response body 311Explanation Summary response body 312
F
Favoriteinput 285
Favorite response body 312Favorites feed
feed items 91list of favorites 85resources 85specific favorite 90
Favorites Page response body 313
Features response body 313Feed Body response body 314Feed Directory Item response body 315Feed Directory response body 315Feed Item Attachment
Basic Template response body 321Canvas Template response body 321Content response body 322Link response body 323Poll response body 324Record Snapshot response body 324Tracked Change response body 324
Feed Item Page response body 324Feed Item Preamble Message Body response body 325Feed Item response body 317Feed Item Topic
input 287Feed Item Topics response body 326Feed items
about 12accessing 166bookmark feed 76bookmarking 166company feed 83deleting 166favorites feed 91files feed 96groups feed 110input 286key prefix filtered feed 101layout 12news feed 116people feed 129posting 12record feed 133rendering 12to feed 148topics feed 151user-profile feed 153
Feed Modified Info response body 326Feed Poll Choice response body 326Feed response body 314Feed Tracked Change response body 327Feed-items resources
accessing specific feed item 166batch 164comments 167likes 169polls 170query 165resources 164topics 171
Feedsabout 12bookmarks resources 74communities moderation 78
380
Index
Feeds (continued)company resources 82favorites resources 85files resources 95filter resources 99groups resources 109list resource 93news resource 113people resources 128record resource 132share an item 46to resources 146topics resources 150user-profile resources 152users resource 239
File Detail response body 327File Share Link response body 327File Shares
input 289File Shares Page response body 328File Summary Page response body 331File Summary response body 328Files
group files 192input 288sync 17topic files 233uploading binary example 9working with 17
Files feedfeed items 96flat feed 98getting updated feed items example 46resources 95URL 95
Files resourcescontent 175file information in batch 179rendition 178shares 176shares link 178specific file information 173user files, filtered by groups 250user files, filtered by sharing 251user files, general 248
Filter a response body 42Filter feed
flat feed 108getting updated feed items example 46key prefix 100key prefix feed items 101list of filters 100resources 99
Filter response bodies 19Filters
exclude 21
Filters (continued)groups 20include 23
Flat feedbookmarks feed 77files feed 98filtered feed 108groups feed 112news feed 127people feed 131record feed 145to feed 149user-profile feed 163
Flat Feed Item response body 331Flat Feed response body 331Folder
input 289Folder Item
input 290Folder Item Page response body 333Folder Item response body 332Folder response body 332Follow record example 52Follower Page response body 333Followers
record resource 221users resources 252
Followinginput 290records 253users 253
Following Counts response body 333Following Page response body 334
G
Get updated feed items 46Group
input 291–292Group chatter settings
input 291Group Chatter Settings response body 336Group Detail response body 336Group Information response body 338Group member
input 293Group Member Page response body 339Group Member response body 338Group Membership Request Collection response body 340Group Membership Request response body 339Group Membership Request Update
input 293Group Page response body 340Group response body 334Group-memberships batch resource 199Group-memberships resource 199
381
Index
Groupscreating example 50joining example 51joining private group example 51posting example 52requesting membership 198requesting membership in a private group 195requesting status for membership requests 195requesting to join private group example 51topic groups 234
Groups feedfeed items 110flat feed 112getting updated feed items example 46resources 109URL 109
Groups resourcesbatching information 192files information 192groups in organization 183information 188members 193members requests for private groups 195membership request 198photo 202settings 205topics 206
H
Hash tagsmessage segment input 294
HTML encoding 3
I
Icon response body 340Influence
resource 206Influence Thresholds response body 340Inputs
attachment:existing content 278attachment:feed poll 279attachment:link 279attachment:new file upload 280batch 281batch request 282canvas app 277comments 283conversation 302dashboard component snapshot 284favorite 285feed item 286feed item topic 287feed poll input 288file input 288
Inputs (continued)file shares 289folder 289folder item 290following 290group 291–292group chatter settings 291group member 293group membership request update 293message body 294message segment:hash tag 294message segment:link 295message segment:mention 295message segment:text 295messages 300moderation flag 296PATCH 9photo 296POST 9PUT 9share 297topic 298topic assignment 297topic endorsement 298user 299user chatter settings 299user message:recipient 301user message:recipient list 301
J
Java example 126JSON 3
K
Knowledgeable People Collection response body 341Knowledgeable People response body 341
L
Like Message Body response body 342Like Page response body 342Like response body 342Likes
access 207delete 207on comments 64on feed item 169resource 207
Limits 3Link post examples 127Links
attachment input 279message segment input 295
List View Definition response body 343
382
Index
List View Record response body 344List View response body 344Localization 3
M
Members of a group 193Mention Completion Page response body 346Mention Completion response body 345Mention Validation response body 347Mention Validations response body 347Mentions
message segment input 295resources 210
Mentions completionsresources 208, 213
Message body input 294Message Collection response body 348Message response body 348Message Segment
Entity Link response body 349Field Change Name response body 350Field Change response body 349Field Change Value response body 350Hashtag response body 350Link response body 351Mention response body 351More Changes response body 352Resource Link response body 352Text response body 352
Message segment inputhash tag 294link 295mention 295text 295
Messagesinput 300user messages, specific 262
Moderation Flaginput 296
Moderation Flags response body 353Motif response body 353Motifs
batch motifs resource 212resource 211
Motifs resources 211
N
New file upload 280News feed
feed items 116flat feed 127getting updated feed items example 46is-modified 114polling for updates 114
News feed (continued)polling for updates example 47resources 113URL 114
O
OAuthauthentication 39user-agent flow 32Web server flow 28
Organizationresource 72
Organization response body 354
P
PATCH input 9People feed
feed items 129flat feed 131getting updated feed items example 46resources 128URL 129
Phone Number response body 355Photo
group 202input 296user 263
Photo response body 356Polling news feed for updates 47Polls
attachment input 279feed poll input 288on feed items 170
POST input 9PUT input 9
Q
Query feed items 165Quick reference 41Quickstart
access token 38Developer Edition 38OAuth 38prerequisites 38
R
Recipientinput 301list input 301
Recommendation response body 356Recommendations
specific action 266
383
Index
Recommendations (continued)specific action and key prefix 268specific action and object category 267specific action and object ID 269
Record feedfeed items 133flat feed 145getting updated feed items example 46resources 132URL 133
Record FieldBlank response body 357Compound response body 357Currency response body 358Date response body 359Percent response body 359Picklist response body 359Reference response body 360Reference with Date response body 360
Record Field response body 357Record Search List View response body 361Record Search Results response body 361Record Summary List response body 362Record Summary response body 361Record View response body 362Record View Section response body 363Records
followers 221following 253recently used 271record information 220resources 220
Records information resource 213Records search resource 214Reference response body 364Refresh tokens 34Related List Column response body 343Related List Sort response body 345Request bodies
attachment:canvas app 277attachment:existing content 278attachment:feed poll 279attachment:link 279attachment:new file upload 280batch 281batch request 282comments 283conversation 302dashboard component snapshot 284favorite 285feed item 286feed item topic 287feed poll input 288file input 288file shares 289folder 289
Request bodies (continued)folder item 290following 290group 291–292group chatter settings 291group member 293group membership request update 293message body 294message segment:hash tag 294message segment:link 295message segment:mention 295message segment:text 295messages 300moderation flag 296photo 296share 297topic 298topic assignment 297topic endorsement 298user chatter settings 299user input 299user message:recipient 301user message:recipient list 301
Requesting membership in a group 198Requesting membership in a private group 195Resources
batch 56batch motifs 212bookmarks 74chatter 62comments 63Communities Moderation 65communities moderation feed 78company feed 82connect 72error responses 25favorites 85feed-items 164feeds 93files 173, 179files feed 95filter feed 99folders 179groups feed 109influence 206likes 207mentions completions 208, 213mentions validations 210motifs 211organization 72people feed 128record search 214records 220records information 213subscriptions 223topics feed 150
384
Index
Resources (continued)topics on records 222user profile 238zone search results 275
Response bodiesAddress 303Batch Result Item 304Batch Results 303Chatter Activity 305Chatter Directory 305Chatter Influence 305ClientInfo 306Comment 306Comment Page 307Community 307Community Page 308Connect Directory 309Conversation Detail 309Conversation Summary 309Conversation Summary Collection 310Conversation Unread Count 310Email Address 310Error Message 310Error with Output 311excluding properties 21Explanation Details 311Explanation Summary 312Favorite 312Favorites Page 313Features 313Feed 314Feed Body 314Feed Directory 315Feed Directory Item 315Feed Item 317Feed Item Attachment:Basic Template 321Feed Item Attachment:Canvas Template 321Feed Item Attachment:Content 322Feed Item Attachment:Link 323Feed Item Attachment:Poll 324Feed Item Attachment:Record Snapshot 324Feed Item Attachment:Tracked Change 324Feed Item Page 324Feed Item Preamble Message Body 325Feed Item Topics 326Feed Modified Info 326Feed Poll Choice 326Feed Tracked Change 327File Detail 327File Share Link 327File Shares Page 328File Summary 328File Summary Page 331filtering 19filtering properties 20–21, 23Flat Feed 331
Response bodies (continued)Flat Feed Item 331Folder 332Folder Item 332Folder Item Page 333Follower Page 333Following Counts 333Following Page 334Group 334Group Chatter Settings 336Group Detail 336Group Information 338Group Member 338Group Member Page 339Group Membership Request 339Group Membership Request Collection 340Group Page 340Icon 340including properties 23Influence Thresholds 340Knowledgeable People 341Knowledgeable People Collection 341Like 342Like Message Body 342Like Page 342List View Definition 343List View Object 344List View Record 344Mention Completion 345Mention Completion Page 346Mention Validation 347Mention Validations 347Message 348Message Collection 348Message Segment:Entity Link 349Message Segment:Field Change 349Message Segment:Field Change Name 350Message Segment:Field Change Value 350Message Segment:Hashtag 350Message Segment:Link 351Message Segment:Mention 351Message Segment:More Changes 352Message Segment:Resource Link 352Message Segment:Text 352Moderation Flags 353Motif 353Organization 354Phone Number 355Photo 356Recommendation 356Record Field 357Record Field:Blank 357Record Field:Compound 357Record Field:Currency 358Record Field:Date 359Record Field:Percent 359
385
Index
Response bodies (continued)Record Field:Picklist 359Record Field:Reference 360Record Field:Reference with Date 360Record Search List View 361Record Search Results 361Record Summary 361Record Summary List 362Record View 362Record View Section 363Reference 364Related List Column 343Related List Sort 345Shares 364Subscription 365Subscription Page 365Time Zone 365Topic 366Topic Collection 366Topic Endorsement 366Topic Endorsement Collection 367Topic Opt Out 367Topic Opt Out Collection 367Topic Suggestion 369Topic Suggestion Collection 369Topics People Are Knowledgeable About 368Topics People Are Knowledgeable About Collection 368User Capabilities 369User Chatter Settings 370User Detail 370User Group Page 372User Page 373User Profile 373User Profile Tab 373User Settings 374User Status 375User Summary 375Zone 376Zone Page 377Zone Search Page 377Zone Search Result 378
Rich input 9
S
Search feed items 165Selecting the right API 2Settings
group 205users 271
Shareinput 297
Shares response body 364Subscribing to a group 193Subscription Page response body 365Subscription response body 365
Subscriptionsresource 223
T
Textmessage segment input 295
Time Zone response body 365To feed
feed items 148flat feed 149resources 146URL 147
Tokens 34–35Topic
input 298Topic Assignment
input 297Topic Collection response body 366Topic endorsement
input 298Topic Endorsement Collection response body 367Topic Endorsement response body 366Topic Opt Out Collection response body 367Topic Opt Out response body 367Topic resource 229Topic response body 366Topic Suggestion Collection response body 369Topic Suggestion response body 369Topics
on feed items 171Topics feed
feed items 151resources 150
Topics FeedURL 151
Topics on recordsresource 222
Topics People Are Knowledgeable About Collection response body 368Topics People Are Knowledgeable About response body 368Topics resource
endorse people 231endorsements 232files information 233groups information 234knowledgeable people 236knowledgeable people opt out 238knowledgeable people opt outs 237list of topics 224related topics 237topic suggestions 226trending topics 228
U
Unfollow record example 52
386
Index
Updating photogroup 202user 263
Uploading binary files 9URLs 4User Capabilities response body 369User chatter settings
input 299User Chatter Settings response body 370User Detail response body 370User Group Page response body 372User Page response body 373User profile
resources 238User Profile response body 373User Profile Tab response body 373User Settings response body 374User Status response body 375User Summary response body 375User-agent OAuth flow 32User-profile feed
feed items 153flat feed 163resources 152URL 153
Users resourcesbatching information 244conversations 244conversations, change status 247conversations, specific 245conversations, unread count 248files, filtered by groups 250files, filtered by sharing 251files, general 248followers 252
Users resources (continued)following 253groups 255knowledgeable about topics 256messages 256messages, specific 262photo 263recommendations 265recommendations for specific action 266recommendations for specific action and object ID 269recommendations, specific action and key prefix 268recommendations, specific action and object category 267topics 274user information 240user profile information 241user records, recent 271user settings 271user status 273
W
Web server OAuth flow 28Wildcards 19
Z
Zone Page response body 377Zone response body 376Zone Search Page response body 377Zone Search Result response body 378Zones 274Zones resources
list of zones in organization 274specific zonezone information 275zone search results 275
387
Index