Qual é o meu plano?
Complemento Agentes de IA - Avançado

Nossa API de exportação de dados serve como chave para desbloquear o potencial completo do seu agente de IA, permitindo que você exporte dados de conversas e integre-os a diversas plataformas e aplicativos.

Seja você desenvolvedor, analista de negócios ou profissional de TI, nossa API fornece uma solução segura e simplificada para extrair metadados de conversas e insights valiosos, permitindo que você promova a inovação, tome decisões informadas e leve sua organização a um novo patamar.

Este artigo contém os seguintes tópicos:

  • Acesso ao ID da organização
  • Geração de um token da API
  • Sobre a API
  • Esquema de arquivos
  • Exemplo de resposta
  • Métricas populares
  • Perguntas frequentes

Acesso ao ID da organização

Somente usuários com função administrativa podem executar essa etapa

  1. Na barra lateral esquerda, clique em Gerenciamento de organizações.
    Observação: se você adquiriu Agentes de IA - Avançado antes de 7 de outubro de 2024, clique em Gerenciamento de usuário > Gerenciamento de organizações.
  2. Clique na sua organização para abrir o perfil dela.
  3. Encontre o ID da sua organização na URL do navegador: 
    https://dashboard.ultimate.ai/admin/organizations/77m57af6811115b53172431s

Geração de um token da API

Somente usuários com função administrativa podem gerar um token

  1. Na barra lateral esquerda, clique em Gerenciamento de organizações.
    Observação: se você adquiriu Agentes de IA - Avançado antes de 7 de outubro de 2024, clique em Gerenciamento de usuário > Gerenciamento de organizações.
  2. Clique na sua organização para abrir o perfil dela.
  3. Clique na aba Chave da API.
  4. Clique em Gerar.
  5. Clique em Salvar.
  6. Copie a chave e guarde-a em segurança.

Screenshot 2024-02-07 at 10.29.51.png

Assim que sair da página de gerenciamento de organizações, você não terá mais acesso ao token. Caso você perca o token gerado, é possível revogá-lo clicando no botão Gerar novamente. A validade do token antigo será revogada e você poderá usar o token recém-gerado.

Sobre a API

A API de exportação de dados é atualizada uma vez por dia, à meia-noite (fuso horário UTC). Esse processo de atualização pode durar algum tempo, então faça a importação no início da manhã (fuso horário UTC) para garantir que os dados estejam disponíveis.

Para a União Europeia: POST - https://api.ultimate.ai/data-export/v2/get-signed-urls

Para os EUA: POST - https://api.us.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 um dia após a data da solicitação. Para receber um link válido, é preciso executar a chamada da API outra vez.
  • Você pode solicitar dados de até 30 dias antes da data atual. Dados mais antigos são considerados históricos e precisam de outras providências.
    • Exemplo: se a data de hoje for 15 de abril de 2024, a data da solicitação pode ser qualquer uma entre 16 de março de 2024 e 15 de abril de 2024.

Esquema de arquivos

A API exporta um documento JSON com todas as conversas de determinado dia, seguindo esta estrutura:

  • O arquivo é uma lista de objetos JSON, em que cada objeto é uma conversa
  • A nomenclatura do arquivo segue a convenção: conversation_bot-id_date_000000000000.json
Propriedade Descrição Type
"bot_id" ID exclusivo do bot 
"bot_id": {
"type": "string"
},
"bot_name" Nome do bot 
"bot_name": {
"type": "string"
},
"conversation_id" ID da conversa gerada 
"conversation_id": {
"type": "string"
},
"platform_conversation_id" ID específico do CRM 
 "platform_conversation_id": {
"type": "string"
},
"conversation_start_time" Data e hora de quando a conversa começou, com base no fuso horário UTC 
"conversation_start_time": {
"type": "string"
},
"conversation_end_time" Data e hora de quando a conversa terminou, 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 da sessão são associados às conversas. É uma lista da chave do parâmetro que tinha um valor. As chaves não definidas não estarão na lista.

Observação:

  • Mesmo que seja armazenada como uma cadeia de caracteres, “conversations_data” contém outro objeto JSON.
  • O score de BSAT é fornecido no objeto de dados das conversas.
    • Valores do score de BSAT
      • -1 = o usuário recebeu o BSAT, mas não deixou uma resposta.
      • NULL = o usuário não recebeu o BSAT.

Exemplo:

