Utilisation de l’API d’exportation de données pour les agents IA - Avancé

Mon édition

Module supplémentaire

Agents IA - avancé

Notre API Exportation des données constitue la clé pour profiter de tout le potentiel de votre agent IA, vous permettant d’exporter les données des conversations et de les intégrer dans différentes plateformes et applications.

Que vous soyez développeur, analyste commercial ou professionnel de l’informatique, notre API fournit une solution rationalisée et sécurisée pour extraire des informations précieuses et des métadonnées de conversation, ce qui vous permet de stimuler l’innovation, de prendre des décisions éclairées et de propulser votre organisation vers de nouveaux sommets.

Cet article aborde les sujets suivants :

• Obtenir l’ID de l’organisation
• Générer un token API
• À propos de l’API
• Schéma de fichiers
• Exemple de réponse
• Mesures populaires
• Questions fréquentes

Obtenir l’ID de l’organisation

Cette étape ne peut être effectuée que par les utilisateurs ayant le rôle d’administrateur

1. Dans la barre latérale gauche, cliquez sur Gestion des organisations.
   Remarque – Si vous avez acheté Agents IA - Avancé avant le 7 octobre 2024, cliquez sur Gestion des utilisateurs > Gestion des organisations à la place.
2. Cliquez sur votre organisation pour ouvrir son profil.
3. Trouvez l’ID de l’organisation dans l’URL dans votre navigateur :

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

Générer un token API

La génération d’un token ne peut être effectuée que par les utilisateurs ayant le rôle d’administrateur

1. Dans la barre latérale gauche, cliquez sur Gestion des organisations.
   Remarque – Si vous avez acheté Agents IA - Avancé avant le 7 octobre 2024, cliquez sur Gestion des utilisateurs > Gestion des organisations à la place.
2. Cliquez sur votre organisation pour ouvrir son profil.
3. Cliquez sur l’onglet Clé API.
4. Cliquez sur Générer.
5. Cliquez sur Enregistrer.
6. Copiez la clé et mettez-la en lieu sûr.

Une fois que vous avez quitté la page Gestion des organisations, vous n’avez plus accès au token. Si vous avez perdu le token que vous avez généré, il vous suffit de le révoquer en cliquant sur le bouton Regénérer. La validité de l’ancien token sera révoquée et vous pourrez utiliser le nouveau token généré.

À propos de l’API

L’API Exportation des données est mise à jour une fois par jour, à minuit UTC (temps universel coordonné). Ce processus de mise à jour peut prendre un certain temps, vous avez donc intérêt à lancer l’importation tôt le matin (heure UTC) pour être sûr que les données sont toujours présentes.

Pour l’UE : POST - https://api.ultimate.ai/data-export/v2/get-signed-urls

Pour les États-Unis : POST - https://api.us.ultimate.ai/data-export/v2/get-signed-urls

En-tête

nom	obligatoire	type
botId	true	string
organizationId	true	string
authorization	true	string

Corps

nom	obligatoire	type
date	true	ISO date string

Réponse

Code HTTP	réponse
200	{ "date": "string", "urls": [ "string" ] }
401	Non autorisé
500	Erreur de serveur interne

Remarque –

• L’URL vers le fichier expire après un jour après la date de la demande. Pour obtenir un lien valide, l’API peut être appelée de nouveau.
• Vous pouvez demander les données avec une date dans la plage de 30 jours à partir de la date en cours. Les données plus anciennes sont considérées comme des données historiques et nécessitent des préparations différentes.
  
  • Exemple : si la date en cours est le 15 avril 2024, la date de la demande peut être toute date entre le 16 mars et le 15 avril 2024.

Schéma de fichiers

L’API produit un document JSON avec toutes les conversations d’un jour donné, en suivant la structure décrite ci-après :

• Le fichier est une liste d’objets JSON, où chaque objet représente une conversation
• Le fichier suivra la convention de nommage conversation_bot-id_date_000000000000.json

