La nostra API di esportazione dei dati è la chiave per sfruttare appieno il potenziale del tuo agenti AI, consentendoti di esportare i dati delle conversazioni e integrarli in diverse piattaforme e applicazioni.
Che tu sia uno sviluppatore, un analista aziendale o un professionista IT, la nostra API offre una soluzione semplificata e sicura per estrarre informazioni preziose e metadati delle conversazioni, consentendoti di promuovere l’innovazione, prendere decisioni informate e portare la tua organizzazione a nuovi traguardi.
Questo articolo include i seguenti argomenti:
- Ottieni l’ID organizzazione
- Genera un token API
- Informazioni sull’API
- Schema di file
- Esempio di risposta
- Metriche popolari
- Domande frequenti
Ottieni l’ID organizzazione
Questo passaggio può essere eseguito solo dagli utenti con un ruolo di amministratore
- Nella barra laterale sinistra, fai clic su Gestione organizzazione.
Nota: Se hai acquistato agenti AI - Avanzati prima del 7 ottobre 2024, fai clic su Gestione utenti > Gestione dell’organizzazione, invece.
- Fai clic sulla tua organizzazione per aprirne il profilo.
- Trova l’ID organizzazione nell’URL del browser:
https://dashboard.ultimate.ai/admin/organizations/77m57af6811115b53172431s
Genera un token API
La generazione di un token può essere eseguita solo dagli utenti con un ruolo di amministratore
- Nella barra laterale sinistra, fai clic su Gestione organizzazione.
Nota: Se hai acquistato agenti AI - Avanzati prima del 7 ottobre 2024, fai clic su Gestione utenti > Gestione dell’organizzazione, invece.
- Fai clic sulla tua organizzazione per aprirne il profilo.
- Seleziona la scheda Chiave API .
- Fai clic su Genera.
- Fai clic su Salva.
- Copia la chiave e tienila al sicuro.
Una volta usciti dalla pagina di gestione dell’organizzazione, non potrai più accedere al token. Se hai perso il token generato in precedenza, puoi semplicemente revocarlo facendo clic sul pulsante Rigenera . La validità del token precedente verrà revocata e potrai usare il token appena generato.
Informazioni sull’API
L’API di esportazione dei dati viene aggiornata una volta al giorno, a mezzanotte UTC (Coordinated Universal Time). Questo processo di aggiornamento può durare un po’ di tempo, quindi l’importazione dell’ora UTC mattutina aiuta a garantire che i dati siano già disponibili.
Per l’UE: POST - https://api.ultimate.ai/data-export/v3/get-signed-urls
Per gli Stati Uniti: POST - https://api.us.ultimate.ai/data-export/v3/get-signed-urls
Intestazione
|
nome |
obbligatorio |
tipo |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Corpo
|
nome |
obbligatorio |
tipo |
|---|---|---|
|
|
|
|
Risposta
|
Codice HTTP |
risposta |
|---|---|
|
200 |
|
|
401 |
Non autorizzato |
|
500 |
Errore interno del server |
Nota:
- L’URL del file scade dopo un giorno dalla data della richiesta. Per ottenere un link valido, è possibile eseguire di nuovo una chiamata API.
- Puoi richiedere dati che risalgono al 1 gennaio 2024. Se hai bisogno di dati meno recenti, contatta assistenza clienti Zendesk per assistenza.
Schema di file
L’output dell’API è un documento JSON con tutte le conversazioni di un determinato giorno, secondo la struttura qui illustrata:
- Il file è un elenco di oggetti JSON in cui ogni oggetto è una conversazione
- Il file avrà il nome convention_bot-id_date_000000000000.json
| Proprietà | Descrizione | Tipo |
| "bot_id" | ID univoco del bot |
"bot_id": {
|
| "bot_name" | Nome del bot |
"bot_name": {
|
| "id_conversazione" | ID conversazione generato |
"conversation_id": {
|
| "platform_conversation_id" | ID specifico CRM |
"platform_conversation_id": {
|
| "conversation_start_time" | Data e ora di inizio della conversazione in base al fuso orario UTC |
"conversation_start_time": {
|
| "conversation_end_time" | Data e ora di conclusione della conversazione in base al fuso orario UTC |
"conversation_end_time": {
|
| "tipo_conversazione" | Tipo di risposta identificato nella conversazione. I valori possibili includono Caso d’uso, Knowledge, Ibrido e Altro. |
"conversation_type": {
|
| "lingua" | Lingua della conversazione |
"language": {
|
| "canale" | Canale della conversazione. Messaggistica o email |
"channel": {
|
| "etichette" | Elenco di tutte le etichette associate alla conversazione |
"labels": {
|
| "segmenti" | Elenco di tutti i segmenti identificati nella conversazione. Ulteriori informazioni sui segmenti. |
"segments": {
|
| "conversations_data" |
I parametri di sessione sono associati alle conversazioni. È un elenco della chiave del parametro in cui aveva un valore. Le chiavi non definite non saranno in questo elenco Nota:
Esempio: "conversations_data": {
|
"conversations_data": {
|
|
"test_mode"
|
Un flag per identificare se la conversazione è di prova |
"test_mode": {
|
| "conversation_status" | Soluzione della conversazione Esempio: bot_handled |
"conversation_status": {
|
| "risoluzione_automatica" | Il risultato della valutazione della conversazione come soluzione automatizzata. Ulteriori informazioni su come vengono calcolate le soluzioni automatizzate. |
"automated_resolutions": {
|
| "automated_resolution_reasoning" | Il ragionamento usato per determinare il motivo per cui una conversazione è stata contrassegnata come risolta automaticamente. |
"automated_resolution_reasoning": {
|
| "last_resolution" |
Questa è la soluzione finale della conversazione. Potrebbe essere informato, risolto, inoltrato o non definito. Questa funzione verrà rimossa il 28 febbraio 2026. Ulteriori informazioni sulla rimozione imminente della funzione. |
"last_resolution": {
|
| "triggered_replies" | I dettagli relativi a una risposta. Ciò include informazioni come answer_id, language, reply_name, reply_type, intent_id. |
"triggered_replies": {
|
| "triggered_procedures" |
Ciò include informazioni come procedure_id, intent_id, use_case_name. Questa sezione è vuota pergli agenti AI che addestrano z ero o quandonon ci sono procedure attivate. |
"triggered_procedures": {
|
| "triggered_use_cases" |
Un flag per identificare se il caso d’uso è configurato come finestra di dialogo o procedura. |
"triggered_use_cases": {
|
| "has_knowledge_response_attempt" | Un flag per identificare se la conversazione è una conversazione Knowledge (con almeno una risposta Knowledge), indipendentemente dal fatto che la risposta sia stata compresa, si sia verificato un errore tecnico, si sia trattato di chiacchiere, ecc. |
"has_knowledge_response_attempt": {
|
| "knowledge_notUnderstood_count" | Il numero di messaggi non compresi nella conversazione di Knowledge. Per le risposte della Knowledge base degli agenti, ciò può includere domande di follow-up in cui l’ agenti AI non ha abbinato la domanda a una fonte di conoscenza appropriata per generare una risposta. |
"knowledge_notUnderstood_count": {
|
| "knowledge_responseGenerated_count" | Il numero di messaggi generati dalla risposta nella conversazione di Knowledge. |
"knowledge_responseGenerated_count": {
|
| "knowledge_errorOccurred_count" | Il numero di messaggi di errore nella conversazione Knowledge. |
"knowledge_errorOccurred_count": {
|
| "knowledge_escalationRequired_count" | Il numero di messaggi escalationRequired nella conversazione Knowledge. Questo stato è applicabile solo alle risposte di Knowledge gestite con risposta generativa. |
"knowledge_escalationRequired_count": {
|
| "knowledge_fallback_count" | Il numero di messaggi di fallback nella conversazione di Knowledge. |
"knowledge_fallback_count": {
|
| "source_sources" | Un elenco del tipo di Knowledge base, del titolo dell’articolo e dell’URL usati nella conversazione. |
"knowledge_sources": {
|
| "bot_messages_count" | Il numero di messaggi agenti AI |
"bot_messages_count": {
|
| "visitor_messages_count" | il numero di messaggi dei clienti |
"visitor_messages_count": {
|
| "not_understood_messages_count" | Il numero di messaggi non compresi in generale |
"not_understood_messages_count": {
|
Esempio di risposta
La risposta della chiamata API è un link URL a un file in un bucket di archiviazione Google a cui puoi accedere con una richiesta GET:
{"date":"2024-05-03","urls":["https://storage.googleapis.com/production-eu-ultimateai-backend-data-export/files/your_bot_id/2024-05-0/conversation_your_bot_id_20240503_000000000000.json…"]} Il file contiene ogni conversazione come oggetto json nel seguente formato:
{
"bot_id": "98174e8d635471c383b9ec7b",
"bot_name": "INDUSTRY DEMO (Travel) - SunCo",
"conversation_id": "67bc4129-6609-4v67-869d-db1d0186d1d8",
"platform_conversation_id": "57459bd72555b8452378f693",
"conversation_start_time": "2024-05-03T08:10:01.211+00:00",
"conversation_end_time": "2024-05-03T08:10:25.744+00:00",
"language": "eng",
"channel": "chat",
"labels": [
"web",
"API:getBookingDetails-Success"
],
"conversations_data": {
"bsatScore" : 5,
"convoId": "552cd72556e8452378d344",
"email": null,
"location": null,
"confidence_score": 95,
"lastDetectedLanguage": "eng",
"lastDetectedSentiment": "neutral",
"usedLanguage": "eng",
"channel": "web",
"bookingNo": null,
"booking":
[{
"country": "Spain",
"url": "https://cdn.pixabay.com/photo/2015/05/05/01/10/house-753270__340.jpg",
"location": "41.3485806,1.9787689",
"city": "Barcelona",
"numOfGuests": 4,
"days": 4,
"arrivalDate": "12-12-2022"
}],
"city": "Barcelona",
"manageBooking": "possible"
},
"test_mode": false,
"conversation_status": "botHandled",
"last_resolution": "resolved"
"triggered_replies": [
{
"reply_timestamp": "2024-05-03T08:10:02.991+00:00",
"reply_id": "53628e8e55b4f2459bcb2e72",
"reply_language": "eng",
"reply_name": "Greeting",
"reply_type": "normal",
"intent_id": "64628b8e55e4f2459bcb2e68"
},
{
"reply_timestamp": "2024-05-03T08:10:03.355+00:00",
"reply_id": "64628e8e55e4f2459bcb2f4b",
"reply_language": "eng",
"reply_name": "Welcome reply",
"reply_type": "welcome"
},
{
"reply_timestamp": "2024-05-03T08:10:12.951+00:00",
"reply_id": "2475e571f88f9c35af3ff45e",
"reply_language": "eng",
"reply_name": "Office or store location and opening hours",
"reply_type": "normal",
"intent_id": "6385e571f88f9c35af3ff46e"
}
],
"triggered_intent_replies": [
{
"intent_timestamp": "2024-05-03T08:10:02.991+00:00",
"intent_id": "53628e8e55b4f2459bcb2e72",
"intent_name": "Greeting",
"not_meaningful": true
},
{
"intent_timestamp": "2024-05-03T08:10:12.951+00:00",
"intent_id": "6375b571f88f9c35af3ff44e",
"intent_name": "Find location of rental",
"not_meaningful": false
}
],
"is_llm_conversation": false,
"bot_messages_count": "7",
"customer_messages_count": "4",
"not_understood_messages_count": "0"
}
Metriche popolari
Complimenti! Hai esportato correttamente i dati della conversazione dell’agente AI . Ecco alcuni dei nostri suggerimenti per iniziare il percorso di esplorazione dei dati dei file esportati.
Metriche agenti AI
SELECT
--Total conversations
count(distinct conversation_id) total_conversations,
--AI agent handled rate
count(distinct case when conversation_status = 'botHandled' then conversation_id end) bot_handled_conversations,
count(distinct case when conversation_status = 'botHandled' then conversation_id end)/count(distinct conversation_id) bot_handled_rate,
--Deflection rate
count(distinct case when conversation_status not in ('email', 'agent', 'customEscalation') then conversation_id end)/count(distinct conversation_id) deflection_rate,
--Escalation rate
count(distinct case when conversation_status in ('email', 'agent', 'customEscalation') then conversation_id end)/count(distinct conversation_id) escalation_rate,
--Failed escalation rate
count(distinct case when conversation_status = 'failedEscalation' then conversation_id end)/count(distinct conversation_id) failed_escalation_rate,
--Message understood rate
(sum(customer_messages_count)-sum(not_understood_messages_count
))/sum(customer_messages_count) messages_understood_rate
FROM TABLE
Primo/ultimo scopo di una conversazione
select
distinct conversation_id,
triggered_use_cases[safe_offset(0)].intent_name first_intent,
array_reverse(triggered_intent_replies)[safe_offset(0)].intent_name last_intent
FROM TABLE
Domande frequenti
-
I file esportati sono immutabili o cambiano nel tempo e richiedono una nuova sincronizzazione?
I file esportati non sono modificabili, quindi non devono essere reimportati, rendendo così la pipeline BI meno soggetta a errori. -
Vedo differenze nei conteggi delle conversazioni per una data specifica tra le conversazioni esportate e l’analisi di riepilogo agenti AI . Quale potrebbe essere il motivo?
I dati esportati per una data specifica contengono dati solo per le conversazioni terminate in quella data. Si tratta di un approccio diverso rispetto all’analiticaRiepilogo agenti AI, in cui è inclusa qualsiasi conversazione in qualsiasi stato. Ciò avviene per diversi motivi, tra cui: immutabilità dei file di esportazione e prevenzione della duplicazione dei dati. -
Allora come posso ottenere la parità tra i numeri riportati nel riepilogo agenti AI e i file esportati?
Per avere un quadro completo di tutte le conversazioni che hanno avuto luogo in un determinato giorno x, puoi semplicemente importare il file generato per il giorno x e il giorno x + 1. Importando i file di queste due date, ti assicuri di aver conteggiato tutte le conversazioni per la data x, anche se sono state trasferite al giorno successivo. -
Vedo differenze nei conteggi delle conversazioni per una data specifica tra le conversazioni esportate e i registri delle conversazioni. Quale potrebbe essere il motivo?
Tieni presente che i dati esportati per una data specifica contengono dati solo per le conversazioni terminate in quella data. Questo è un approccio diverso rispetto ai registri delle conversazioni, in cui qualsiasi conversazione in qualsiasi stato viene inclusa per abilitare il debug in tempo reale. -
Una conversazione include informazioni su tutte le risposte attivate in una conversazione, anche se tali risposte sono avvenute il giorno precedente?
Sì. Se una conversazione è inclusa nel file, conterrà tutti i suoi dati, anche se si è verificata in un giorno precedente. -
Il mio agente virtuale ha conversazioni come parte del motore dei suggerimenti. Verranno visualizzate nell’esportazione?
Sì. Sebbene nel dashboard di riepilogo agenti AI siano esclusi, saranno comunque disponibili nei dati esportati. Per escluderli e ottenere la parità con il dashboard di riepilogo agenti AI , filtra per "bot_messages_count > 0".
Avvertenza sulla traduzione: questo articolo è stato tradotto usando un software di traduzione automatizzata per fornire una comprensione di base del contenuto. È stato fatto tutto il possibile per fornire una traduzione accurata, tuttavia Zendesk non garantisce l'accuratezza della traduzione.
Per qualsiasi dubbio sull'accuratezza delle informazioni contenute nell'articolo tradotto, fai riferimento alla versione inglese dell'articolo come versione ufficiale.