Uso da API de exportação de dados para agentes avançados de IA

Qual é o meu plano?

Complemento

Agentes de IA - Avançado

Nossa API de exportação de dados é a chave para aproveitar todo o potencial de seu agente de IA, permitindo exportar dados de conversas e integrá-los em diversas plataformas e aplicativos. Seja você um desenvolvedor, analista de negócios ou profissional de TI, nossa API oferece uma solução otimizada e segura para extrair insights valiosos e metadados de conversas, permitindo que você impulsione a inovação, tome decisões informadas e conduza sua organização a novos patamares.

Este artigo apresenta o uso e as saídas da API de exportação de dados.

Obter ID da organização

Esta etapa pode ser realizada apenas por usuários com função de administrador

1. Vá até Gerenciamento de usuários > Gerenciamento da organização. 
2. Abra o perfil da sua organização.
3. O ID da sua organização está na URL.

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

Como gerar um token de API

Somente usuários com função de administrador por gerar um token de API

1. Vá até Gerenciamento de usuários > Gerenciamento da organização. 
2. Abra o perfil da sua organização.
3. Vá até Chave da API no menu à esquerda.
4. Clique em Gerar e pressione o botão Salvar.
5. Copie a chave e mantenha-a em segurança.

Depois de sair da página Gerenciamento da organização, você não terá acesso ao token. Se perder o token gerado anteriormente, você pode simplesmente cancelá-lo clicando no botão Gerar novamente . A validade do token antigo será cancelada e você poderá usar o token que acaba de ser gerado.

 

Sobre a API

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

Cabeçalho

name	obrigatório	type
botId	true	string
organizationId	true	string
authorization	true	string

Corpo

name	obrigatório	type
date	true	ISO date string

Resposta

Código HTTP	resposta
200	{ "date": "string", "urls": [ "string" ] }
401	Não autorizado.
500	Erro interno do servidor

 

Observação:

• A URL para o arquivo expira após um dia da data da solicitação. Para obter um link válido, é possível realizar novamente uma chamada da API.
• Você pode solicitar dados com uma data dentro do intervalo de 30 dias a partir da data atual. Quaisquer dados mais antigos são considerados dados históricos e requerem preparações diferentes.
  
  • Exemplo: se a data atual for 15 de abril de 2024, a data da solicitação poderá ser qualquer data entre 15 de abril de 2024 e 16 de março de 2024.

Esquema de arquivo

A saída da API é um documento JSON com todas as conversas de um determinado dia, seguindo a estrutura descrita aqui:

• O arquivo é uma lista de objetos JSON, onde cada objeto é uma conversa
• O arquivo terá a convenção de nome Conversa_id-agenteIA_data_000000000000.json

Propriedade	Descrição	Type
"bot_id"	ID exclusiva do agente de IA	"bot_id": { "type": "string" },
"bot_name"	Nome do agente de IA	"bot_name": { "type": "string" },
"conversation_id"	ID da conversa gerada	"conversation_id": { "type": "string" },
"platform_conversation_id"	ID específica do CRM	"platform_conversation_id": { "type": "string" },
"conversation_start_time"	Data e hora de início da conversa com base no fuso horário UTC	"conversation_start_time": { "type": "string" },
"conversation_end_time"	Data e hora do fim da conversa com base no fuso horário UTC	"conversation_end_time": { "type": "string" },
"language"	Idioma da conversa	"language": { "type": "string" },
"channel"	Canal da conversa. Chat ou ticket.	"channel": { "type": "string" },
"labels"	Lista de todos os rótulos associados à conversa	"labels": { "type": "array", "items": { "type": "string" } },
"conversations_data"	Os parâmetros de sessão são associados às conversas. Trata-se de uma lista da chave do parâmetro na qual ele tinha um valor. As chaves indefinidas não estarão nesta lista. Observação: mesmo que esteja armazenado como uma cadeia de caracteres, o “conversations_data” contém outro objeto JSON. O score de BSAT é fornecido no objeto de dados de conversas. Valores do score BSAT: -1 = O usuário recebeu a oferta de BSAT, mas não deixou uma resposta. NULL = BSAT não foi oferecido ao usuário. Exemplo: "conversations_data": { "parameter1": true, "parameter2": "parameter_value", "parameter3": "1234" },	"conversations_data": { "type": "string" },
"test_mode"	Sinalizador para identificar se a conversa é uma conversa de teste	"test_mode": { "type": "boolean" },
"conversation_status"	Resolução da conversa. Exemplo: bot_handled	"conversation_status": { "type": "string" },
"last_resolution"	Trata-se da resolução final da conversa. Que pode ser informada, resolvida, transferida ou indefinida.	"last_resolution": { "type": "string" },
"triggered_replies"		"triggered_replies": { "type": "array", "items": { "type": "string" } },
"triggered_intent_replies"	Respostas com base na intenção	"triggered_intent_replies": { "type": "array", "items": { "type": "string" } },
"is_llm_conversation"	Sinalizador para identificar se a conversa é do tipo LLM (ter pelo menos uma resposta do LLM)	"is_llm_conversation": { "type": "boolean" },
"llm_notUnderstood_count"	Total de mensagens "não entendido" na conversa do LLM	"llm_notUnderstood_count": { "type": "string" },
"llm_responseGenerated_count"	Total de mensagens geradas por resposta na conversa do LLM	"llm_responseGenerated_count": { "type": "string" },
"llm_errorOccurred_count"	Total de mensagens "ocorreu um erro" na conversa do LLM	"llm_errorOccurred_count": { "type": "string" },
"llm_escalationRequired_count"	Total de mensagens "transferência obrigatória" na conversa do LLM	"llm_escalationRequired_count": { "type": "string" },
"llm_fallback_count"	Total de mensagens de fallback na conversa do LLM	"llm_fallback_count": { "type": "string" },
"bot_messages_count"	Total de mensagens de agente de IA	"bot_messages_count": { "type": "string" },
"visitor_messages_count"	Total de mensagens do visitante	"visitor_messages_count": { "type": "string" },
"not_understood_messages_count"	Total de mensagens "não entendido" em geral	"not_understood_messages_count": { "type": "string" },

