Notificações por API: leads e alertas do bot no seu servidor

Quais notificações chegam

Os eventos de tokens se referem ao saldo da conta inteira, não a um bot, por isso chegam às URLs de todos os bots com API ativada. Vários bots com a mesma URL recebem uma única requisição.

Como conectar

1. 1

   Abra as notificações do bot

   Vá em Recepção → Bots, escolha o bot e abra a aba Notificações. Na linha API clique em Configurar notificações.

2. 2

   Cole a URL do receptor

   Em URL do receptor informe o endereço que aceita requisições POST: o endpoint do seu CRM, um gatilho webhook do Make ou do n8n, ou um Catch Hook do Zapier. A URL deve começar com https://.

3. 3

   Clique em Testar

   Um lead de exemplo com o evento test é enviado para a URL. Abaixo do botão aparecem o código de resposta, o tempo e o início da resposta do seu servidor. Código 2xx significa que funciona. Não é preciso salvar a URL antes de testar.

   O teste pode ser executado até 5 vezes por minuto por bot, para que a configuração nunca vire uma enxurrada de requisições a um servidor de terceiros.

4. 4

   Salve

   Clique em Salvar: a linha API na lista de notificações passa para Notificações configuradas. Para parar o envio, clique em Desativar na mesma janela.

Somente URLs HTTPS são aceitas. Endereços internos e locais (localhost, 10.x, 192.168.x etc.) são recusados: o receptor precisa estar acessível pela internet.

Formato da requisição

Método POST, corpo JSON em UTF-8. O tipo de notificação está no campo event e no cabeçalho X-Webhook-Event. O campo type continua por compatibilidade com integrações antigas (lead_new, lead_update, bot_chat_have_mistake, tokens_threshold, tokens_depleted, bot_reply_no_balance, lead_test).

Lead: lead.created e lead.updated

{
  "event": "lead.created",
  "type": "lead_new",
  "bot_id": "c8df2a84-9b17-4bf9-9248-9cee74eaeee6",
  "data": {
    "lead": {
      "id": "9b2f6c1e-…",
      "name": "Anna",
      "phone": "+15551234567",
      "email": "[email protected]",
      "telegram_username": null,
      "city": "Austin",
      "address": null,
      "scheduled_call": null,
      "type_payment": null,
      "need_delivery": null,
      "delivery_time": null,
      "meeting_date_time_office": null,
      "meeting_date_time_client": null,
      "extended_info": null,
      "status": "NEW",
      "comment": "Wants a quote for 3 rooms"
    },
    "botChatId": 12345,
    "shortInfo": "Wants a renovation quote for three rooms, asks for a call in the evening",
    "messages": "Client: …\nBot: …",
    "linkToChat": "https://…",
    "channelUrl": "https://…"
  },
  "timestamp": "2026-09-21T12:00:00.000Z",
  "delivery_id": "3f1c2a4e-…"
}

• data.lead.id é o mesmo em lead.created e em cada lead.updated de um lead: use-o para atualizar o registro no seu sistema.
• Os campos que o bot não coletou chegam como null.
• shortInfo é o resumo da conversa e messages a transcrição: curta ou completa conforme a configuração do bot Como formatar a notificação no Telegram?.
• linkToChat leva à conversa no canal de origem quando a plataforma oferece esse link.

Ajuda necessária: chat.help_needed

{
  "event": "chat.help_needed",
  "type": "bot_chat_have_mistake",
  "bot_id": "c8df2a84-9b17-4bf9-9248-9cee74eaeee6",
  "data": {
    "reason": "bot_asked",
    "botId": "c8df2a84-9b17-4bf9-9248-9cee74eaeee6",
    "botChatId": 12345,
    "shortInfo": "The client asks about a custom order",
    "messages": "Client: …\nBot: …",
    "linkToChat": "https://…"
  },
  "timestamp": "2026-09-21T12:05:00.000Z",
  "delivery_id": "…"
}

O bot neste chat já pausou e está esperando uma pessoa: abra a conversa pelo linkToChat ou em Chats e responda ao cliente você mesmo.

Saldo de tokens: tokens.*

{
  "event": "tokens.low",
  "type": "tokens_threshold",
  "bot_id": "c8df2a84-9b17-4bf9-9248-9cee74eaeee6",
  "bot_ids": [
    "c8df2a84-9b17-4bf9-9248-9cee74eaeee6",
    "5e0a7d31-…"
  ],
  "data": {
    "tokensRemaining": 50000
  },
  "timestamp": "2026-09-21T13:00:00.000Z",
  "delivery_id": "…"
}

Os eventos de tokens chegam uma vez por URL: bot_ids lista todos os bots com esta URL e bot_id é o bot cujo segredo assinou a requisição. Use tokens.low para recarregar a tempo e trate tokens.depleted e tokens.bot_silent como alarmes: os clientes ficam sem resposta.

Verificação da assinatura

O segredo de assinatura fica na mesma janela, no bloco Segredo de assinatura (botões Mostrar e Copiar). Cada bot tem o seu próprio segredo. A assinatura é o HMAC-SHA256 da string X-Webhook-Timestamp + . + o corpo bruto da requisição, com o segredo como chave, em hex e com o prefixo sha256=. Calcule sobre o corpo antes de fazer o parse do JSON: um JSON re-serializado pode não coincidir byte a byte.

import crypto from "node:crypto";

// rawBody: the request body as a string, BEFORE JSON.parse
function isValid(rawBody, headers, secret) {
  const expected =
    "sha256=" +
    crypto
      .createHmac("sha256", secret)
      .update(headers["x-webhook-timestamp"] + "." + rawBody)
      .digest("hex");
  const got = headers["x-webhook-signature"] || "";
  return (
    got.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))
  );
}

import hashlib, hmac

def is_valid(raw_body: bytes, headers, secret: str) -> bool:
    message = headers["X-Webhook-Timestamp"].encode() + b"." + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, headers.get("X-Webhook-Signature", ""))

Para recusar repetições, compare X-Webhook-Timestamp com a hora atual (por exemplo, no máximo 5 minutos) e guarde os delivery_id já processados.

Se o segredo vazar, clique em Gerar novo: o anterior para de funcionar na hora, então atualize-o no seu servidor.

Entrega e resposta do seu servidor

• Responda com um código 2xx em até 10 segundos. Faça o processamento pesado depois de responder, em segundo plano.
• Redirecionamentos não são seguidos: informe a URL final.
• Envios com falha não são repetidos. A notificação por API se perde, mas os outros canais (Telegram, e-mail, CRM) continuam funcionando e o lead fica em Leads.
• A API funciona junto com os outros canais, não no lugar deles: você pode receber leads no Telegram e no seu sistema ao mesmo tempo.