Riferimento della Chat API

Autenticazione

Ogni richiesta viene autenticata con la chiave API del tuo spazio di lavoro, inviata nell'header X-API-Key (oppure come parametro api_key). Le chiavi hanno l'aspetto ck_live_.... Tratta la chiave come una password - chiunque la possieda puo inviare messaggi addebitati al tuo spazio di lavoro. Ruotala in qualsiasi momento da Impostazioni -> Accesso API; la chiave precedente smette di funzionare immediatamente.

Invia un messaggio

POST https://chatixy.com/api/v1/chat

curl https://chatixy.com/api/v1/chat \
  -H "X-API-Key: ck_live_YOUR_KEY" \
  -F "message=How do I reset my password?"

Parametri:

• message (stringa) - il messaggio del visitatore. Obbligatorio a meno che non siano allegati files.
• ticket_id (stringa, opzionale) - continua una conversazione esistente. Omettilo per iniziarne una nuova.
• visitor_email / visitor_name (stringa, opzionale) - allega i dettagli di contatto al ticket.
• files (multipart, opzionale) - allegati del visitatore. Richiede un piano con caricamento file.

Risposta

La chiamata restituisce 202 Accepted non appena il messaggio viene memorizzato; la risposta dell'AI viene generata in modo asincrono.

{
  "status": { "code": 202, "message": "Message received and being processed" },
  "data": {
    "ticket_id": 1234,
    "ticket_number": "T-1234",
    "id": "<visitor_hash>",
    "processing": true
  }
}

Riporta data.ticket_id come ticket_id nella chiamata successiva per mantenere attiva la conversazione. Per ricevere la risposta dell'AI, iscriviti tramite WebSocket (ActionCable) al canale identificato da data.id - lo stesso hash del visitatore usato dal widget incorporato.

Leggere le conversazioni

Recupera i ticket e i relativi messaggi con la stessa X-API-Key. Ogni endpoint di lettura è limitato al tuo workspace ed è disponibile con il piano Business.

• GET /api/v1/chat/tickets - elenca i ticket, dal più recente al meno recente. Parametri di query: status, limit (max 100), offset. Restituisce tickets e pagination.
• GET /api/v1/chat/tickets/:id - un singolo ticket.
• GET /api/v1/chat/tickets/:id/messages - i messaggi di un ticket in ordine, ciascuno con role, content e attachments.

curl https://chatixy.com/api/v1/chat/tickets \
  -H "X-API-Key: ck_live_YOUR_KEY"

Limiti di frequenza e quota

Le richieste sono limitate a circa 20 al minuto per chiave (e per IP). Ogni risposta generata attinge anche dal limite mensile di messaggi del tuo piano; una volta esaurito, l'endpoint restituisce un 200 con data.limit_reached: true invece di generare una risposta.

Errori

• 401 - nessuna chiave API fornita.
• 404 - la chiave non corrisponde ad alcuno spazio di lavoro (ad es. dopo una rotazione).
• 403 plan_upgrade_required - lo spazio di lavoro non e sul piano Business.
• 403 - l'abbonamento non e attivo, oppure la richiesta proviene da un dominio non consentito dalle impostazioni del widget.
• 422 - il messaggio manca (e non sono stati allegati file).