Chatter REST API

Integrate mobile apps, intranet sites, and third-party web applications with Salesforce using Chatter REST API. In this release, we introduce read and unread feed elements and enhance direct messages, moderation, and streams.
Note

Note

To create custom Chatter and communities experiences in Salesforce, use ConnectApi (Chatter in Apex): New and Changed Classes and Enums.

New and Changed Chatter REST API Resources

Chatter Feeds

Access the read by capability of a feed element
Make a GET request to the new /chatter/feed-elements/feedElementId/capabilities/read-by resource.
Mark a feed element as read for the context user
Make a PATCH request to the new /chatter/feed-elements/feedElementId/capabilities/read-by resource with the new Read By Capability Input or with the isReadByMe parameter.
Mark multiple feed elements as read by the context user at the same time
Make a PATCH request to the new /chatter/feed-elements/batch/feedElementIds/capabilities/read-by resource with the new Read By Capability Input or with the isReadByMe parameter.
Get information about who read a feed element and when
Make a GET request to the new /chatter/feed-elements/feedElementId/capabilities/read-by/items resource.
Get all the read or unread feed elements for the context user from a group feed
Make a GET request to the existing /chatter/feeds/record/recordId/feed-elements resource with the filter parameter set to Read or Unread. The recordId must be a group ID.
Update the members of a direct message
Make a PATCH request to the existing /chatter/feed-elements/feedElementId/capabilities/direct-message resource with the updated Direct Message Capability Input.
Get a page of members of a direct message
Make a GET request to the existing /chatter/feed-elements/feedElementId/capabilities/direct-message/members resource with the new page parameter.
Get the original members for a direct message
Make a GET request to the new /chatter/feed-elements/feedElementId/capabilities/direct-message/original-members resource.
Get the membership activities for a direct message
Make a GET request to the new /chatter/feed-elements/feedElementId/capabilities/direct-message/membership-activity resource.
Get the URL to the communities direct message moderation feed
Make a GET request to the new /connect/communities/communityId/chatter/feeds/direct-message-moderation resource.
Get the direct messages that are flagged for moderation in the community
Make a GET request to the new /connect/communities/communityId/chatter/feeds/direct-message-moderation/feed-elements resource.
Get the feed elements authored by the user profile owner from the user profile feed
Make a GET request to the existing /chatter/feeds/user-profile/userId/feed-elements resource with the filter parameter set to AuthoredBy.
Get sorted feed streams
Make a GET request to the existing /chatter/streams resource with the new sort parameter.
Search feed streams
Make a GET request to the existing /chatter/streams resource with the new q parameter.
Subscribe a user to receive stream subscription notifications
When users opt to receive notifications for their streams, they get an email on every post in the stream.
Make a POST request to the existing /chatter/subscriptions/notification/entityId/members/userId resource with the Notification Member Input or the notificationFrequency parameter and where entityId is a stream ID.
Get information about the frequency with which a user receives stream subscription notifications
Make a GET request to the existing /chatter/subscriptions/notification/entityId/members/userId resource, where entityId is a stream ID.
Unsubscribe a user from receiving stream notifications
Make a DELETE request to the existing /chatter/subscriptions/notification/entityId/members/userId resource, where entityId is a stream ID.
Get the custom filtered feed elements from the case feed
Make a GET request to the existing /chatter/feeds/record/recordId/feed-elements resource with the new customFilter parameter.
Get the URL to the landing feed and a page of feed elements
Make a GET request to the new /chatter/feeds/landing resource with the pageSize parameter.
Get a page of feed elements from several feeds
Make a GET request to these existing feeds resources with the new pageSize parameter.
  • /chatter/feeds/company
  • /chatter/feeds/direct-messages
  • /chatter/feeds/pending-review
  • /connect/communities/communityId/chatter/feeds/home
  • /connect/communities/communityId/chatter/feeds/direct-message-moderation
  • /connect/communities/communityId/chatter/feeds/moderation
Access the extensions capability of a feed element (pilot)
Note

