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
- 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.
- Cliquez sur votre organisation pour ouvrir son profil.
- 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
- 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.
- Cliquez sur votre organisation pour ouvrir son profil.
- Cliquez sur l’onglet Clé API.
- Cliquez sur Générer.
- Cliquez sur Enregistrer.
- 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/v3/get-signed-urls
Pour les États-Unis : POST - https://api.us.ultimate.ai/data-export/v3/get-signed-urls
En-tête
|
nom |
obligatoire |
type |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Corps
|
nom |
obligatoire |
type |
|---|---|---|
|
|
|
|
Réponse
|
Code HTTP |
réponse |
|---|---|
|
200 |
|
|
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 des données remontant jusqu’au 1er janvier 2024. Si vous avez besoin de données plus anciennes, contactez l’assistance client Zendesk.
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": {
|
| "bot_name" | Nom du bot |
"bot_name": {
|
| "conversation_id" | ID de conversation générée |
"conversation_id": {
|
| "platform_conversation_id" | ID spécifique au CRM |
"platform_conversation_id": {
|
| "conversation_start_time" | Date et heure du début de la conversation, en fonction du fuseau horaire UTC |
"conversation_start_time": {
|
| "conversation_end_time" | Date et heure de la fin de la conversation, en fonction du fuseau horaire UTC |
"conversation_end_time": {
|
| "conversation_type" | Type de réponse qui a été identifié dans la conversation. Les valeurs possibles incluent Cas d’utilisation, Connaissances, Hybride et Autres. |
"conversation_type": {
|
| "language" | Langue de la conversation |
"language": {
|
| "channel" | Canal de la conversation. Messagerie ou E-mail. |
"channel": {
|
| "labels" | Liste des libellés associés à la conversation |
"labels": {
|
| "segments" | Liste de tous les segments identifiés dans la conversation. En savoir plus au sujet des segments. |
"segments": {
|
| "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 –
Exemple : "conversations_data": {
|
"conversations_data": {
|
|
"test_mode"
|
Drapeau indiquant si la conversation est une conversation test |
"test_mode": {
|
| "conversation_status" | Résolution de la conversation. Exemple : bot_handled |
"conversation_status": {
|
| "automated_resolution" | Résultat de l’évaluation de la conversation en tant que résolution automatisée. En savoir plus sur le calcul des résolutions automatisées. |
"automated_resolutions": {
|
| "automated_resolution_reasoning" | Raisonnement utilisé pour déterminer pourquoi une conversation a été marquée comme résolue automatiquement. |
"automated_resolution_reasoning": {
|
| "last_resolution" |
Résolution finale de la conversation. Valeurs possibles : informée, résolue, remontée ou indéfinie. Nous supprimerons cette fonctionnalité le 28 février 2026. En savoir plus sur la suppression de cette fonctionnalité. |
"last_resolution": {
|
| "triggered_replies" | Détails associés à une réponse. Cela inclut des informations comme reply_id, language, reply_name, reply_type, intent_id. |
"triggered_replies": {
|
| "triggered_procedures" |
Cela inclut des informations comme procedure_id, intent_id, use_case_name. Cette section est vide pour les agents sans formation ou quand aucune procédure n’est déclenchée. |
"triggered_procedures": {
|
| "triggered_use_cases" |
Drapeau indiquant si le cas d’utilisation est configuré comme un dialogue ou une procédure. |
"triggered_use_cases": {
|
| "has_knowledge_response_attempt" | Drapeau indiquant si la conversation est une conversation Connaissances (a au moins une réponse Connaissances), que la réponse Connaissances ait été comprise ou non, qu’une erreur soit survenue, qu’elle se soit limitée à des bavardages, etc. |
"has_knowledge_response_attempt": {
|
| "knowledge_notUnderstood_count" | Nombre de messages non compris dans la conversation Connaissances Pour les réponses Connaissances agentiques, cela peut inclure des questions de suivi pour lesquelles l’agent IA n’a pas fait correspondre la question à la source de connaissances appropriée pour générer une réponse. |
"knowledge_notUnderstood_count": {
|
| "knowledge_responseGenerated_count" | Nombre de messages générés par réponse dans la conversation Connaissances |
"knowledge_responseGenerated_count": {
|
| "knowledge_errorOccurred_count" | Nombre de messages d’erreur dans la conversation Connaissances |
"knowledge_errorOccurred_count": {
|
| "knowledge_escalationRequired_count" | Nombre de messages de remontée obligatoire dans la conversation Connaissances Ce statut s’applique uniquement aux réponses Connaissances génératives de type reply-handled. |
"knowledge_escalationRequired_count": {
|
| "knowledge_fallback_count" | Nombre de messages de remplacement dans la conversation Connaissances |
"knowledge_fallback_count": {
|
| "knowledge_sources" | Liste du type de la base de connaissances, du titre de l’article et l’URL utilisés dans la conversation. |
"knowledge_sources": {
|
| "bot_messages_count" | Nombre de messages d’agent IA |
"bot_messages_count": {
|
| "visitor_messages_count" | Nombre de messages clients |
"visitor_messages_count": {
|
| "not_understood_messages_count" | Nombre de messages non compris en général |
"not_understood_messages_count": {
|
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",
"customer_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,
--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
Première/dernière intention d’une conversation
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
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".