Webhook de Integrações

📬 Webhook - Integrações por Fila (N8N)

Este modelo de dados corresponde aos webhooks configurados na aba Integrações por Fila da tela Webhooks (integrações do tipo N8N, vinculadas a uma fila).

A cada nova mensagem recebida ou enviada em um ticket que esteja na fila vinculada à integração, o NEXTCHAT dispara automaticamente uma requisição POST para o seu endpoint configurado — respeitando os eventos marcados (“Mensagem recebida”, “Mensagem enviada”, “Ticket em atendimento”, “Ticket pendente”, “Mensagens de grupo” e “Enviar mídia em base64”).

Se desejar sugerir o envio de novos campos, abra uma issue no repositório!

Como funcionam os envios:

Requisição POST com Content-Type: application/json;
Se um Bearer Token / API Key estiver configurado na integração, ele vai no cabeçalho X-N8N-API-KEY;
O envio ocorre com um atraso de ~3 segundos e, em caso de falha, o sistema tenta até 3 vezes (com 3 minutos de intervalo entre as tentativas).

Diferença em relação ao Canal: a integração por fila envia apenas eventos de mensagem. Ela não possui os eventos de ciclo de vida do ticket (Novo ticket, Ticket transferido, Ticket fechado) — esses existem somente no Webhook de Canal.

📦 Estrutura dos Dados Enviados

Atenção

Atenção: assim como no evento de mensagem do canal, o webhook de fila não possui o campo Type — a identificação é feita pelos próprios campos (fromMe, ticket.status, etc.).

const dataToSend = {
  messageId: message.messageId,         // ID único da mensagem
  messageBody: message.body,            // Texto da mensagem
  timestamp: message.timestamp,         // Data/hora da mensagem (timestamp UNIX)
  status: message.status,               // Status da mensagem (ex: "received", "sended")
  fromMe: message.fromMe,               // true = enviada por mim | false = recebida
  mediaType: message.mediaType,         // Tipo de mídia (ex: "image", "video", "audio", "document")
  mediaUrl: message.mediaUrl,           // URL para download da mídia (se aplicável)
  mediaBase64: mediaBase64,             // Conteúdo da mídia em base64 (somente se "Enviar mídia em base64" estiver ativado; caso contrário, null)
  isDeleted: message.isDeleted,         // true = mensagem apagada
  sendType: message.sendType,           // Tipo de envio (ex: "manual", "bot", "API")
  edited: message.edited,               // true = mensagem foi editada
  reactions: message.reactions,         // Reações associadas à mensagem (se houver)
  dataJson: message.dataJson,           // Dados brutos da mensagem (JSON)
  ticket: {                             // Informações do ticket associado
    id: ticket.id,
    status: ticket.status,
    protocol: ticket.protocol,
    queueId: ticket.queueId,
    apiConfig: ticket.apiConfig,        // Chave externa, caso configurada (ver abaixo)
    isGroup: ticket.isGroup             // true = ticket de grupo
  },
  contact: contact ? {                  // Informações do contato do ticket (remetente ou destinatário)
    id: contact.id,
    name: contact.name,
    phoneNumber: contact.number,
    profilePicUrl: contact.profilePicUrl,
    email: contact.email,
    isGroup: contact.isGroup,
    pushname: contact.pushname,
    lid: contact.lid,
    kanbanId: contact.kanbanId,
    followupId: contact.tunelId
  } : null,
  contactmessage:                       // Quem enviou a mensagem dentro de um GRUPO (somente quando o ticket é de grupo)
    contactmessage && ticket.isGroup
      ? {
          id: contactmessage.id,
          name: contactmessage.name,
          phoneNumber: contactmessage.number,
          profilePicUrl: contactmessage.profilePicUrl,
          email: contactmessage.email,
          isGroup: contactmessage.isGroup,
          pushname: contactmessage.pushname,
          lid: contactmessage.lid,
          kanbanId: contactmessage.kanbanId,
          followupId: contactmessage.tunelId
        }
      : null,
  user: user ? {                        // Informações do usuário (caso mensagem enviada manualmente)
    id: user.id,
    name: user.name,
    email: user.email
  } : null,
  whatsapp: {                           // Informações da conexão WhatsApp
    id: whatsapp.id,
    name: whatsapp.name
  }
};

A estrutura acima é a mesma do evento de mensagem do Webhook de Canal — a diferença está apenas em quando ela é enviada: na fila, apenas para tickets que estejam na fila vinculada à integração, e sem os filtros de eventos de ticket.

⚙️ Como os eventos da fila filtram os envios

Evento na tela	Regra aplicada antes de enviar
Mensagem recebida	Só envia se a mensagem foi recebida (`fromMe = false`).
Mensagem enviada	Só envia se a mensagem foi enviada (`fromMe = true`).
Ticket em atendimento	Só envia mensagens de tickets com status Aberto (`open`).
Ticket pendente	Só envia mensagens de tickets com status Pendente (`pending`).
Mensagens de grupo	Se desligado, mensagens de grupos não geram envio.
Enviar mídia em base64	Se ligado, inclui o conteúdo da mídia em `mediaBase64` (quando houver mídia).

Se “Ticket em atendimento” e “Ticket pendente” estiverem desligados, nenhuma mensagem será enviada, mesmo com “Mensagem recebida”/“Mensagem enviada” ativadas.

🔑 Sobre o Campo `apiConfig`

O campo apiConfig é utilizado para identificar o ticket em sistemas externos.

Ele é preenchido automaticamente quando você informa um valor no campo externalKey ao criar o ticket via API.

Exemplo de configuração:

{
  "externalKey": "ID_UNICA_DO_SISTEMA_CLIENTE_PARA_EXECUTAR_UMA_ACAO_COM_WEBHOOK"
}

Esse campo é extremamente útil para vincular o ticket a alguma operação ou registro no seu sistema próprio.

🛠️ Observações Importantes

Os dados são enviados no formato application/json, via requisição POST;
O token configurado (opcional) é enviado no cabeçalho X-N8N-API-KEY;
Todos os webhooks ocorrem em tempo real (com atraso inicial de ~3s e até 3 tentativas em caso de falha);
Esteja preparado para receber múltiplos eventos em sequência;
Novos campos podem ser adicionados futuramente — recomendamos manter o parser do seu sistema flexível!

Conecte suas mensagens, tickets e automações em tempo real com o NEXTCHAT! 🚀