Chatter REST API

Integrate mobile apps, intranet sites, and third-party web applications with Salesforce using Chatter REST API. Create draft posts, threaded comments, a folder’s share link, and managed content topics.
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

These resources are new or have changes.

Chatter Feeds

Create a draft post
Make a POST request to the existing /chatter/feed-elements resource with the updated Status Capability Input request body.
Get the URL to the context user’s draft feed
Make a GET request to the new /chatter/feeds/draft/me resource.
Get all posts that the context user drafted
Make a GET request to the new /chatter/feeds/draft/me/feed-elements resource.
Publish a draft post
Make a POST request to the new /chatter/feed-elements/publish-draft resource with the feedElementId parameter.
Access the comments capability for a comment
Make a GET request to the new /chatter/comments/commentId/capabilities/comments resource.
Get threaded comments for a comment
Make a GET request to the new /chatter/comments/commentId/capabilities/comments/items resource.
Get a threaded comment in context of its parent comments and parent post
Make a GET request to the new /chatter/comments/commentId/thread-context resource.
Get comments in a threaded style for a feed element
Make a GET request to the existing /chatter/feed-elements/feedElementId/capabilities/comments resource with the new threadedCommentsCollapsed parameter set to false.
Make a GET request to the existing /chatter/feed-elements/feedElementId/capabilities/comments/items resource with the new threadedCommentsCollapsed parameter set to false.
Get a feed element with comments in a threaded style
Make a GET request to the existing /chatter/feed-elements/feedElementId resource with the new threadedCommentsCollapsed parameter set to false.
Get feed elements with comments in a threaded style for a home feed
Make a GET request to the existing /connect/communities/communityId/chatter/feeds/home/feed-elements resource with the new threadedCommentsCollapsed parameter set to false.
Get feed elements with comments in a threaded style for a record feed
Make a GET request to the existing /chatter/feeds/record/recordId/feed-elements resource with the new threadedCommentsCollapsed parameter set to false.
Get feed elements with comments in a threaded style for a user profile feed
Make a GET request to the existing /chatter/feeds/user-profile/userId/feed-elements resource with the new threadedCommentsCollapsed parameter set to false.
Get and search feed elements with comments in a threaded style
Make a GET request to the existing /chatter/feed-elements resource with the existing q parameter and the new threadedCommentsCollapsed parameter set to false.
Create a threaded comment
Make a POST request to the existing /chatter/feed-elements/feedElementId/capabilities/comments/items with the updated Comment Input request body.

Collaborative Forecasts

Get a list of managers or territories between the context user and a specified user or territory in the forecast hierarchy
Make a GET request to the new /connect/forecasting/ancestors/forecastingTypeId resource.
Note

Note

This resource replaces the /connect/forecasting/manager-ancestors and /connect/forecasting/manager-ancestors/forecastingManagerUserRoleId resources.

Get the appropriate list of forecasts for a given user’s dropdown menu on the forecasts page
Make a GET request to the new /connect/forecasting/my-forecasts-list/forecastingTypeId resource.
Get a list of users and territories whose forecasts the context user has access to view
Make a GET request to the new /connect/forecasting/jump-to-user/forecastingTypeId resource.
Note

Note

This resource replaces the /connect/forecasting/jump-to-user resource.

Folders

Access a folder’s share link
Make a GET request to the new /connect/folders/folderId/folder-shares/link resource.
Create a folder’s share link
Make a PUT request to the new /connect/folders/folderId/folder-shares/link resource.
Delete a folder’s share link
Make a DELETE request to the new /connect/folders/folderId/folder-shares/link resource.

Managed Topics

Create content managed topics
Make a POST request to the existing /connect/communities/communityId/managed-topics resource with the updated Managed Topic Input or with the managedTopicType parameter set to Content.
Get content managed topics
To get one topic, make a GET request to the existing /connect/communities/communityId/managed-topics/managedTopicId resource.
To get all topics, make a GET request to the existing /connect/communities/communityId/managed-topics resource, with the managedTopicType parameter set to Content.
Delete content managed topics
Make a DELETE request to the existing /connect/communities/communityId/managed-topics/managedTopicId resource.

List Share

Get share data for a list view
Make a GET request to the new /connect/list-shares/listViewId resource.
Share a list view with groups
Make a PUT request to the new /connect/list-shares/listViewId resource.
Delete a list view’s share data
Make a DELETE request to the new /connect/list-shares/listViewId resource.
Get data on all groups, and all potential groups, a list view is shared with
Make a GET request to the new /connect/list-share-recipients resource.

Live Message

