A mensagem e o interlocutor
Uma mensagem é uma fala da conversa. Os dois endpoints de ingestão usam o mesmo objeto, e é ele que a MAIA lê para auditar.
Campos
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
interlocutor | string | sim | Quem falou. Lista fechada (abaixo), sem distinção de maiúsculas. |
emitidaEm | datetime com fuso | sim | Quando a mensagem foi enviada. Ver Fuso horário. |
texto | string | condicional | O conteúdo. Obrigatório quando não há urlAudio. |
urlAudio | string | condicional | Mensagem de voz. Obrigatório quando não há texto. Ver URLs de áudio. |
id | string | sim em conversa parcial | Identificador da mensagem na origem. Único na conversa, estável entre envios. Ver abaixo. |
Uma mensagem sem texto e sem urlAudio é recusada com 400:
{ "erro": "Validação falhou", "detalhes": [{ "campo": "Mensagens[3]", "mensagem": "Mensagem sem texto e sem áudio." }] }
Aceitá-la gravaria uma fala que não vira número na conversa e que a transcrição também não alcança — um buraco silencioso no meio do atendimento.
texto e urlAudio juntos
É válido e tem significado: a origem já transcreveu. O texto vale para a análise, e a URL fica
para o supervisor ouvir. A plataforma nunca transcreve por cima do que você mandou.
O interlocutor
Lista fechada de quatro valores:
| Valor | Quem é | O que muda na auditoria |
|---|---|---|
Operador | O atendente humano | É a conduta dele que o checklist julga. Saudação, procedimento, cordialidade, encerramento — tudo é medido nas falas marcadas assim. |
Cliente | A pessoa atendida | O que ela diz é contexto e motivo do contato, nunca objeto de julgamento. |
Bot | Resposta automática, URA, chatbot | Conta como "lado da empresa", mas não é o operador: uma saudação feita pelo bot não credita o atendente. |
Sistema | Evento do canal — transferência, encerramento por inatividade, mensagem de protocolo | Fica fora do cálculo de duração da conversa (ver abaixo). |
Qualquer outro valor é recusado com 400 e a lista dos aceitos:
{ "erro": "Interlocutor inválido: 'Atendente'. V álidos: Operador, Cliente, Bot, Sistema" }
Errar o interlocutor não dá erro HTTP — dá auditoria errada, e ninguém percebe.
Se as falas do atendente entram como Cliente, um critério do tipo "o atendente se apresentou?"
passa a ser avaliado sobre o que o cliente disse. A nota sai, parece legítima, e está medindo a pessoa
errada. Nenhuma validação pega isso: o payload é perfeitamente válido.
Se o seu sistema tem papéis com outros nomes (agent, atendente, user, contact), faça o mapeamento
explicitamente e teste com uma conversa real em homologação, conferindo na tela quem apareceu de cada
lado.
Por que Sistema fica fora da duração
A plataforma calcula a duração da conversa do primeiro ao último turno humano. Mensagens de
Sistema são excluídas porque "encerrado por inatividade" chega dez minutos depois de a última pessoa
falar — e incluí-la transformaria uma conversa de quatro minutos numa de quinze. O que se audita é o
tempo de atendimento, não o de espera do canal.
Mande os eventos de sistema: eles dão contexto à leitura (uma transferência explica uma quebra no atendimento). Só não os use para marcar fala de pessoa.
Bot não é Operador
Se a sua operação usa URA ou chatbot antes do humano, marque essas falas como Bot. Marcá-las como
Operador credita ao atendente coisas que ele não fez — e, pior, pode reprovar o atendente por algo
que o bot fez mal.
O id da mensagem
Obrigatório em toda conversa parcial. Sem ele a resposta é 400 e a conversa não entra.
Ele é o que identifica a mesma fala entre um envio e o seguinte, e disso dependem duas coisas.
A primeira é a continuação da conversa. Quando uma conversa parcial é reenviada com a
continuação (ver Conversa que continuou), a plataforma une o que você
mandou com o que já tem, casando as mensagens pelo id. É o que permite você mandar só as mensagens
novas — e é o que impede que mandar a conversa inteira duplique tudo.
A segunda vale dinheiro do cliente: transcrição de áudio. Transcrever é o item mais caro do pipeline, cobrado por minuto, e a plataforma precisa saber quais áudios já passaram por isso.
- Com
id: casa as mensagens e reaproveita as transcrições já pagas. - Sem
id: tenta casar pelaurlAudio, que funciona quando a URL é a mesma. - Sem os dois: transcreve tudo de novo, e o cliente paga de novo.
Não há tentativa de casar por texto e horário: casar errado seria pior que pagar novamente — uma fala real seria sobrescrita por outra e sumiria do material que a auditoria julga.
Requisitos do id: único dentro da conversa, e estável entre envios. As duas coisas são
validadas: id repetido na mesma conversa é 400, e uma conversa com id em algumas mensagens e não em
outras também — união pela metade duplicaria as falas sem id.
O id nativo do WhatsApp serve. Um índice de array não serve: se uma mensagem for inserida no meio, os índices andam e o casamento passa a apontar para a fala errada.
Só na conversa que nasce fechada — parcial: false j á no primeiro envio, sem nenhuma versão anterior.
Ela nunca será continuada, então não há o que casar. Mesmo assim, mandar o id não custa nada e
protege você do dia em que essa conversa precisar virar parcial.
Ordem das mensagens
Mande na ordem cronológica, mas não se preocupe: a plataforma ordena por emitidaEm antes de
gravar. Isso tem duas consequências úteis:
- Array embaralhado não gera versão nova nem duplicata falsa — a comparação de conteúdo acontece depois da ordenação. Ver Idempotência.
emitidaEmerrado desordena a conversa e degrada a auditoria, mesmo com o array na ordem certa. O horário é a fonte da ordem, não a posição no array.