Response Bodies for Chat REST API

A request to a Chat REST API resource returns a response code. The successful execution of a resource request can also return a response body in JSON format.

The legacy chat product is scheduled for retirement on February 14, 2026, and is in maintenance mode until then. During this phase, you can continue to use chat, but we no longer recommend that you implement new chat channels. To avoid service interruptions to your customers, migrate to Messaging for In-App and Web. Messaging offers many of the chat features that you love plus asynchronous conversations that can be picked back up at any time. Learn about chat retirement in Help.

Response Properties

Property NameTypeDescriptionAvailable Versions
resultsArray of Result objectsA list of Salesforce IDs that correspond to agents and chat buttons and their respective availability to receive new chat requests.29.0

Response body

Response Properties

Property NameTypeDescriptionAvailable Versions
queuePositionintegerThe position of the chat visitor in the chat queue.29.0
geoLocationGeoLocation objectThe chat visitor’s location, based on the IP address from which the request originated.29.0
urlStringThe URL that the chat visitor is visiting.29.0
orefStringThe original URL that the chat request came from.29.0
postChatUrlStringThe URL to which to redirect the chat visitor after the chat has ended.29.0
sneakPeekEnabledBooleanWhether Sneak Peek is enabled for the agent who accepts the chat.29.0
chatMessagesArray of TranscriptEntry objectsThe chat message structure that’s synchronized across the agent.js and chasitor.js files.29.0

Response body

Response properties

Property NameTypeDescriptionAvailable Versions
idleTimeoutWarningEventStringInforms the server when a warning is triggered or cleared. Possible values: triggered and cleared.35.0

Response properties

Property NameTypeDescriptionAvailable Versions
reasonStringThe reason that the chat ended.29.0
attachedRecordsStringReturns a list of record IDs mapped to the chat’s transcript object with the corresponding transcript field names containing those mappings. This mapping data is useful for enhancing your post chat implementation.
Available if post-chat is enabled on the chat button. If the client uses attachedRecords post chat and a chasitor ends the chat without the client receiving the ChatEnded response, call Messages again after calling ChatEnd.
29.0

Response properties

Property NameTypeDescriptionAvailable Versions
nameStringThe name of the agent who is engaged in the chat.29.0
userIdStringThe user ID of the agent who is engaged in the chat.29.0
sneakPeekEnabledBooleanWhether Sneak Peek is enabled for the agent who accepts the chat.29.0
chasitorIdletimeoutChasitorIdleTimeoutSettingsGives the settings for chat visitor idle time-out.35.0

Response body

Response properties

Property NameTypeDescriptionAvailable Versions
nameStringThe name of the agent who is engaged in the chat.29.0
textStringThe text of the chat message that the agent sent to the chat visitor.29.0

Response body

Response properties

Property NameTypeDescriptionAvailable Versions
reasonStringThe reason why the chat request failed—for example, no agents were available to chat or an internal error occurred.29.0
postChatUrlStringThe URL of the post-chat page to which to redirect the chat visitor after the chat has ended.29.0

Response body

Response properties

Property NameTypeDescriptionAvailable Versions
queuePositionintegerThe position of the chat visitor in the chat queue.29.0
estimatedWaitTimenumberThe estimated wait time for the button in seconds. If the server cannot retrieve the wait time, this property returns -1.47.0
geoLocationGeoLocation objectThe chat visitor’s location, based on the IP address from which the request originated.29.0
urlStringThe URL that the chat visitor is visiting.29.0
orefStringThe original URL that the chat request came from.29.0
postChatUrlStringThe URL to which to redirect the chat visitor after the chat has ended.29.0
customDetailsArray of CustomDetail objectsThe custom details of the deployment from which the chat request was initiated.29.0
visitorIdStringThe ID of the chat visitor.29.0

Response body

Response properties

Property NameTypeDescriptionAvailable Versions
nameStringThe name of the agent to whom the chat was transferred.29.0
userIdStringThe ID of the chat visitor.29.0
sneakPeekEnabledBooleanWhether Sneak Peek is enabled for the agent to whom the chat was transferred.29.0
chasitorIdletimeoutChasitorIdleTimeoutSettingsGives the settings for chat visitor idle time-out.35.0

Response body

Response properties

Property NameTypeDescriptionAvailable Versions
typeStringThe type of custom event that occurred, used for adding the event listener on the chat visitor’s side.29.0
dataStringData that’s relevant to the event that was sent to the chat visitor.29.0

Response body

Response Properties

Property NameTypeDescriptionAvailable Versions
messagesArray of Message objectsThe messages that were sent over the course of a chat.29.0
offsetintegerAn internal number to be used with a ReconnectSession request that tracks which messages your client has received.29.0
sequenceintegerThe sequence of the message as it was received over the course of a chat.29.0

Response body

Response properties

Property NameTypeDescriptionAvailable Versions
locationStringThe URL of the web page that the chat visitor is viewing.29.0

Response body

Response properties

Property NameTypeDescriptionAvailable Versions
positionintegerThe updated position of the chat visitor in the chat queue.29.0
estimatedWaitTimenumberThe estimated wait time for the button in seconds. If the server cannot retrieve the wait time, this property returns -1.47.0

Response body

Response properties

Property NameTypeDescriptionAvailable Versions
resetSequenceBooleanIf true, the sequence for the next request should be reset.37.0
affinityTokenStringThe affinity token for the session that’s passed in the header for all future requests.37.0

Response body

Response Properties

Property NameTypeDescriptionAvailable Versions
sensitiveDataRulesSensitiveDataRule objectList of sensitive data rules and their details.29.0

Response body

Response Properties

Property NameTypeDescriptionAvailable Versions
idStringThe session ID for the new session.29.0
keyStringThe session key for the new session.29.0
affinityTokenStringThe affinity token for the session that’s passed in the header for all future requests.29.0
clientPollTimeoutintegerThe number of seconds before you must make a Messages request before your Messages long polling loop times out and is terminated.29.0

Response body

Response Properties

Property NameTypeDescriptionAvailable Versions
pingratenumberThe rate at which the visitor must ping the server to maintain the Chat visitor session.29.0
contentServerUrlStringThe URL of the content server.29.0
buttonsArray of button objectsA list of chat buttons, along with their settings information, that were specified when you made the Settings request.29.0

Response body

This response is returned for requests to Visitor resources if the Live Agent instance URL is not correct for the Organization ID provided.

Response Properties

Property NameTypeDescriptionAvailable Versions
newUrlStringThe new Chat API endpoint for your org if your org is moved. It can be moved due to a planned org migration or during a Site Switch to a different instance.29.0

Response body

Where LIVE_AGENT_POOL is a variable.

Response Properties

Property NameTypeDescriptionAvailable Versions
sessionIdStringThe session ID for the new session.29.0

Response body

See Also