Verwenden der Datenexport-API für AI Agents – Advanced

Welchen Plan habe ich

Add-on

AI Agents – Advanced

Mit unserer Datenexport-API können Sie das Potenzial Ihres AI Agent voll ausschöpfen, indem Sie Konversationsdaten exportieren und in verschiedene Plattformen und Anwendungen integrieren.

Sie stellt eine optimierte und sichere Lösung bereit, mit der Entwickler, Business-Analysten und IT-Experten gleichermaßen wertvolle Insights und Konversationsmetadaten gewinnen können, die Sie in die Lage versetzen, Innovationen voranzutreiben, fundierte Entscheidungen zu treffen und Ihr Unternehmen zu neuen Höhen zu führen.

In diesem Beitrag werden folgende Themen behandelt:

• Organisations-ID abrufen
• API-Token generieren
• Überblick über die API
• Dateischema
• Beispielantwort
• Beliebte Metriken
• Häufig gestellte Fragen

Organisations-ID abrufen

Dieser Schritt kann nur von Benutzern mit einer Administratorrolle ausgeführt werden.

1. Klicken Sie in der linken Seitenleiste auf Organisationsverwaltung.
   Hinweis: Wenn Sie AI Agents – Advanced vor dem 7. Oktober 2024 erworben haben, klicken Sie stattdessen auf Benutzerverwaltung > Organisationsverwaltung.
2. Klicken Sie auf Ihre Organisation, um ihr Profil zu öffnen.
3. Entnehmen Sie Ihre Organisations-ID der URL in der Adresszeile Ihres Browsers:

   https://dashboard.ultimate.ai/admin/organizations/77m57af6811115b53172431s

API-Token generieren

Ein Token kann nur von Benutzern mit einer Administratorrolle generiert werden.

1. Klicken Sie in der linken Seitenleiste auf Organisationsverwaltung.
   Hinweis: Wenn Sie AI Agents – Advanced vor dem 7. Oktober 2024 erworben haben, klicken Sie stattdessen auf Benutzerverwaltung > Organisationsverwaltung.
2. Klicken Sie auf Ihre Organisation, um ihr Profil zu öffnen.
3. Klicken Sie auf die Registerkarte API-Schlüssel.
4. Klicken Sie auf Generieren.
5. Klicken Sie auf Speichern.
6. Kopieren Sie den Schlüssel und bewahren Sie ihn sicher auf.

Nach dem Verlassen der Seite „Organisationsverwaltung“ haben Sie keine Möglichkeit mehr, auf das Token zuzugreifen. Falls Sie das zuvor generierte Token verlieren, können Sie es mit der Schaltfläche Neu generieren einfach widerrufen. Dadurch wird das alte Token ungültig und Sie können das neu generierte Token verwenden.

Überblick über die API

Die Datenexport-API wird täglich um Mitternacht UTC (Coordinated Universal Time) aktualisiert. Da die Aktualisierung einige Zeit in Anspruch nehmen kann, sollten Sie den Importvorgang in den frühen Morgenstunden (UTC) starten, um sicherzustellen, dass die aktuellen Daten verfügbar sind.

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

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

Kopfbereich

name	erforderlich	type
botId	true	string
organizationId	true	string
authorization	true	string

Text

name	erforderlich	type
date	true	ISO date string

Antwort

HTTP-Code	Antwort
200	{ "date": "string", "urls": [ "string" ] }
401	Nicht autorisiert
500	Interner Serverfehler

Hinweis:

• Die URL der Datei läuft einen Tag nach dem Anfragedatum ab. Um einen gültigen Link zu erhalten, können Sie den API-Aufruf wiederholen.
• Sie können Daten der vergangenen 30 Tage anfordern. Ältere Daten gelten als historische Daten und müssen in besonderer Weise aufbereitet werden.
  
  • Beispiel: Bei einem Abruf am 15. April 2024 können Daten zwischen dem 16. März 2024 und dem 15. April 2024 abgerufen werden.