Exemplo de resposta

A resposta da chamada da API é um link de URL para um arquivo em um depósito de armazenamento do Google que você pode acessar com uma solicitação 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…"]}

O arquivo contém cada conversa como um objeto json seguindo 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

Parabéns! Você exportou com êxito os dados de conversa do agente de IA . Aqui estão algumas de nossas sugestões para iniciar a jornada de exploração de dados dos arquivos exportados.

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

Primeira/última intenção de uma conversa

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 primeira intenção significativa (ou 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

Perguntas frequentes

• Os arquivos exportados são imutáveis ou mudam com o tempo, exigindo que você os sincronize novamente?
  Os arquivos exportados são imutáveis, portanto, não precisam ser reimportados, tornando seu pipeline de BI menos sujeito a erros.
• Os números de conversas de uma data específica são diferentes entre as conversas exportadas e a análise de resumo do agente de IA. Qual poderia ser o motivo?
  Os dados exportados de uma data específica têm dados apenas das conversas que terminaram nessa data. Trata-se de uma abordagem diferente da análise de resumo do agente de IA, na qual qualquer conversa em qualquer estado é incluída. Isso é feito por vários motivos, entre eles: imutabilidade do arquivo de exportação e prevenção de dados duplicados.
• Então, como posso conseguir que haja correspondência entre os números relatados no resumo do agente de IA e os arquivos exportados?
  Para ter uma visão completa de todas as conversas que ocorreram em um determinado dia x, basta gerar o arquivo incorporando o dia x e o dia x + 1. Ao gerar o arquivo incluindo essas duas datas, você garante que terá contado todas as conversas da data x, mesmo que ela tenha continuidade no dia seguinte.
• Os números das conversas de uma data específica são diferentes entre as conversas exportadas e os registros de conversas. Qual poderia ser o motivo?
  Lembre-se de que os dados exportados de uma data específica têm dados apenas das conversas que terminaram nessa data. Trata-se de uma abordagem diferente dos registros de conversas, onde qualquer conversa em qualquer estado é incluída para permitir a depuração em tempo real.
• Uma conversa inclui informações sobre todas as respostas acionadas em uma conversa, mesmo que essas respostas tenham ocorrido no dia anterior?
  Sim. Se uma conversa for incluída no arquivo, ela terá todos os seus dados, mesmo que tenha ocorrido no dia anterior.
• Meu agente de IA tem conversas como parte do mecanismo de sugestões. Elas serão exibidas na exportação?
  Sim. Embora elas sejam excluídas do painel de resumo do agente de IA, estarão disponíveis nos dados exportados. Para excluí-las e fazer com os valores correspondam com o painel de resumo do agente de IA, filtre por "bot_messages_count > 0".