Chatter REST API Developer Guide

Chatter REST API Developer Guide
Introduction
When to Use Chatter REST API
Chatter REST API Architecture
Chatter REST API Rate Limits
Build the Resource URL
Send HTTP Requests
HTTP Request Flow and a Response Body
Inputs and Binary File Upload Examples
Wildcards
Specify Response Sizes
Response Body Encoding
Status Codes and Error Responses
OAuth and Chatter REST API
Use CORS to Access Supported Salesforce APIs, Apex REST, and Lightning Out
Quick Start
Work with Features
Examples
Resources
Request Bodies
Response Bodies
Appendices
PDF

Newer Version Available

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

HTTP Request Flow and a Response Body

Review the process flow for Chatter REST API, including resource and response examples.
The general process flow for using Chatter REST API is:
  1. Send an HTTP request to Salesforce.
  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, context user. For example, to return the user-profile information for the current, context user, use this resource.
You could also specify a particular user by user ID.
When you successfully access a resource, a response body is returned in JSON or XML. By default, JSON is returned. Each response body can contain one or more response bodies. For example, the following is the response body of the user resource. It includes other response bodies as well, such as address, current status, and phone numbers.
Property Type Description Filter Group and Version Available Version
aboutMe String Text from user's profile. Big, 29.0 23.0
additional​Label String An extra label for the user, for example, “Customer,” “Partner,” or “Acme Corporation.” If the user doesn’t have an extra label, the value is null. Small, 30.0 30.0
address Address User’s address. Big, 29.0 23.0
bannerPhoto Banner Photo User’s banner photo. Big, 36.0 36.0
chatterActivity Chatter Activity Chatter activity statistics. Big, 29.0 23.0
chatterInfluence Chatter Influence User’s influence rank. Big, 29.0 23.0
community​Nickname String User’s nickname in the community. Medium, 32.0 32.0
companyName String Company name. Small, 29.0 23.0
currentStatus User Status

This property is no longer available as of version 25.0.

Note

User's current status.		 23.0–25.0
displayName String User’s name that is displayed in the community. If nicknames are enabled, the nickname is displayed. If nicknames aren’t enabled, the full name is displayed. Small, 32.0 32.0
email String User's email address. Medium, 29.0 23.0
firstName String User's first name. In version 39.0 and later, if nicknames are enabled, firstName is null. Small, 29.0 23.0
followersCount Integer Number of users following this user. Big, 29.0 23.0
followingCounts Following Counts Information about items the user is following. Big, 29.0 23.0
groupCount Integer Number of groups user is following. Big, 29.0 23.0
hasChatter Boolean true if user has access to Chatter; false otherwise. Small, 31.0 31.0
id String 18-character ID of the user. Small, 29.0 23.0
isActive Boolean true if user is active, false otherwise. Small, 29.0 23.0
isChatterGuest Boolean

This property is no longer available as of version 26.0. Use the userType property instead.

Note

true if user is a Chatter customer, false otherwise.		 23.0–25.0
isInThis​Community Boolean true if user is in the same community as the context user; false otherwise. Can be false for record feed @mentions on posts with the scope “All Users.” Small, 29.0 28.0
lastName String User's last name. In version 39.0 and later, if nicknames are enabled, lastName is null. Small, 29.0 23.0
managerId String 18-character ID of the user’s manager. Big, 29.0 23.0
managerName String Locale-based concatenation of manager's first and last names. Big, 29.0 23.0
motif Motif Small, medium, and large icons indicating that the object is a user. The motif can also contain the object’s base color.

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

 Small, 29.0 27.0
mySubscription Reference If the context user is following this user, contains information about the subscription, otherwise null. Medium, 29.0 23.0
name String Locale-based concatenation of first and last names. In version 39.0 and later, if nicknames are enabled, name is the nickname. Small, 29.0 23.0
outOfOffice Out of Office (Pilot) Extra out-of-office message, if one exists, for the user.

We provide Out of Office to selected customers through a pilot program that requires agreement to specific terms and conditions. To be nominated to participate in the program, contact Salesforce. Pilot programs are subject to change, and we can’t guarantee acceptance. Out of Office isn’t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. We can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.

Note

 Small, 40.0 40.0
phoneNumbers Phone Number[] Collection of user's phone numbers. Big, 29.0 23.0
photo Photo Information about the user's photos. Small, 29.0 23.0
reputation Reputation Reputation of the user in the community, which is determined by the number of points earned from events and actions performed in the community. Big, 32.0 32.0
stamps Stamp[] Collection of the user’s stamps. Small, 39.0 39.0
thanksReceived Integer Number of thanks the user has received. Big, 29.0 29.0
title String Title of the user. Small, 29.0 23.0
type String Value is User. Small, 29.0 23.0
url String URL to the user's Chatter profile. Small, 29.0 23.0
username String User name of the user, such as Admin@mycompany.com. Small, 29.0 24.0
userType String Specifies the type of user. Valid values are:
  • ChatterGuest—User is an external user in a private group.
  • ChatterOnly—User is a Chatter Free customer.
  • Guest—User is unauthenticated.
  • Internal—User is a standard organization member.
  • Portal—User is an external user in a customer portal, partner portal, or community.
  • System—User is Chatter Expert or a system user.
  • Undefined—User is a user type that is a custom object.
 Medium, 29.0 26.0
In JSON format, the output is:

Salesforce runs on multiple server instances. The examples in this guide use instance_name to indicate the instance.

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.

Note