API REST · EasyLiveChat

§ 00Cos'è l'API REST

EasyLiveChat espone una REST API su /api/v1/* in modo che codice esterno — il tuo backend, un'integrazione CRM, un flusso Zapier o n8n, uno script di migrazione — possa leggere e scrivere nel tuo workspace senza che un agente umano sia loggato. Ogni chiamata è autenticata con una chiave API creata nel dashboard e con ambito tenant.

Se hai mai chiamato l'API di Stripe, Slack o GitHub, funziona allo stesso modo: token segreto a lunga durata in un header Authorization, body di richiesta e risposta JSON, codici di stato HTTP prevedibili.

Una chiave API non porta mai 2FA o password — è proprio questo il senso. È una credenziale che incorpori in un altro software affinché agisca per conto del tuo tenant, solo con gli scope che gli concedi.

§ 01Disponibilità per piano

L'API REST è disponibile in ogni piano a pagamento ed è sbloccata durante la prova di 14 giorni. Nessuna fatturazione per chiamata.

Allo scadere della prova, l'API passa in sola lettura — le scritture restituiscono 402 finché il workspace non viene aggiornato. Le letture continuano a funzionare per non interrompere mai i tuoi export storici.

§ 02Autenticazione

Crea una chiave da https://app.livechattools.com/settings/api-keys. Scegli il set minimo di scope di cui l'integrazione ha davvero bisogno. Puoi revocare una chiave dalla stessa pagina in qualsiasi momento — smette di funzionare all'istante, senza alcun effetto sul dashboard o sui login mobile dei tuoi agenti.

Passa la chiave a ogni richiesta, come token Bearer o tramite x-api-key:

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

Verifica che la chiave funzioni prima di collegarla a qualsiasi cosa — /me restituisce i tuoi scope e il tenant:

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

La chiave grezza è mostrata solo una volta alla creazione. Persa? Revocala e creane una nuova — non c'è modo di recuperare il valore originale.

§ 03Scope

Gli scope sono controllati a ogni richiesta. Una chiave con solo scope :read non può mutare dati per sbaglio — utile per dashboard di sola lettura, export BI o pipeline di analytics.

Scope	Permette
conversations:read	Elencare e leggere conversazioni e i loro messaggi.
conversations:write	Chiudere, riaprire o riassegnare conversazioni.
messages:read	Leggere lo storico messaggi di una conversazione.
messages:write	Inviare un nuovo messaggio come agente.
contacts:read	Elencare e cercare contatti.

Principio del minimo privilegio — chiavi separate per integrazione. Una chiave di sola lettura trapelata sulla tua pipeline di reporting è molto meno dannosa di un'unica chiave "fa-tutto" condivisa nello stack.

§ 04Endpoint

Ogni percorso è radicato in /api/v1. Le risposte sono JSON. I tempi sono ISO 8601 UTC.

`GET /api/v1/me`

Restituisce l'identità della chiave e il tenant. Nessuno scope richiesto — utile per testare la connessione.

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`

Elenca le conversazioni dalla più recente. Tutti i filtri sono opzionali.

?status= OPEN · SNOOZED · CLOSED
?channel= WIDGET · WHATSAPP · TELEGRAM · MESSENGER · INSTAGRAM
?limit= 1–200, predefinito 50
?cursor= id dell'ultima riga della pagina precedente

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`

Recupera una conversazione con il contatto associato.

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

Storico messaggi paginato per una conversazione, più recenti prima.

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

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

Invia un messaggio in uscita in una conversazione. Viene smistato al canale corrispondente (widget, WhatsApp, Telegram, Messenger, Instagram) esattamente come farebbe la risposta di un agente umano.

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 è opzionale — se omesso, il messaggio viene attribuito al primo OWNER o ADMIN attivo del workspace. Passa un id esplicito quando vuoi che un account bot specifico appaia nella conversazione.

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

Aggiorna lo stato di una conversazione (OPEN · SNOOZED · CLOSED) o l'agente assegnato. Passa assignedAgentId: null per disassegnare.

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`

Elenca i contatti del workspace. ?q= cerca per nome, email o telefono.

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

§ 05Paginazione

Tutti gli endpoint di lista usano la paginazione a cursore. La forma della risposta è:

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

Per recuperare la pagina successiva, passa nextCursor come ?cursor= nella richiesta successiva. Quando nextCursor è null hai raggiunto la fine.

§ 06Errori

Gli errori restituiscono sempre un body JSON con un codice di errore e (dove utile) un messaggio leggibile. Lo stato HTTP rispecchia il significato:

Stato	Codice	Significato
401	UNAUTHENTICATED	Chiave mancante, malformata o revocata.
402	TRIAL_EXPIRED	Prova scaduta — le scritture sono bloccate, le letture funzionano ancora.
403	FORBIDDEN	La chiave è valida ma manca lo scope richiesto da questo endpoint.
404	NOT_FOUND	La conversazione, il contatto o un'altra risorsa non esiste sul tuo tenant.
400	INVALID_BODY	Al body della richiesta mancano campi richiesti o ha tipi sbagliati.
429	RATE_LIMITED	Troppe richieste — fermati e riprova dopo qualche secondo.

§ 07Webhook (compagni)

L'API REST è ottima per tirare e spingere secondo i tuoi tempi. Per le notifiche push quando succede qualcosa lato EasyLiveChat — un nuovo messaggio cliente, una conversazione chiusa, un agente che entra — configura webhook in uscita in Impostazioni → Webhook.

I messaggi inviati tramite POST /api/v1/conversations/:id/messages attivano anche il webhook message.created, quindi se hai un'integrazione che invia e un'altra che ascolta, vedrai i tuoi stessi invii rimbalzare attraverso il canale webhook.

§ 08Limiti di velocità

Ogni tenant ha fino a 240 richieste al minuto per path, condivise tra tutte le chiavi del tenant. Raggiungere il limite restituisce 429 con header Retry-After.

Se la tua integrazione ha legittimamente bisogno di un tetto più alto (import massivo, invio massivo), scrivi al supporto — lo alziamo per il tuo tenant.

Suggerisci una modifica