Dateischema

Die API gibt ein JSON-Dokument aus, das alle Konversationen eines bestimmten Tages enthält und wie folgt strukturiert ist:

• Die Datei ist eine Liste von JSON-Objekten, von denen jedes eine Konversation darstellt.
• Der Dateiname folgt dem Schema „Konversation_Bot-ID_Datum_000000000000.json“.

Eigenschaft	Beschreibung	Typ
"bot_id"	Eindeutige ID des Bots	"bot_id": { "type": "string" },
"bot_name"	Name des Bots	"bot_name": { "type": "string" },
"conversation_id"	ID der generierten Konversation	"conversation_id": { "type": "string" },
"platform_conversation_id"	CRM-spezifische ID	"platform_conversation_id": { "type": "string" },
"conversation_start_time"	Datum und Uhrzeit des Beginns der Konversation in UTC	"conversation_start_time": { "type": "string" },
"conversation_end_time"	Datum und Uhrzeit des Endes der Konversation in UTC	"conversation_end_time": { "type": "string" },
"language"	Sprache der Konversation	"language": { "type": "string" },
"channel"	Kanal der Konversation (Chat oder Ticket)	"channel": { "type": "string" },
"labels"	Liste aller mit der Konversation verknüpften Stichwörter	"labels": { "type": "array", "items": { "type": "string" } },
"conversations_data"	Liste der mit der Konversation verknüpften Sitzungsparameter. Enthält nur die Parameterschlüssel, die einen Wert aufweisen. Nicht definierte Schlüssel sind nicht aufgeführt. Hinweis: Obwohl die Konversationsdaten als Zeichenfolge gespeichert werden, enthält auch "conversations_data" ein JSON-Objekt. Der BSAT-Wert wird im Konversationsdatenobjekt bereitgestellt. BSAT-Bewertungen -1 = Benutzer hat eine BSAT-Anfrage erhalten, aber nicht beantwortet NULL = Benutzer hat keine BSAT-Anfrage erhalten Beispiel: "conversations_data": { "parameter1": true, "parameter2": "parameter_value", "parameter3": "1234" },	"conversations_data": { "type": "string" },
"test_mode"	Markierung zur Kennzeichnung von Testkonversationen	"test_mode": { "type": "boolean" },
"conversation_status"	Lösung der Konversation (Beispiel: bot_handled)	"conversation_status": { "type": "string" },
"last_resolution"	Endgültige Lösung der Konversation (mögliche Werte: informiert, gelöst, eskaliert oder nicht definiert)	"last_resolution": { "type": "string" },
"triggered_replies"		"triggered_replies": { "type": "array", "items": { "type": "string" } },
"triggered_intent_replies"	Absichtsbasierte Antworten	"triggered_intent_replies": { "type": "array", "items": { "type": "string" } },
"is_llm_conversation"	Markierung zur Kennzeichnung von LLM-Konversationen (mit mindestens einer LLM-Antwort)	"is_llm_conversation": { "type": "boolean" },
"llm_notUnderstood_count"	Anzahl der nicht verstandenen Nachrichten in der LLM-Konversation	"llm_notUnderstood_count": { "type": "string" },
"llm_responseGenerated_count"	Anzahl der generierten Antwortnachrichten in der LLM-Konversation	"llm_responseGenerated_count": { "type": "string" },
"llm_errorOccurred_count"	Anzahl der Nachrichten mit „Fehler aufgetreten“ in der LLM-Konversation	"llm_errorOccurred_count": { "type": "string" },
"llm_escalationRequired_count"	Anzahl der Nachrichten mit „Eskalation erforderlich“ in der LLM-Konversation	"llm_escalationRequired_count": { "type": "string" },
"llm_fallback_count"	Anzahl der Fallback-Nachrichten in der LLM-Konversation	"llm_fallback_count": { "type": "string" },
"bot_messages_count"	Anzahl der AI Agent-Nachrichten	"bot_messages_count": { "type": "string" },
"visitor_messages_count"	Anzahl der Besuchernachrichten	"visitor_messages_count": { "type": "string" },
"not_understood_messages_count"	Anzahl der nicht verstandenen Nachrichten insgesamt	"not_understood_messages_count": { "type": "string" },

