Chatter REST API Developer's Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
PDF

Newer Version Available

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

Understanding a Chatter REST API Request and Response

The general process flow for using Chatter REST API is as follows:
  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 the following resource:
1/chatter/users/me
You could also specify a particular user by user Id:
1/chatter/users/005D0000001GLoh
When you successfully access a resource, a response body is returned in JSON or XML. By default, JSON is returned. Each response 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:
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 additional label for the user, for example, “Customer,” “Partner,” or “Acme Corporation.” If the user doesn’t have an additional label, the value is null. Small, 30.0 30.0
address Address Address Big, 29.0 23.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 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 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, this contains information about the subscription, else returns null Medium, 29.0 23.0
name String Locale-based concatenation of user's first and last names Small, 29.0 23.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
recordViewUrl String The URL of the Chatter REST API record view resource for this record, or null if this record does not have a record view layout, or if “Connect Records API” is not enabled for this organization, or if the record type isn’t supported. Small, 30.0 30.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
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 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 as follows: 
1{
2   "aboutMe": "I'm excited to be part of the team focused on building out our apps business
3 and showing our customers their future.",
4   "additionalLabel" : null,
5   "address": {
6      "city": "Seattle",
7      "country": "US",
8      "state": "WA",
9      "street": "2001 8th Ave",
10      "zip": "98121"
11      "formattedAdress": "2001 8th Ave\nSeattle, WA 98121\nUS"
12   },
13   "chatterActivity": {
14      "commentCount": 0,
15      "commentReceivedCount": 1,
16      "likeReceivedCount": 0,
17      "postCount": 2
18   },
19   "chatterInfluence" : {
20     "percentile" : "0.6666666666666667",
21     "rank" : 1
22   },
23   "communityNickname": "marRave",
24   "companyName": "Seattle Apps",
25   "displayName": "Marion Raven",
26   "email": "mraven@seattleapps.com",
27   "firstName": "Marion",
28   "followersCount": 1,
29   "followingCounts": {
30      "people": 5,
31      "records": 0,
32      "total": 5
33   },
34   "groupCount": 3,
35   "hasChatter": true,
36   "id": "005D0000001Kl6xIAC",
37   "isActive": true,
38   "isInThisCommunity" : true,
39   "lastName": "Raven",
40   "managerId": null,
41   "managerName": null,
42   "motif": {
43      "color" : "20aeb8",
44      "largeIconUrl": "/img/icon/profile64.png",
45      "mediumIconUrl": "/img/icon/profile32.png",
46      "smallIconUrl": "/img/icon/profile16.png"
47   },
48   "mySubscription": null,
49   "name": "Marion Raven",
50   "phoneNumbers": [{
51      "label": "Work",
52      "phoneNumber": "(206) 999-2846",
53      "phoneType": "Work"
54   }],
55   "photo": {
56      "fullEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cGW2pGjfqoWUUgTENHjVyS1i9x6Z16L8wXEGigpcWjAd",
57      "largePhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/F",
58      "photoVersionId": "729D00000000BDV",
59      "smallPhotoUrl": "https://instance_name/profilephoto/729D00000000BDV/T",
60      "standardEmailPhotoUrl": "https://instance_name/ncsphoto/SqRfG_-PUTY6KtfOp_f0cGW2pGjfqoWUUgTENHjVyS1q43x_rW2ciXBHst0Eh3Y6",
61      "url":  "/services/data/v32.0/chatter/users/005D0000001LL8OIAW/photo"
62   },
63   "recordViewUrl" : "/services/data/v32.0/connect/records/005D0000001RGVKIA4",
64   "reputation" : null,
65   "thanksReceived" : null,
66   "title": null,
67   "type": "User",
68   "url": "/services/data/v32.0/chatter/users/005D0000001Kl6xIAC",
69   "userType": "Internal";
70   "username": "mraven@seattleapps.com"
71}

Salesforce runs on multiple server instances. The examples in this guide use instance_name to indicate the instance. The instance for your organization may be similar to na1.salesforce.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.

Note