Chatter REST API Developer's Guide

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

http://tools.ietf.org/html/draft-ietf-oauth-v2-10

http://www.iso.org/iso/catalogue_detail?csnumber=40874

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



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 [email protected]

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


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": "[email protected]","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": "[email protected]"

}

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


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

http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2

http://tools.ietf.org/html/rfc2388

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


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



"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


• 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


• 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


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:


ConnectApi.ChatterFeeds.getFeedItemsFromFeed

GET /chatter/feeds/company/feed-itemsCompany

(communityIdOrNull,ConnectApi.FeedType.Company)


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.


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.



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


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.


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": "[email protected]"

}

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 1</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 valuename 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",


"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 1

<baz>baz value</baz><someObject>

</someObject></foo>

sub 1</someObject></foo>

<foo><someObject>

include=/someObject/sub<foo><bar>bar value</bar>

To filter a propertynested in a response

sub 1<baz>baz value</baz>body, include the <someObject>parent response body </someObject>

</foo>sub value</someObject>

</foo>name as a filtersegment.

<foo><someList>

include=/someList/item/id<foo><bar>bar valu</bar>


<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",


{"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

https://www.owasp.org/index.php/XSS_%28Cross_Site_Scripting%29_Prevention_Cheat_Sheet

http://www.apps.ietf.org/rfc/rfc2396.html


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

http://tools.ietf.org/html/draft-ietf-oauth-v2-10

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


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:


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:


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


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:


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 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:


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:


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.


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


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


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:


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


• 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


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

http://curl.haxx.se/

http://developer.force.com/join

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 [email protected] 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

[email protected]

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" :{


42


"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" :{


"messageSegments" : [{"type": "Text","text" : "New comment"

}]

}}

/services/data/v30.0/chatter/feed-items/0D5D0000000DaSbKAK/comments?text=New+comment


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" :{



43


"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" :{



"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


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:


Batch InputRequest body:

{"batchRequests" : [


{"method" : "Post","url" : "/v30.0/chatter/feed-items/feedItemId/likes"

},{

"method" : "Get","url" : "/v30.0/chatter/feed-items/feedItemId"

}],"haltOnError" : "false"

}

Batch ResultsReturns:

45


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 body example:

46


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:


This News Feed URL resource:/chatter/feeds/news/005xx000001Sv1mAAB


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


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:


/services/data/v30.0/chatter/feeds/news/me/feed-itemsExample:


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:


/services/data/v30.0/chatter/feeds/record/0F9D00000000I4O/feed-itemsExample:


Get a record feed with internal feed items only


GETHTTP method:

NARequest body:

showInternalOnlyRequest parameter:

/services/data/v30.0/chatter/feeds/record/0F9D00000000I4O/feed-items?showInternalOnly=trueExample:


48


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:


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


Subscription PageReturns:

Get Chatter activity statistics for a user

/chatter/users/userIdResource:

GETHTTP method:

NARequest body:


/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


NARequest body:


/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",


"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",


"cropY" : "20","fileId" : "069D00000001IOh"

}

PhotoReturns:

50


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


Group MemberReturns:

Request to join a private group

/chatter/groups/groupId/members/requestsResource:

POSTHTTP method:

NARequest body:


NARequest body example:

/services/data/v30.0/chatter/groups/0F9D000000006bOKAQ/members/requests


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


Group Membership RequestReturns:

51


Post to a group

/chatter/feeds/record/groupId/feed-itemsResource:

POSTHTTP method:

Feed Item InputRequest body:

TextRequest parameter:

{ "body" :{


"messageSegments" : [{"type": "Text","text" : "Check out the latest building proposal"

}]

}}

/feeds/record/0F9D000000006bO/feed-items?text=Has+everyone+seen+the+latest+building+proposal?


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


SubscriptionReturns:

Unfollow records

Note that a complete structured resource is not returned, just a return code.

/chatter/subscriptions/subscriptionIdResource:

DELETEHTTP method:

NARequest body:


52


/services/data/v30.0/chatter/subscriptions/0E8D00000001JkFKAUExample:

204: Successful DeleteReturns:

Get feed items for a record


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



Update a user profile

/chatter/users/userIdResource:

PATCHHTTP method:

aboutMeRequest parameter:

/services/data/v30.0/chatter/users/me?aboutMe=Writer+at+Salesforce


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


53


{ "cropSize" : "240","cropX" : "20",


"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"]

}


/services/data/v30.0/chatter/users/me/messages?recipients=005D0000001GOYpIAO,005D0000001GbdHIAS&text=Are+we+ready+for+next+week's+customer+meeting?


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:


/services/data/v30.0/chatter/users/batch/005D0000001Kl6xIAC,005D0000005J3D4HVB, . . .


Batch ResultsReturns:

54


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


"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


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


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


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:



},{


}]

}

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.


"method" : "Get","url" : "/v30.0/chatter/feeds/user-profile/men"

},{


}

60


],"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"


}]

}

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


{"method": "Post","url": "/v30.0/chatter/feeds/news/me/feed-items","binaryPartName": "binaryPart1","binaryPartNameAlias": "feedItemFileUpload","richInput": {

"attachment": {"attachmentType": "NewFile","description": "description1","title": "contentFile1"

},"body": {


"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


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


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": {


},"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


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


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




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


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




AvailableVersion

RequiredorOptional

DescriptionTypeName






JSON


}

Properties



Stringvisibility


68





AvailableVersion

RequiredorOptional

DescriptionTypeName





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.


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


69




AvailableVersion

RequiredorOptional

DescriptionTypeName






JSON


}

Properties



Stringvisibility




AvailableVersion

RequiredorOptional

DescriptionTypeName



70


AvailableVersion

RequiredorOptional

DescriptionTypeName



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.


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


HTTP methodsGET, HEAD


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


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.


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


HTTP methodsGET and HEAD

Response bodyConnect Directory

OrganizationInformation about the logged-in user’s organization and settings.

Resource

/connect/organization



Response bodyOrganization

72

Connect ResourcesChatter REST API Resources


{"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


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.



Request parameter


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




Request parameters

AvailableVersion

RequiredorOptional


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


AvailableVersion

RequiredorOptional


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




77


Request parameters


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.


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


78

Communities Moderation Feed ResourceChatter REST API Resources


GET parameters

AvailableVersion

RequiredorOptional



Stringpage




IntegerpageSize


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




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


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": {


},"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


"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": {


},"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": {


},"reference": {

"id": "005D0000001QdELIA0","url": "/services/data/v30.0/connect/communities/0DBD000000002etOAA

/chatter/users/005D0000001QdELIA0"},"text": "Abby Bass","type": "EntityLink"

}],"text": "Abby Bass"

},

81


"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

}


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.


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



82

Company Feed ResourcesChatter REST API Resources

Request parameters



Stringsort




Response bodyFeed


