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.
Note
Response Properties
| Property Name | Type | Description | Available Versions |
|---|---|---|---|
results | Array of Result objects | A list of Salesforce IDs that correspond to agents and chat buttons and their respective availability to receive new chat requests. | 29.0 |
Response body
1{
2"results":{
3 "type":"array",
4 "description":"List of valid patterns of IDs and their availability.",
5 "items":{
6 "name":"result",
7 "type":"object",
8 "properties":{
9 "id":{
10 "type":"string",
11 "description":"ID of the entity.",
12 "required":true,
13 "version":29.0
14 },
15 "isAvailable":{
16 "type":"boolean",
17 "description":"Whether or not the entity is available for chat.",
18 "version":29.0
19 }
20 }
21 },
22 "required":true,
23 "version":29.0
24 }
25}Response Properties
| Property Name | Type | Description | Available Versions |
|---|---|---|---|
queuePosition | integer | The position of the chat visitor in the chat queue. | 29.0 |
geoLocation | GeoLocation object | The chat visitor’s location, based on the IP address from which the request originated. | 29.0 |
url | String | The URL that the chat visitor is visiting. | 29.0 |
oref | String | The original URL that the chat request came from. | 29.0 |
postChatUrl | String | The URL to which to redirect the chat visitor after the chat has ended. | 29.0 |
sneakPeekEnabled | Boolean | Whether Sneak Peek is enabled for the agent who accepts the chat. | 29.0 |
chatMessages | Array of TranscriptEntry objects | The chat message structure that’s synchronized across the agent.js and chasitor.js files. | 29.0 |
Response body
1{
2 queuePosition: 1,
3 geoLocation: {
4 countryCode: "US",
5 countryName: "United States of America",
6 region: "CA",
7 city: "San Francisco",
8 organization: Salesforce,
9 latitude: 37.793880,
10 longitude: -122.395114
11 },
12 url: "http://yoursite",
13 oref: "http://www.google.com?q=yoursite",
14 postChatUrl: "http://yoursite/postchat",
15 sneakPeekEnabled: true,
16 chatMessages: [
17 {
18 type: "Agent",
19 name: "Andy L.",
20 content: "Hello, how can I help you?",
21 timestamp: 1376596367548,
22 sequence: 1
23 },
24 {
25 type: "Chasitor",
26 name: "Jon A.",
27 content: "I have a question for you.",
28 timestamp: 1376596349132
29 sequence: 2
30 }
31 ]
32}Response properties
| Property Name | Type | Description | Available Versions |
idleTimeoutWarningEvent | String | Informs the server when a warning is triggered or cleared. Possible values: triggered and cleared. | 35.0 |
Response properties
| Property Name | Type | Description | Available Versions |
reason | String | The reason that the chat ended. | 29.0 |
attachedRecords | String | Returns 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 Name | Type | Description | Available Versions |
|---|---|---|---|
name | String | The name of the agent who is engaged in the chat. | 29.0 |
userId | String | The user ID of the agent who is engaged in the chat. | 29.0 |
sneakPeekEnabled | Boolean | Whether Sneak Peek is enabled for the agent who accepts the chat. | 29.0 |
chasitorIdletimeout | ChasitorIdleTimeoutSettings | Gives the settings for chat visitor idle time-out. | 35.0 |
Response body
1{
2 name: "Andy L.",
3 userId: "f1dda237-57f8-4816-b8e8-59775f1e44c8",
4 sneakPeekEnabled: true
5}Response properties
| Property Name | Type | Description | Available Versions |
|---|---|---|---|
name | String | The name of the agent who is engaged in the chat. | 29.0 |
text | String | The text of the chat message that the agent sent to the chat visitor. | 29.0 |
Response body
1{
2 name: "Andy L."
3 text: "Hello, how can I help you?"
4}Response properties
| Property Name | Type | Description | Available Versions |
|---|---|---|---|
reason | String | The reason why the chat request failed—for example, no agents were available to chat or an internal error occurred. | 29.0 |
postChatUrl | String | The URL of the post-chat page to which to redirect the chat visitor after the chat has ended. | 29.0 |
Response body
1{
2 reason: "Unavailable",
3 postChatUrl: "http://yoursite/postChat"
4}Response properties
| Property Name | Type | Description | Available Versions |
|---|---|---|---|
queuePosition | integer | The position of the chat visitor in the chat queue. | 29.0 |
estimatedWaitTime | number | The estimated wait time for the button in seconds. If the server cannot retrieve the wait time, this property returns -1. | 47.0 |
geoLocation | GeoLocation object | The chat visitor’s location, based on the IP address from which the request originated. | 29.0 |
url | String | The URL that the chat visitor is visiting. | 29.0 |
oref | String | The original URL that the chat request came from. | 29.0 |
postChatUrl | String | The URL to which to redirect the chat visitor after the chat has ended. | 29.0 |
customDetails | Array of CustomDetail objects | The custom details of the deployment from which the chat request was initiated. | 29.0 |
visitorId | String | The ID of the chat visitor. | 29.0 |
Response body
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}"Response properties
| Property Name | Type | Description | Available Versions |
|---|---|---|---|
name | String | The name of the agent to whom the chat was transferred. | 29.0 |
userId | String | The ID of the chat visitor. | 29.0 |
sneakPeekEnabled | Boolean | Whether Sneak Peek is enabled for the agent to whom the chat was transferred. | 29.0 |
chasitorIdletimeout | ChasitorIdleTimeoutSettings | Gives the settings for chat visitor idle time-out. | 35.0 |
Response body
1{
2 name: "Ryan S.",
3 userId: "edacfa56-b203-43d5-9e1b-678278b61263",
4 sneakPeekEnabled: false
5}Response properties
| Property Name | Type | Description | Available Versions |
|---|---|---|---|
type | String | The type of custom event that occurred, used for adding the event listener on the chat visitor’s side. | 29.0 |
data | String | Data that’s relevant to the event that was sent to the chat visitor. | 29.0 |
Response body
1{
2 type: "CreditCardEntered",
3 data: "5105105105105100"
4}Response Properties
| Property Name | Type | Description | Available Versions |
|---|---|---|---|
messages | Array of Message objects | The messages that were sent over the course of a chat. | 29.0 |
offset | integer | An internal number to be used with a ReconnectSession request that tracks which messages your client has received. | 29.0 |
sequence | integer | The sequence of the message as it was received over the course of a chat. | 29.0 |
Response body
1{
2 messages: [
3 {
4 type: "ChatEstablished",
5 message: {
6 name: "Andy L.",
7 userId: "f1dda237-57f8-4816-b8e8-59775f1e44c8",
8 sneakPeekEnabled: true
9 }
10 }
11 ],
12 sequence: 1,
13 offset: 1234567890
14}Response properties
| Property Name | Type | Description | Available Versions |
|---|---|---|---|
location | String | The URL of the web page that the chat visitor is viewing. | 29.0 |
Response body
1{
2 location: "http://yoursite/page2"
3}Response properties
| Property Name | Type | Description | Available Versions |
|---|---|---|---|
position | integer | The updated position of the chat visitor in the chat queue. | 29.0 |
estimatedWaitTime | number | The estimated wait time for the button in seconds. If the server cannot retrieve the wait time, this property returns -1. | 47.0 |
Response body
1{
2 position: 3,
3 estimatedWaitTime: 120
4}Response properties
| Property Name | Type | Description | Available Versions |
|---|---|---|---|
resetSequence | Boolean | If true, the sequence for the next request should be reset. | 37.0 |
affinityToken | String | The affinity token for the session that’s passed in the header for all future requests. | 37.0 |
Response body
1{
2 resetSequence: true,
3 affinityToken: "73061fa0"
4}Response Properties
| Property Name | Type | Description | Available Versions |
|---|---|---|---|
sensitiveDataRules | SensitiveDataRule object | List of sensitive data rules and their details. | 29.0 |
Response body
1{
2 "sensitiveDataRules": [
3 {
4 "name": "Replace-Bad-Word",
5 "pattern": "bad",
6 "id": "0GORM00000001dM",
7 "replacement": "bad word",
8 "actionType": "Replace"
9 },
10 {
11 "name": "Filter-Out-Digits",
12 "pattern": "[0-9]+",
13 "id": "0GORM00000001dW",
14 "replacement": "<DIGIT>",
15 "actionType": "Replace"
16 }
17 ]
18}Response Properties
| Property Name | Type | Description | Available Versions |
|---|---|---|---|
id | String | The session ID for the new session. | 29.0 |
key | String | The session key for the new session. | 29.0 |
affinityToken | String | The affinity token for the session that’s passed in the header for all future requests. | 29.0 |
clientPollTimeout | integer | The 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
1{
2 id: "241590f5-2e59-44b5-af89-9cae83bb6947",
3 key:
4 "f6c1d699-84c7-473f-b194-abf4bf7cccf8!b65b13c7-f597-4dd2-aa3a-cbe01e69f19c",
5 affinityToken: "73061fa0"
6 clientPollTimeout: "30"
7}Response Properties
| Property Name | Type | Description | Available Versions |
|---|---|---|---|
pingrate | number | The rate at which the visitor must ping the server to maintain the Chat visitor session. | 29.0 |
contentServerUrl | String | The URL of the content server. | 29.0 |
buttons | Array of button objects | A list of chat buttons, along with their settings information, that were specified when you made the Settings request. | 29.0 |
Response body
1{
2 "pingRate":{
3 "type":"number",
4 "description":"The rate at which the visitor should ping the server to maintain presence",
5 "required":true,
6 "version":29.0
7 },
8 "contentServerUrl":{
9 "type":"string",
10 "description":"The content server URL",
11 "required":true,
12 "version":29.0
13 },
14 "buttons":{
15 "type":"array",
16 "description":"The list of buttons",
17 "items":{
18 "name":"button",
19 "type":"object",
20 "properties":{
21 "id":{
22 "type":"string",
23 "description":"The id of the button",
24 "required":true,
25 "version":29.0
26 },
27 "type":{
28 "type":"string",
29 "description":"The type of the button",
30 "required":true,
31 "version":29.0,
32 "enum":["Standard","Invite","ToAgent"]
33 },
34 "endpointUrl":{
35 "type":"string",
36 "description":"The custom chat window url of the button",
37 "required":false,
38 "version":29.0
39 },
40 "prechatUrl":{
41 "type":"string",
42 "description":"The prechat url of the button",
43 "required":false,
44 "version":29.0
45 },
46 "language":{
47 "type":"string",
48 "description":"The language setting of the button",
49 "required":false,
50 "version":29.0
51 },
52 "isAvailable":{
53 "type":"boolean",
54 "description":"Whether or not the button is available for chat",
55 "version":29.0
56 },
57 /* Invite related settings */
58 "inviteImageUrl":{
59 "type":"string",
60 "description":"The image of the button",
61 "required":false,
62 "version":29.0
63 },
64 "inviteImageWidth":{
65 "type":"number",
66 "description":"The width of the button image",
67 "required":false,
68 "version":29.0
69 },
70 "inviteImageHeight":{
71 "type":"number",
72 "description":"The height of the button image",
73 "required":false,
74 "version":29.0
75 },
76 "inviteRenderer":{
77 "type":"string",
78 "description":"The animation option of the invite",
79 "required":false,
80 "version":29.0,
81 "enum":["Slide","Fade","Appear","Custom"]
82 },
83 "inviteStartPosition":{
84 "type":"string",
85 "description":"The start position of the animation",
86 "required":false,
87 "version":29.0,
88 "enum":["TopLeft","TopLeftTop","Top","TopRightTop","TopRight",
89 "TopRightRight","Right","BottomRightRight","BottomRight",
90 "BottomRightBottom","Bottom","BottomLeftBottom","BottomLeft",
91 "BottomLeftLeft","Left","TopLeftLeft"]
92 },
93 "inviteEndPosition":{
94 "type":"string",
95 "description":"The end position of the animation",
96 "required":false,
97 "version":29.0,
98 "enum":["TopLeft","Top","TopRight","Left","Center","Right","BottomLeft","Bottom","BottomRight"]
99 },
100 "hasInviteAfterAccept":{
101 "type":"boolean",
102 "description":"Whether or not invite will trigger after accepting",
103 "required":false,
104 "version":29.0
105 },
106 "hasInviteAfterReject":{
107 "type":"boolean",
108 "description":"Whether or not invite will trigger after rejecting",
109 "required":false,
110 "version":29.0
111 },
112 "inviteRejectTime":{
113 "type":"number",
114 "description":"The auto reject setting of the invite",
115 "required":false,
116 "version":29.0
117 },
118 "inviteRules":{
119 "type":"object",
120 "description":"The rules of the invite",
121 "required":false,
122 "version":29.0
123 }
124 /* Invite related settings */
125 }
126 },
127 "required":true,
128 "version":29.0
129 }
130 }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 Name | Type | Description | Available Versions |
|---|---|---|---|
newUrl | String | The 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
1{
2 "messages": [
3 "type": "SwitchServer"
4 "message": {
5 "newUrl": "https://LIVE_AGENT_POOL.salesforceliveagent.com/chat"
6 }
7 ]
8}Where LIVE_AGENT_POOL is a variable.
Response Properties
| Property Name | Type | Description | Available Versions |
|---|---|---|---|
sessionId | String | The session ID for the new session. | 29.0 |
Response body
1"sessionId":{
2 "type":"string",
3 "description":"The session id of the visitor",
4 "required":true,
5 "version":29.0
6 }See Also
j