Como funciona

O Webhook no Chatbot permite integrar fluxos de atendimento com sistemas externos, como CRM, ERP, financeiro, e-commerce, plataformas de assinatura, APIs próprias ou sistemas internos.

Fluxo simplificado:

Usuário envia mensagem
↓
Chatbot chega ao nó Webhook
↓
Digitalizei envia uma requisição POST
↓
Seu sistema processa os dados
↓
Retorna uma resposta
↓
Chatbot continua o fluxo automaticamente

Configuração

No construtor de chatbot, adicione o bloco:

Disparar Webhook

Informe a URL pública que receberá as requisições.

Exemplo:

https://api.seusistema.com/webhook-chatbot

Dados enviados para o seu sistema

Quando o webhook é executado, a Digitalizei envia todo o contexto da conversa, incluindo:

Possíveis respostas configuradas no bloco;
Dados da sessão;
Dados do canal;
Dados do contato;
Perguntas respondidas;
Menus selecionados;
Última mensagem recebida.

A requisição é enviada via método:

POST

Com o formato:

Content-Type: application/json

Estrutura resumida

{
  "responseKeys": [
    "CLIENTE_EXISTE",
    "CLIENTE_NAO_EXISTE"
  ],
  "sessionId": "567ca9b8-eaa9-4a33-8cf9-d2c67060af74",
  "session": {},
  "channel": {},
  "contact": {},
  "questions": {},
  "menus": {},
  "lastMessage": {}
}

Payload completo enviado

Abaixo está um exemplo completo do payload enviado pela Digitalizei ao disparar um webhook no chatbot.

Dependendo da configuração do fluxo, alguns campos podem estar ausentes ou retornar como null.

{
  "responseKeys": [
    "CLIENTE_EXISTE",
    "CLIENTE_NAO_EXISTE"
  ],
  "sessionId": "567ca9b8-eaa9-4a33-8cf9-d2c67060af74",
  "session": {
    "id": "567ca9b8-eaa9-4a33-8cf9-d2c67060af74",
    "createdAt": "2024-06-02T12:00:10.38771Z",
    "departmentId": "07deebd3-dede-42d1-9169-75e00efdf088",
    "userId": null,
    "number": "2024062700164",
    "utm": {
      "clid": "asldkjasLKJASLKDJLKJASLDKJASGFui3HT7c7KUdBaB7lOHHxp5CxufCY0GjlvZcDRpsTaRbZMQ",
      "term": null,
      "medium": "REFERRAL",
      "source": "INSTAGRAM",
      "content": "Campanha de Natal Minas Gerais!",
      "campaign": "776107696326",
      "headline": "Converse conosco",
      "referralUrl": "https://www.instagram.com/p/x466u6s5ykjs/"
    }
  },
  "channel": {
    "id": "0a4ca3cd-b9fd-4523-a032-5a343bf7b209",
    "key": "551140037752",
    "platform": "WhatsApp",
    "displayName": "(11) 3000-0000"
  },
  "contact": {
    "id": "f8f43b22-2f20-42f3-be13-65bf90282143",
    "name": "David",
    "phonenumber": "+55|1199999999",
    "display-phonenumber": "(11) 99999-9999",
    "email": "[email protected]",
    "instagram": null,
    "tags": [
      "Lead"
    ],
    "cnpj": "00.000.000/0000-00",
    "metadata": {
      "cod-ext": "abcd"
    }
  },
  "questions": {
    "cb-ec36e3fe-qst-c0b0875a": {
      "text": "Qual seu CNPJ?",
      "answer": "00.000.000/0000-00"
    }
  },
  "menus": {
    "cb-ec36e3fe-mn-943b055a": {
      "text": "Qual opção você deseja?",
      "answer": "Comprar"
    }
  },
  "lastMessage": {
    "id": "152d4d13-0b13-49bb-bafc-3923434f204b",
    "createdAt": "2024-06-27T19:09:22.592061Z",
    "type": "IMAGE",
    "text": null,
    "fileId": "aa546fa6-ca68-4a8b-a57d-c031460fae69",
    "file": {
      "publicUrl": "https://cdn.flw.chat/upload/88fb5de-0cc2-4209-b456-47b454ee6e14/IMAGE/c40e85e_20240627190923197_436019626068697.jpg?AWSAccessKeyId=XXXX",
      "extension": ".jpg",
      "mimeType": "image/jpeg",
      "name": "436019626068697.jpg",
      "size": 233541
    }
  }
}

Objetos do payload

Objeto	Descrição
`responseKeys`	Lista de respostas esperadas pelo bloco do chatbot
`sessionId`	ID da conversa atual
`session`	Dados gerais da sessão de atendimento
`session.utm`	Dados de origem, campanha e rastreamento
`channel`	Canal por onde a conversa está acontecendo
`contact`	Dados do contato relacionado à conversa
`questions`	Respostas dadas em perguntas anteriores do fluxo
`menus`	Opções selecionadas em menus anteriores
`lastMessage`	Última mensagem recebida na conversa

Como usar o campo responseKeys

O campo responseKeys informa quais caminhos o chatbot espera receber como resposta.

Exemplo:

[
  "CLIENTE_EXISTE",
  "CLIENTE_NAO_EXISTE"
]