Get Live Message channels
Make a GET request to the new /connect/livemessage/channels resource.
Manage a Live Message channel
Make a POST request to the new /connect/livemessage/channels resource with the new Live Message Channel Input request body.

Next Best Actions (Pilot)

Note

Note

We provide Einstein Next Best Action 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. Einstein Next Best Action 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. You can provide feedback and suggestions for Einstein Next Best Action in the IdeaExchange.

All the Next Best Action resources, even resources introduced in version 43.0, now have a minimum version of 44.0. All the properties of the related request and response bodies also have a minimum version of 44.0.
Execute a strategy
Make a POST request to the existing /connect/recommendation-strategies/strategyName/recommendations resource.

This resource no longer supports GET requests.

Social Engagement

Get a managed social account that is in the org and assigned to the user
Make a GET request to the new /connect/social-engagement/managed-social-accounts/id resource.
Get a list of managed social accounts that are in the org and assigned to the user
Make a GET request to the new /connect/social-engagement/managed-social-accounts resource.

Social Engagement Setup

Get managed social accounts from a recently authenticated social network
Make a GET request to the new /connect/social-engagement/setup/managed-social-accounts resource.
Add managed social accounts from a recently authenticated social network
Make POST request to the new /connect/social-engagement/setup/managed-social-accounts resource.
Get a social account
Make a GET request to the new /connect/social-engagement/setup/managed-social-accounts/id resource.
Manage a social account
Make a PATCH request to the new /connect/social-engagement/setup/managed-social-accounts/id resource with the new Managed Social Account Setup Input request body.
Delete a social account
Make a DELETE request to the new /connect/social-engagement/setup/managed-social-accounts/id resource.
Enable and disable social customer service
Make a GET or DELETE request to the new /connect/social-engagement/setup resource.
Get and accept the terms of service
Make a PUT or PATCH request to the new /connect/social-engagement/terms-of-service resource.

New and Changed Chatter REST API Request Bodies

These request bodies are new or have changes.

Chatter Feeds

Comment Input
This request body has one new property.
  • threadParentId—ID of the parent comment for a threaded comment.
Feed Element Capabilities Input
This request body has one new property.
  • status—Change the status of a feed post or comment.
Status Capability Input
This request body has one changed property.
  • feedEntityStatus—Now includes the Draft value.

List Share

List Current Share Collection Input
This new request body has one property.
  • currentListShares—List of 15-character IDs that identify the groups or roles with which to share the list.

Live Message

Live Message Channel Input
This new request body has these properties.
  • messageType—Type of channel.
  • messagingPlatformKey—ID of the message channel on the external service. This value can be found in the GET response.

Managed Topics

Managed Topic Input
This request body has one changed property.
  • managedTopicType—Now includes the Content value.

Next Best Actions (Pilot)

Next Best Action Strategy Input
This new request body has these properties.
  • contextRecordId—ID of the context record. For example, if the next best action is on a case detail page, the ID of the case.
  • maxResults—Maximum number of results. Valid values are from 1 to 25. The default is 3.
  • strategyContext—Variable and value mappings for the strategy.

Social Customer Service

Social Customer Service Configuration Input
This new request body has these properties.
  • callbackUrl—Callback URL used to generate tenant setup URL.
  • inboundApexHandlerId—ID of the inbound Apex handler that is responsible for inserting any records as a result of inbound social data. Default value is null and uses the default inbound Apex handler provided by Social Customer Service.
  • inboundParentPostEnabled—Indicates whether the parent post of an inbound post should also be sent to your org. The parent post represents the social post that this post is replying to. Default value is false.
  • runAsUserId—ID of the user that is executing your inbound Apex handler. Default value is the ID of the context user.
  • socialPublishingApprovalEnabled—Indicates whether some agents require approval to publish on social networks. Default value is false.

Social Engagement

Managed Social Account Setup Input
This new request body has these properties.
  • managedAccountId—ID for this managed account in a third-party system (for example, Social Studio).
  • parentProviderUserId—User ID of the user on the social network if the managed social account is a fan page (for example, a Facebook fan page).
  • providerUserId—User ID of the user on the social network, or the Page ID of the page if the managed social account is a fan page.
  • socialNetwork—Social network that this account belongs to.
  • status—Status of this managed social account.

New and Changed Chatter REST API Response Bodies

These response bodies are new or have changes.

Chatter Feeds

Comment
This response body has these new properties.
  • threadLevel—Level of nesting for a comment. 0 indicates a standard comment with a parent post. 1 indicates a threaded comment with a parent comment and a parent post. 2 indicates a threaded comment with two parent comments and a parent post. The UI is limited to these three levels.
  • threadParentId—ID of the parent comment for a threaded comment.
