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
- 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.
- Clique na sua organização para abrir o perfil dela.
- 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
- 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.
- Clique na sua organização para abrir o perfil dela.
- Clique na aba Chave da API.
- Clique em Gerar.
- Clique em Salvar.
- Copie a chave e guarde-a em segurança.
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/v3/get-signed-urls
Para os EUA: POST - https://api.us.ultimate.ai/data-export/v3/get-signed-urls
Cabeçalho
|
name |
obrigatório |
type |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Corpo
|
name |
obrigatório |
type |
|---|---|---|
|
|
|
|
Resposta
|
Código HTTP |
resposta |
|---|---|
|
200 |
|
|
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 com data retroativa para até 1.º de janeiro de 2024. Para ajuda, se precisar de dados mais antigos, entre em contato com o suporte ao cliente Zendesk.
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": {
|
| "bot_name" | Nome do bot |
"bot_name": {
|
| "conversation_id" | ID da conversa gerada |
"conversation_id": {
|
| "platform_conversation_id" | ID específico do CRM |
"platform_conversation_id": {
|
| "conversation_start_time" | Data e hora de quando a conversa começou, com base no fuso horário UTC |
"conversation_start_time": {
|
| "conversation_end_time" | Data e hora de quando a conversa terminou, com base no fuso horário UTC |
"conversation_end_time": {
|
| "conversation_type" | Tipo de resposta identificado na conversa. Os valores possíveis incluem Caso de uso, Conhecimento, Híbrido e Outros. |
"conversation_type": {
|
| "language" | Idioma da conversa |
"language": {
|
| "channel" | Canal da conversa. Mensagens ou e-mail |
"channel": {
|
| "labels" | Lista de todos os rótulos associados à conversa |
"labels": {
|
| "segments" | Lista de todos os segmentos identificados na conversa. Saiba mais sobre segmentos. |
"segments": {
|
| "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:
Exemplo: "conversations_data": {
|
"conversations_data": {
|
|
"test_mode"
|
Uma marcação para identificar se a conversa é um teste |
"test_mode": {
|
| "conversation_status" | Resolução da conversa, por exemplo: bot_handled |
"conversation_status": {
|
| "automated_resolution" | O resultado da avaliação da conversa como uma resolução automatizada. Saiba mais sobre como as resoluções automatizadas são calculadas. |
"automated_resolutions": {
|
| "automated_resolution_reasoning" | O raciocínio usado para determinar por que uma conversa foi marcada como resolvida automaticamente. |
"automated_resolution_reasoning": {
|
| "last_resolution" |
É a resolução final da conversa; pode ser informada, resolvida, escalada ou indefinida Removeremos esse recurso em 28 de fevereiro de 2026. Saiba mais sobre a próxima remoção de recursos. |
"last_resolution": {
|
| "triggered_replies" | Os detalhes relacionados a uma resposta. Inclui informações como reply_id, language, reply_name, reply_type, intent_id. |
"triggered_replies": {
|
| "triggered_procedures" |
Inclui informações como procedure_id, intent_id, use_case_name. Esta seção fica vazia para agentes de IA sem treinamento ou quando não há procedimentos iniciados por gatilho. |
"triggered_procedures": {
|
| "triggered_use_cases" |
Uma marcação para identificar se o caso de uso está configurado como um diálogo ou um procedimento. |
"triggered_use_cases": {
|
| "has_knowledge_response_attempt" | Uma marcação para identificar se é uma conversa do Conhecimento (tem pelo menos uma resposta do Conhecimento), independentemente de a resposta do Conhecimento ter sido entendida, de ter ocorrido um erro técnico, de ter sido uma conversa casual e etc. |
"has_knowledge_response_attempt": {
|
| "knowledge_notUnderstood_count" | A quantidade de mensagens não entendidas na conversa do Conhecimento. Para respostas agênticas do Conhecimento, isso pode incluir perguntas de acompanhamento em que o agente de IA não associou a pergunta a uma origem de conhecimento apropriada para gerar uma resposta. |
"knowledge_notUnderstood_count": {
|
| "knowledge_responseGenerated_count" | A quantidade de mensagens geradas por resposta na conversa do Conhecimento. |
"knowledge_responseGenerated_count": {
|
| "knowledge_errorOccurred_count" | A quantidade de mensagens de erro na conversa do Conhecimento. |
"knowledge_errorOccurred_count": {
|
| "knowledge_escalationRequired_count" | A quantidade de mensagens escalationRequired na conversa do Conhecimento. Esse status é aplicável somente para respostas generativas do Conhecimento. |
"knowledge_escalationRequired_count": {
|
| "knowledge_fallback_count" | A quantidade de mensagens de fallback na conversa do Conhecimento. |
"knowledge_fallback_count": {
|
| "knowledge_sources" | Uma lista do tipo de base de conhecimento, título do artigo e URL usados na conversa. |
"knowledge_sources": {
|
| "bot_messages_count" | A quantidade de mensagens do agente de IA |
"bot_messages_count": {
|
| "visitor_messages_count" | A quantidade de mensagens do cliente |
"visitor_messages_count": {
|
| "not_understood_messages_count" | A quantidade de mensagens não entendidas em geral |
"not_understood_messages_count": {
|
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",
"customer_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,
--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
Primeira/última intenção de uma conversa
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
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".