Beispielantwort

Die Antwort auf den API-Aufruf ist ein URL-Link zu einer Datei in einem Google Storage-Bucket, auf das Sie mit einer GET-Anfrage zugreifen können:

{"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…"]}

Die Datei enthält die einzelnen Konversationen als JSON-Objekte im folgenden Format:

{
  "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"
}

Beliebte Metriken

Herzlichen Glückwunsch! Sie haben die Konversationsdaten des AI Agent erfolgreich exportiert. Hier sind einige Vorschläge für Ihren Einstieg in die Analyse der Daten in den exportierten Dateien.

AI Agent-Metriken

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

Erste / letzte Absicht aus einer Konversation

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

Metriken nach der ersten sinnvollen (oder gefilterten) Absicht

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

Häufig gestellte Fragen

• Sind die exportierten Dateien unveränderlich, oder ändern sie sich im Lauf der Zeit und müssen daher neu synchronisiert werden?
  Die exportierten Dateien sind unveränderlich und müssen nicht erneut importiert werden. Dadurch ist Ihre BI-Pipeline weniger fehleranfällig.
• In der Exportdatei und der Übersichtsanalyse des AI Agent sind für ein Datum nicht dieselbe Anzahl von Konversationen enthalten. Was könnte der Grund dafür sein?
  In den Exportdaten sind zu einem bestimmten Datum nur die Konversationen aufgeführt, die an dem betreffenden Tag beendet wurden. Im Gegensatz dazu enthält die Übersichtsanalyse des AI Agent alle Konversationen unabhängig von ihrem Status. Das liegt unter anderem daran, dass die Exportdatei unveränderlich ist und Datenduplikate vermieden werden sollen.
• Wie kann ich dann erreichen, dass die Zahlen in der Übersicht des AI Agent und in den exportierten Dateien übereinstimmen?
  Um die an einem bestimmten Tag geführten Konversationen zu erfassen, können Sie einfach die für Tag x und Tag x+1 generierte Datei einlesen. Auf diese Weise stellen Sie sicher, dass alle Konversationen des Tages x berücksichtigt werden, auch wenn sie erst am nächsten Tag beendet wurden.
• In der Exportdatei und den Konversationsprotokollen sind für ein Datum nicht dieselbe Anzahl von Konversationen enthalten. Was könnte der Grund dafür sein?
  Denken Sie daran, dass in den Exportdaten zu einem bestimmten Datum nur die Konversationen aufgeführt sind, die an dem betreffenden Tag beendet wurden. Im Gegensatz dazu enthalten die Konversationsprotokolle alle Konversationen unabhängig von ihrem Status, um die Fehlersuche in Echtzeit zu ermöglichen.
• Enthält eine Konversation Informationen zu allen in einer Konversation ausgelösten Antworten, auch wenn diese am Vortag gesendet wurden?
  Ja. Wenn eine Konversation in die Datei aufgenommen wurde, enthält die Datei auch Daten, die von einem früheren Tag stammen.
• Mein virtueller Agent weist Konversationen im Zusammenhang mit einer Vorschlagsengine auf. Sind auch diese Konversationen im Export enthalten?
  Ja. Diese Konversationen werden zwar in der Dashboard-Übersicht des AI Agent nicht berücksichtigt, sind aber in den exportierten Daten enthalten. Wenn Sie erreichen möchten, dass die exportierten Daten mit der Dashboard-Übersicht des AI Agent übereinstimmen, können Sie diese Konversationen mit dem Filter „bot_messages_count > 0“ ausschließen.