Propriété	Description	Type
"bot_id"	ID unique du bot	"bot_id": { "type": "string" },
"bot_name"	Nom du bot	"bot_name": { "type": "string" },
"conversation_id"	ID de conversation générée	"conversation_id": { "type": "string" },
"platform_conversation_id"	ID spécifique au CRM	"platform_conversation_id": { "type": "string" },
"conversation_start_time"	Date et heure du début de la conversation, en fonction du fuseau horaire UTC	"conversation_start_time": { "type": "string" },
"conversation_end_time"	Date et heure de la fin de la conversation, en fonction du fuseau horaire UTC	"conversation_end_time": { "type": "string" },
"language"	Langue de la conversation	"language": { "type": "string" },
"channel"	Canal de la conversation. Chat ou ticket	"channel": { "type": "string" },
"labels"	Liste des libellés associés à la conversation	"labels": { "type": "array", "items": { "type": "string" } },
"conversations_data"	Les paramètres de la session sont associés aux conversations. Il s’agit d’une liste de clés de paramètres ayant une valeur. Les clés non définies ne seront pas dans la liste. Remarque – Même si elle est stockée sous forme de chaîne, “conversations_data” contient un autre objet JSON. Le score BSAT est inclus dans l’objet de données des conversations. Valeurs de score BSAT -1 = le BSAT a été proposé à l’utilisateur mais celui-ci n’a pas répondu NULL = le BSAT n’a pas été proposé à l’utilisateur Exemple : "conversations_data": { "parameter1": true, "parameter2": "parameter_value", "parameter3": "1234" },	"conversations_data": { "type": "string" },
"test_mode"	Un drapeau indiquant si la conversation est une conversation test	"test_mode": { "type": "boolean" },
"conversation_status"	Résolution de la conversation. Exemple : bot_handled	"conversation_status": { "type": "string" },
"last_resolution"	Résolution finale de la conversation. Valeurs possibles : informée, résolue, remontée ou indéfinie.	"last_resolution": { "type": "string" },
"triggered_replies"		"triggered_replies": { "type": "array", "items": { "type": "string" } },
"triggered_intent_replies"	Réponses basées sur l’intention	"triggered_intent_replies": { "type": "array", "items": { "type": "string" } },
"is_llm_conversation"	Drapeau indiquant si la conversation est une conversation LLM (doit avoir au moins une réponse LLM)	"is_llm_conversation": { "type": "boolean" },
"llm_notUnderstood_count"	Nombre de messages non compris dans la conversation LLM	"llm_notUnderstood_count": { "type": "string" },
"llm_responseGenerated_count"	Nombre de messages générés par réponse dans la conversation LLM	"llm_responseGenerated_count": { "type": "string" },
"llm_errorOccurred_count"	Nombre de messages d’erreur dans la conversation LLM	"llm_errorOccurred_count": { "type": "string" },
"llm_escalationRequired_count"	Nombre de messages de remontée obligatoire dans la conversation LLM	"llm_escalationRequired_count": { "type": "string" },
"llm_fallback_count"	Nombre de messages de remplacement dans la conversation LLM	"llm_fallback_count": { "type": "string" },
"bot_messages_count"	Nombre de messages d’agent IA	"bot_messages_count": { "type": "string" },
"visitor_messages_count"	Nombre de messages de visiteurs	"visitor_messages_count": { "type": "string" },
"not_understood_messages_count"	Nombre de messages non compris en général	"not_understood_messages_count": { "type": "string" },

Exemple de réponse

La réponse de l’appel API est un lien (URL) vers un fichier dans un espace de stockage Google auquel vous pouvez accéder avec une demande 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…"]}

Le fichier contient chaque conversation en tant qu’objet json au format suivant :

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

Mesures populaires

Félicitations ! Vous avez exporté avec succès les données des conversations de l’agent IA. Voici quelques suggestions pour commencer à explorer les données de vos fichiers exportés.

Mesures de l’agent IA

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

Première/dernière intention d’une conversation

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

Mesures par première intention pertinente (ou filtrée)

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

Questions fréquentes

• Les fichiers exportés sont-ils immuables ou changent-ils au fil du temps, ce qui vous oblige à les resynchroniser ?
  Les fichiers exportés sont immuables, ils n’ont pas besoin d’être réimportés, ce qui évite les erreurs au niveau de votre pipeline BI.
• Je constate des différences dans le nombre de conversations pour une date spécifique, entre les conversations exportées et les analyses récapitulatives de l’agent IA. Pouvez-vous m’expliquer pourquoi ?
  Les données exportées pour une date spécifique ne concernent que les conversations qui se sont terminées à cette date. Il s’agit d’une approche différente de celle des analyses récapitulatives de l’agent IA, dans lesquelles toutes les conversations sont incluses, quel que soit leur état. Cela se fait pour de multiples raisons, comme l’immuabilité des fichiers exportés et la prévention des données en double.
• Comment puis-je alors obtenir la parité entre les nombres signalés par le résumé de l’agent IA et les fichiers exportés ?
  Pour obtenir une vision d’ensemble de toutes les conversations qui ont eu lieu un jour donné (x), il vous suffit d’ingérer le fichier généré pour le jour x et jour x + 1. En ingérant les fichiers de ces deux dates, vous serez certain d’avoir compté toutes les conversations pour la date x, même si elles ont débordé jusqu’au jour suivant.
• Je constate des différences dans les nombres de conversations pour une date spécifique entre les conversations exportées et les journaux de conversations. Pouvez-vous m’expliquer pourquoi ?
  N’oubliez pas que les données exportées à une date spécifique ne contiennent que les données des conversations qui se sont terminées à cette date. Il s’agit d’une approche différente de celle des journaux de conversation, dans lesquels toutes les conversations sont incluses, quel que soit leur état.
• Est-ce qu’une conversation inclut des informations concernant toutes les réponses déclenchées dans une conversation, même si ces réponses se sont produites le jour précédent ?
  Oui. Si une conversation est incluse dans le fichier, toutes ses données seront présentes, même si elles concernent une activité de la veille.
• Mon agent virtuel a des conversations provenant du moteur de suggestions. Est-ce que ces conversations sont incluses dans l’exportation ?
  Oui. Bien qu’elles soient exclues du tableau de bord récapitulatif de l’agent IA, elles feront partie des données exportées. Pour les exclure et obtenir la parité avec le tableau de bord récapitulatif de l’agent IA, filtrez par "bot_messages_count > 0".