Uso dell’API di esportazione dati per agenti di AI avanzati

What's my plan?

Add-on

AI agents - Advanced

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

1. 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.
2. Fai clic sulla tua organizzazione per aprirne il profilo.
3. 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

1. 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.
2. Fai clic sulla tua organizzazione per aprirne il profilo.
3. Seleziona la scheda Chiave API .
4. Fai clic su Genera.
5. Fai clic su Salva.
6. 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.

POST - https://api.ultimate.ai/data-export/v2/get-signed-urls

Intestazione

name	obbligatorio	tipo
botId	true	string
organizationId	true	string
authorization	true	string

Corpo

name	obbligatorio	tipo
date	true	ISO date string

Risposta

Codice HTTP	risposta
200	{ "date": "string", "urls": [ "string" ] }
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 con una data entro un intervallo di 30 giorni dalla data corrente. Tutti i dati meno recenti sono considerati dati storici e richiedono preparazioni diverse.
  
  • Esempio: Se la data corrente è il 15 aprile 2024, la data della richiesta può essere qualsiasi data compresa tra il 16 marzo 2024 e il 15 aprile 2024.

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": { "type": "string" },
"bot_name"	Il nome del bot	"bot_name": { "type": "string" },
"id_conversazione"	ID conversazione generato	"conversation_id": { "type": "string" },
"platform_conversation_id"	ID specifico per CRM	"platform_conversation_id": { "type": "string" },
"conversation_start_time"	Data e ora di inizio della conversazione in base al fuso orario UTC	"conversation_start_time": { "type": "string" },
"conversation_end_time"	Data e ora di conclusione della conversazione in base al fuso orario UTC	"conversation_end_time": { "type": "string" },
"lingua"	Lingua della conversazione	"language": { "type": "string" },
"canale"	Canale della conversazione. Chat o ticket	"channel": { "type": "string" },
"etichette"	elenco di tutte le etichette associate alla conversazione	"labels": { "type": "array", "items": { "type": "string" } },
"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: anche se è memorizzato come stringa, “conversations_data” contiene un altro oggetto JSON il punteggio BSAT è fornito nell’oggetto dati conversazioni Valori del punteggio BSAT -1 = L’utente ha ricevuto l’opzione BSAT ma non ha lasciato una risposta NULL = all’utente non è stato offerto BSAT Esempio: "conversations_data": { "parameter1": true, "parameter2": "parameter_value", "parameter3": "1234" },	"conversations_data": { "type": "string" },
"test_mode"	un flag per identificare se la conversazione è di prova	"test_mode": { "type": "boolean" },
"conversation_status"	Soluzione della conversazione Esempio: bot_handled	"conversation_status": { "type": "string" },
"last_resolution"	Questa è la soluzione finale della conversazione. Potrebbe essere informato, risolto, inoltrato o non definito.	"last_resolution": { "type": "string" },
"triggered_replies"		"triggered_replies": { "type": "array", "items": { "type": "string" } },
"triggered_intent_replies"	le risposte basate sullo scopo	"triggered_intent_replies": { "type": "array", "items": { "type": "string" } },
"is_llm_conversation"	un contrassegno per identificare se la conversazione è una conversazione LLM (disporre almeno di una risposta LLM)	"is_llm_conversation": { "type": "boolean" },
"llm_notUnderstood_count"	il numero di messaggi non compresi nella conversazione LLM	"llm_notUnderstood_count": { "type": "string" },
"llm_responseGenerated_count"	il numero di messaggi generati dalle risposte nella conversazione LLM	"llm_responseGenerated_count": { "type": "string" },
"llm_errorOccurred_count"	il numero di messaggi di errore nella conversazione LLM	"llm_errorOccurred_count": { "type": "string" },
"llm_escalationRequired_count"	il numero di messaggi escalationRequired nella conversazione LLM	"llm_escalationRequired_count": { "type": "string" },
"llm_fallback_count"	il numero di messaggi di fallback nella conversazione LLM	"llm_fallback_count": { "type": "string" },
"bot_messages_count"	il numero di messaggi agenti AI	"bot_messages_count": { "type": "string" },
"visitor_messages_count"	il numero di messaggi dei visitatori	"visitor_messages_count": { "type": "string" },
"not_understood_messages_count"	il numero di messaggi non compresi in generale	"not_understood_messages_count": { "type": "string" },

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",
  "visitor_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,

--Bot 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,

--Informed rate
count(distinct case when last_resolution = 'informed' then conversation_id end)/count(distinct conversation_id) informed_rate,

--Custom resolution rate
count(distinct case when last_resolution in ('informed', 'resolved') then conversation_id end)/count(distinct conversation_id) automation_rate,

--Message understood rate
(sum(visitor_messages_count)-sum(not_understood_messages_count
))/sum(visitor_messages_count) messages_understood_rate

FROM TABLE

Primo/ultimo scopo di una conversazione

select 
distinct conversation_id,
triggered_intent_replies[safe_offset(0)].intent_name first_intent,
array_reverse(triggered_intent_replies)[safe_offset(0)].intent_name last_intent
FROM TABLE

Metriche per primo scopo significativo (o filtrato).

with meaningful_intents as (
select conversation_id, first_meaningful_intent, conversation_status from 
(
select distinct conversation_id,
intent.intent_name first_meaningful_intent,
conversation_status,
--order by ascending intent_timestamp for last intent
ROW_NUMBER() OVER (PARTITION BY conversation_id order by intent.intent_timestamp asc) rn,
FROM TABLE
LEFT JOIN UNNEST(triggered_intent_replies) intent
--select only intents that are labeled as meaningful
where intent.not_meaningful is false 
--filter for specific intents
and intent.intent_name not in ('Greeting', 'Talk to a human/agent')
)
where rn=1
)

--calculate metrics for each intent
select first_meaningful_intent,
count(distinct conversation_id) total_conversations,
count(distinct case when conversation_status = 'botHandled' then conversation_id end)/count(distinct conversation_id) bot_handled_rate
from meaningful_intents
group by first_meaningful_intent
order by total_conversations desc

Domande frequenti

• I file esportati sono immutabili o cambiano nel tempo e devi sincronizzarli di nuovo?
  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 sono incluse tutte le conversazioni 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 da 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 è avvenuta il 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 questi 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.