Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

7 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 

Repository files navigation

1. Backend authorization

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.

2. Create a new customer

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'

3. HTTP flow

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.

3. Equivalent RTM / WebSocket flow

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

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors