API v2 Conversazioni

Usa questi endpoint per leggere la cronologia delle conversazioni e lavorare con i messaggi di API v2. Ogni endpoint di questa pagina richiede Authorization: Bearer YOUR_API_KEY e l'accesso a {agentId}.

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.

Oggetti di risposta

I riepiloghi delle conversazioni contengono:

Gli oggetti messaggio contengono:

Le righe dei messaggi di tipo strumento sono escluse dalle trascrizioni delle conversazioni e dagli elenchi dei messaggi.

Elenca le conversazioni

Percorso: /api/v2/agents/{agentId}/conversations

GET /api/v2/agents/{agentId}/conversations

Autenticazione: Chiave API Bearer con accesso a {agentId}.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations?source=all&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Successo: 200 OK

{
  "data": [
    {
      "id": "b2mD4kL8pQ1sT6vX",
      "title": "Where is my order?",
      "createdAt": 1784332800,
      "updatedAt": 1784332860,
      "userId": "customer_123",
      "source": "api_v2",
      "status": "ongoing"
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Limiti, cursori, valori di source non validi e parametri source duplicati restituiscono 400 VALIDATION_INVALID_BODY.

Esporta le conversazioni

Percorso: /api/v2/agents/{agentId}/conversations/export

GET /api/v2/agents/{agentId}/conversations/export

Autenticazione: Chiave API Bearer con accesso a {agentId}.

L'esportazione usa lo stesso ordinamento delle conversazioni e lo stesso contratto di cursore dell'endpoint di elenco, ma limita ogni pagina a 20 conversazioni. Ogni conversazione include tutti i messaggi non di tipo strumento, ordinati dal più vecchio al più recente.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations/export?source=api_v2' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Successo: 200 OK

{
  "data": [
    {
      "id": "b2mD4kL8pQ1sT6vX",
      "title": "Where is my order?",
      "createdAt": 1784332800,
      "updatedAt": 1784332860,
      "userId": "customer_123",
      "source": "api_v2",
      "status": "ongoing",
      "messages": [
        {
          "id": "122",
          "role": "user",
          "parts": [{ "type": "text", "text": "Where is my order?" }],
          "createdAt": 1784332800,
          "feedback": null,
          "metadata": null
        }
      ]
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Recupera una conversazione

Percorso: /api/v2/agents/{agentId}/conversations/{conversationId}

GET /api/v2/agents/{agentId}/conversations/{conversationId}

Autenticazione: Chiave API Bearer con accesso a {agentId}.

La risposta include l'intera trascrizione non di tipo strumento, ordinata dal più vecchio al più recente. Questo endpoint non è paginato tramite cursore; usa l'endpoint di elenco dei messaggi per un accesso paginato ai messaggi API v2.

Successo: 200 OK

{
  "data": {
    "id": "b2mD4kL8pQ1sT6vX",
    "title": "Where is my order?",
    "createdAt": 1784332800,
    "updatedAt": 1784332860,
    "userId": "customer_123",
    "source": "api_v2",
    "status": "ongoing",
    "messages": [
      {
        "id": "122",
        "role": "user",
        "parts": [{ "type": "text", "text": "Where is my order?" }],
        "createdAt": 1784332800,
        "feedback": null,
        "metadata": null
      }
    ]
  },
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Una conversazione mancante all'interno della fonte selezionata restituisce 404 RESOURCE_NOT_FOUND.

Elenca i messaggi

Percorso: /api/v2/agents/{agentId}/conversations/{conversationId}/messages

GET /api/v2/agents/{agentId}/conversations/{conversationId}/messages

Autenticazione: Chiave API Bearer con accesso a {agentId}. La conversazione deve essere una conversazione API v2.

I cursori dei messaggi sono l'unico tipo di cursore di paginazione v2 il cui componente ID lato server viene validato come stringa numerica, perché i messaggi usano ID bigint. Ogni altra risorsa v2 paginata valida ID di tipo UUID. Tratta entrambe le forme come opache; non costruire né decodificare mai i cursori. All'interno di ogni pagina restituita, i messaggi sono ordinati dal più vecchio al più recente.

Successo: 200 OK

{
  "data": [
    {
      "id": "122",
      "role": "user",
      "parts": [{ "type": "text", "text": "Where is my order?" }],
      "createdAt": 1784332800,
      "feedback": null,
      "metadata": null
    },
    {
      "id": "123",
      "role": "assistant",
      "parts": [{ "type": "text", "text": "Please share your order number." }],
      "createdAt": 1784332860,
      "feedback": "positive",
      "metadata": null
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 2
  }
}

Una conversazione API v2 mancante restituisce 404 RESOURCE_NOT_FOUND; limiti e cursori non validi restituiscono 400 VALIDATION_INVALID_BODY.

Riprova una risposta dell'assistente

Percorso: /api/v2/agents/{agentId}/conversations/{conversationId}/retry

POST /api/v2/agents/{agentId}/conversations/{conversationId}/retry

Autenticazione: Chiave API Bearer con accesso a {agentId}. La conversazione deve essere una conversazione API v2.

Il tentativo di rigenerazione elimina il messaggio utente precedente, la risposta dell'assistente selezionata e ogni messaggio successivo, quindi rinvia quel testo utente per rigenerare la risposta. Se la rigenerazione non riesce a essere salvata, le righe eliminate vengono ripristinate.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations/b2mD4kL8pQ1sT6vX/retry' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"messageId":"123","stream":false}'

Successo: 200 OK. Con stream: true, la risposta è uno stream di Server-Sent Events che usa lo stesso formato di evento della chat. Con stream: false, la risposta è:

{
  "data": {
    "id": "124",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "Here is a regenerated answer." }],
    "metadata": {
      "conversationId": "b2mD4kL8pQ1sT6vX",
      "finishReason": "stop",
      "usage": { "credits": 1 }
    }
  }
}

Un JSON malformato restituisce 400 VALIDATION_INVALID_JSON. I corpi non validi restituiscono 400 VALIDATION_INVALID_BODY. Consulta CHAT_RETRY_MESSAGE_NOT_FOUND, CHAT_RETRY_NO_USER_MESSAGE, RESOURCE_NOT_FOUND e INTERNAL_SERVER_ERROR nel catalogo degli errori.

Invia un risultato di uno strumento

Percorso: /api/v2/agents/{agentId}/conversations/{conversationId}/tool-result

POST /api/v2/agents/{agentId}/conversations/{conversationId}/tool-result

Autenticazione: Chiave API Bearer con accesso a {agentId}.

{
  "toolCallId": "call_123",
  "output": { "available": true }
}

Risposta: Un'azione in sospeso corrispondente viene acquisita una sola volta e la continuazione viene restituita come text/event-stream. Le chiamate sconosciute o scadute restituiscono 404; i risultati concorrenti o in conflitto restituiscono 409.

Imposta o cancella il feedback di un messaggio

Percorso: /api/v2/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback

PATCH /api/v2/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback

Autenticazione: Chiave API Bearer con accesso a {agentId}. La conversazione deve essere una conversazione API v2.

{messageId} deve poter essere convertito in un intero positivo e deve identificare un messaggio dell'assistente AI nella conversazione specificata.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations/b2mD4kL8pQ1sT6vX/messages/123/feedback' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"feedback":"positive"}'

Successo: 200 OK

{
  "data": {
    "id": "123",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "Please share your order number." }],
    "createdAt": 1784332860,
    "feedback": "positive",
    "metadata": null
  }
}

Un JSON malformato restituisce 400 VALIDATION_INVALID_JSON; un corpo non valido restituisce 400 VALIDATION_INVALID_BODY; una conversazione mancante restituisce 404 RESOURCE_NOT_FOUND; un messaggio mancante restituisce 404 RESOURCE_MESSAGE_NOT_FOUND; e un obiettivo che non è un messaggio dell'assistente AI restituisce 422 RESOURCE_MESSAGE_NOT_ASSISTANT.

Elenca le conversazioni di un utente

Percorso: /api/v2/agents/{agentId}/users/{userId}/conversations

GET /api/v2/agents/{agentId}/users/{userId}/conversations

Autenticazione: Chiave API Bearer con accesso a {agentId}.

{userId} deve essere lungo da 1 a 128 caratteri e può contenere solo lettere, numeri, ., _ e -.

Solo la chat API v2 scrive userId, quindi questo endpoint restituisce solo conversazioni API v2. La sua risposta con esito positivo usa lo stesso envelope paginato di riepilogo delle conversazioni di Elenca le conversazioni.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/users/customer_123/conversations' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Successo: 200 OK. ID utente, limiti, cursori o un uso non valido di source restituiscono 400 VALIDATION_INVALID_BODY.

Riferimenti correlati

• Panoramica API v2 e chat
• Catalogo degli errori API v2
• Contatti e identità verificata