API REST · EasyLiveChat

§ 00O que é a API REST

EasyLiveChat expõe uma API REST em /api/v1/* para que código externo — seu próprio backend, uma integração com CRM, um fluxo Zapier ou n8n, um script de migração — possa ler e escrever no seu workspace sem que um agente humano esteja logado. Cada chamada é autenticada por uma chave API criada no painel e com escopo do seu tenant.

Se você já chamou a API do Stripe, Slack ou GitHub, funciona da mesma forma: token secreto de longa duração em um cabeçalho Authorization, corpos JSON de requisição e resposta, e códigos de status HTTP previsíveis.

Uma chave API nunca carrega 2FA ou senha — esse é todo o ponto. É uma credencial que você embute em outro software para que ele atue em nome do seu tenant, apenas com os escopos que você concede.

§ 01Disponibilidade por plano

A API REST está disponível em todos os planos pagos e fica desbloqueada durante o teste de 14 dias. Não há cobrança por chamada.

Quando o teste expira, a API passa a somente leitura — escritas retornam 402 até o workspace ser atualizado. Leituras continuam funcionando para que suas exportações históricas nunca quebrem.

§ 02Autenticação

Crie uma chave em https://app.livechattools.com/settings/api-keys. Escolha o menor conjunto de escopos que a integração realmente precisa. Você pode revogar uma chave na mesma página a qualquer momento — ela para de funcionar instantaneamente, sem afetar o dashboard ou os logins mobile dos seus agentes.

Passe a chave em cada requisição, como token Bearer ou via x-api-key:

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

Verifique se a chave funciona antes de plugar em qualquer coisa — /me retorna seus escopos e seu tenant:

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

A chave bruta só é exibida uma vez na criação. Perdeu? Revogue e crie uma nova — não há como recuperar o valor original.

§ 03Escopos

Os escopos são verificados a cada requisição. Uma chave só com escopos :read nunca pode mutar dados por engano — útil para dashboards somente leitura, exports BI ou pipelines de analytics.

Escopo	Permite
conversations:read	Listar e ler conversas e suas mensagens.
conversations:write	Fechar, reabrir ou reatribuir conversas.
messages:read	Ler o histórico de mensagens de uma conversa.
messages:write	Enviar uma nova mensagem como agente.
contacts:read	Listar e pesquisar contatos.

Princípio do menor privilégio — chaves separadas por integração. Uma chave somente-leitura vazada no seu pipeline de relatórios é muito menos prejudicial do que uma única chave "faz-tudo" compartilhada por todo o stack.

§ 04Endpoints

Todo caminho começa em /api/v1. Respostas são JSON. Tempos em ISO 8601 UTC.

`GET /api/v1/me`

Retorna a identidade da chave e o tenant. Não exige escopo — útil para testar a conexão.

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 as conversas mais recentes primeiro. Todos os filtros são opcionais.

?status= OPEN · SNOOZED · CLOSED
?channel= WIDGET · WHATSAPP · TELEGRAM · MESSENGER · INSTAGRAM
?limit= 1–200, padrão 50
?cursor= id da última linha da 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`

Busca uma conversa com seu contato anexado.

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

Histórico de mensagens paginado para uma conversa, mais recentes primeiro.

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

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

Envia uma mensagem de saída em uma conversa. É distribuída ao canal correspondente (widget, WhatsApp, Telegram, Messenger, Instagram) exatamente como faria a resposta de um 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 é opcional — se omitido, a mensagem é atribuída ao primeiro OWNER ou ADMIN ativo do workspace. Passe um id explícito quando quiser que uma conta de bot específica apareça na conversa.

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

Atualiza o status de uma conversa (OPEN · SNOOZED · CLOSED) ou seu agente atribuído. Passe assignedAgentId: null para desatribuir.

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 contatos no workspace. ?q= busca por nome, email ou telefone.

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

§ 05Paginação

Todos os endpoints de lista usam paginação por cursor. O formato da resposta é:

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

Para buscar a próxima página, passe nextCursor como ?cursor= na próxima requisição. Quando nextCursor for null, você chegou ao fim.

§ 06Erros

Erros sempre retornam um corpo JSON com um código de erro e (quando útil) uma mensagem legível. O status HTTP reflete o significado:

Status	Código	Significado
401	UNAUTHENTICATED	Chave ausente, malformada ou revogada.
402	TRIAL_EXPIRED	Teste expirado — escritas bloqueadas, leituras continuam funcionando.
403	FORBIDDEN	Chave é válida mas falta o escopo que este endpoint exige.
404	NOT_FOUND	A conversa, contato ou outro recurso não existe no seu tenant.
400	INVALID_BODY	O corpo da requisição não tem campos obrigatórios ou tem tipos errados.
429	RATE_LIMITED	Muitas requisições — espere e tente de novo após alguns segundos.

§ 07Webhooks (complementar)

A API REST é ótima para puxar e enviar no seu ritmo. Para notificações push quando algo acontece do lado do EasyLiveChat — uma nova mensagem de cliente, uma conversa fechando, um agente entrando — configure webhooks de saída em Ajustes → Webhooks.

Mensagens enviadas via POST /api/v1/conversations/:id/messages também disparam o webhook message.created, então se você tem uma integração enviando e outra ouvindo, verá suas próprias escritas voltando pelo canal do webhook.

§ 08Limites de taxa

Cada tenant tem até 240 requisições por minuto por caminho, compartilhadas entre todas as chaves do tenant. Atingir o limite retorna 429 com cabeçalho Retry-After.

Se sua integração precisa legitimamente de um teto maior (importação em massa, envio em massa), envie e-mail ao suporte — elevamos para o seu tenant.

Sugerir uma edição