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.

Screenshot 2024-02-07 at 10.29.51.png

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/v3/get-signed-urls

USA: POST - https://api.us.ultimate.ai/data-export/v3/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 anfordern, die bis zum 1. Januar 2024 zurückgehen. Wenn Sie ältere Daten benötigen, wenden Sie sich an den Zendesk-Kundensupport.

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"
},
"conversation_type" In der Konversation identifizierter Antworttyp. Mögliche Werte: „Use case“, „Knowledge“, „Hybrid“ und „Others“ 
"conversation_type": {
"type": "string"
},
"language" Sprache der Konversation 
"language": {
"type": "string"
},
"channel" Kanal der Konversation Entweder Messaging oder E-Mail 
"channel": {
"type": "string"
},
"labels" Liste aller mit der Konversation verknüpften Stichwörter 
"labels": {
"type": "array",
"items": {
"type": "string"
  }
},
"segments" Liste aller in der Konversation identifizierten Segmente. Weitere Infos über Benutzersegmente finden Sie hier. 
"segments": {
"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"
},
"automated_resolution" Das Ergebnis der Bewertung, bei der die Konversation als automatisierte Lösung eingestuft wurde. Weitere Informationen zur Berechnung automatisierter Lösungen finden Sie hier. 
"automated_resolutions": {
"type": "string"
},
"automated_resolution_reasoning" Begründung, warum eine Konversation als automatisch gelöst markiert wurde. 
"automated_resolution_reasoning": {
"type": "string"
},
"last_resolution"

Endgültige Lösung der Konversation. Mögliche Werte: „informed“, „resolved“, „escalated“ oder „undefined“.

Diese Funktion wird am 28. Februar 2026 entfernt. Weitere Informationen zur bevorstehenden Entfernung von Funktionen finden Sie hier.

 
"last_resolution": {
"type": "string"
},
"triggered_replies" Die Details zu einer Antwort. Dazu gehören Werte wie „reply_id“, „language“, „reply_name“, „reply_type“ und „intent_id“. 
"triggered_replies": {
"type": "array",
"items": {
"type": "string"
   }
},
"triggered_procedures"

Dazu gehören Werte wie „procedure_id“, „intent_id“ und „use_case_name“. 

Dieser Abschnitt ist leer für AI Agents ohne Training oder wenn keine Abläufe ausgelöst wurden.

 
"triggered_procedures": {
"type": "array",
"items": {
"type": "string"
}
},
"triggered_use_cases"

Markierung, die angibt, ob der Anwendungsfall als Dialog oder als Ablauf konfiguriert ist.

 
"triggered_use_cases": {
"type": "array",
"items": {
"type": "string"
   }
},
"has_knowledge_response_attempt" Markierung, die angibt, ob es sich um eine Wissenskonversation handelt ( mit mindestens einer Wissensantwort), unabhängig davon, ob die Wissensantwort verstanden wurde, ein technischer Fehler aufgetreten ist, es sich um Small Talk handelte usw.  
"has_knowledge_response_attempt": {
"type": "boolean"
},
"knowledge_notUnderstood_count" Anzahl der nicht verstandenen Nachrichten in der Wissenskonversation. Bei agentischen Wissensantworten gehören dazu auch Folgefragen, wenn der AI Agent keine geeignete Wissensquelle berücksichtigt hat, um eine Antwort auf die Frage zu generieren. 
"knowledge_notUnderstood_count": {
"type": "string"
},
"knowledge_responseGenerated_count" Anzahl der generierten Antwortnachrichten in der Wissenskonversation 
"knowledge_responseGenerated_count": {
"type": "string"
},
"knowledge_errorOccurred_count" Anzahl der Nachrichten mit „Fehler aufgetreten“ in der Wissenskonversation 
"knowledge_errorOccurred_count": {
"type": "string"
},
"knowledge_escalationRequired_count" Anzahl der Nachrichten mit „Eskalation erforderlich“ in der Wissenskonversation. Dieser Status gilt nur für generative, als Antwort verarbeitete Wissensantworten. 
"knowledge_escalationRequired_count": {
"type": "string"
},
"knowledge_fallback_count" Anzahl der Fallback-Nachrichten in der Wissenskonversation 
"knowledge_fallback_count": {
"type": "string"
},
"knowledge_sources" Liste der in der Konversation verwendeten Arten von Wissensdatenbanken, Beitragstitel und URLs. 
"knowledge_sources": {
"type": "array",
"items": {
"type": "string"
}
},
"bot_messages_count" Anzahl der AI Agent-Nachrichten 
"bot_messages_count": {
"type": "string"
},
"visitor_messages_count" Anzahl der Kundennachrichten 
 "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",
  "customer_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,

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

Erste / letzte Absicht aus einer Konversation

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

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.

 

Powered by Zendesk