Getting Started with the Chat REST API

Learn how to start, confirm, and end a Chat session with the Chat REST API.

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

Retrieve Your Chat API Endpoint

Your Chat API endpoint is a unique URL that lets you access data from your organization’s Chat sessions. To find your organization’s Chat API endpoint:

From Setup, in the Quick Find box, enter Chat Settings, and then select Chat Settings.
Retrieve the hostname from the Chat API Endpoint. The hostname is the URL without “/chat/rest/” at the end, for example, “https://yourChatApiEndpoint.com”. Substitute HOSTNAME in the Chat API endpoints with this URL.

The hostname that you retrieve from the Chat Settings page in Settings.

Start a Chat Session

To start a Chat session, send a SessionId request. Replace HOSTNAME with the URL that you retrieved from Chat API Endpoint.

1GET https://HOSTNAME/chat/rest/System/SessionId/

Use these Request Headers.

X-LIVEAGENT-AFFINITY
X-LIVEAGENT-API-VERSION

Confirm the Chat Session Started

A ChatRequestSuccess response tells you that the Chat session started.

1{
2        queuePosition: 1,
3        estimatedWaitTime: 120,
4        geoLocation: {
5                countryCode:"US",
6                countryName: "United States of America",
7                region: "CA",
8                city: "San Francisco",
9                organization: Salesforce,
10                latitude: 37.793880,
11                longitude: -122.395114
12        },
13        url: "http://yoursite",
14        oref: "http://www.google.com?q=yoursite",
15        postChatUrl: "http://yoursite/postchat",
16        customDetails: [
17                {
18                        label: "E-mail Address",
19                        value: "jon@example.com",
20                        transcriptFields: [
21                                 "c__EmailAddress"
22                         ],
23                        displayToAgent: true
24                }                        
25
26        ],
27        visitorId: "acd47048-bd80-476e-aa33-741bd5cb05d3"
28}

Then wait for a ChatEstablished response. That response tells you that an agent accepted the chat session.

1{
2        name: "Andy L.",
3        userId: "f1dda237-57f8-4816-b8e8-59775f1e44c8",
4        sneakPeekEnabled: true
5}

Now you’re ready to send, for example, Messages requests. Before you send further requests, wait until you receive the ChatRequestSuccess and ChatEstablished responses, otherwise the API throws a Null Pointer exception, and you receive a 500 error.

End the Chat Session

The Chat session ends when you send a ChatEnd request or send a DELETE SessionId request. In both request types, X-LIVEAGENT-SESSION-KEY is the unique ID of the Chat session that you want to end.

Here’s the ChatEnd request.

1https://HOSTNAME/chat/rest/Chasitor/ChatEnd

Use these Request Headers.

X-LIVEAGENT-AFFINITY
X-LIVEAGENT-API-VERSION
X-LIVEAGENT-SESSION-KEY
X-LIVEAGENT-SEQUENCE

Here’s the SessionId request.

1DELETE https://HOSTNAME/chat/rest/System/SessionId/X_LIVEAGENT_SESSION_KEY

Where HOSTNAME and X_LIVEAGENT_SESSION_KEY are variables.

Use these Request Headers.

X-LIVEAGENT-AFFINITY
X-LIVEAGENT-API-VERSION