LiveChat User Management API Guide

Auth method: OAuth 2.0 (Bearer token)

Setup steps

1. Register an app in the LiveChat Developer Console (https://developers.livechat.com/console/).
2. Choose OAuth 2.0 grant type: Authorization Code (for user-context) or Client Credentials (for server-to-server).
3. Request required scopes (e.g., agents--all:rw) during app registration.
4. Exchange authorization code or client credentials for an access token at https://accounts.livechat.com/v2/token.
5. Include the token in every API request as: Authorization: Bearer .

Required scopes

List Agents

• Method: GET
• URL: https://api.livechatinc.com/v3.6/configuration/action/list_agents
• Watch out for: Despite being a 'list' operation, the endpoint uses POST with a JSON body. Filtering by group_ids is supported in the request body.

Request example

POST /v3.6/configuration/action/list_agents
Authorization: Bearer <token>
Content-Type: application/json
{}

Response example

{
  "agents": [
    {"id":"agent@example.com","name":"Jane Doe","role":"agent"}
  ]
}

Get Agent

• Method: POST
• URL: https://api.livechatinc.com/v3.6/configuration/action/get_agent
• Watch out for: Requires agents--all:ro scope; agents--my:ro only works for the authenticated agent's own record.

Request example

POST /v3.6/configuration/action/get_agent
Authorization: Bearer <token>
{"id":"agent@example.com"}

Response example

{
  "id":"agent@example.com",
  "name":"Jane Doe",
  "role":"agent",
  "max_chats_count":5
}

Create Agent

• Method: POST
• URL: https://api.livechatinc.com/v3.6/configuration/action/create_agent
• Watch out for: Creates an invitation; agent must accept via email. awaiting_approval=true until accepted. Seat limits apply per plan.

Request example

POST /v3.6/configuration/action/create_agent
Authorization: Bearer <token>
{
  "id":"new@example.com",
  "name":"New Agent",
  "role":"agent"
}

Response example

{
  "id":"new@example.com",
  "name":"New Agent",
  "awaiting_approval":true
}

Update Agent

• Method: POST
• URL: https://api.livechatinc.com/v3.6/configuration/action/update_agent
• Watch out for: Returns empty object on success. Only fields included in the body are updated (partial update semantics).

Request example

POST /v3.6/configuration/action/update_agent
Authorization: Bearer <token>
{
  "id":"agent@example.com",
  "max_chats_count":8,
  "role":"administrator"
}

Response example

{}

Delete Agent

• Method: POST
• URL: https://api.livechatinc.com/v3.6/configuration/action/delete_agent
• Watch out for: Permanently removes the agent and reassigns open chats. Cannot delete the last administrator.

Request example

POST /v3.6/configuration/action/delete_agent
Authorization: Bearer <token>
{"id":"agent@example.com"}

Response example

{}

List Groups

• Method: POST
• URL: https://api.livechatinc.com/v3.6/configuration/action/list_groups
• Watch out for: Group IDs are integers, not strings. Agent membership is managed via update_agent or update_group.

Request example

POST /v3.6/configuration/action/list_groups
Authorization: Bearer <token>
{}

Response example

{
  "groups":[
    {"id":1,"name":"Sales","agent_priorities":{}}
  ]
}

Create Group

• Method: POST
• URL: https://api.livechatinc.com/v3.6/configuration/action/create_group
• Watch out for: agent_priorities map uses agent email as key and priority string as value.

Request example

POST /v3.6/configuration/action/create_group
Authorization: Bearer <token>
{
  "name":"Support Tier 2",
  "agent_priorities":{"agent@example.com":"normal"}
}

Response example

{
  "id":5,
  "name":"Support Tier 2"
}

Update Group

• Method: POST
• URL: https://api.livechatinc.com/v3.6/configuration/action/update_group
• Watch out for: Sending agent_priorities replaces the entire map for included agents; omitted agents retain existing priority.

Request example

POST /v3.6/configuration/action/update_group
Authorization: Bearer <token>
{
  "id":5,
  "agent_priorities":{"new@example.com":"first"}
}

Response example

{}

• Rate limits: LiveChat enforces per-license rate limits on the Configuration API. Limits are applied per access token / license combination. Exceeding limits returns HTTP 429.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: Response headers X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset are returned. On 429, Retry-After header indicates seconds to wait. Exact per-plan differentiation is not publicly documented.
• Pagination method: cursor
• Default page size: 1000
• Max page size: 1000
• Pagination pointer: page_id

• Webhooks available: Yes
• Webhook notes: LiveChat supports webhooks via the Configuration API. Webhooks can be registered per license and fire on agent/chat lifecycle events.
• Alternative event strategy: LiveChat also supports the Real-Time Messaging (RTM) WebSocket API for push-based event streaming without polling.
• Webhook events: agent_created, agent_updated, agent_deleted, agent_suspended, agent_unsuspended, agent_approved, chat_started, chat_ended, incoming_chat, routing_status_set

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• No SCIM 2.0 endpoint is officially documented by LiveChat.
• SSO via SAML 2.0 is available on the Enterprise plan (Okta and OneLogin IdPs documented).
• User provisioning must be performed via the Configuration API or manually.

Provisioning a new agent requires POST /configuration/action/create_agent with id (email), name, and role. The agent is not active until they accept the invitation email; awaiting_approval: true during this window.

Downstream provisioning steps - group assignment, routing configuration - should gate on awaiting_approval: false to avoid operating on an inactive record. Group assignment is handled via POST /configuration/action/update_agent with a groups array specifying group id and priority.

Offboarding uses POST /configuration/action/delete_agent. Deletion is permanent and immediate; there is no suspend or deactivate state. As a soft-disable pattern before full deletion, setting max_chats_count to 0 via update_agent prevents new chat routing without removing the agent record. Retrieve current group memberships and settings via get_agent before deletion for audit logging.

For IdP-driven role sync - for example, mapping Okta group membership to LiveChat roles - the flow is: receive IdP event, map to 'agent' or 'administrator' (the only two assignable roles; 'owner' cannot be set via API), then POST /configuration/action/update_agent with the updated role field. If group membership also changed, follow with update_group. This pipeline must be custom-built; LiveChat has no native SCIM endpoint at any documented tier.

Provision a new agent and assign to a group

1. POST /configuration/action/create_agent with id (email), name, and role fields.
2. Note awaiting_approval=true; agent must accept the invitation email before they can log in.
3. POST /configuration/action/update_agent with the agent id and groups array including the target group id and priority.
4. Optionally POST /configuration/action/update_group to set agent_priorities for the new agent.

Watch out for: The agent cannot be assigned chats or appear online until they accept the invitation. Automate a check on awaiting_approval before downstream provisioning steps.

Deprovision an agent (offboarding)

1. POST /configuration/action/get_agent to retrieve current group memberships and settings for audit logging.
2. POST /configuration/action/delete_agent with the agent's email id.
3. Verify open chats are reassigned by monitoring via the Agent Chat API or webhooks.

Watch out for: Deletion is permanent and immediate. There is no suspend/deactivate state - consider updating max_chats_count to 0 as a temporary soft-disable before full deletion.

Sync agent role changes from an IdP (e.g., Okta) via API

1. Receive a user-update event from the IdP (e.g., via Okta webhook or SCIM-like polling).
2. Map IdP group/role to LiveChat role ('agent' or 'administrator').
3. POST /configuration/action/update_agent with id and updated role field.
4. POST /configuration/action/update_group if group membership also changed.

Watch out for: LiveChat has no native SCIM endpoint; this sync must be custom-built. SSO (SAML) handles authentication but not automated provisioning/deprovisioning.

The most significant integration trap is the invitation model: create_agent does not activate an agent - it sends an email. Any automation that proceeds to assign chats, set routing status, or validate group membership before the agent accepts will operate on a ghost record.

Poll or webhook on agent_approved before treating a provisioning job as complete.

A second trap is the shared rate limit. At 1,000 requests per 10 minutes per license, multiple integrations or sync jobs running concurrently against the same license will contend for the same quota. Bulk onboarding operations should be serialized and instrumented with X-RateLimit-Remaining checks.

The Configuration API is also entirely separate from the Agent Chat API and Customer Chat API - user management endpoints do not exist in those APIs, and mixing base URLs will produce 404s or auth errors.

For identity graph integrity: because id is email-based, any IdP-side email change must trigger a delete-and-recreate cycle in LiveChat, not an update. Treat the LiveChat agent record as non-portable across email changes and design reconciliation logic accordingly.