Note

We provide Extensions to selected customers through a pilot program that requires agreement to specific terms and conditions. Extensions is subject to change and 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.

Make a GET request to the new /chatter/feed-elements/feedElementId/capabilities/extensions resource.
Create a feed element with an extension (pilot)
Make a POST request to the existing /chatter/feed-elements resource with the Feed Item Input and the new Extensions Capability Input.
Get extensions (pilot)
Make a GET request to the new /chatter/extensions resource.

Community Moderation

Get audit statistics for a user in a community
Make a GET request to the new /connect/communities/communityId/chatter/users/userId/audit-actions/counts resource.
Get more details about flagged posts, comments, and files
Make GET requests to these existing resources with the new page and pageSize parameters.
  • /connect/communities/communityId/chatter/feed-elements/feedElementId/capabilities/moderation
  • /connect/communities/communityId/chatter/comments/commentId/moderation-flags
  • /connect/communities/communityId/files/fileId/moderation-flags

Files

Get information about supported previews for a specific version of a file
Make a GET request to the existing /connect/files/fileId/previews resource with the new versionNumber parameter.
Generate the supported previews for a specific version of a file
Make a PATCH request to the existing /connect/files/fileId/previews resource with the new versionNumber parameter.
Get the preview of a specific version of a file
Make a GET request to the existing /connect/files/fileId/previews/previewFormat resource with the new versionNumber parameter.

Topics

Assign topics to or unassign topics from articles in a data category
Make a POST request to the new /connect/topics/data-category-groups/dataCategoryGroup/data-categories/dataCategory/articles resource with the new Article Topic Assignment Job Input.
Get topic and article assignment rules
Make a GET request to the new /connect/topics/data-category-rules/data-category-groups/dataCategoryGroup/data-categories/dataCategory resource.
Create topic and article assignment rules
Make a POST request to the new /connect/topics/data-category-rules/data-category-groups/dataCategoryGroup/data-categories/dataCategory resource with the existing Topic Names Input.
Reassign topic and article assignment rules
Make a PUT request to the new /connect/topics/data-category-rules/data-category-groups/dataCategoryGroup/data-categories/dataCategory resource with the existing Topic Names Input.

New and Changed Chatter REST API Request Bodies

Chatter Feeds

Alternative Input (Pilot)
This new request body has these properties.
  • textRepresentation—Text representation of the extension.
  • thumbnailUrl—Thumbnail URL for the extension.
  • title—Title of the extension.
Direct Message Capability Input
This request body has one new property.
  • membersToRemove—List of user IDs for members to remove from the direct message.
Extension Input (Pilot)
This new request body has these properties.
  • alternativeRepresentation—Alternative representation of the extension.
  • extensionId—ID of the extension.
  • payload—Payload associated with the extension.
  • payloadVersion—Payload version that identifies the structure of the payload associated with the extension.
Extensions Capability Input (Pilot)
This new request body has one property.
  • itemsToAdd—Collection of extensions to associate with the feed element.
Feed Element Capabilities Input
This request body has one new property.
  • extensions—Create one or more extensions to associate with a feed element.
Read By Capability Input
This new request body has these properties.
  • isReadByMe—Specifies to mark the feed element as read (true) for the context user.
  • lastReadDateByMe—Specifies the last date when the feed element is marked as read for the context user. If you don’t specify a date or you specify a future date, the current system date is used.

Topics

Article Topic Assignment Job Input
This new request body has these properties.
  • operation—Specifies the type of operation to perform on articles and topics. Values are:
    • AssignTopicsToArticle—Assign topics to articles in a data category.
    • UnassignTopicsFromArticle—Unassign topics from articles in a data category.
  • topicNames—List of topic names to assign to or unassign from articles.

New and Changed Chatter REST API Response Bodies

Chatter Feeds

Alternative (Pilot)
This new response body has these properties.
  • textRepresentation—Text representation of the extension.
  • thumbnailUrl—Thumbnail URL for the extension.
  • title—Title of the extension.
Direct Message Capability
This response body has these new properties.
  • memberChanges—Member activities of the direct message, with the most recent activity first.
  • originalMembers—Original members of the direct message.
Direct Message Membership Activity
This new response body has these properties.
  • activityDate—Direct message member activity date.
  • actor—User who changed the direct message membership.
  • membersAdded—Members added to the direct message as part of the activity.
  • membersRemoved—Members removed from the direct message as part of the activity.
Direct Message Membership Activity Collection
This new response body has these properties.
  • activities—Collection of direct message member activities.
  • currentPageToken—Token identifying the current page.
  • currentPageUrl—Chatter REST API URL identifying the current page.
  • nextPageToken—Token identifying the next page, or null if there isn’t a next page.
  • nextPageUrl—Chatter REST API URL identifying the next page, or null if there isn’t a next page. Check whether this value is null before getting another page. If a page doesn’t exist, a ConnectApi.NotFoundException error is returned.
Extension (Pilot)
This new response body has these properties.
  • alternativeRepresentation—Alternative representation of the extension.
  • extensionId—ID of the extension.
  • payload—Payload associated with the extension.
  • payloadVersion—Payload version that identifies the structure of the payload associated with the extension.
Extension Definition (Pilot)
This new response body has these properties.
  • canAccess—Indicates whether users can access the extension when it’s associated with a feed element.
  • canCreate—Indicates whether users can create a feed element with the extension in the org.
  • createdDate—Date when the extension was created.
  • description—Description of the extension.
  • iconUrl—URL to the icon for the extension.
  • id—ID of the extension.
  • informationCollection—Collection of extension information.
  • isEnabledInCommunity—Indicates whether the extension is enabled in communities.
  • isEnabledInLightningPublisher—Indicates whether the extension is enabled in the Lightning publisher.
  • name—Name of the extension.
Extension Definition Collection (Pilot)
This new response body has these properties.
  • currentPageToken—Token identifying the current page.
  • currentPageUrl—Chatter REST API URL identifying the current page.
  • extensionDefinitions—Collection of extension definitions.
  • nextPageToken—Token identifying the next page, or null if there isn’t a next page.
  • nextPageUrl—Chatter REST API URL identifying the next page, or null if there isn’t a next page. Check whether this value is null before getting another page. If a page doesn’t exist, a ConnectApi.NotFoundException error is returned.
  • total—Total number of extensions returned.
Extensions Capability (Pilot)
This new response body has one property.
  • items—Collection of extensions.
Feed
This response body has these new properties.
  • feedElements—Page of feed elements for the feed specified in redirectedFeedType. Otherwise, null.
  • redirectedFeedType—Specifies which feed is returned if pageSize is specified. Otherwise, null.
Feed Element Capabilities
This response body has one new property.
  • extensions—If a feed element has this capability, it has one or more extension attachments.
Lightning Extension Information (Pilot)
This new response body has these properties.
  • compositionComponent—Component to use in compose state.
  • extensionInformationType—Value is Lightning.
  • headerTextLabel—Label for the extension’s header.
  • hoverTextLabel—Label for hovering over the extension.
  • renderComponent—Component to use in render or preview state.
Read By
This new response body has these properties.
  • lastReadDateByUser—When the user last read the feed element.
  • user—Information about the user who read the feed element.
Read By Capability
This new response body has these properties.
  • isReadByMe—Specifies whether the feed element has been read (true) or not (false) by the context user.
  • lastReadDateByMe—Last date when the feed element was marked read for the context user. Otherwise, null.
  • page—First page of information about who read the feed element and when.
Read By Collection
This new response body has these properties.
  • currentPageToken—Token identifying the current page.
  • currentPageUrl—Chatter REST API URL identifying the current page.
  • items—Collection of read-by information, including users and when they last read the feed element.
  • nextPageToken—Token identifying the next page, or null if there isn’t a next page.
  • nextPageUrl—Chatter REST API URL identifying the next page, or null if there isn’t a next page. Check whether this value is null before getting another page. If a page doesn’t exist, a ConnectApi.NotFoundException error is returned.
  • previousPageToken—Reserved for future use.
  • previousPageUrl—Reserved for future use.
  • total—Total number of users who read the feed element.
