Overview

Using the mlivechat API

Build bots and integrations on the same API our own apps use: take chats, reply, hand over to a person, and hear about every event as it happens.

Before you start

Every call needs a token, and every error has the same shape. Read these first:

Authorization: bot tokens and visitor tokens
Errors: the error shape and every code
Versions: what can change inside v1

Call the API, open the WebSocket or get webhooks

The same chats can be reached three ways. Most bots call the API to act, and use a webhook or the WebSocket to hear about new chats and messages.

Way	Connection and use	Updates arrive by
API methods	One HTTPS `POST` per method, with a JSON body. Use it for bots and integrations that act on chats.	Webhooks or the WebSocket
WebSocket	One open connection. Use it when your bot or interface must see changes the moment they happen.	Pushes
Webhooks	We call your HTTPS URL when something happens. Use it when you can’t keep a socket open.	Your URL

The APIs

API	Who uses it	Methods
Agent Chat API	A bot or an integration working chats, with a bot token	13
Customer Chat API	The visitor’s chat window, with a visitor token	15
Configuration API	Agents, groups, tags, saved replies and webhooks	10
Realtime	Bots and visitors that keep a WebSocket open	9 actions, 19 pushes
Webhooks	Your server, called by us	7 events

Base URL

Every method goes to one host, under the version prefix /v1: /v1/agent/action/<method>, /v1/customer/action/<method> and /v1/configuration/action/<method>. The WebSocket opens on the same host.

Base URLText

https://app.staging.mlive.chat/v1

Requests and responses

Bodies and responses are JSON with snake_case field names. IDs are UUID strings and times are ISO 8601 in UTC. Request bodies are read strictly: an unknown field is a validation error. Your organization and role always come from the token, never from the path, query or body.

Pagination

Lists that can grow without end answer one page at a time, with items and next_page_id. Pass next_page_id back as page_id to get the next page; it is null on the last one. limit sets the page size, 1 to 100, default 50. Short lists, such as agents, groups, tags and canned responses, come back whole, as a plain array.

PageJSON

{
  "items": [
    "…"
  ],
  "next_page_id": "MjAyNi0xMS0xM1QwOTozMDowMFo"
}

Rate limits

Over a limit, a call answers 429 with rate_limited and a Retry-After header in seconds. A bot sends at most 30 messages per 10 seconds. The WebSocket has its own limits, in Realtime. Calls with a limit of their own:

Call	Limit
Get an access token	10/min per IP, plus the 300/min per-IP limit of every `/customer` route.
Get a WebSocket ticket	429 when the organization is at its concurrent-visitor cap or the visitor exceeds 30/min.
Send an event	30 per 10 s per agent or bot, and 100 calls per 10 s across these methods.
Send a typing indicator	20 per 10 s.

Versions

This is version 1 of the API, under /v1. Changes inside v1 only add things: new endpoints, new optional fields, new events. Read responses leniently and ignore fields you don’t know. Questions about the API: support@mlive.chat.