{"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



Request parameters

AvailableVersion

RequiredorOptional




• FewerUpdates—Displays all posts andcomments from people and records the user

83


AvailableVersion

RequiredorOptional


follows and groups the user is a member of, buthides system-generated posts from records thatnobody commented on.



Stringpage




IntegerpageSize



Stringq




Stringsort




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




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.


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



HTTP methodsGET, HEAD, or POST


Root XML tag<favorite>

85

Favorites Feed ResourcesChatter REST API Resources

JSON for POST

{"searchText" : "release","targetId" : "0TOD0000000099d"

}

Properties for POST


24.0Text of the feed search. Usethis parameter for feedsearches only.

StringsearchText

28.0Id of the topic. Use thisparameter for topics only.

StringtargetId




StringsearchText


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": {


},"mySubscription": null,"name": "Kristen Powell",

86


"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": {



},"mySubscription": null,"name": "Kristen Powell","photo": {

"fullEmailPhotoUrl":"https://instance_name/ncsphoto/g7O1xwgBO8dGwLadBRB8WWNbBNusiqjZbvaWEEu-3etqqIFpNksYLrC-v3JYOGjg",





}},{

"community": null,"createdBy": {

"companyName": "Powell Industries","firstName": "Kristen","id": "005D0000001Gif0IAC",

87


"isActive": true,"isInThisCommunity": true,"lastName": "Powell","motif": {








},"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": {








"url": "/services/data/v30.0/chatter/users/005D0000001Gif0IAC/photo"},"title": null,

88


"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": {




89







}}

],"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



HTTP methodsGET, HEAD, PATCH, or DELETE

Request parameter for GET or HEAD



Stringsort



90




Request body for PATCH

Root XML tag<favorite>

JSON for PATCH

{"updateLastViewDate" : "true"

}

Properties for PATCH


24.0Sets the last view date ofthe specified feed favorite

BooleanupdateLastViewDate

to the current system time.Default value is false.

Request parameter for PATCH


Sets the last view date of the specifiedfeed favorite to the current system time.Default value is false.


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





Request parameters

AvailableVersion

RequiredorOptional







Stringpage




IntegerpageSize



Stringq



92


AvailableVersion

RequiredorOptional



Stringsort






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/



Response bodyFeed Directory


