Riferimento API

Tutte le richieste API vengono autenticate usando una chiave API inviata nell'header X-Api-Key.

Ottenere la tua chiave API

1. Vai su Impostazioni → Chiavi API nel tuo pannello
2. Clicca su Crea chiave API e dagli un nome
3. Copia la chiave immediatamente — viene mostrata una sola volta
4. Memorizzala in modo sicuro (variabile d'ambiente, gestore di segreti)

Effettuare richieste

Includi la chiave in ogni richiesta:

curl -H "X-Api-Key: tak_your_key_here" \
     https://api.enuchat.com/api/v1/tenant-api/widgets

Tutte le risposte sono JSON. Le risposte di successo hanno un campo data. Gli errori hanno un campo error con code e message.

Sicurezza: Le chiavi API sono hashate (SHA-256) nel nostro database. Non memorizziamo mai la chiave grezza. Tratta la tua chiave come una password — non comittarla nel codice o condividerla pubblicamente.

GET /widgets

Elenca tutti i widget del tuo account.

Risposta

{'{'}
  "data": [
{'{'}
      "id": "019d19c6-7e0b-...",
      "name": "Main Website Chat",
      "isActive": true,
      "aiEnabled": true,
      "translationEnabled": true,
      "primaryColor": "#2563eb",
      "position": "bottom-right"
    }
  ]
}

GET /conversations

Elenca conversazioni, ordinate per messaggio più recente.

Parametri query

Esempio

curl -H "X-Api-Key: tak_..." \
     "https://api.enuchat.com/api/v1/tenant-api/conversations?status=open&limit=10"

Risposta

{'{'}
  "data": [
{'{'}
      "id": "019d6724-000e-...",
      "widgetId": "019d19c6-7e0b-...",
      "visitorId": "v-abc123",
      "visitorName": "John",
      "visitorEmail": "john{'@'}example.com",
      "visitorLanguage": "en",
      "status": "open",
      "assignedTo": null,
      "lastMessageAt": "2026-04-11T14:30:00+00:00",
      "startedAt": "2026-04-11T14:25:00+00:00"
    }
  ]
}

GET /conversations/{'{'}id}

Ottieni una conversazione con tutti i messaggi.

Parametri query

Risposta

{'{'}
  "data": {'{'}
    "id": "019d6724-000e-...",
    "visitorLanguage": "en",
    "status": "open",
    "messages": [
{'{'}
        "id": "019d6724-1234-...",
        "role": "visitor",
        "content": "Hello, how much does it cost?",
        "contentLanguage": "en",
        "translatedContent": "Cześć, ile to kosztuje?",
        "translatedLanguage": "pl",
        "isAutoReply": false,
        "createdAt": "2026-04-11T14:25:30+00:00"
      },
{'{'}
        "id": "019d6724-5678-...",
        "role": "ai",
        "content": "Our plans start at €19/month...",
        "isAutoReply": true,
        "createdAt": "2026-04-11T14:25:32+00:00"
      }
    ]
  }
}

POST /conversations/{'{'}id}/messages

Invia un messaggio a una conversazione. Il messaggio sarà consegnato al visitatore in tempo reale tramite il widget di chat.

Corpo richiesta

{'{'}
  "content": "Thanks for reaching out! We'll process your request.",
  "role": "system"
}

Risposta (201 Created)

{'{'}
  "data": {'{'}
    "id": "019d6725-abcd-...",
    "role": "system",
    "content": "Thanks for reaching out!",
    "createdAt": "2026-04-11T14:35:00+00:00"
  }
}

PATCH /conversations/{'{'}id}

Aggiorna lo stato o l'assegnazione di una conversazione.

Corpo richiesta

{'{'}
  "status": "closed"
}

GET /billing/balance

Ottieni il tuo piano attuale e saldo crediti.

Risposta

{'{'}
  "data": {'{'}
    "plan": "pro",
    "creditBalance": 4500000,
    "totalCreditsAdded": 10000000
  }
}

Integrazione CRM

Fai polling per nuove conversazioni e sincronizza i dati dei visitatori (nome, email, lingua) al tuo CRM. Usa l'ID conversazione come riferimento esterno.

Follow-up automatizzati

Dopo che una conversazione è chiusa, invia un messaggio di follow-up tramite l'API: «Grazie per la chat! C'è qualcos'altro in cui possiamo aiutare?»

Alternativa ai webhook

Finché i webhook in uscita non sono disponibili, fai polling dell'endpoint conversazioni periodicamente per rilevare nuovi messaggi o cambi di stato.

Operazioni di massa

Chiudi tutte le conversazioni più vecchie di 7 giorni, assegna conversazioni agli operatori in base a logica esterna, o esporta la cronologia delle conversazioni per analisi.