Fuso horário
Dois campos carregam data e hora, e os dois pedem fuso explícito:
| Campo | Onde | O que é |
|---|---|---|
ocorridaEm | raiz do payload | Quando a interação aconteceu na origem — não quando você a enviou. |
emitidaEm | cada mensagem | Quando aquela fala foi enviada. |
O formato
ISO-8601 com offset, ou UTC com Z:
2026-09-01T14:03:00-03:00 ← com offset (preferido)
2026-09-01T17:03:00Z ← UTC
A plataforma armazena tudo em UTC e exibe no fuso do usuário. Mandar com offset é preferível porque preserva a informação de onde aquilo aconteceu — útil numa operação com filiais em fusos diferentes.
Por que sem fuso é perigoso
2026-09-01T14:03:00 ← sem fuso: ACEITO, e interpretado errado
Uma data sem offset é ambígua: 14h de onde? A conversa entra, o payload passa na validação, e nada dá erro.
O estrago aparece depois, em dois lugares:
No relatório por turno. Uma conversa das 14h de Brasília interpretada como 14h UTC vira 11h no relatório. Um recorte "atendimentos da tarde" perde metade das conversas e ganha as da manhã de outro turno. O número sai, parece certo, e está medindo outra coisa.
Na ordem da conversa. As falas são ordenadas por emitidaEm antes de serem gravadas. Se os horários
estiverem deslocados de forma inconsistente — algumas com fuso, outras sem —, a conversa pode ser gravada
fora de ordem. A auditoria então lê um diálogo em que a resposta vem antes da pergunta, e julga o
atendente por um atendimento que não aconteceu daquele jeito.
Não há validação que pegue isso, e não há sintoma imediato. O primeiro sinal costuma ser o cliente estranhando um relatório meses depois.
Confira em homologação: envie uma conversa com horários conhecidos e verifique, na tela, se as falas aparecem na ordem e no horário certos.
ocorridaEm em conversa longa
Uma conversa que dura dias — o caso da ociosidade — tem um começo e um fim distantes. O que mandar em
ocorridaEm?
Escolha um critério e seja consistente. O começo da conversa é o mais comum, e é o que faz uma conversa aparecer no dia em que o cliente procurou. O fim também é defensável, se o que o cliente audita é o momento do desfecho.
O que não funciona é alternar: metade das conversas datada pelo início e metade pelo fim faz todo recorte por período ficar aproximado sem ninguém saber.
Vale alinhar com o cliente — é ele quem vai filtrar por data.
ocorridaEm originalQuando você reenvia uma conversa que continuou, mande o mesmo ocorridaEm do primeiro envio. Mudá-lo
faria a mesma conversa mudar de dia no relatório entre uma versão e outra.
Duração
A duração da conversa é calculada do primeiro ao último turno humano, ignorando mensagens de
Sistema. Isso depende inteiramente de emitidaEm estar certo.
Em voz, duracaoSegundos é informado por você e tem prioridade — o discador sabe a duração real da
ligação melhor do que a diferença entre horários de fala. Ausente, ela é calculada dos turnos.