Skip to main content
Todo webhook chega no mesmo envelope — event, sent_at e data — descrito em Webhooks. Esta página é sobre o data. Há dois formatos, e só dois: todo lead.* traz o lead inteiro, e todo message.* traz a mensagem. A integração não precisa de um parser por evento.
Campo novo pode aparecer a qualquer momento — acrescentar não quebra o contrato. Leia os campos que você usa e ignore os que não conhece; não recuse o evento por causa de um campo a mais.

Eventos lead.*

lead.created, lead.stage_changed, lead.won, lead.lost e lead.updated trazem o mesmo objeto: o lead como ele está no momento do evento. O que mudou você deduz pelo nome do evento (lead.stage_changed → olhe stage).
Lead com mais de uma venda traz em sale_value a soma das vendas ganhas, e em product o produto da venda mais recente. Para ver venda por venda, use GET /v1/sales. Ver Vendas.
lead.created

Eventos flow.*

flow.entered sai quando um lead entra num fluxo publicado; flow.finished, quando o caminho dele no fluxo termina (a peça de fim, o fim do caminho, o teto de passos do dia, ou a versão apagada). Os dois trazem o mesmo objeto:
  • Não saem em modo teste, e não saem para o comentário repetido que a janela de “uma entrada por pessoa” segurou — ele não é uma entrada nova.
  • Um fluxo com dois caminhos ao mesmo tempo pode mandar um flow.finished por caminho.
  • O lead tirado do fluxo fora de uma passada (a peça de fim de outro caminho, a migração de versão, a pausa) não gera flow.finished.

Evento comment.received

Alguém comentou num post do Instagram da empresa. O comentário do próprio perfil não conta.
texto é o comentário limpo — sem menções @, links, hashtags e emoji repetido — inteiro; texto_curto é o mesmo cortado em 60 caracteres sem quebrar palavra (o {{comentario}} dos fluxos). resposta_a é o id do comentário respondido, quando o comentário é uma resposta. lead_criado diz se este comentário criou o lead. fluxos são os fluxos em que o comentário entrou, e respondido_pelo_fluxo diz se algum deles vai responder em público (tem a peça “responder o comentário”, fora do modo teste, e não é o repetido segurado sem resposta). O evento sai antes da resposta: ela é publicada segundos depois. Para responder você mesmo, POST /v1/comentarios/{comentario_id}/respostas.

Eventos message.*

message.received é a mensagem que o lead mandou. message.sent é a que saiu para o lead — de quem quer que tenha sido: a equipe pelo inbox, alguém pelo celular, um fluxo, ou um agente pela API. Quem foi está em source.

source: quem escreveu

message_id não é o id da API. Ele é o id que o WhatsApp deu à mensagem, e as rotas /v1/mensagens/{id} respondem 404 para ele. Use metricaas_message_id.
atendimento e ia_pausada dizem o estado depois da mensagem. Num message.sent com source = celular, ia_pausada já chega true: a resposta humana pausou a IA naquele mesmo instante.

message.received — texto

message.received — áudio

O api_url é relativo à base da API: o arquivo está em https://app.metricaas.com.br/v1/mensagens/{id}/midia, com o seu token. A mídia é copiada para o nosso armazenamento logo depois que a mensagem chega; se você pedir antes de terminar, a resposta é 409 com Retry-After — espere e peça de novo. Ver a seção de áudio da receita Agente de IA com n8n.

message.sent — enviada por um agente (source: api)

Repare: a resposta do agente não tirou a conversa de aguardando. A fala da IA não conta como alguém da equipe assumindo — ver Conversas e mensagens.

message.sent — respondida pelo celular (source: celular)

Aqui um humano respondeu: a conversa saiu da fila (em_atendimento) e a IA foi pausada (ia_pausada: true). A partir daqui, o envio pela API nesta conversa responde 409 até alguém retomar a IA ou resolver a conversa.