Chat REST API Developer Guide

Overview
Getting Started with the Chat REST API
Request Headers
Your Message Long Polling Loop
Using Estimated Wait Time Instead of Queue Position for a Chat Session (Beta)
Chat REST API Resources
Request Bodies for Chat REST API
Response Bodies for Chat REST API
Chat REST API Data Types
Status Codes and Error Responses
PDF

Note: This release is in preview. Features described here don’t become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, 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.

Request Headers

Each Chat REST API resource requires one or more headers to make a request.

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.

Note

Not all resources require all of the available request headers. Each resource indicates which headers are required to make a request.

The following headers are available:
Header Syntax Description
X-LIVEAGENT-API-VERSION The Salesforce API version for the request.
X-LIVEAGENT-AFFINITY The system-generated ID used to identify the Chat session on the Chat servers. This affinity token is included in the response body of the SessionId request.
X-LIVEAGENT-SESSION-KEY The unique ID associated with your Chat session.

Your session key shouldn’t be shared or sent over insecure channels, as it allows access to potentially sensitive chat information.

Note
X-LIVEAGENT-SEQUENCE The sequence of messages you have sent to the Chat server to help the Chat server avoid processing duplicate messages. This number should be increased by one with every new request.