Pular para o conteúdo principal

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​

CampoTipoObrigatórioRegras
interlocutorstringsimQuem falou. Lista fechada (abaixo), sem distinção de maiúsculas.
emitidaEmdatetime com fusosimQuando a mensagem foi enviada. Ver Fuso horário.
textostringcondicionalO conteúdo. Obrigatório quando não há urlAudio.
urlAudiostringcondicionalMensagem de voz. Obrigatório quando não há texto. Ver URLs de áudio.
idstringsim em conversa parcialIdentificador 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:

ValorQuem éO que muda na auditoria
OperadorO atendente humanoÉ a conduta dele que o checklist julga. Saudação, procedimento, cordialidade, encerramento — tudo é medido nas falas marcadas assim.
ClienteA pessoa atendidaO que ela diz é contexto e motivo do contato, nunca objeto de julgamento.
BotResposta automática, URA, chatbotConta como "lado da empresa", mas não é o operador: uma saudação feita pelo bot não credita o atendente.
SistemaEvento do canal — transferência, encerramento por inatividade, mensagem de protocoloFica 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" }
Este é o campo que mais merece cuidado

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 pela urlAudio, 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.

Quando você pode omitir

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.
  • emitidaEm errado 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.