{"favorites": [{


"companyName": "SeattleApps","firstName": "Rene","id": "005D0000001LFNnIAO","isActive": true,

93

Feeds ResourceChatter REST API Resources

"lastName": "Holmes","motif": {


},"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": {


},"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":


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


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




Request parameter



Stringsort




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


96




Request parameters

AvailableVersion

RequiredorOptional







Stringpage




IntegerpageSize



Stringq




Stringsort


97


AvailableVersion

RequiredorOptional






StringupdatedSince


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.


Resource

/chatter/feeds/files/me/feed-items/flat

or

/chatter/feeds/files/userId/feed-items/flat



98



Request parameters



IntegernumFeedItems



Stringpage









Filter Feed ResourcesThe filter feed is the news feed filtered to contain feed items whose parent is a specified object type.


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.



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



100



Request parameters



Stringsort




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


{"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


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




Request parameters

AvailableVersion

RequiredorOptional







Stringpage



102


AvailableVersion

RequiredorOptional



IntegerpageSize



Stringq




Stringsort






StringupdatedSince


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


"isInThisCommunity": true,"lastName": "Li","motif": {



"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"


"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",


},"likesMessage": null,"moderationFlags": null,"modifiedDate": "2013-09-10T00:28:16.000Z","myLike": null,"originalFeedItem": null,"originalFeedItemActor": null,"parent": {


104








/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": {


"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": {


105


},"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": {











"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",


},

106


"likesMessage": null,"moderationFlags": null,"modifiedDate": "2013-09-04T22:38:42.000Z","myLike": null,"originalFeedItem": null,"originalFeedItemActor": null,"parent": {














},"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


"text": "Connect","type": "EntityLink"

},{

"text": ".","type": "Text"

}],"text": "Deanna Li created the public group Connect."

},"relativeCreatedDate": "September 4, 2013 at 3:38 PM","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.


Resource

/chatter/feeds/filter/me/feed-items/flat

or

/chatter/feeds/filter/userId/feed-items/flat




Request parameters



IntegernumFeedItems

and 100. Default value is 25. Becausefeed items may include comments,specifying 25 flat feed items may

108



actually return more. For example, ifeach feed item has one comment, andrecentCommentCount is greater than1, 50 flat feed items are returned.


Stringpage








Groups Feed ResourcesA feed containing all feed items from all groups the current user either owns or is a member of.


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


109

Groups Feed ResourcesChatter REST API Resources



Request parameters



Stringsort




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




110


Request parameters

AvailableVersion

RequiredorOptional







Stringpage




IntegerpageSize



Stringq




Stringsort




111


AvailableVersion

RequiredorOptional




StringupdatedSince


Groups Feed Items FlatThis resource is deprecated as of version 26.0.


Resource

/chatter/feeds/groups/me/feed-items/flat

or

/chatter/feeds/groups/userId/feed-items/flat




Request parameters



IntegernumFeedItems


112




Stringpage








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.


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




Request parameter



Stringsort




Response bodyFeed


{"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


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



115



Request parameter

AvailableSince

Required orOptional


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



HTTP methodsGET, POST, HEAD

116



AvailableVersion

RequiredorOptional







Stringpage




IntegerpageSize



Stringq




Stringsort




117


AvailableVersion

RequiredorOptional




StringupdatedSince


Root XML tag<feedItem>

JSONThe following example attaches a poll to a feed item:

{ "attachment":{

"attachmentType":"Poll","pollChoices": [

"Monday","Tuesday"

]},"body" : {


"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


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


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


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.


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


AvailableVersion

RequiredorOptional


27.0RequiredThe attachment type. Must contain the valueNewFile.


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.



24.0RequiredFile name of a file to be uploaded and posted.Stringtitle




Default values:

• For external users, the default value is AllUsers.External users must use this value to see theirposts.



Parameters for posting a link

121


AvailableVersion

RequiredorOptional


27.0RequiredThe attachment type. Must contain the valueLink.


26.0OptionalSpecifies if the new feed item should bebookmarked for the user (true) or not(false). Default value is false.



23.0RequiredURL of the link.Stringurl

23.0OptionalName of the URL.StringurlName


• 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


27.0RequiredThe attachment type. Must contain the valuePoll.




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


AvailableVersion

RequiredorOptional





Default values:




Parameters for sharing a post

AvailableVersion

RequiredorOptional




24.0RequiredThe ID of the feed item you want toshare.18-character ID


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




Default values:

123


AvailableVersion

RequiredorOptional





Parameters for posting text only

AvailableVersion

RequiredorOptional




23.0RequiredText of the feed item. The maximum numberof characters is 1000.

Stringtext




Default values:




Parameters for posting a canvas app

124


AvailableVersion

RequiredorOptional


29.0RequiredThe attachment type. Must contain the valueCanvas.


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




Default values:




Response body for GET or HEADFeed Item Page

125


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


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.


Resource

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

or

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



127



Request parameters



IntegernumFeedItems



Stringpage









People Feed ResourcesAll feed items posted by all of the people the logged-in user follows.


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




Request parameters



Stringsort




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





Request parameters

AvailableVersion

RequiredorOptional







Stringpage




IntegerpageSize



Stringq



130


AvailableVersion

RequiredorOptional



Stringsort






StringupdatedSince


People Feed Items FlatThis resource is deprecated as of version 26.0.


Resource

/chatter/feeds/people/me/feed-items/flat

or

/chatter/feeds/people/userId/feed-items/flat




131


Request parameters



IntegernumFeedItems



Stringpage









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.


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.



Request parameters



Stringsort




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


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.




AvailableVersion

RequiredorOptional







Stringpage



134


AvailableVersion

RequiredorOptional



IntegerpageSize



Stringq



30.0OptionalSpecifies whether to show only feed items frominternal (non-community) users (true), or not(false). The default value is false.

BooleanshowInternalOnly


Stringsort






StringupdatedSince




{ "attachment":{


"Monday","Tuesday"

]},"body" : {


135



}]

}}

Properties

AvailableVersion

DescriptionTypeName





• Attachment Input: Feed Poll (v26.0)• Attachment Input: Link (v23.0)• Attachment Input: New File Upload

(v23.0)












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


AvailableVersion

DescriptionTypeName

shared post. You should onlyshare a post or upload a file, notboth in the same post.


Stringvisibility



Default values:


• For internal users, the default valueis InternalUsers. Internal userscan accept this value or use the valueAllUsers to allow external users tosee their posts.




AvailableVersion

RequiredorOptional








137


AvailableVersion

RequiredorOptional





Default values:





AvailableVersion

RequiredorOptional













138


AvailableVersion

RequiredorOptional





Default values:





AvailableVersion

RequiredorOptional












Default values:


139


AvailableVersion

RequiredorOptional





AvailableVersion

RequiredorOptional












Default values:





140


AvailableVersion

RequiredorOptional











Default values:





AvailableVersion

RequiredorOptional





Stringtext

141


AvailableVersion

RequiredorOptional





Default values:





AvailableVersion

RequiredorOptional







Stringheight






Stringparameters



StringthumbnailUrl

142


AvailableVersion

RequiredorOptional






Default values:






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": {


143



"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5savQXz9sPZRCJJB7fC4UIka",


"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5saluKolvB94ZwqX5yHBSBOh",



"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",


},"likesMessage": null,"modifiedDate": "2012-09-12T01:01:42.000Z","moderationFlags": null,"myLike": null,"originalFeedItem": null,"originalFeedItemActor": null,"parent": {


"color": "1797C0","largeIconUrl": "/img/icon/profile64.png",

144


"mediumIconUrl": "/img/icon/profile32.png","smallIconUrl": "/img/icon/profile16.png"


"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5savQXz9sPZRCJJB7fC4UIka",


"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5saluKolvB94ZwqX5yHBSBOh",



"messageSegments": [{"motif": {


},"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.


Resource

/chatter/feeds/record/me/feed-items/flat

or

/chatter/feeds/record/userId/feed-items/flat

145





Request parameters



IntegernumFeedItems



Stringpage








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


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




Request parameters



Stringsort




Response bodyFeed

147


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




Request parameters

AvailableVersion

RequiredorOptional







Stringpage



148


AvailableVersion

RequiredorOptional



IntegerpageSize



Stringq




Stringsort





To Feed Items FlatThis resource is deprecated as of version 26.0.


Resource

/chatter/feeds/to/me/feed-items/flat

or

/chatter/feeds/to/userId/feed-items/flat



149



Request parameters



IntegernumFeedItems



Stringpage









Topics Feed ResourcesThe feed of the specified topic.


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



Request parameters



Stringsort




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



151

Topics Feed ResourcesChatter REST API Resources

Request parameters

AvailableVersion

RequiredorOptional



Stringpage

of the response body, in one of the URLparameters, such as nextPageURL.


IntegerpageSize


Stringsort






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.


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



Request parameters



Stringsort




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


Resource

/chatter/feeds/user-profile/me/feed-items

or

/chatter/feeds/user-profile/userId/feed-items






{ "attachment":{


"Monday","Tuesday"

]},"body" : {



}]

}}

Properties

AvailableVersion

DescriptionTypeName





• Attachment Input: Feed Poll (v26.0)• Attachment Input: Link (v23.0)

154


AvailableVersion

DescriptionTypeName

• Attachment Input: New File Upload(v23.0)












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.


Stringvisibility



Default values:

155


AvailableVersion

DescriptionTypeName


• For internal users, the default valueis InternalUsers. Internal userscan accept this value or use the valueAllUsers to allow external users tosee their posts.




AvailableVersion

RequiredorOptional











Default values:




156



AvailableVersion

RequiredorOptional
















Default values:





157


AvailableVersion

RequiredorOptional












Default values:





AvailableVersion

RequiredorOptional









158


AvailableVersion

RequiredorOptional





Default values:





AvailableVersion

RequiredorOptional











Default values:

159


AvailableVersion

RequiredorOptional






AvailableVersion

RequiredorOptional





Stringtext




Default values:





160


AvailableVersion

RequiredorOptional







Stringheight






Stringparameters



StringthumbnailUrl





Default values:




161



AvailableVersion

RequiredorOptional







Stringpage

of the response body, in one of the URLparameters, such as nextPageURL, , for example:



IntegerpageSize



Stringq




Stringsort




162




User-Profile Feed Items FlatThis resource is deprecated as of version 26.0.


Resource

/chatter/feeds/user-profile/me/feed-items/flat

or

/chatter/feeds/user-profile/userId/feed-items/flat



Request parameters



IntegernumFeedItems



Stringpage







163




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.


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



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



Request parameters

AvailableSince

RequiredorOptional


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.


28.0OptionalThe sort order of the results. Values are:Stringsort

• CreatedDateDesc

165

Feed-Items QueryChatter REST API Resources

AvailableSince

RequiredorOptional


• LastModifiedDateDesc

The default value is CreatedDateDesc.


Feed-Items, Specific Feed ItemAccess, delete, or bookmark a specific feed item.

Resource

/chatter/feed-items/feedItemId


HTTP methodsGET, DELETE, PATCH, or HEAD

Request body for PATCHThe root XML tag is <feedItem>.


Specify true to add the current feeditem to the list of bookmarked feed


items for the current user. Specifyfalse to remove this feed item fromthe list of bookmarked feed items forthe current user.



Specify true to add the current feeditem to the list of bookmarked feed


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




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.


24.0RequiredID of an existing file to be posted.StringcontentDocumentId

23.0OptionalText of the comment.Stringtext

Parameters for posting text


23.0RequiredThe comment text.Stringtext



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




Note: There aren’t any request parameters for POST.


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": {



"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5saBc65JKjmm4DaxyLRr1XQK",


"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZNDZe0BfzuOg1WyB6Vo-DB",


}}],"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.


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


Root XML tag<feedPoll>

Properties


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


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


HTTP methodsDELETE, POST

Request parameter for DELETE


28.0RequiredID of an existing topicStringtopicId

171

Feed-Items TopicsChatter REST API Resources


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



28.0Required for existingtopics if the


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.


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.


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.


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.


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



173

Files ResourcesChatter REST API Resources

HTTP methodsGET, POST, PATCH, DELETE, or HEAD

Note: POST, PATCH, and DELETE available since version 26.0.


Root XML tag<fileInput>

JSON

{"desc" : "Employee Survey Results","title" : "emp_surv_results"

}

Properties


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


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.



Request parameters for GET and HEAD

Get information about the specified file.

174


AvailableVersion

DescriptionTypeName

23.0Specify an existing version number for the file. If notspecified, the latest version is returned.

IntegerversionNumber


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.


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


HTTP methodsGET

175


Request parameters

AvailableVersion

DescriptionTypeName

23.0Specify an existing version number for the file. If notspecified, the latest version is returned.


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


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


Root XML tag<fileShares>

JSON example

{"message": "I shared a document with you.","shares": [

{ "id": "005D0000001Az4l", "sharingType": "V" },

176


{ "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 Shares LinkA description of a file shared as a link. Create, access, and delete a file’s share link.

Resource



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


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


DescriptionTypeName

Specify the type of rendition to bereturned. Default value isTHUMB120BY90. Valid values are:

Stringtype

• FLASH

• PDF

• 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



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.


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.


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



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


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


Resource

/chatter/folders/folderId/items




AvailableVersion


30.0OptionalAn integer specifying a page of items. The defaultvalue is 0, which returns the first page.

Integerpage


IntegerpageSize

Response body for GETFolder Item Page


Folder Item Input

Request parameters for POSTAdd a file to a folder

AvailableVersion


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


30.0RequiredThe path to the folderStringfolderPath

30.0RequiredThe item type. To create a folder, the value mustbe Folder.

Stringtype

181


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.


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



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


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.


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



AvailableRequired orOptional


29.0Optionaltrue if this group allows Chatter customers, falseotherwise. After this property is set to true, itcannot be set to false.


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.


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":

[email protected]_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


"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": {




"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":

[email protected]_name.chatter.salesforce.com,"fileCount": 0,"id": "0F9D00000000FG0KAM",

186


"information": {"text": null,"title": null


"color": "1797C0","largeIconUrl": "/img/icon/groups64.png","mediumIconUrl": "/img/icon/groups32.png","smallIconUrl": "/img/icon/groups16.png"


"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": {


},"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": {


"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


"previousPageUrl": null}

Group InformationInformation about a group.

Resource

/chatter/groups/groupId


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


this property is set to true, it cannotbe set to false.

188

Group InformationChatter REST API Resources

AvailableVersion

DescriptionTypeName


28.0The “Information” section of thegroup If the group is private, the


“Information” section is visible only tomembers. The “Description” sectionis visible to everyone.


BooleanisArchived





Stringowner


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



AvailableVersion

Required orOptional


29.0Optionaltrue if this group allows Chatter customers, falseotherwise. After this property is set to true, it cannot beset to false.


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.


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


"emailToChatterAddress":[email protected]_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": {



"id": "0FBD00000002vOVOAY","url": "/services/data/v30.0/chatter/group-memberships/0FBD00000002vOVOAY"

},"name": "App Builders","owner": {




"fullEmailPhotoUrl":"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sa4idjK69Im5uTYfmFricjT",


"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sbMgjs7ldMuVclujIS-dbL9",


},"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


},"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.



Response bodyBatch Results

Group FilesReturns information about the files posted to the specified group.

Resource

/chatter/groups/groupID/files



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


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





Root XML tag<member>

Properties


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




Integerpage



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": {


},

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


HTTP methodsGET, HEAD, and POST

Request parameter for GET


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


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


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


"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",


}}],"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": {


},"mySubscription": null,"name": "Gordon Johnson","photo": {


"largePhotoUrl": "https://instance_name/profilephoto/729D00000000LJL/F",

197


"photoVersionId": "729D00000000LJLIA2","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000LJL/T","standardEmailPhotoUrl":

"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cPhKrC7plNhUw5eOz7Aj1u-6d5rE2mNaMaBZfGnFX65O",


}}

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


HTTP methodsGET, HEAD, and PATCH

Request body for PATCHGroup Membership Request Update



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": {





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


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.


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



HTTP methodsGET, DELETE, HEAD, PATCH

PATCH is supported in version 29.0.


Root XML tag<member>

JSON example

{"role" : "GroupManager","userId" : "005B0000000Ge16"

}

Properties



Stringrole

• GroupManager

• StandardMember


StringuserId

Note: To update a group member’s role in a PATCH request, pass only the role property, don’t pass theuserId property.

200





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:


Resource

/chatter/group-memberships/batch/membershipIds

Where membershipIds is a comma separated list of membership IDs.



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


"user": {"companyName": "Universal Containers","firstName": "Gordon","id": "005D0000001LLO1IAO","isActive": true,"isInThisCommunity": true,"lastName": "Johnson","motif": {


},"mySubscription": {

"id": "0E8D0000000T5ZUKA0","url": "/services/data/v30.0/chatter/subscriptions/0E8D0000000T5ZUKA0"

},"name": "Gordon Johnson","photo": {


"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"


}]

}

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


HTTP methodsGET, POST, DELETE, or HEAD


Root XML tag<photo>

JSON example

{ "cropSize" : "120","cropX" : "0","cropY" : "0","fileId" : "069D00000001IOh"

}

Properties

AvailableVersion


29.0Required to crop an uploadedfile or an existing file.

The length, in pixels, of any edgeof the crop square.

IntegercropSize


The position X, in pixels, fromthe left edge of the image to thestart of the crop square. Top leftis position (0,0).

IntegercropX


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.


203




29.0Required to crop anuploaded file or anexisting file.

The length, in pixels,of any edge of the cropsquare.

IntegercropSize


The position X, inpixels, from the leftedge of the image tothe start of the crop

IntegercropX

square. Top left isposition (0,0).


The position Y, inpixels, from the topedge of the image tothe start of the crop

IntegercropY



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


provided, the latestversion is used.

Note: Photos are processed asynchronously and may not be visible right away.

204


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


HTTP methodsGET, HEAD, or 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



27.0The frequency with which agroup member receives email


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



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


HTTP methodGET or HEAD

