Configure the backend credentials:
export TEXT_CLIENT_ID='YOUR_CLIENT_ID'
export TEXT_CLIENT_SECRET='YOUR_CLIENT_SECRET'
export TEXT_CALLBACK_URI='http://localhost:8080/callback'Initially, an Owner/Admin signs in and authorizes the app in a browser. Open the following URL after substituting and URL-encoding values. redirect_uri is the URL-encoded TEXT_CALLBACK_URI; it must be on the Redirect URI whitelist and match the value used in the code exchange exactly. Generate a random state; your backend callback must validate it and read the returned code:
https://accounts.livechat.com/?response_type=code&client_id=CLIENT_ID&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback&state=RANDOM_STATE
Exchange the code on the backend — authorization code exchange:
export AUTHORIZATION_CODE='CODE_RECEIVED_BY_BACKEND_CALLBACK'
curl --fail-with-body --silent --show-error \
-X POST 'https://accounts.livechat.com/v2/token' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode "client_id=$TEXT_CLIENT_ID" \
--data-urlencode "client_secret=$TEXT_CLIENT_SECRET" \
--data-urlencode "redirect_uri=$TEXT_CALLBACK_URI" \
--data-urlencode "code=$AUTHORIZATION_CODE"Response excerpt:
{
"access_token": "AGENT_ACCESS_TOKEN",
"refresh_token": "AGENT_REFRESH_TOKEN",
"organization_id": "ORGANIZATION_ID",
"expires_in": 28800,
"scope": "customers:own"
}Limits: 20 valid access tokens and refresh tokens per client per account.
Copy the returned values:
export AGENT_TOKEN='COPY_ACCESS_TOKEN_FROM_RESPONSE'
export REFRESH_TOKEN='COPY_REFRESH_TOKEN_FROM_RESPONSE'
export TEXT_ORGANIZATION_ID='COPY_ORGANIZATION_ID_FROM_RESPONSE'Refresh the agent token before expiry — refresh token grant:
curl --fail-with-body --silent --show-error \
-X POST 'https://accounts.livechat.com/v2/token' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode "client_id=$TEXT_CLIENT_ID" \
--data-urlencode "client_secret=$TEXT_CLIENT_SECRET" \
--data-urlencode "refresh_token=$REFRESH_TOKEN"
export AGENT_TOKEN='COPY_NEW_ACCESS_TOKEN_FROM_REFRESH_RESPONSE'
export REFRESH_TOKEN='COPY_REFRESH_TOKEN_FROM_REFRESH_RESPONSE'Store tokens securely. Reuse and refresh this authorization across runs; browser interaction is needed again only if authorization expires or is revoked. This shows standard server-side code grant; the OAuth reference also documents recommended PKCE.
Use the agent token grant. Omitting entity_id creates a new customer identity on each request. New customer grant
curl --fail-with-body --silent --show-error \
-X POST 'https://accounts.livechat.com/v2/customer/token' \
-H "Authorization: Bearer $AGENT_TOKEN" -H 'Content-Type: application/json' \
--data "{\"grant_type\":\"agent_token\",\"client_id\":\"$TEXT_CLIENT_ID\",\"response_type\":\"token\"}"Response excerpt:
{
"access_token": "CUSTOMER_ACCESS_TOKEN",
"entity_id": "CUSTOMER_ID",
"expires_in": 28800,
"organization_id": "ORGANIZATION_ID"
}export CUSTOMER_TOKEN='COPY_CUSTOMER_ACCESS_TOKEN_FROM_RESPONSE'
export CUSTOMER_ID='COPY_ENTITY_ID_FROM_RESPONSE'The returned organization must match TEXT_ORGANIZATION_ID from the agent token response. Use CUSTOMER_TOKEN for chat calls. Retain CUSTOMER_ID; to renew a token for the same customer, include entity_id — existing customer grant:
curl --fail-with-body --silent --show-error \
-X POST 'https://accounts.livechat.com/v2/customer/token' \
-H "Authorization: Bearer $AGENT_TOKEN" -H 'Content-Type: application/json' \
--data "{\"grant_type\":\"agent_token\",\"client_id\":\"$TEXT_CLIENT_ID\",\"response_type\":\"token\",\"entity_id\":\"$CUSTOMER_ID\"}"
export CUSTOMER_TOKEN='COPY_NEW_CUSTOMER_ACCESS_TOKEN_FROM_RESPONSE'Use the customer token and required organization_id query parameter. Replace returned IDs before continuing; this demonstration is independent of the RTM flow. Web API methods and headers
Start a chat — start_chat. continuous: true permits starting without an online group. An available agent is needed for an immediate reply.
curl --fail-with-body --silent --show-error \
-X POST "https://api.livechatinc.com/v3.6/customer/action/start_chat?organization_id=$TEXT_ORGANIZATION_ID" \
-H "Authorization: Bearer $CUSTOMER_TOKEN" -H 'Content-Type: application/json' \
--data '{"continuous":true}'Response: {"chat_id":"CHAT_ID","thread_id":"THREAD_ID"}. Save the chat ID:
export CHAT_ID='COPY_CHAT_ID_FROM_RESPONSE'Send text — send_event.
curl --fail-with-body --silent --show-error \
-X POST "https://api.livechatinc.com/v3.6/customer/action/send_event?organization_id=$TEXT_ORGANIZATION_ID" \
-H "Authorization: Bearer $CUSTOMER_TOKEN" -H 'Content-Type: application/json' \
--data "{\"chat_id\":\"$CHAT_ID\",\"event\":{\"type\":\"message\",\"text\":\"Hello, I need help with my order.\",\"recipients\":\"all\"}}"Response: {"event_id":"EVENT_ID"}.
Fetch the chat and its latest thread — get_chat.
curl --fail-with-body --silent --show-error \
-X POST "https://api.livechatinc.com/v3.6/customer/action/get_chat?organization_id=$TEXT_ORGANIZATION_ID" \
-H "Authorization: Bearer $CUSTOMER_TOKEN" -H 'Content-Type: application/json' \
--data "{\"chat_id\":\"$CHAT_ID\"}"Response excerpt:
{
"id": "CHAT_ID",
"thread": {
"id": "THREAD_ID",
"active": true,
"events": [{ "id": "EVENT_ID", "type": "message", "text": "Hello, I need help with my order." }]
}
}End the chat — deactivate_chat closes the current thread. Its request field is id. Success: HTTP 200 OK, no response payload.
curl --fail-with-body --silent --show-error \
-X POST "https://api.livechatinc.com/v3.6/customer/action/deactivate_chat?organization_id=$TEXT_ORGANIZATION_ID" \
-H "Authorization: Bearer $CUSTOMER_TOKEN" -H 'Content-Type: application/json' \
--data "{\"id\":\"$CHAT_ID\"}"For a returning customer, find conversations with list_chats:
curl --fail-with-body --silent --show-error \
-X POST "https://api.livechatinc.com/v3.6/customer/action/list_chats?organization_id=$TEXT_ORGANIZATION_ID" \
-H "Authorization: Bearer $CUSTOMER_TOKEN" -H 'Content-Type: application/json' \
--data '{}'Reuse an active chat. Reopen an inactive one with resume_chat:
curl --fail-with-body --silent --show-error \
-X POST "https://api.livechatinc.com/v3.6/customer/action/resume_chat?organization_id=$TEXT_ORGANIZATION_ID" \
-H "Authorization: Bearer $CUSTOMER_TOKEN" -H 'Content-Type: application/json' \
--data "{\"chat\":{\"id\":\"$CHAT_ID\"}}"list_chats returns summaries; get_chat returns one thread. Use paginated list_threads for history across threads.
For a fresh demonstration, repeat section 2 to create another new customer; reuse the OAuth agent authorization from section 1. Connect with a WebSocket client, e.g. wscat, then send JSON frames. Substitute actual token/IDs in frames; shell variables are not expanded inside interactive input. RTM endpoint
wscat -c "wss://api.livechatinc.com/v3.6/customer/rtm/ws?organization_id=$TEXT_ORGANIZATION_ID"OUT means client → server; IN means server → client. IN examples are excerpts, omitting unrelated fields. Match responses by request_id, check success, and handle type: "push" separately; pushes can interleave with responses.
Log in within 30 seconds — login. The token string includes Bearer .
OUT:
{ "request_id": "1", "action": "login", "payload": { "token": "Bearer CUSTOMER_TOKEN" } }IN:
{
"request_id": "1",
"action": "login",
"type": "response",
"success": true,
"payload": { "customer": { "id": "CUSTOMER_ID" }, "has_active_thread": false, "chats": [] }
}Start — start_chat.
OUT:
{ "request_id": "2", "action": "start_chat", "payload": { "continuous": true } }IN:
{
"request_id": "2",
"action": "start_chat",
"type": "response",
"success": true,
"payload": { "chat_id": "CHAT_ID", "thread_id": "THREAD_ID" }
}The incoming_chat push carries the new chat and thread (excerpt):
IN:
{
"version": "3.6",
"action": "incoming_chat",
"type": "push",
"payload": {
"requester_id": "CUSTOMER_ID",
"chat": { "id": "CHAT_ID", "thread": { "id": "THREAD_ID", "active": true } }
}
}Send text — send_event.
OUT:
{
"request_id": "3",
"action": "send_event",
"payload": {
"chat_id": "CHAT_ID",
"event": { "type": "message", "text": "Hello, I need help with my order.", "recipients": "all" }
}
}IN:
{
"request_id": "3",
"action": "send_event",
"type": "response",
"success": true,
"payload": { "event_id": "EVENT_ID" }
}An agent reply arrives as an incoming_event push:
IN:
{
"version": "3.6",
"action": "incoming_event",
"type": "push",
"payload": {
"chat_id": "CHAT_ID",
"thread_id": "THREAD_ID",
"event": {
"id": "REPLY_EVENT_ID",
"type": "message",
"text": "How can I help?",
"author_id": "AGENT_ID",
"recipients": "all"
}
}
}The same push also reports customer messages: author_id identifies the sender. Deduplicate events by event.id when combining pushes with fetched history.
Fetch the chat — get_chat.
OUT:
{ "request_id": "4", "action": "get_chat", "payload": { "chat_id": "CHAT_ID" } }IN:
{
"request_id": "4",
"action": "get_chat",
"type": "response",
"success": true,
"payload": {
"id": "CHAT_ID",
"thread": {
"id": "THREAD_ID",
"active": true,
"events": [{ "id": "EVENT_ID", "type": "message", "text": "Hello, I need help with my order." }]
}
}
}End the chat — deactivate_chat.
OUT:
{ "request_id": "5", "action": "deactivate_chat", "payload": { "id": "CHAT_ID" } }IN:
{ "request_id": "5", "action": "deactivate_chat", "type": "response", "success": true, "payload": {} }The chat_deactivated push confirms the active thread closed:
IN:
{
"version": "3.6",
"action": "chat_deactivated",
"type": "push",
"payload": { "chat_id": "CHAT_ID", "thread_id": "THREAD_ID", "user_id": "CUSTOMER_ID" }
}Throughout the authenticated session, send ping every 15 seconds; idle connections close after approximately 30 seconds. Server pinging
OUT:
{ "request_id": "ping-1", "action": "ping", "payload": {} }IN:
{ "request_id": "ping-1", "action": "ping", "type": "response", "success": true }Closing the WebSocket only disconnects the client; use deactivate_chat to end the thread. Pushes require no registration and have no retries; fetch state again after reconnecting. RTM pushes