Comment Capabilities
This response body has one new property.
  • comments—If a comment has this capability, it has threaded comments.
Comment Page
This response body has these new properties.
  • previousPageToken—Token identifying the previous page, or null if there isn’t a previous page.
  • previousPageUrl—Chatter REST API URL identifying the previous page, or null if there isn’t a previous page.

Collaborative Forecasts

Forecasting Ancestors
This new response body replaces Forecasting Manager Ancestors and has these properties.
  • ancestors—List of parent user nodes.
  • url—URL endpoint that was accessed.
  • userRoleId—Unique identifier of the forecasting user’s role attached to this profile.
Forecasting Manager
This response body has these new properties.
  • territory2Id—Unique identifier of the territory attached to this profile.
  • territory2Name—Name of the territory attached to this profile.
Forecasting Manager Ancestors
Forecasting Ancestors replaces this response body.
Forecasting My Forecasts
This new response body has these properties.
  • formattedLabel—For territory-based forecast types, the composite label of the user and the territory. For role-based forecast types, the user’s full name.
  • territory2Id—For territory-based forecast types, the unique identifier of the territory attached to this profile. For role-based forecast types, this property is blank.
  • territory2Name—For territory-based forecast types, the name of the territory attached to this profile. For role-based forecast types, this property is blank.
  • userId—Unique identifier of the forecasting user.
  • userRoleId—Unique identifier of the forecasting user’s role attached to this profile.
Forecasting My Forecasts Collection
This new response body has these properties.
  • forecastManagerList—For territory-based forecast types, a list of territories that the context user is a forecast manager of. For role-based forecast types, the context user, if the context user is a forecast manager in the role hierarchy.
  • representativeList—For territory-based forecast types, a list of territories that the context user is assigned to but that have no forecast manager. For role-based forecast types, the context user, if the context user is part of the role hierarchy and not a forecast manager.
  • sharedList—List of users that have shared their forecasts with the context user. null for territory-based forecast types.
  • url—URL endpoint that was accessed.
  • viewAllForecastsList—For territory-based forecast types, a list of territories and their respective forecast managers at the top level of the territory hierarchy. For role-based forecast types, a list of users at the top level of the role hierarchy.
Forecasting User
This response body has these new properties.
  • displayLabel—Label of an entry in the user’s dropdown menu on the forecasts page.
  • territoryId—ID of a territory that’s included in the user’s dropdown menu on the forecasts page.
  • territoryName—Name of a territory that’s included in the user’s dropdown menu on the forecasts page.

Folders

Folder Share Link
This new response body has this property.
  • folderViewUrl—URL where the folder can be viewed. This value is also called the folder share link.

List Share

List Share
This new response body has these properties.
  • groupId—ID for the group or role that the list is shared with.
  • label—Label for the group or role.
List Share Category
This new response body has these properties.
  • imageColor—Color of the image for the recipient.
  • imageUrl—URL of the image for the recipient.
  • shareLabel—Translated label to show in the UI for this category of shares.
  • shareType—Type of group a list view is shared with.
  • shares—List of structures for shared groups.
  • shareListComplete—Indicates whether the shares list contains all available results (true) or not (false).
List Share Collection
This new response body has these properties.
  • availableListShares—Share categories that the list can be shared with.
  • currentListShares—Share categories that the list is shared with.
List Current Share Collection
This new response body has these properties.
  • currentListShares—List of share categories that the list is currently shared with.

Live Message

Live Message Channel
This new response body has these properties.
  • developerName—Unique developer name of the channel.
  • id—ID of the message channel, if it is added to the org.
  • isActive—Indicates whether the channel is currently active (true) or not (false).
  • masterLabel—User friendly name of the channel.
  • messageType—Type of channel.
  • messagingPlatformKey—User friendly name of the channel.
Live Message Channels
This new response body has these properties.
  • channels—Live Message channels.
  • cursor—Live Message page cursor.

Managed Topics

Managed Topic Collection
This response body has this new property.
  • nextPageUrl—Chatter REST API URL identifying the next page, or null if there isn’t a next page.

Next Best Actions (Pilot)

Next Best Action Flow Action
This new response body has these properties.
  • id—ID of the proposition.
  • name—Name of the proposition.
  • parameters—List of parameters to pass to the action.
  • type—Type of action.
Next Best Action Parameter
This new response body has these properties.
  • name—Name of the parameter.
  • type—Type of the parameter.
  • value—Value of the parameter.
Next Best Action Proposition Recommendation
This new response body has these properties.
  • id—ID of the proposition.
  • name—Name of the proposition.
  • type—Type of target.
  • url—URL to the proposition.