Response bodyInfluence Thresholds


{"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


HTTP methodsGET, DELETE or HEAD

Response body for GET or HEADLike


{"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"




"https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cEw-MQI3xmkJ21oNEOQ-5sZNDZe0BfzuOg1WyB6Vo-DB",


}}

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




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




AvailableSince


29.0RequiredThe feed item parent ID (for new feed items)or feed item ID (for comments).

StringparentId

210

Mentions ValidationsChatter REST API Resources

AvailableSince


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.


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


211

Motifs ResourcesChatter REST API Resources


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





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



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


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



214

Record View SearchChatter REST API Resources


AvailableVersion

Required orOptional


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:


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


ExampleThis GET request searches for any records whose fields contain the characters “th” plus any additional characters:

GET /connect/records?q=th*


{"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


"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 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",



} ],"id" : "001D000000I8eltIAB","motif" : {"color" : "236FBD","largeIconUrl" : "/img/icon/accounts64.png","mediumIconUrl" : "/img/icon/accounts32.png","smallIconUrl" : "/img/icon/accounts16.png"

},

217


"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 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",



} ],"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


"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" : "Company","text" : "Key Shoppe","type" : "Text"

}, {"label" : "Email","text" : null,"type" : "Email"

}, {"label" : "Lead Status","text" : "Open - Not Contacted","type" : "Picklist"

} ],

219


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


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



Response bodyRecord Summary

220

Records ResourcesChatter REST API Resources


{"id": "069D00000001FHFIA2","motif": {

"largeIconUrl": "/img/content/content64.png","mediumIconUrl": "/img/content/content32.png","smallIconUrl": "/img/icon/files16.png"


"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


As of version 29.0, you can use a topic ID for the recordId.


Request parameters


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


HTTP methodsGET, DELETE, POST



30.0RequiredID of an existing topicStringtopicId



Root XML tag<topicAssignment>

JSONThe following example assigns a topic to a record:

{ "topicId": "0TOD0000000090r"}

Properties

AvailableVersion


30.0Required for existing topicsif the topicName propertyisn’t used.

ID of an existing topic.StringtopicId


Name of a new or existingtopic.

StringtopicName

the topicId property isn’tused.

222

Topics on Records ResourceChatter REST API Resources



30.0Required for existingtopics if the


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


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.


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


In version 28.0, use /chatter/topics.


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.


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


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


In version 28.0, use /chatter/topics/suggestions.


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


In versions 24.0–28.0, use /chatter/topics/trending.


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


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


In version 28.0, use /chatter/topics/topicId.

HTTP methodsGET, PATCH, DELETE, and HEAD


Root XML tag<topic>

JSON

{"description" : "World Wide Web Consortium (W3C) is the main international

standards organization for the Web.""name" : "W3C"}

Properties


28.0Text description of thetopic

Stringdescription

28.0Name of the topic. Use thisproperty to change only the

Stringname

capitalization and spacingof the topic 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


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 SinceRequired or OptionalDescriptionTypeParameter Name


Integerpage

page of endorsements.The default value iszero.


IntegerpageSize


231

Topics, Endorse PeopleChatter REST API Resources


Root XML tag<topicEndorsement>

JSON

{"userId" : "005B0000000Ge16"

}

Properties

Available VersionRequired orOptional

DescriptionTypeName

30.0RequiredID of the user to beendorsed for thespecified topic.

StringuserId



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


HTTP methodsGET, HEAD, DELETE

Response body for GETTopic Endorsement

232

Topic EndorsementsChatter REST API Resources


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


HTTP 204

Topic FilesReturns information about the five files most recently posted to the specified topic.

Resource

/connect/topics/topicId/files


In version 28.0, use /chatter/topics/topicId/files.



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"


"id": "0E8D0000000T5JrKAK","url": "/services/data/v30.0/chatter/subscriptions/0E8D0000000T5JrKAK"

},"name": "Recruitment Poster","origin": "Chatter","owner": {


"color": "1797C0","largeIconUrl": "/img/icon/profile64.png","mediumIconUrl": "/img/icon/profile.png","smallIconUrl": "/img/icon/profile.png"



"largePhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/F","photoVersionId": "729D00000000BDV","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/T","standardEmailPhotoUrl":


"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"


}

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


In version 28.0, use /chatter/topics/topicId/groups.


Response bodyGroup Page


"currentPageUrl": "/services/data/v30.0/chatter/groups","groups": [

{"canHaveChatterGuests": false,"community": null"description": "Get company announcements and other important updates","emailToChatterAddress":

[email protected]_name.chatter.salesforce.com,"fileCount": 0,"id": "0F9D00000000FG0KAM","information": {

"text": null,"title": null




"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": {


},"mySubscription": null,"name": "Marion Raven","photo": {

235

Topic GroupsChatter 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"},"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001Kl6xIAC","userType: "Internal"

},"pendingRequests": 0,"photo": {


"largePhotoUrl": "https://instance_name/profilephoto/729D00000000BDQ/F","photoVersionId": "729D00000000BDQ","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000BDQ/T","standardEmailPhotoUrl": "https://instance_name/ncsphoto/


},"type": "CollaborationGroup","url": "/services/data/v30.0/chatter/groups/0F9D00000000FG0KAM","visibility": "PublicAccess"


}

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



Request parameters



Integerpage


236

Topics, Knowledgeable People ListChatter REST API Resources



IntegerpageSize


Response bodyKnowledgeable People Collection

Related TopicsList of five topics most closely related to the specified topic.

Resource

/connect/topics/topicId/related-topics


In version 28.0, use /chatter/topics/topicId/relatedtopics.



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



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


HTTP methodsGET, HEAD, DELETE

Response body for GETTopic Opt Out


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


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


238

Topics, Opt Out from Knowledgeable People ListChatter REST API Resources

http://help.salesforce.com


Parameters


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.


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



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


241

User Profile InformationChatter REST API Resources

PATCH available in 29.0

HTTP methodsGET, HEAD, PATCH


Root XML tag<user>

Properties


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."}



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


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": "[email protected]","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": {


},"mySubscription": null,"name": "Marion Raven","phoneNumbers": [{

"phoneNumber": "(206) 999-2846","type": "Work"

}],"photo": {


243


"largePhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/F","photoVersionId": "729D00000000BDV","smallPhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/T","standardEmailPhotoUrl": "https://instance_name/ncsphoto/


},"thanksReceived": null,"title": null,"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001Kl6xIAC","userType": "Internal","username": "[email protected]"

}

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.




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



244

Batch User InformationChatter REST API Resources



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


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



HTTP methodsGET, PATCH, or HEAD




OptionalStringq


Note: Thequeryparameteronly searchesmessage textbodies, notuser names,titles, and soon.


Root XML tag<conversation>

246

User Conversations, SpecificChatter REST API Resources

Properties


24.0Changes the conversationstatus to unread (false)or read (true).

Booleanread



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


24.0Changes the conversationstatus to unread (false)or read (true).

Booleanread

247

Change Status of ConversationsChatter REST API Resources

Request parameters


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



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


HTTP methodsGET, POST, or HEAD


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.


JSON

{"desc":"Employee Survey Results","title":"emp_surv_results"

}

Properties



Stringdesc



folder, and is syncedbetween that folder andChatter; false otherwise.




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


between that folder and Chatter; falseotherwise.

24.0Title of the fileStringtitle

249

Users Files, GeneralChatter REST API Resources




Integerpage



IntegerpageSize



Stringq


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



Request parameters



Integerpage



IntegerpageSize



Stringq



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



Request parameters



Integerpage



IntegerpageSize



Stringq



User FollowersReturns information about the followers for the specified user.

Resource

/chatter/users/me/followers

or

/chatter/users/userId/followers


252

User FollowersChatter REST API Resources


Request parameters



Integerpage


IntegerpageSize


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


Following topics is available since version 29.0.

HTTP methodsGET, POST, or HEAD


Root XML tag<following>

253

FollowingChatter REST API Resources

Properties


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.



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


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.


Integerpage


IntegerpageSize


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



Request parameters

AvailableVersion

Required orOptional


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



Request parameters



Integerpage



IntegerpageSize


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





Root XML tag<message>

Properties


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"}



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



23.0A page token thatindicates where

OptionalStringpage

retrieval begins. Getthis token from theNextPageUrlproperty in theresponse body.

23.0Specifies the numberof items per page.

OptionalIntegerpageSize



OptionalStringq


Note: Thequeryparameter

258



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": {




"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_",


},"title": "Senior Manager",

259


"type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LFNnIAO","userType": "Internal"

},{

"companyName": null,"firstName": "Desmond","id": "005D0000001LJvOIAW","isActive": true,"lastName": "Catillo","motif": {


},"mySubscription": null,"name": "Desmond Catillo","photo": {






},"title": "Senior Manager","type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LJvOIAW","userType": "Internal"

}],"sender": {








"url": "/services/data/v30.0/chatter/users/005D0000001LLO6IAO/photo"},"title": "Senior Manager","type": "User",

