Uso de la API de exportación de datos para los agentes IA avanzados

¿Qué plan tengo?

Complemento

Agentes IA - Avanzado

Con nuestra API de exportación de datos, podrá exportar los datos de las conversaciones e integrarlos en distintas plataformas y aplicaciones, liberando así todo el potencial del agente IA.

Ya sea desarrollador, analista de negocios o profesional de TI, nuestra API proporciona una solución sencilla y segura para extraer información valiosa y metadatos de la conversación. Así podrá impulsar la innovación, tomar decisiones bien fundamentadas y llevar a su organización a otro nivel.

En este artículo se tratan los siguientes temas:

• Obtener la ID de la organización
• Generar un token de API
• Acerca de la API
• Esquema de archivos
• Ejemplo de respuesta
• Métricas populares
• Preguntas frecuentes

Obtener la ID de la organización

Esto solo pueden hacerlo los usuarios que tienen un rol de administrador

1. En la barra lateral izquierda, haga clic en Administración de las organizaciones.
   Nota: Si compró Agentes IA – Avanzado antes del 7 de octubre de 2024, haga clic en Administración de usuarios > Administración de las organizaciones.
2. Haga clic en la organización para abrir el perfil.
3. Ubique la ID de la organización en la URL en el navegador:

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

Generar un token de API

Solo los usuarios que tienen un rol de administrador pueden generar tokens

1. En la barra lateral izquierda, haga clic en Administración de las organizaciones.
   Nota: Si compró Agentes IA – Avanzado antes del 7 de octubre de 2024, haga clic en Administración de usuarios > Administración de las organizaciones.
2. Haga clic en la organización para abrir el perfil.
3. Seleccione la pestaña Clave API.
4. Haga clic en Generar.
5. Haga clic en Guardar.
6. Copie la clave y guárdela en un lugar seguro.

Una vez que salga de la página Administración de las organizaciones, ya no tendrá acceso al token. Si ha perdido el token que generó anteriormente, puede simplemente revocarlo haciendo clic en el botón Volver a generar. El token anterior será revocado y podrá usar el recién creado.

Acerca de la API

La API de exportación de datos se actualiza una vez al día, a medianoche UTC (hora universal coordinada). Este proceso de actualización puede llevar un tiempo, por lo que es conveniente realizar la importación temprano en la mañana (hora UTC) para garantizar que los datos ya estén disponibles.

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

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

Encabezado

nombre	requerido	tipo
botId	true	string
organizationId	true	string
authorization	true	string

Cuerpo

nombre	requerido	tipo
date	true	ISO date string

Respuesta

código HTTP	respuesta
200	{ "date": "string", "urls": [ "string" ] }
401	No autorizado
500	Error interno del servidor

Nota:

• El URL del archivo vence un día después de la fecha de la solicitud. Para obtener un vínculo válido, se puede realizar una llamada de API otra vez.
• Se pueden solicitar datos cuya fecha esté dentro de los 30 días anteriores a la fecha actual. Los datos más antiguos se consideran datos históricos y necesitan preparaciones diferentes.
  
  • Ejemplo: Si la fecha actual es el 15 de abril de 2024, la fecha de solicitud puede ser cualquier fecha entre el 16 de marzo de 2024 y el 15 de abril de 2024.

Esquema de archivos

La salida de la API es un documento JSON que tiene todas las conversaciones de un día específico y sigue la estructura que se describe aquí:

• El archivo es una lista de objetos JSON en los que cada objeto es una conversación
• El archivo usará esta nomenclatura: conversation_bot-id_date_000000000000.json

