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ê manda | Fica |
|---|---|
Campanha | campanha |
CAMPANHA | campanha |
Nome da Fila | nome_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çãoUma 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 reservada | Quem preenche |
|---|---|
data | A plataforma, a partir de ocorridaEm. |
canal | A plataforma, pelo endpoint que você chamou. |
checklist | A plataforma, quando escolhe o roteiro de auditoria. |
status_avaliacao | A 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ê:
| Papel | Exemplo 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 atendente | atendente_email |
| Id da equipe | equipe_id |
| Nome da equipe | equipe |
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.