260


"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": {








},"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": {


},"mySubscription": null,"name": "Desmond Catillo","photo": {


261






},"title": "Senior Manager","type": "User","url": "/services/data/v30.0/chatter/users/005D0000001LJvOIAW","userType": "Internal"

}],"sender": {








"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




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




Root XML tag<photo>

JSON example

{ "cropSize" : "120","cropX" : "0","cropY" : "0",

263

User PhotoChatter REST API Resources

"fileId" : "069D00000001IOh"}

Properties

AvailableVersion




IntegercropSize


The position X, in pixels, fromthe left edge of the image to thestart of the crop square. Top leftis position (0,0).

IntegercropX


The position Y, in pixels, fromthe top edge of the image to thestart of the crop square. Top leftis position (0,0).

IntegercropY


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.





The length, in pixels,of any edge of the cropsquare.

IntegercropSize


The position X, inpixels, from the leftedge of the image tothe start of the crop

IntegercropX



The position Y, inpixels, from the topedge of the image tothe start of the crop

IntegercropY

264

User PhotoChatter REST API Resources




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


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




Request parameters


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


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.


266

User Recommendations for a Specific ActionChatter REST API Resources


Request parameters



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


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



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



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


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



◊ 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).






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



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



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





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


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.





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.


271

User Records, Recently UsedChatter REST API Resources

HTTP methodsGET, HEAD, or 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.



27.0The default frequency withwhich a user receives email


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


Root XML tag<userStatus>

Properties


23.0–24.0Description of messagebody.



DescriptionTypeName

Text of the item to be posted to theuser's status

String Text to posttext

Response body for GET or POSTUser Status


<?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




Zones ResourcesInformation about Chatter Answers zones.


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/


HTTP methodsGET



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


HTTP methodsGET

Response body for GETZone

Zone Search ResultsSearch results from a search in a Chatter Answers zone.

Resource

/connect/zones/zoneId/search-results


275

Zone InformationChatter REST API Resources

HTTP methodsGET



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.


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


27.0The attachment type. Mustcontain the valueExistingContent.


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":{


"Monday","Tuesday"

]}

}

Properties


27.0The attachment type. Mustcontain the value Poll.


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


27.0The attachment type. Mustcontain the value Link.


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


27.0The attachment type. Must contain thevalue NewFile.


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


version 27.0. Usedescription instead.

27.0Optional. Description of the file.Stringdescription


Batch InputRoot XML Tag

<batch>

JSON



},{


}]

}

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" : {


"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


23.0Description of message bodyMessage Body Inputbody

Dashboard Component Snapshot InputRoot XML tag

<dashboardComponentSnapshot>

JSON

{"parentId" : "0F9D00000000I4O","feedItemBody" : {


"text" : "Sales Heat","type" : "Text"

}]

}}

Properties


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


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



StringsearchText


StringtargetId

JSON for PATCH

{"updateLastViewDate" : "true"

}

Properties for PATCH


24.0Sets the last view date of thespecified feed favorite to the


current system time. Defaultvalue is false.

285

Feed Favorite InputChatter REST API Request Bodies

Feed Item InputRoot XML tag

<feedItem>


{ "attachment":{


"Monday","Tuesday"

]},"body" : {



}]

}}

Properties

AvailableVersion

DescriptionTypeName

Optional. You can specify only one of thesevalues in the attachment parameter. Valuesare:


• 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)



If you specify originalFeedItemId toshare a feed item, use the body propertyto add a comment to the feed item.


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.




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.


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


29.0Required for existing topics ifthe topicName property isn’tused



Name of a new or existingtopic, up to 150 characters

StringtopicName

the topicId property isn’tused

Feed Poll InputRoot XML tag

<feedPoll>

Properties


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.


JSON

{"desc":"Employee Survey Results","title":"emp_surv_results"

}

288

Feed Poll InputChatter REST API Request Bodies

Properties



Stringdesc



folder, and is synced betweenthat folder and Chatter;false otherwise.



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


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


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


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


23.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:


• 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


property is set to true, it cannot be setto false.


28.0The “Information” section of the groupIf the group is private, the “Information”


section is visible only to members. The“Description” section is visible toeveryone.

292

Group InputChatter REST API Request Bodies

AvailableVersion

DescriptionTypeName


BooleanisArchived





Stringowner


Stringvisibility

• PublicAccess

• PrivateAccess

Group Member InputRoot XML tag

<member>

JSON example

{"role" : "GroupManager","userId" : "005B0000000Ge16"

}

Properties



Stringrole

• GroupManager

• StandardMember


StringuserId

Group Membership Request UpdateRoot XML tag

<groupMembershipRequestUpdate>

293

Group Member InputChatter REST API Request Bodies