Propiedad	Descripción	Tipo
"bot_id"	La ID única del bot	"bot_id": { "type": "string" },
"bot_name"	El nombre del bot	"bot_name": { "type": "string" },
"conversation_id"	La ID de conversación generada	"conversation_id": { "type": "string" },
"platform_conversation_id"	La ID específica de CRM	"platform_conversation_id": { "type": "string" },
"conversation_start_time"	La fecha y hora de inicio de la conversación en función de la zona horaria UTC	"conversation_start_time": { "type": "string" },
"conversation_end_time"	La fecha y hora de finalización de la conversación en función de la zona horaria UTC	"conversation_end_time": { "type": "string" },
"language"	El idioma de la conversación	"language": { "type": "string" },
"channel"	El canal de la conversación: chat o ticket	"channel": { "type": "string" },
"labels"	Una lista de todos los rótulos asociados con la conversación	"labels": { "type": "array", "items": { "type": "string" } },
"conversations_data"	Los parámetros de sesión están asociados con las conversaciones. Esta propiedad enumera las claves de parámetro con un valor. Las claves no definidas no se incluirán en la lista. Nota: Aunque se guarda como una cadena, “conversations_data” contiene otro objeto JSON. La puntuación de BSAT se proporciona en el objeto de datos de la conversación. Valores de puntuación de BSAT -1 = al usuario se le ofreció BSAT, pero no dejó una respuesta NULL = al usuario no se le ofreció BSAT Ejemplo: "conversations_data": { "parameter1": true, "parameter2": "parameter_value", "parameter3": "1234" },	"conversations_data": { "type": "string" },
"test_mode"	Una marca que identifica si la conversación es una conversación de prueba	"test_mode": { "type": "boolean" },
"conversation_status"	Resolución de la conversación (ejemplo: bot_handled)	"conversation_status": { "type": "string" },
"last_resolution"	La última resolución de la conversación. Podría ser informada, resuelta, escalada o sin definir.	"last_resolution": { "type": "string" },
"triggered_replies"		"triggered_replies": { "type": "array", "items": { "type": "string" } },
"triggered_intent_replies"	Las respuestas basadas en la intención	"triggered_intent_replies": { "type": "array", "items": { "type": "string" } },
"is_llm_conversation"	Una marca que identifica si la conversación es una conversación de LLM (tiene por lo menos una respuesta de LLM)	"is_llm_conversation": { "type": "boolean" },
"llm_notUnderstood_count"	El número de mensajes que no se comprendieron en la conversación de LLM	"llm_notUnderstood_count": { "type": "string" },
"llm_responseGenerated_count"	El número de mensajes generados por respuestas en la conversación de LLM	"llm_responseGenerated_count": { "type": "string" },
"llm_errorOccurred_count"	El número de mensajes que dicen que ocurrió un error en la conversación de LLM	"llm_errorOccurred_count": { "type": "string" },
"llm_escalationRequired_count"	El número de mensajes en los que fue necesario un escalamiento en la conversación de LLM	"llm_escalationRequired_count": { "type": "string" },
"llm_fallback_count"	El número de mensajes alternativos en la conversación de LLM	"llm_fallback_count": { "type": "string" },
"bot_messages_count"	El número de mensajes del agente IA	"bot_messages_count": { "type": "string" },
"visitor_messages_count"	El número de mensajes de los visitantes	"visitor_messages_count": { "type": "string" },
"not_understood_messages_count"	El número de mensajes que no se comprendieron en general	"not_understood_messages_count": { "type": "string" },

Ejemplo de respuesta

La respuesta de la llamada de la API es un vínculo de URL a un archivo en un depósito de almacenamiento de Google al que se puede acceder a través de una solicitud 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…"]}

El archivo contiene cada conversación como un objeto json y sigue este 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"
}

Métricas populares

¡Felicitaciones! Ha exportado correctamente los datos de conversación del agente IA. Estas son algunas de nuestras sugerencias para comenzar a explorar los datos de los archivos exportados.

Métricas del agente 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

Primera / Última intención de una conversación

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

Métricas por la primera intención significativa (o filtrada)

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

Preguntas frecuentes

• ¿Son inmutables los archivos exportados o cambian con el tiempo y es necesario volver a sincronizarlos?
  Como los archivos exportados son inmutables, no es necesario volver a importarlos, lo que hace que el pipeline de BI sea menos vulnerable a errores.
• Hay una diferencia en los recuentos de conversaciones para una fecha específica entre las conversaciones exportadas y los análisis de resumen del agente IA. ¿Cuál podría ser el motivo?
  Los datos exportados para una fecha específica tienen datos solo para las conversaciones que finalizaron ese día. Es un enfoque diferente que en el análisis del resumen del agente IA, donde se incluye cualquier conversación en cualquier estado. Esto se hace por varias razones, como la inmutabilidad del archivo de exportación y la prevención de datos duplicados.
• ¿Entonces cómo puedo lograr paridad entre las cifras del resumen del agente IA y los archivos exportados?
  Para obtener un panorama completo de todas las conversaciones que se mantuvieron en un día x, puede simplemente ingerir el archivo generado para el día x y el día x + 1. Al ingerir los archivos de estos dos días, se asegurará de que ha contado todas las conversaciones para la fecha x, aunque se hayan desbordado al día siguiente.
• Hay una diferencia en los recuentos de conversaciones para una fecha específica entre las conversaciones exportadas y los registros de conversaciones. ¿Cuál podría ser el motivo?
  Recuerde que los datos exportados para una fecha específica tienen datos solo para las conversaciones que finalizaron ese día. Es un enfoque diferente que en los registros de conversaciones, en los que se incluye cualquier conversación en cualquier estado para permitir la depuración en tiempo real.
• ¿Incluye una conversación información sobre todas las respuestas disparadas mientras tuvo lugar, aunque esas respuestas sean del día anterior?
  Sí. Si una conversación se incluye en un archivo, tendrá todos los datos, aunque sean del día anterior.
• Mi agente virtual tiene conversaciones como parte del motor de sugerencias. ¿Aparecerán en la exportación?
  Sí. Aunque estas conversaciones se excluyen del panel de resumen del agente IA, seguirán estando disponibles en los datos exportados. Para excluirlas y lograr paridad con el panel de resumen del agente IA, filtre en función de "bot_messages_count > 0".