Seu sistema deve retornar uma dessas opções no campo response.

Respostas do Webhook

Após receber a requisição, seu sistema deve responder com:

200 OK

e um JSON válido.

Resposta simples

Utilizada apenas para direcionar o fluxo.

{
  "response": "CLIENTE_EXISTE"
}

Resposta com mensagem

Permite enviar uma mensagem ao usuário antes de seguir o fluxo.

{
  "response": "CLIENTE_EXISTE",
  "messages": [
    {
      "text": "Seu cadastro foi localizado."
    }
  ]
}

Resposta com arquivo

Permite enviar arquivos dinamicamente.

{
  "response": "CLIENTE_EXISTE",
  "messages": [
    {
      "fileUrl": "https://empresa.com/boleto.pdf"
    }
  ]
}

Resposta com template

Permite enviar templates previamente cadastrados.

{
  "response": "CLIENTE_EXISTE",
  "messages": [
    {
      "template": {
        "id": "ab78cd_oferta",
        "parameters": {
          "valor": "R$ 9,99"
        }
      }
    }
  ]
}

Exemplo completo de resposta

{
  "response": "CLIENTE_EXISTE",
  "messages": [
    {
      "text": "Segue seu boleto abaixo para pagamento. Vencimento dia 10/01"
    },
    {
      "fileUrl": "https://empresa.com/boleto.pdf"
    },
    {
      "template": {
        "id": "ab78cd_oferta",
        "parameters": {
          "valor": "R$ 9,99"
        }
      }
    }
  ]
}

Perguntas Dinâmicas

Este recurso permite carregar opções de resposta em tempo real diretamente de sistemas externos.

Quando o usuário chega à etapa correspondente, o chatbot consulta seu webhook e renderiza as opções retornadas.

Estrutura de retorno

{
  "text": "Como podemos ajudar hoje?",
  "type": "BUTTONS",
  "options": []
}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`text`	String	Não	Texto principal exibido
`type`	String	Sim	Tipo de exibição
`options`	Array	Sim	Lista de opções

Tipos disponíveis

BUTTONS

Exibe botões clicáveis.

{
  "type": "BUTTONS"
}

LIST

Exibe uma lista de opções.

{
  "type": "LIST"
}

NUMBERS

Exibe opções numeradas.

{
  "type": "NUMBERS"
}

Estrutura do Array options

Cada item dentro de options suporta os seguintes campos:

Campo	Obrigatório	Descrição
`text`	Sim	Texto da opção
`description`	Não	Descrição auxiliar
`url`	Não	Link externo

Exemplo de perguntas dinâmicas

{
  "text": "Como podemos ajudar hoje?",
  "type": "BUTTONS",
  "options": [
    {
      "text": "Área do Cliente",
      "url": "https://empresa.com/cliente"
    },
    {
      "text": "Suporte Técnico"
    }
  ]
}

Casos de uso

Consulta de cliente

Cliente informa CPF ou CNPJ
↓
Webhook consulta CRM
↓
Cliente encontrado
↓
Fluxo segue para CLIENTE_EXISTE

Consulta financeira

Cliente solicita boleto
↓
Webhook consulta sistema financeiro
↓
Retorna PDF
↓
Chatbot envia boleto

Consulta de pedido

Cliente informa número do pedido
↓
Webhook consulta ERP
↓
Retorna status atualizado
↓
Chatbot informa andamento

Consulta de assinatura

Cliente informa documento
↓
Webhook consulta plataforma de assinatura
↓
Retorna situação
↓
Fluxo continua automaticamente

Exemplo utilizando N8N

Fluxo comum:

Webhook
↓
Consultar CRM ou sistema externo
↓
IF Cliente Existe
├── Sim → CLIENTE_EXISTE
└── Não → CLIENTE_NAO_EXISTE

Resposta do N8N:

{
  "response": "CLIENTE_EXISTE",
  "messages": [
    {
      "text": "Encontramos seu cadastro."
    }
  ]
}

Boas práticas

Responda rapidamente

Retorne:

200 OK

o mais rápido possível.

Evite processamentos longos

Não deixe o usuário aguardando enquanto seu sistema executa várias ações.

Quando possível:

Recebe webhook
↓
Consulta informação necessária
↓
Retorna resposta
↓
Processamentos adicionais acontecem depois

Valide os dados recebidos

Nem todos os campos são obrigatórios.

Alguns dados podem estar ausentes ou retornar como null, dependendo do canal, do contato e do fluxo configurado.

Trate falhas com um caminho alternativo

Configure no chatbot uma resposta de erro, como:

FALHA

E retorne:

{
  "response": "FALHA"
}

Assim o usuário poderá ser direcionado para um fluxo alternativo.

Perguntas frequentes

Qual método HTTP é utilizado?

POST

Qual formato é enviado?

application/json

Posso enviar mensagens e arquivos na mesma resposta?

Sim.

Posso enviar templates do WhatsApp?

Sim, desde que o template esteja previamente cadastrado.

Posso buscar informações em sistemas externos?

Sim. Esse é o principal objetivo deste recurso.

Posso utilizar com N8N, Make ou Zapier?

Sim. O recurso é compatível com qualquer plataforma capaz de receber e responder requisições HTTP.