API REST · EasyLiveChat

§ 00Qué es la API REST

EasyLiveChat expone una API REST en /api/v1/* para que código externo — tu propio backend, una integración con CRM, un flujo de Zapier o n8n, un script de migración — pueda leer y escribir en tu workspace sin que un agente humano esté conectado. Cada llamada se autentica con una clave API creada en el panel y con alcance por tenant.

Si alguna vez has llamado a la API de Stripe, Slack o GitHub, funciona igual: token secreto de larga duración en una cabecera Authorization, cuerpos de petición y respuesta JSON, códigos de estado HTTP predecibles.

Una clave API nunca lleva 2FA ni contraseña — ese es justamente el punto. Es una credencial que incrustas en otro software para que actúe en nombre de tu tenant, sólo con los ámbitos que le das.

§ 01Disponibilidad por plan

La API REST está disponible en todos los planes de pago y se desbloquea durante la prueba de 14 días. No hay facturación por llamada.

Cuando expira la prueba, la API pasa a sólo lectura — las escrituras devuelven 402 hasta que se actualice el workspace. Las lecturas siguen funcionando para que tus exportaciones históricas nunca se rompan.

§ 02Autenticación

Crea una clave en https://app.livechattools.com/settings/api-keys. Elige el conjunto más pequeño de ámbitos que la integración realmente necesita. Puedes revocar una clave desde la misma página en cualquier momento — deja de funcionar al instante, sin afectar al dashboard ni a los inicios de sesión móviles de tus agentes.

Pasa la clave en cada solicitud, como Bearer o vía x-api-key:

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

Verifica que la clave funciona antes de cablearla a nada — /me devuelve tus ámbitos y tu tenant:

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

La clave en bruto sólo se muestra una vez al crearla. ¿La perdiste? Revócala y crea una nueva — no hay forma de recuperar el valor original.

§ 03Ámbitos (scopes)

Los ámbitos se comprueban en cada solicitud. Una clave con sólo ámbitos :read nunca puede mutar datos por accidente — útil para dashboards de sólo lectura, exports BI o pipelines de analítica.

Ámbito	Permite
conversations:read	Listar y leer conversaciones y sus mensajes.
conversations:write	Cerrar, reabrir o reasignar conversaciones.
messages:read	Leer el historial de mensajes de una conversación.
messages:write	Enviar un nuevo mensaje como agente.
contacts:read	Listar y buscar contactos.

Principio del menor privilegio — claves separadas por integración. Una clave de sólo lectura filtrada en tu pipeline de reportes hace mucho menos daño que una única clave "todopoderosa" compartida en todo tu stack.

§ 04Endpoints

Cada ruta arranca en /api/v1. Las respuestas son JSON. Las horas son ISO 8601 UTC.

`GET /api/v1/me`

Devuelve la identidad de la clave y el tenant. No requiere ámbito — útil para probar la conexión.

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`

Lista las conversaciones más nuevas primero. Todos los filtros son opcionales.

?status= OPEN · SNOOZED · CLOSED
?channel= WIDGET · WHATSAPP · TELEGRAM · MESSENGER · INSTAGRAM
?limit= 1–200, por defecto 50
?cursor= id de la última fila de la página anterior

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`

Obtiene una conversación con su contacto adjunto.

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

Historial de mensajes paginado para una conversación, los más nuevos primero.

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

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

Envía un mensaje saliente en una conversación. Se distribuye al canal correspondiente (widget, WhatsApp, Telegram, Messenger, Instagram) exactamente igual que la respuesta de un agente humano.

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 es opcional — si se omite, el mensaje se atribuye al primer OWNER o ADMIN activo del workspace. Pasa un id explícito cuando quieras que una cuenta de bot concreta aparezca en la conversación.

`PATCH /api/v1/conversations/:id`

Actualiza el estado de una conversación (OPEN · SNOOZED · CLOSED) o su agente asignado. Pasa assignedAgentId: null para des-asignar.

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`

Lista los contactos del workspace. ?q= busca por nombre, email o teléfono.

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

§ 05Paginación

Todos los endpoints de lista usan paginación por cursor. La forma de la respuesta es:

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

Para obtener la siguiente página, pasa nextCursor como ?cursor= en la siguiente petición. Cuando nextCursor es null has llegado al final.

§ 06Errores

Los errores siempre devuelven un cuerpo JSON con un código de error y (cuando ayuda) un mensaje legible. El estado HTTP refleja el significado:

Estado	Código	Significado
401	UNAUTHENTICATED	Clave faltante, mal formada o revocada.
402	TRIAL_EXPIRED	Prueba expirada — las escrituras están bloqueadas, las lecturas siguen funcionando.
403	FORBIDDEN	La clave es válida pero le falta el ámbito que necesita este endpoint.
404	NOT_FOUND	La conversación, contacto u otro recurso no existe en tu tenant.
400	INVALID_BODY	Al cuerpo de la solicitud le faltan campos requeridos o tiene tipos incorrectos.
429	RATE_LIMITED	Demasiadas peticiones — espera y reintenta tras unos segundos.

§ 07Webhooks (complemento)

La API REST es genial para tirar y empujar a tu ritmo. Para notificaciones push cuando ocurre algo del lado de EasyLiveChat — un nuevo mensaje de cliente, una conversación cerrándose, un agente uniéndose — configura webhooks salientes en Ajustes → Webhooks.

Los mensajes que envías vía POST /api/v1/conversations/:id/messages también disparan el webhook message.created, así que si tienes una integración enviando y otra escuchando, verás tus propios envíos rebotados por el canal del webhook.

§ 08Límites de tasa

Cada tenant tiene hasta 240 peticiones por minuto y por ruta, compartidas por todas las claves de ese tenant. Al alcanzar el límite se devuelve 429 con cabecera Retry-After.

Si tu integración necesita legítimamente un tope más alto (importación masiva, envío masivo), escribe a soporte — lo subimos para tu tenant.

Sugerir una edición