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

Newer Version Available

This content describes an older version of this product. View Latest

Request Bodies for Chat REST API

To perform a POST or GET request, pass query parameters or create a request body that’s formatted in JSON. Request bodies can contain one or more other request bodies that are nested inside. Each request body can contain unique request properties.

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

ChasitorInit

Request properties
Property Name Type Description Available Versions
organizationId String The chat visitor’s Salesforce organization ID. 29.0
deploymentId String The ID of the deployment from which the chat originated. 29.0
buttonId String The ID of the button from which the chat originated. 29.0
agentId String The ID of the agent of a direct-to-agent chat request. For normal chat requests, leave this field empty. 29.0
doFallback Boolean Specifies the fallback mode if agentId is present. If the value is false, it attempts to route the chat session back to that specific agent. If the value is true, it attempts to route the chat session back to the specific agent first but, if the agent is unavailable, it attempts to route to the button next. 29.0
sessionId String The chat visitor’s Chat session ID. 29.0
userAgent String The chat visitor’s browser user agent. 29.0
language String The chat visitor’s spoken language. 29.0
screenResolution String The resolution of the chat visitor’s computer screen. 29.0
visitorName String The chat visitor’s custom name. 29.0
prechatDetails Array of CustomDetail objects The pre-chat information that was provided by the chat visitor. 29.0
prechatEntities Array of Entity objects The records created, searched for, or both depending on what EntityFieldsMaps has enabled. 29.0
buttonOverrides Array of Strings
The button override is an ordered list of routing targets and overrides the buttonId, agentId, and doFallback modes. The possible options are:
  • buttonId—Normal routing
  • agentId—Direct-to-agent routing with no fallback
  • agentId_buttonId—Direct-to-agent routing with fallback to the button

You can list one or more of these options, where the order specifies the routing target order. The second or third target is attempted only if the previous one fails.

 29.0
receiveQueueUpdates Boolean Indicates whether the chat visitor receives queue position updates (true) or not (false). 29.0
isPost Boolean Indicates whether the chat request was made properly through a POST request (true) or not (false). 29.0
Request body
1{
2        organizationId: "00DD0000000JVXs",
3        deploymentId: "572D000000000J6",
4        buttonId: "573D000000000OC",
5        agentId: "005B0000000F3b2",
6        doFallback: true,
7        sessionId: "5503f854-0203-4324-8ed5-f793a367426f",
8        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1500.95 Safari/537.36",
9        language: "en-US",
10        screenResolution: "2560x1440",
11        visitorName: "Jon A.",
12        prechatDetails: [
13                {
14                        label: "E-mail Address",
15                        value: "jon@example.com",
16                        entityFieldMaps: [
17                           {
18                                entityName: "Contact",
19                                fieldName: "Email",
20                                isFastFillable: false,
21                                isAutoQueryable: true,
22                                isExactMatchable: true
23                           }
24                        ],
25                        transcriptFields: [
26                                "c__EmailAddress"
27                        ],
28                        displayToAgent: true
29                }             
30        ],
31        prechatEntities: [],
32        buttonOverrides: [
33                "573D000000000OD"
34        ],
35        receiveQueueUpdates: true,
36        isPost: true
37}

ChasitorResyncState

Request properties
Property Name Type Description Available Versions
organizationId String The chat visitor’s Salesforce organization ID. 29.0
Request body
1{
2        organizationId: "00DD0000000JVXs"
3}

ChasitorSneakPeek

Request properties
Property Name Type Description Available Versions
position integer The position of the Sneak Peek update in the chat. 29.0
text String The text that the chat visitor is typing in the text input area of the chat window. 29.0
Request body
1{
2        position: 3,
3        text: "Hi there."
4}

ChatMessage

Request properties
Property Name Type Description Available Versions
text String The text of the chat visitor’s message to the agent. 29.0
Request body
1{
2        text: "I have a question about my account."
3}

CustomEvent

Request properties
Property Name Type Description Available Versions
type String The type of custom event that occurred, used for adding the event listener on the agent’s side. 29.0
data String Data that’s relevant to the event that was sent to the agent. 29.0
Request body
1{
2        type: "PromptForCreditCard",
3        data: "Visa"
4}

MultiNoun

Request properties
Name Type Description Available Versions
nouns Array of NounWrapper objects An array of noun objects and their properties that are batched in the MultiNoun request. 29.0
Request body
1{
2        nouns: [
3                {
4                        prefix: "Chasitor",
5                        noun: "ChatMessage",
6                        object: {
7                                text: "Goodbye"
8                        }
9                },
10                {
11                        prefix: "Chasitor",
12                        noun: "ChatEnd",
13                        object: {}
14                }
15        ]
16}

SensitiveDataRuleTriggered for Agents

Request properties
Property Name Type Description Available Versions
rules Array of Rule objects A list of sensitive data rules applied to the chat session. 29.0
chatId String The ID of the chat session.
Request body
1{
2    "rules": [
3        {
4            "name": "Replace-Bad-Word"
5        },
6        {
7            "name": "Filter-Out-Digits"
8        }
9    ],
10    "chatId": "1a240b1a-f60e-456d-9f77-41cbfa7b9159"
11}

SensitiveDataRuleTriggered for Chasitors

Request properties
Property Name Type Description Available Versions
rules Array of Rule objects A list of sensitive data rules applied to the chat session. 29.0
Request body
1{
2    "rules": [
3        {
4            "id": "0GORM00000001dM",
5            "name": "Replace-Bad-Word"
6        },
7        {
8            "id": "0GORM00000001dW",
9            "name": "Filter-Out-Digits"
10        }
11    ]
12}