"conversations_data": {
"parameter1": true,
"parameter2": "parameter_value",
"parameter3": "1234"
},
 
"conversations_data": {
"type": "string"
},

"test_mode"

 

 

 Uma marcação para identificar se a conversa é um teste 
"test_mode": {
"type": "boolean"
},
"conversation_status" Resolução da conversa, por exemplo: bot_handled 
"conversation_status": {
"type": "string"
},
"last_resolution" É a resolução final da conversa; pode ser informada, resolvida, escalada ou indefinida 
"last_resolution": {
"type": "string"
},
"triggered_replies"   
"triggered_replies": {
"type": "array",
"items": {
"type": "string"
   }
},
"triggered_intent_replies"

As respostas baseadas em intenção

 
"triggered_intent_replies": {
"type": "array",
"items": {
"type": "string"
   }
},
"is_llm_conversation" Uma marcação para identificar se a conversa é de LLM (tem pelo menos uma resposta de LLM) 
"is_llm_conversation": {
"type": "boolean"
},
"llm_notUnderstood_count" A quantidade de mensagens não entendidas na conversa de LLM 
"llm_notUnderstood_count": {
"type": "string"
},
"llm_responseGenerated_count" A quantidade de mensagens geradas por resposta na conversa de LLM 
"llm_responseGenerated_count": {
"type": "string"
},
"llm_errorOccurred_count" A quantidade de mensagens de erro na conversa de LLM 
"llm_errorOccurred_count": {
"type": "string"
},
"llm_escalationRequired_count" A quantidade de mensagens escalationRequired na conversa de LLM 
"llm_escalationRequired_count": {
"type": "string"
},
"llm_fallback_count" A quantidade de mensagens de fallback na conversa de LLM 
"llm_fallback_count": {
"type": "string"
},
"bot_messages_count" A quantidade de mensagens do agente de IA 
"bot_messages_count": {
"type": "string"
},
"visitor_messages_count" A quantidade de mensagens do visitante 
 "visitor_messages_count": {
"type": "string"
},
"not_understood_messages_count" A quantidade de mensagens não entendidas 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 bucket 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 da conversa do agente de IA. Aqui estão algumas das nossas sugestões para começar 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 ao longo do tempo e precisam passar por uma nova sincronização?
    Os arquivos exportados são imutáveis, então não precisam ser reimportados, o que torna seu pipeline de BI menos propenso a erros.
  • Percebo diferenças nos números das conversas para uma data específica entre as conversas exportadas e as análises de resumo do agente de IA. Qual pode ser o motivo?
    Os dados exportados para uma data específica se referem apenas a conversas que terminaram nessa data. Essa é uma abordagem diferente das análises de resumo do agente de IA, que incluem qualquer conversa, em qualquer estado. Isso é feito por diversos motivos, entre os quais: imutabilidade do arquivo exportado e prevenção contra dados duplicados.
  • Então como posso alcançar a paridade entre os números reportados no resumo do agente de IA e nos arquivos exportados?
    Para ter uma visão completa de todas as conversas que aconteceram em determinado dia x, você pode simplesmente ingerir o arquivo gerado para o dia x e o dia x + 1. Ao ingerir arquivos dessas duas datas, você garante que terá considerado todas as conversas da data x, mesmo que elas tenham se estendido ao dia seguinte.
  • Percebo diferenças nos números das conversas para uma data específica entre as conversas exportadas e os registros de conversas. Qual pode ser o motivo?
    Lembre-se de que os dados exportados para uma data específica se referem apenas a conversas que terminaram nessa data. Essa é uma abordagem diferente dos registros de conversas, que incluem qualquer conversa, em qualquer estado, para possibilitar a depuração em tempo real.
  • Uma conversa inclui informações sobre todas as respostas iniciadas por gatilho, mesmo que essas respostas tenham acontecido em um dia anterior?
    Sim. Se uma conversa constar no arquivo, ele terá todos os dados dela, mesmo que ela tenha ocorrido em um dia anterior.
  • Meu agente virtual tem conversas como parte do mecanismo de sugestão. Elas vão aparecer na exportação?
    Sim. Embora elas sejam excluídas do painel de resumo do agente de IA, elas ainda estarão disponíveis nos dados exportados. Para excluí-las e alcançar paridade com o painel de resumo do agente de IA, filtre por "bot_messages_count > 0".

Powered by Zendesk