API v2

API v2 è una API REST strutturata per gestire gli agenti e creare esperienze di chat personalizzate. Aggiunge la gestione degli agenti, la chat in streaming, la cronologia delle conversazioni, il feedback dei messaggi, i contatti, i lead, le fonti, le impostazioni e gli endpoint di addestramento.

L'accesso API richiede un piano Hobby o superiore con fatturazione attiva.

URL di base

https://your-domain.com/api/v2

Autenticazione

Ad eccezione del controllo di stato, invia la chiave API del tuo workspace come token Bearer:

Authorization: Bearer YOUR_API_KEY

Crea e revoca le chiavi API da Impostazioni > Chiavi API.

Formato della risposta

La maggior parte delle risposte con esito positivo restituisce un oggetto risorsa oppure un envelope data:

{
  "data": []
}

Gli endpoint di elenco includono la paginazione tramite cursore:

{
  "data": [],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 0
  }
}

Gli errori usano un oggetto error strutturato:

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body"
  }
}

Ogni risposta v2 include un'intestazione x-request-id. Includila quando contatti il supporto per una richiesta API.

Ambito delle conversazioni

Gli endpoint di sola lettura per le conversazioni usano per impostazione predefinita source=api_v2. Imposta source=widget per restituire le conversazioni del widget e del Playground; le righe del Playground sono memorizzate con la fonte widget. Imposta source=all per restituire le conversazioni API v2, widget e Playground. I risultati restano sempre limitati all'agente dell'account autenticato. Un valore source non valido, o più di un parametro di query source, restituisce 400 VALIDATION_INVALID_BODY. La prosecuzione della chat, i tentativi di rigenerazione, il feedback, l'elenco dei messaggi e le letture per utente restano limitati alle conversazioni API v2.

Controllo di stato

GET /api/v2/health

Il controllo di stato non richiede autenticazione.

Successo: 200 OK

{
  "status": "ok",
  "timestamp": 1784332800
}

timestamp è il timestamp Unix corrente, in secondi.

Chat

POST /api/v2/agents/{agentId}/chat

Richiesta:

{
  "message": "What plans do you offer?",
  "conversationId": "optional-existing-conversation-id",
  "userId": "optional-user-id",
  "stream": true
}

Le risposte in streaming usano i Server-Sent Events. Lo stream include gli eventi message-start, text-start, text-delta, text-end, message-metadata, finish e [DONE]. Un errore dello stream o dell'hook di completamento genera un evento error con error.code impostato su CHAT_STREAMING_ERROR; questo codice, valido solo nel protocollo SSE, è separato dal catalogo degli errori REST strutturato. message-metadata contiene l'ID del messaggio dell'assistente quando la persistenza va a buon fine, oltre all'ID della conversazione, all'ID utente, al motivo di conclusione e all'utilizzo. Il suo messageId è null quando non è stato persistito alcun messaggio dell'assistente. Quando la risposta si ferma su un'azione lato client, lo stream emette anche un evento tool-call con { "id", "name", "arguments" }; invia l'esito all'endpoint tool-result per riprendere la conversazione — la risposta a quella richiesta trasmette in streaming la continuazione.

Le risposte non in streaming restituiscono:

{
  "data": {
    "id": "123",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "..." }],
    "pendingToolCall": null,
    "metadata": {
      "userMessageId": "122",
      "conversationId": "abc123",
      "userId": "user_123",
      "finishReason": "stop",
      "usage": { "credits": 1 }
    }
  }
}

Nelle risposte non in streaming, i valori data.id e metadata.userMessageId sono ID numerici dei messaggi serializzati come stringhe, oppure null quando il messaggio corrispondente non è stato persistito. metadata.userId è l'ID utente fornito/memorizzato, oppure null. pendingToolCall è null, a meno che la risposta non si sia fermata su una chiamata a uno strumento lato client; in tal caso contiene { "id", "name", "arguments" } per l'endpoint dei risultati degli strumenti.

Riepilogo degli endpoint

Feedback

Usa il feedback per contrassegnare i messaggi dell'assistente API v2 come positive, negative o null. Consulta Conversazioni, messaggi e feedback per lo schema della richiesta, la risposta e la gestione degli errori.

Paginazione

Tratta i cursori come token opachi restituiti dalla API. Riproponi il valore di pagination.cursor invariato nella richiesta successiva; non costruirlo né decodificarlo.

I contatti accettano anche search. I lead accettano i filtri di data e ora ISO 8601 inclusivi createdAfter e createdBefore. Le fonti accettano sourceType con i valori web_crawl, file_upload, text_snippet o qna_entry.

Il formato dei cursori è un dettaglio implementativo interno. I client devono trattare ogni cursore come opaco e riproporlo invariato, senza costruirlo né decodificarlo.

Errori comuni

Consulta il catalogo completo degli errori API v2 per tutti i 27 codici dichiarati, gli stati HTTP, le cause scatenanti e i codici riservati.

Riferimento

• Catalogo degli errori
• Agenti e impostazioni
• Conversazioni, messaggi, retry e feedback
• Fonti e addestramento
• Contatti e lead
• Canale Instagram

Prossimi passi

• Crea una chiave API
• Configura la verifica dell'identità
• Rivedi gli errori di API v2
• Gestisci agenti e impostazioni
• Lavora con le conversazioni
• Gestisci fonti e addestramento
• Gestisci contatti e lead
• Gestisci il canale Instagram