Next Best Action Recommendation
This new response body has these properties.
  • acceptanceLabel—Text indicating user acceptance of the recommendation.
  • actionReference—Reference to the action to perform, for example, launching a flow.
  • description—Description of the recommendation.
  • id—ID of the recommended entity.
  • imageUrl—URL to the asset file to display.
  • name—Name of the recommended entity.
  • rejectionLabel—Text indicating user rejection of the recommendation.
  • target—Target to act on.
  • targetAction—Action to recommend.
  • url—URL to the recommended entity.
Next Best Action Recommendation Proposition
This response body was removed.
Proposition
This response body has these new properties.
  • acceptanceLabel—Text indicating user acceptance of the recommendation.
  • image—Image to display.
  • rejectionLabel—Text indicating user rejection of the recommendation.

Social Engagement

Managed Social Account
This new response body has these properties.
  • defaultResponseAccountId—Default response account to use when replying to posts sent to this account.
  • displayName—Real name (or user name if real name not available) for this account on the social network.
  • externalPictureUrl—URL to the account's avatar image.
  • id—Internal SFDC ID for this managed social account.
  • label—Label for the social account.
  • profileUrl—URL to the account's profile.
  • socialNetwork—Social network that this account belongs to.
  • uniqueName—Unique name used for distinguishing same name fan pages; acts like a user name for a fan page.
  • username—Unique user name or handle for this account on the social network.
Managed Social Accounts
This new response body has this property.
  • managedSocialAccounts—List of managed social accounts that are in the org and assigned to the user.
Managed Social Account Setup
This new response body has these properties.
  • authorizedByUsername—Authorized-by user name used for displaying authorized name in fan pages.
  • defaultResponseAccountId—Default response account to use when replying to posts sent to this account.
  • displayName—Real name (or user name if real name not available) for this account on the social network.
  • externalPictureUrl—URL to the account's avatar image.
  • id—Internal SFDC ID for this managed social account.
  • isActive—Indicates whether the account is considered active (true) or not (false).
  • isAuthenticated—Indicates whether the account is authenticated (true) or needs to be reauthenticated (false).
  • label—Label for the social account.
  • managedAccountId—ID for this account in a third-party system (for example, Social Studio).
  • parentProviderUserId—User ID of the user on the social network if the managed social account is a fan page (for example, a Facebook fan page).
  • profileUrl—URL to the account's profile.
  • providerUserId—User ID of the user on the social network, or the Page ID of the page if the managed social account is a fan page.
  • socialNetwork—Social network that this account belongs to.
  • status—Status of this managed social account.
  • uniqueName—Unique name used for distinguishing same name fan pages; acts like a user name for a fan page.
  • username—Unique user name or handle for this account on the social network.
Managed Social Accounts Setup
This new response body has this property.
  • managedSocialAccounts—List of managed social account setup entities.
Managed Social Account Setup Authentication
This new response body has this property.
  • oauthJWT—JSON web token (JWT). This JWT must be in the form field (tokenString) when you POST to the OAuth URL. This token expires every 60 seconds, so fetch it on demand.
  • oauthUrl—OAuth URL. POST to this URL to begin the OAuth process. The response to a POST request is an HTML page.
Social Customer Service Configuration
This new response body has this property.
  • inboundApexHandlerId—ID of the Apex class that handles inbound social data.
  • isInboundParentPostEnabled—Indicates whether a social post's parent should be sent to this org.
  • isPackageInstalled—Indicates whether a Social Customer Service package is installed to this org.
  • isSocialPublishingApprovalEnabled—Indicates whether some agents require approval before publishing social posts.
  • isTenantConnectionValid—Indicates whether the tenant connection is valid. This value is true if we're able to connect to Social Studio and false if you need to reauthenticate to Social Studio using the setupTenantUrl response parameter.
  • managedSocialAccountCount—Current number of social accounts that this org has.
  • managedSocialAccountLimit—Maximum number of social accounts that this org is allowed to have.
  • runAsUserId—ID of the context user.
  • setupTenantUrl—Setup tenant URL used to direct the user's browser to authorize their tenant.
  • tenantType—Type of tenant in this org (for example, Starter). Null if no tenant is configured.
Terms of Service
This new response body has this property.
  • acceptingUserId—ID of the user who accepted the terms of service. Specify null if not accepted.
  • termsOfServiceUrl—URL for the terms of service page.

Users

User Detail
For performance reasons, this response body no longer returns the stamps property. To get a user’s stamps in version 44.0 and later, use SOQL.
User Summary
For performance reasons, this response body no longer returns the stamps property. To get a user’s stamps in version 44.0 and later, use SOQL.