Pular para o conteúdo principal

Metadados e atendente

metadados é um dicionário livre de string: string que acompanha a interação. É por ele que o cliente filtra, agrupa e monta relatório: "nota média por campanha", "não conformidades por equipe", "desempenho do atendente A-77 no mês".

Sem metadados a interação é auditada normalmente — só não é recortável. Um relatório sem recorte é uma média só, e média só não move operação.

"metadados": {
"campanha": "cobranca",
"fila": "renegociacao",
"produto": "cartao",
"atendente_id": "A-77",
"atendente_nome": "Ana Souza",
"equipe": "Cobrança Sul"
}

As regras​

Chaves são normalizadas​

Minúsculas, trim, e espaço vira _:

Você mandaFica
Campanhacampanha
CAMPANHAcampanha
Nome da Filanome_da_fila
produto produto

Campanha, campanha e CAMPANHA são o mesmo campo. Isso é bom: o payload não depende de quem digitou. Mas escolha uma forma e mantenha.

Chave desconhecida é criada na hora​

O cliente não precisa cadastrar o campo antes. Uma chave que a plataforma nunca viu passa a existir automaticamente e volta em metadadosNovos na resposta.

metadadosNovos é o seu detector de erro de digitação

Uma chave com grafia errada não dá erro — vira um campo novo. campanaha passa a existir ao lado de campanha, e o relatório do cliente ganha um filtro fantasma com três interações dentro.

Se metadadosNovos vem preenchido em produção depois do go-live, é sinal de que algo mudou no seu mapeamento. Vale um alerta.

Chaves reservadas são descartadas​

Quatro chaves pertencem à plataforma e são ignoradas se você mandar, voltando em metadadosIgnorados:

Chave reservadaQuem preenche
dataA plataforma, a partir de ocorridaEm.
canalA plataforma, pelo endpoint que você chamou.
checklistA plataforma, quando escolhe o roteiro de auditoria.
status_avaliacaoA plataforma, quando a auditoria conclui.

A interação não é recusada por isso — a chave é descartada e você é avisado. Perder a interação inteira por um campo mal endereçado seria pior que ignorá-lo avisando.

Valores são texto​

Data, número e opção são interpretados do lado de lá. Mande como string: "2026-09-01", "3", "sim".

Chave ou valor vazio é ignorado silenciosamente — não gera erro nem entra no dicionário.

O atendente: não há cadastro de operador​

Esta é a parte que mais surpreende quem integra, então vale ser explícito.

O QA Analytics não tem cadastro de operador. Não existe endpoint para criar atendente, não existe id de atendente na plataforma. Quem atendeu é um metadado como qualquer outro.

A razão é operação real: rotatividade em atendimento é alta, e exigir cadastro prévio significaria que uma conversa atendida por alguém contratado ontem não entraria — ou entraria órfã.

Como a plataforma sabe qual chave é o atendente​

O cliente declara, na tela dele, quais chaves do dicionário significam o quê:

PapelExemplo de chave
Id do atendente (é por ele que se agrupa)atendente_id
Nome do atendente (é por ele que se exibe)atendente_nome
E-mail do atendenteatendente_email
Id da equipeequipe_id
Nome da equipeequipe
Combine as chaves com o cliente ANTES de integrar

Esta é a conversa que mais economiza retrabalho no projeto. Se você manda agente_matricula e o cliente declarou atendente_id, os relatórios por atendente vêm vazios — e nada no payload ou na resposta indica o problema.

Alinhe a lista de chaves, mande-as sempre, e confira na tela do cliente em homologação que o nome do atendente aparece na interação.

As duas formas de mandar​

Direto em metadados — a forma preferida:

"metadados": { "atendente_id": "A-77", "atendente_nome": "Ana Souza" }

Pelo campo de topo matriculaOperador — para quem já integra assim:

"matriculaOperador": "A-77"

A plataforma copia o valor para a chave que o cliente declarou como id do atendente. Se o cliente ainda não declarou os papéis, o valor não tem onde entrar e é ignorado — sem erro, sem aviso na resposta. Gravá-lo sob um nome inventado criaria um campo que ninguém pediu e que nenhum filtro rotula.

Se vierem os dois, o dicionário ganha: ele é o canal específico.

Agrupe pelo id, exiba o nome​

Mande os dois. O relatório agrupa pelo id e mostra o nome.

Agrupar pelo nome partiria o histórico de uma pessoa em duas linhas no dia em que a origem corrigisse uma grafia — "Ana Souza" e "Ana Sousa" viram dois atendentes, cada um com metade do desempenho.

Se você só tem o nome, mande só o nome: funciona, com essa fragilidade conhecida.

Metadado obrigatório​

O cliente pode marcar um campo como obrigatório na configuração dele. Se ele não vier:

  • a interação é aceita e auditada normalmente;
  • a resposta traz pendenteMetadadoObrigatorio: true;
  • a pendência aparece para o cliente resolver.

A gravação nunca é recusada por metadado faltante. Perder a conversa — que aconteceu uma vez e não se refaz — por causa de um campo ausente seria trocar a evidência da auditoria por um dado de recorte.

Se pendenteMetadadoObrigatorio vem true de forma consistente, o cliente marcou como obrigatório um campo que você não manda. Vale conversar.

Metadado não se corrige por reenvio​

Metadados não entram na comparação de conteúdo da idempotência. Reenviar a mesma conversa com metadados corrigidos devolve 200 Duplicada e não atualiza o que está gravado.

Confira os metadados antes de enviar. Ver Idempotência.

Sugestão de conjunto mínimo​

Sem conhecer a operação do cliente, este conjunto cobre a maioria dos recortes que um time de qualidade pede:

"metadados": {
"atendente_id": "<id estável do atendente>",
"atendente_nome": "<nome para exibir>",
"equipe_id": "<id estável da equipe>",
"equipe": "<nome da equipe>",
"campanha": "<campanha ou operação>",
"fila": "<fila de atendimento>",
"produto": "<produto, quando aplicável>"
}

Ajuste com o cliente. O importante é que as chaves sejam estáveis depois de acordadas.