Drive your workspace
from your own code.

§ 00What the REST API is

EasyLiveChat exposes a REST API at /api/v1/* so external code — your own backend, a CRM integration, a Zapier or n8n flow, a migration script — can read and write your workspace without a human agent being logged in. Every call is authenticated with an API key minted in the dashboard and scoped to your tenant.

If you've ever called the Stripe, Slack, or GitHub API, this works the same way: long-lived secret token in an Authorization header, JSON request and response bodies, predictable HTTP status codes.

An API key never carries 2FA or a password — that's the whole point. It's a credential you embed in another piece of software so that software can act on your tenant's behalf, with only the scopes you give it.

§ 01Plan availability

The REST API is available on every paid plan and unlocked during the 14-day trial. There's no per-call billing.

Once a trial expires, the API switches to read-only — writes return 402 until the workspace is upgraded. Reads keep working so your historical exports never break.

§ 02Authentication

Mint a key from https://app.livechattools.com/settings/api-keys. Pick the smallest set of scopes the integration actually needs. You can revoke a key from the same page at any time — it stops working instantly, with no effect on your agents' dashboard or mobile logins.

Pass the key on every request, either as a Bearer token or via x-api-key:

Authorization: Bearer plk_<your-key>
# — or, equivalently —
x-api-key: plk_<your-key>

Verify the key works before wiring it into anything — /me echoes your scopes and tenant:

curl https://api.livechattools.com/api/v1/me \
  -H "Authorization: Bearer plk_<your-key>"

The raw key is only shown once at creation. Lost it? Revoke it and mint a new one — there's no way to recover the original value.

§ 03Scopes

Scopes are checked on every request. A key with only :read scopes can never accidentally mutate data — useful for read-only dashboards, BI exports, or analytics pipelines.

Principle of least privilege — separate keys per integration. A leaked read-only key on your reporting pipeline is much less damaging than a single "do-everything" key shared across your stack.

§ 04Endpoints

Every path is rooted at /api/v1. Responses are JSON. Times are ISO 8601 UTC.

GET /api/v1/me

Echoes the key's identity and tenant. No scope required — useful for connection testing.

curl https://api.livechattools.com/api/v1/me \
  -H "Authorization: Bearer plk_<key>"

{
  "apiKeyId": "ck...",
  "scopes": ["conversations:read","messages:write"],
  "tenant": { "id": "...", "name": "Acme", "slug": "acme", "planTier": "GROWTH" }
}

GET /api/v1/conversations

List conversations newest-first. All filters are optional.

• ?status= OPEN · SNOOZED · CLOSED
• ?channel= WIDGET · WHATSAPP · TELEGRAM · MESSENGER · INSTAGRAM
• ?limit= 1–200, default 50
• ?cursor= id of the last row from the previous page

curl "https://api.livechattools.com/api/v1/conversations?status=OPEN&limit=50" \
  -H "Authorization: Bearer plk_<key>"

{
  "data": [
    { "id":"...", "sourceChannel":"WHATSAPP", "status":"OPEN",
      "lastMessagePreview":"hi there", "lastMessageAt":"..." }
  ],
  "nextCursor": "..."
}

GET /api/v1/conversations/:id

Fetch one conversation with its contact attached.

GET /api/v1/conversations/:id/messages

Paginated message history for a conversation, newest first.

curl "https://api.livechattools.com/api/v1/conversations/<id>/messages?limit=50" \
  -H "Authorization: Bearer plk_<key>"

POST /api/v1/conversations/:id/messages

Send an outbound message on a conversation. Fans out to the matching channel (widget, WhatsApp, Telegram, Messenger, Instagram) exactly the way a human agent's reply would.

curl -X POST "https://api.livechattools.com/api/v1/conversations/<id>/messages" \
  -H "Authorization: Bearer plk_<key>" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Your order has shipped." }'

# → 201 Created
{ "message": { "id":"...", "senderType":"AGENT", "body":"Your order has shipped.", "createdAt":"..." } }

senderAgentId is optional — if omitted, the message is attributed to the first active OWNER or ADMIN on the workspace. Pass an explicit id when you want a specific bot account to appear in the conversation.

PATCH /api/v1/conversations/:id

Update a conversation's status (OPEN · SNOOZED · CLOSED) or its assigned agent. Pass assignedAgentId: null to un-assign.

curl -X PATCH "https://api.livechattools.com/api/v1/conversations/<id>" \
  -H "Authorization: Bearer plk_<key>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "CLOSED" }'

GET /api/v1/contacts

List contacts in the workspace. ?q= matches name, email, or phone.

curl "https://api.livechattools.com/api/v1/contacts?q=acme" \
  -H "Authorization: Bearer plk_<key>"

§ 05Pagination

All list endpoints use cursor pagination. The response shape is:

{
  "data": [ /* up to ?limit= rows */ ],
  "nextCursor": "<id of last row>"   // or null when there are no more
}

To fetch the next page, pass nextCursor as ?cursor= on the next request. When nextCursor is null you've reached the end.

§ 06Errors

Errors always return a JSON body with an error code and (where helpful) a human-readable message. The HTTP status mirrors the meaning:

§ 07Webhooks (companion)

The REST API is great for pulling and pushing on your schedule. For push notifications when something happens on the EasyLiveChat side — a new customer message, a conversation closing, an agent joining — configure outbound webhooks in Settings → Webhooks.

Messages you send via POST /api/v1/conversations/:id/messages also fire the message.created webhook, so if you have both an integration sending messages and another listening for them, you'll see your own writes echoed back through the webhook channel.

§ 08Rate limits

Each tenant gets up to 240 requests per minute per path, shared across all keys on that tenant. Hitting the limit returns 429 with a Retry-After header.

If your integration legitimately needs a higher cap (bulk import, mass-message-out), email support — we'll raise it for your tenant.