Properties


27.0Use this property to provide a message to theuser if their membership request is declined.


The value of this property is used only whenthe value of the status property isDeclined.


27.0Valid values:Stringstatus

• Accepted

• Declined

Message Body Input


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.


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


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.


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.


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.


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


}

Properties


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.


Photo InputDescribes a photo input.

Root XML tag<photo>

JSON example

{ "cropSize" : "120","cropX" : "0","cropY" : "0","fileId" : "069D00000001IOh"

}

Properties

AvailableVersion




IntegercropSize

296

Moderation Flag InputChatter REST API Request Bodies

AvailableVersion



The position X, in pixels, from theleft edge of the image to the startof the crop square. Top left isposition (0,0).

IntegercropX


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.


Share InputJSON example

{"id": "005D0000001Az4l","sharingType": "V"

}

Properties


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


30.0Required for existing topics ifthe topicName property isn’tused.

ID of an existing topic.StringtopicId


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


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:


• 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


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


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


23.018-character ID of the userwho receives the message.

Stringrecipient

User Message Recipient List InputRoot XML tag

<message>

Properties


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


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


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



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



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



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


(v26.0)• Group Member for

/chatter/group-memberships/batch/membershipIds

(v27.0)• Group for

/chatter/groups/batch/groupIds

(v23.0)• Motif for


(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



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



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



24.0Small, 29.0Percentile value for the user’s influence rank withinthe organization or community

Stringpercentile

305

Chatter ActivityChatter REST API Response Bodies

AvailableVersion



24.0Small, 29.0Number indicating the user’s influence rank, relativeto all other users within the organization orcommunity

Integerrank

ClientInfo

AvailableVersion



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



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



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



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



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



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



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



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



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



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


23.0Small, 29.0URL to the next page of messages, that is, olderconversations

StringnextPageUrl

Conversation Unread Count

AvailableVersion



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



29.0Small, 29.0Display name for an email addressStringdisplayName

29.0Small, 29.0Email addressStringemailAddress

Error Message

AvailableVersion



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



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



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



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



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



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



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



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



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



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



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



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



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—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



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



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



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


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


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


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


AvailableVersion



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.


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


AvailableVersion



• 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 Item Attachment: Basic Template

AvailableVersion

Filter Typeand Version


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



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.


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



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



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.


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


322

Feed Item Attachment: ContentChatter REST API Response Bodies

AvailableVersion



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.













23.0Small, 29.0Title of the fileStringtitle

27.0Small, 29.0ContentStringtype

23.0Medium, 29.0Version Id of the fileStringversionId

Feed Item Attachment: Link

AvailableVersion



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



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



29.0Small, 29.0A representation of a record.Record ViewrecordView

29.0Small, 29.0RecordSnapshotStringtype

Feed Item Attachment: Tracked Change

AvailableVersion



29.0Small, 29.0Collection of feed tracked changes.Feed TrackedChange[]

changes

29.0Small, 29.0TrackedChangeStringtype

Feed Item Page

AvailableVersion



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



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







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



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



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



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



by 100 to get the percentage of votes cast for thispoll choice.

Feed Tracked Change

AvailableVersion



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



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



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



• N—No access

• V—Viewer

File Shares Page

AvailableVersion



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



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.


328

File Shares PageChatter REST API Response Bodies

AvailableVersion



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


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


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.


StringrecordViewUrl


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



29.0Medium, 29.0URL to the 240px by 180px rendition for the file,if available. Renditions are processed asynchronously


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


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:


















24.0Small, 29.0Title of the fileStringtitle

24.0Small, 29.0ContentDocumentStringtype

330

File SummaryChatter REST API Response Bodies

AvailableVersion



24.0Small, 29.0URL for the fileStringurl

24.0Medium, 29.0Version number of the fileStringversionNumber

File Summary Page

AvailableVersion



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



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



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



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.


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


StringrecordViewUrl


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



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



30.0Medium, 30.0Chatter REST API URL identifying the currentpage.


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



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


StringnextPageUrl



23.0Small, 29.0Total number of followersIntegertotal

Following Counts

AvailableVersion



23.0Small, 29.0Number of people the user is followingIntegerpeople

333

Folder Item PageChatter REST API Response Bodies

AvailableVersion



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



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



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.


23.0Small, 29.0true if this group allows Chatter customers, falseotherwise


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



29.0Big, 29.0Specifies whether automatic archiving is disabledfor the group (true) or not (false).


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


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


StringrecordViewUrl


23.0Small, 29.0CollaborationGroupStringtype

23.0Small, 29.0Relative URL string to the groupStringurl

335

GroupChatter REST API Response Bodies

AvailableVersion



23.0Small, 29.0Values are:Stringvisibility

• PrivateAccess

• PublicAccess

Group Chatter SettingsA user’s Chatter settings for a specific group.

AvailableVersion



27.0Small, 29.0The frequency with which a group member receivesemail from a group. One of the following values:


• 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



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.


23.0Small, 29.0true if this group allows Chatter customers, falseotherwise


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



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


• StandardMember

23.0Medium, 29.0If the logged-in user is a member of this group, thiscontains information about that subscription, orreturns null otherwise


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


StringrecordViewUrl


337

Group DetailChatter REST API Response Bodies

AvailableVersion



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



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



23.0Small, 29.018-character ID of the group membershipStringid

23.0Small, 29.0Values are:Stringrole

• GroupOwner

• GroupManager

• NotAMember


• 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



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



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


used only when the value of the status propertyis Declined.


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



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



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



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



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



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



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





30.0Small, 30.0Collection of knowledgeable people response bodiesKnowledgeablePeople[]

knowledgeableUsers


StringnextPageUrl

341

Knowledgeable PeopleChatter REST API Response Bodies

AvailableVersion





Like

AvailableVersion

Filter Groupor Version


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






• Message Segment: Resource Link


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



23.0Medium, 29.0URL to the current page of likesStringcurrentPageUrl

23.0Small, 29.0Collection of likesLike[]likes

342

LikeChatter REST API Response Bodies

AvailableVersion



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



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



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



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



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



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



27.0Small, 29.0Small, medium, and large icons indicating the typeof the object. The motif can also contain the object’sbase color.


Motifmotif

23.0Medium, 29.0If the logged-in user is following this file, thiscontains information about the subscription;otherwise returns null.


23.0Small, 29.0The localized name of this record.Stringname


StringrecordViewUrl


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



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



29.0Big, 29.0An additional label (if one exists) for the recordrepresented by this completion, for example,“(Customer)” or “(Acme Corporation)”.


345

List View SortChatter REST API Response Bodies

AvailableVersion



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







Mention Completion PageA paginated list of Mention Completion response bodies.

AvailableVersion



29.0Medium, 29.0URL of the current pageStringcurrentPageUrl

29.0Small, 29.0Collection of Mention Completion response bodiesto use in a mention.

MentionCompletion[]

mentionCompletions


StringnextPageUrl



346

Mention Completion PageChatter REST API Response Bodies

Mention ValidationInformation about whether a proposed mention is valid for the context user.

AvailableVersion



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



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



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


StringsentDate

23.0Small, 29.0Information about the user who sent this messageUser Summarysender

23.0Small, 29.0URL to this messageStringurl

Message Collection

AvailableVersion





23.0Small, 29.0Collection of one or more messagesMessage[]messages


StringnextPageUrl

348

MessageChatter REST API Response Bodies

Message Segment: Entity LinkRepresents an entity, such as a user or a group.

AvailableVersion



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




Segments[]segments


• 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


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



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



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



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



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



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



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



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



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



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



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:


},

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



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



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



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


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



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



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



• 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



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

• Email

• Number

• Phone

• Text

Record Field: BlankA record field displayed as a place holder in a grid of fields.

AvailableVersion



29.0Small, 29.0BlankStringtype

Record Field: CompoundA record field that is a composite of sub-fields.

357

Record FieldChatter REST API Response Bodies

AvailableVersion



29.0Big, 29.0A collection of sub-fields that make up thecompound field. A collection of these responsebodies:

fields

• Record Field











Stringtext



• Address

• Compound

• Location

• Name

Record Field: CurrencyA record field containing a currency value.

AvailableVersion





Stringtext


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



29.0Medium, 29.0A date that a machine can read.DatedateValue



Stringtext



• Date

• DateTime

• Time

Record Field: PercentA record field containing a percentage value.

AvailableVersion



29.0Medium, 29.0The value of the percentage.Doublevalue



Stringtext


29.0Small, 29.0PercentStringtype

Record Field: PicklistA record field containing an enumerated value.

AvailableVersion




359

Record Field: DateChatter REST API Response Bodies

AvailableVersion




Stringtext


29.0Small, 29.0PicklistStringtype

Record Field: ReferenceA record field containing a reference to another object.

AvailableVersion




29.0Medium, 29.0The object referenced by the record field.Referencereference


Stringtext


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



29.0Medium, 29.0A time at which the referenced object acted.DatedateValue


29.0Medium, 29.0The object referenced by the record field.Referencereference


Stringtext



• CreatedBy

• LastModifiedBy

360

Record Field: ReferenceChatter REST API Response Bodies

Record Search List ViewA list view structure visible after searching for records.

AvailableVersion



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



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



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.


361

Record Search List ViewChatter REST API Response Bodies

AvailableVersion



23.0Small, 29.0The localized nameStringname


StringrecordViewUrl


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



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


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.


Motifmotif

362

Record Summary ListChatter REST API Response Bodies

AvailableVersion

FilterGroup andVersion


23.0Medium,29.0

If the logged in user is following this file, thiscontains information about the subscription,otherwise returns null.


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



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



363

Record View SectionChatter REST API Response Bodies

AvailableVersion









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



23.0Small, 29.018-character ID of the object being referencedStringid

23.0Small, 29.0URL to the resource endpointStringurl

Shares

AvailableVersion



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



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



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.


23.0Medium, 29.0Returns the previous page of subscriptions. If thereis no previous page, returns the string “null”


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



30.0Small, 30.0Signed offset, in hours, from GMTDoublegmtOffset

30.0Small, 30.0Display name of this time zoneStringname

Topic

AvailableVersion



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



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



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



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





30.0Small, 30.0Collection of topic endorsement response bodiesTopicEndorsement[]

topicEndorsements


StringnextPageUrl



Topic Opt OutAn “opt out” from a topic. Indicates that a user doesn’t want to be identified as knowledgeable about a topic.

AvailableVersion



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





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



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





30.0Small, 30.0Collection of topics people are knowledgeable aboutresponse bodies

Topics People AreKnowledgeableAbout[]

knowledgeableAboutTopic


StringnextPageUrl

368

Topics People Are Knowledgeable AboutChatter REST API Response Bodies

AvailableVersion





Topic Suggestion

AvailableVersion



28.0Small, 29.0Topic that already exists or null for a new topicTopicexistingTopic

28.0Small, 29.0Name of the topicStringname

Topic Suggestion Collection

AvailableVersion



28.0Small, 29.0Collection of topic suggestion response bodiesTopic Suggestion[]topicSuggestions

User Capabilities

AvailableVersion



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



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



27.0Small, 29.0The default frequency with which a user receivesemail from a group when they join it. Values are:


• 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



23.0Big, 29.0Text from user's profileStringaboutMe




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



User's current status

23.0Medium, 29.0User's email addressStringemail


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.0Big, 29.018-character ID of the user’s managerStringmanagerId

23.0Big, 29.0Locale-based concatenation of manager's first andlast names

StringmanagerName


The motif icon is not the user’s profile picture.

Motifmotif



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


StringrecordViewUrl


371

User DetailChatter REST API Response Bodies

AvailableVersion



29.0Big, 29.0Number of thanks the user has receivedIntegerthanksReceived




24.0Small, 29.0User name of the user, such [email protected]

Stringusername

26.0Medium, 29.0Type of user. Values are:StringuserType








User Group PageA paginated collection of groups a user is a member of.

AvailableVersion




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”


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




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


24.0Small, 29.0Collection of user detail information.User Detail[]users

User Profile

AvailableVersion



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



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



29.0Small, 29.0The current tab’s content URL (for non built-intab types)

StringtabUrl

User SettingsSettings specific to a user.

AvailableVersion



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



24.0Small, 29.018-character ID of the userStringuserId

24.0Small, 29.0Locale of userStringuserLocale

User Status

AvailableVersion



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






23.0Small, 29.0Name of the companyStringcompanyName


23.0Small, 29.018-character IDStringid

25.0Small, 29.0true if user is active, false otherwise.BooleanisActive







375

User StatusChatter REST API Response Bodies

AvailableVersion




The motif icon is not the user’s profile photo.

Motifmotif



23.0Small, 29.0Locale-based concatenation of first and last namesStringname

23.0Small, 29.0Information about the user's photoPhotophoto


StringrecordViewUrl





26.0Medium, 29.0Type of user. Valid values are:StringuserType








ZoneA Chatter Answers zone.

AvailableVersion



29.0Big, 29.0The description of the zoneStringdescription

376

ZoneChatter REST API Response Bodies

AvailableVersion



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



29.0Small, 29.0Collection of one or more zonesZone[]zones




StringnextPageUrl

Zone Search PageA page of results from a search within a Chatter Answers zone.

AvailableVersion



29.0Medium, 29.0Token identifying the current page.StringcurrentPageToken



377

Zone PageChatter REST API Response Bodies

AvailableVersion



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


StringnextPageUrl

Zone Search ResultThe result of a search within a Chatter Answers zone.

AvailableVersion



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

Documents

Chatter REST API Developer's Guide