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.

Using Estimated Wait Time Instead of Queue Position for a Chat Session (Beta)

By default, the Chat API returns queue position information that you can relay to customers. However, you can also receive the estimated wait time in addition to the queue position. Sometimes, the estimated wait time more effectively conveys the right information to customers than a queue position number. This feature is available in API version 47.0 and later.

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

As a beta feature, Estimated Wait Time is a preview and isn’t part of the “Services” under your main subscription agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the basis of generally available products and features. Salesforce doesn’t guarantee general availability of this feature within any particular time frame or at all, and we can discontinue it at any time. This feature is for evaluation purposes only, not for production use. It’s offered as is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications and Content apply equally to your use of this feature.

Note

The following algorithm is used to calculate the wait time:

1A = (0.9 * A′) + (0.1 * W)

Where:

  • A′ is the previous value for A. If no previous value exists, this value is W.
  • W is the wait time of the chat that has most recently been accepted.

The value returned is the value of A minus the time already spent waiting.

Additional algorithm details:

  • This value is calculated separately for each chat button.
  • A is recalculated each time a chat is accepted.
  • 0 is returned if the result is less than 0.
  • -1 is returned when the value cannot be calculated.

To use this feature, specify that you want the estimated wait time from the Settings request (by setting Settings.needEstimatedWaitTime to 1) and the Availability request (by setting Availability.needEstimatedWaitTime to 1). When this value is set to 1, the response includes the estimated wait time for each button ID requested.

If receiveQueueUpdates is set when initializing the session, ChatRequestSuccess and QueueUpdate will both contain the estimated wait time (in seconds) in their responses.