Loading

Use Chat REST API to initiate a chat session

Дата публикации: Apr 5, 2024
Описание

IMPORTANT:

The legacy chat product is in maintenance-only mode, and we won't continue to build new features. You can continue to use it, but we no longer recommend that you implement new chat channels. Instead, you can modernize your customer communication with 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.


Overview

The Live Agent REST API allows you to programmatically create Live Agent sessions, send messages to available agents, create new records based on chat information, etc.,all through HTTP messages. A use case would be if you want to use the capabilities of Live Agent via a third party tool, perhaps an internal chat client in your organization.

This article will walk you through the basics steps on how to use the API to initiate a chat session.

Решение

Basic Flow


Before we go into details on how to use this API, it’s important that you understand the basic flow of HTTP messages required to initiate a Live Agent session. At a high level, the flow is as follows
 
1. Get a Session Id by sending a GET request. You will use this session on subsequent calls to the API.
2. Send a chat request by submitting a POST request.
3. Pull messages from the server to know whether the chat has been accepted, and whether there are new messages from the live agent user. This is done by sending a GET request.
4. Send messages to the live agent user by submitting a POST request. 
 

What you need


To follow the examples in this article, you need a Live Agent enabled org and an HTTP client. In this case we’ll use Google Chrome’s REST Console.
 

Live Agent Endpoint


To make REST-based calls to the API, you first have to find your endpoint. This is located on Setup Up | Chat (Formerly Live Agent) | Chat Settings. 

This is the endpoint you will use to create a session, request for chats, send messages, etc.
 
1. Getting a Session Id

To get a session Id, you need to send a GET request to with the following details

Endpoint: /chat/rest/System/SessionId

Headers:

X-LIVEAGENT-API-VERSION : 34
X-LIVEAGENT-AFFINITY : null

You will get a response similar to the following
{
    "clientPollTimeout": 40,
    "key": "49d50d5a-790f-40ec-98ca-8b813e6f0347!c007a252-0f76-473f-b411-588930e09be0",
    "affinityToken": "2c931fa0",
    "id": "49d50d5a-790f-40ec-98ca-8b813e6f0347"
}

2. Sending a Chat Request

Note: This step must be done almost immediately after getting the response from the previous step as there's a timeout value for the session. It's recommended that you have two REST Console windows opened so that you can quickly change from one request to another.

Using the information from the above response, we’ll send a chat request. To make sure this works, you should log in as a Live Agent user and make yourself available.

To send a chat request, submit a POST message with the following details

Endpoint: /chat/rest/Chasitor/ChasitorInit

Headers (replace the values below using the information from the previous response)

X-LIVEAGENT-API-VERSION : 34
X-LIVEAGENT-AFFINITY :"affinityToken-from-response“
X-LIVEAGENT-SESSION-KEY : “key-from-response”
X-LIVEAGENT-SEQUENCE : 1

Payload:
{
"organizationId": "{!orgId}", 
"deploymentId": "{!deploymentId}", 
"buttonId": "{!chatButtonId}", 
"sessionId": "id-from-response", 
"userAgent": "Lynx/2.8.8", 
"language": "en-US", 
"screenResolution": "1900x1080", 
"visitorName": "Frank Underwood", 
"prechatDetails": [],  "prechatEntities": [], 
"receiveQueueUpdates": true, 
"isPost": true 
}

You should receive a 200 OK response and you should see a chat request in the Live Agent widget.

3. Pulling messages from the server

The response from the previous step only tells you whether the HTTP request was successful, but not whether the chat was accepted, rejected, whether there was an agent available, etc.To get this information, you need to pull messages from the server. 

To do this, send a GET request with the following details

Endpoint: chat/rest/System/Messages

Headers:

X-LIVEAGENT-API-VERSION : 34
X-LIVEAGENT-AFFINITY :"affinityToken-from-response“
X-LIVEAGENT-SESSION-KEY : “key-from-response”

The first time you send this request, you should get a response similar to the following, letting you know the chat request was successful and that the live agent user sent a message, among other details.. 
{"messages":[{"type":"ChatRequestSuccess", "message":{"geoLocation":
{"countryCode":"US","longitude":-122.39419555664062,"countryName":"United States",
"organization":"Salesforce.com",{"type":"ChatMessage", "message":{"text":"hello json",
"name":"pablo g"}},
{"type":"AgentNotTyping", "message":{}}], "sequence":4}

In the response above, the "text" attribute shows a message sent from the live agent user to the visitor.

4. Sending messages to the live agent user

To send messages to the live agent user, simply submit a POST request with the following details

Endpoint: /chat/rest/Chasitor/ChatMessage

Headers:

X-LIVEAGENT-API-VERSION : 34
X-LIVEAGENT-AFFINITY :"affinityToken-from-response“
X-LIVEAGENT-SESSION-KEY : “key-from-response”

Payload: 
{"text" : "Hi, I need help with my TV settings."}

If the request is successful you will see the message in the live agent chat window. 
 
What's next?

There are many other things you can do with the REST API, for example creating records automatically based on the visitor details, see Sample Request for creating a Case with Live Agent REST API for an example of how to do this. 

The Live Agent REST API Developer's Guide also contains a lot of useful information on how to interact with the API.
Номер статьи базы знаний

000386079

 
Загрузка
Salesforce Help | Article