Social Post Capability
This response body has these new properties.
  • likedBy—External social account who liked the social post.
  • reviewScale—Review scale of the social post.
  • reviewScore—Review score of the social post.
User Settings
This response body has one new property.
  • canAccessPersonalStreams—User can access personal stream feeds.

Community Moderation

Moderation Audit Record Count
This new response body has one property.
  • auditActionToCount—The number of actions audited for a user in a community. For String values of audit actions, see NetworkActivityAudit in the Object Reference for Salesforce and Force.com.
Moderation Flag Item Detail
This new response body has these properties.
  • createdBy—ID of the user who flagged the item.
  • createdDate—Date when the item was flagged.
  • id—ID of the moderation flag.
  • moderationType—Specifies the type of moderation flag. Values are:
    • FlagAsInappropriate—Flag for inappropriate content.
    • FlagAsSpam—Flag for spam.
  • note—Note from user who flagged the item.
  • visibility—Specifies the visibility behavior of a flag for various user types. Values are:
    • ModeratorsOnly—The flag is visible only to users with moderation permissions on the flagged element or item.
    • SelfAndModerators—The flag is visible to the creator of the flag and to users with moderation permissions on the flagged element or item.
Moderation Flags
This response body has these new properties.
  • flagCountByReason—Number of moderation flags categorized by reason.
  • flags—Collection of flags.
Moderation Flags Collection
This new response body has these properties.
  • currentPageToken—Token identifying the current page.
  • currentPageUrl—Chatter REST API URL identifying the current page.
  • flags—List of flag details.
  • nextPageToken—Token identifying the next page, or null if there isn’t a next page.
  • nextPageUrl—Chatter REST API URL identifying the next page, or null if there isn’t a next page. Check whether this value is null before getting another page. If a page doesn’t exist, a ConnectApi.NotFoundException error is returned.
  • pageSize—Number of items per page.

Files

Content
This response body has one new property.
  • imageDetails—Image details, or null if the file isn’t an image.
File Preview Collection
This response body has one new property.
  • versionNumber—Version number of the file.
Folder
This response body has one new property.
  • folderPaths—Collection of folder paths.
Folder Path
This new response body has these properties.
  • folderId—ID of the folder.
  • folderName—Name of the folder, or null for the root.

Files Connect

Files Connect Repository
This response body has one new property.
  • authentication—Repository authentication information.
Files Connect Repository Authentication
This new response body has these properties.
  • authFlowUrl—Depends on the authProtocol.
    • NoAuthenticationnull.
    • Oauth—URL to start the OAuth flow.
    • Password—URL to the authentication settings for external systems.
  • authProtocol—Specifies the authentication protocol used for the repository.
    • NoAuthentication—Repository doesn’t require authentication.
    • Oauth—Repository uses OAuth authentication protocol.
    • Password—Repository uses user name and password authentication protocol.
  • userHasAuthSettings—Specifies whether the user has credentials or the administrator configured the external data source to use the same set of credentials for every user (true). Otherwise, false.

Records

Entity Label
This new response body has these properties.
  • label—Localized singular label of the entity.
  • labelPlural—Localized plural label of the entity.
Record Summary
This response body has one new property.
  • entityLabel—Label of the record’s entity.

Users Out of Office (Pilot)

Note

Note

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.

Mention Completion
This response body has one new property.
  • outOfOffice—If the record represented by this completion is a user, an additional out-of-office message, if one exists, for the user.
Out of Office (Pilot)
This new response body has one property.
  • message—Out-of-office message for the user.
User Detail
This response body has one new property.
  • outOfOffice—Extra out-of-office message, if one exists, for the user.
User Summary
This response body has one new property.
  • outOfOffice—Extra out-of-office message, if one exists, for the user.