Números da caixa de entrada e webhooks de mensagens recebidas

Na página Números da caixa de entrada, você escolhe quais dos seus números de WhatsApp são sincronizados com a caixa de entrada Unibox, onde sua equipe lê e responde os chats deles. Dê a um número uma URL de webhook, e o WbizTool também envia ao seu servidor cada nova mensagem que ele recebe ou envia, como JSON assinado: registre conversas em um CRM, avise sua equipe ou dispare uma resposta automática.

Está criando o receptor? Vá para Como os webhooks são entregues, Verificar a assinatura e Payload.

Quem pode fazer isso: Proprietários e Editores adicionam números, alteram webhooks e veem o segredo do webhook. Analistas não veem Números da caixa de entrada na barra lateral. É preciso ter o add-on Unibox: US$ 20 por mês ou US$ 200 por ano pelos preços de tabela nos EUA para cada número na caixa de entrada (o seu preço aparece em Cobrança e planos), adicionado a um plano pago ou vitalício por um Proprietário em Cobrança e planos (veja Add-ons). A quantidade dele é quantos números podem estar na caixa de entrada ao mesmo tempo.

Abra Números da caixa de entrada em Caixa de entrada na barra lateral ou acesse /unibox/listeners/.

Antes de começar#

• O add-on Unibox com um número da caixa de entrada livre: a linha abaixo do título da página diz, por exemplo, "2 de 3 números da caixa de entrada em uso (add-on Unibox)", ou "Sem add-on Unibox" (veja Sem o add-on Unibox).
• Um número de WhatsApp conectado com código QR ou código de login, mostrando Conectado em Números do WhatsApp. Números conectados pela extensão do navegador não podem ser adicionados. Uma conta do Telegram conectada pode ser adicionada como um número.
• Para um webhook: um endereço https:// de no máximo 500 caracteres na internet pública (não localhost nem uma rede privada) que aceite requisições POST com corpo JSON e responda 2xx em até 8 segundos.

Adicionar um número à caixa de entrada#

1. Abra a janela

   Clique em Adicionar número à caixa de entrada no canto superior direito da página.

2. Escolha o número

   Escolha-o em Número do WhatsApp. A lista mostra seus números conectados que ainda não estão na caixa de entrada.

3. Adicione um webhook (opcional)

   Digite seu endereço em URL do webhook (opcional). Aparece então Mensagens a notificar: deixe marcado Mensagens recebidas, Mensagens enviadas ou os dois. Você pode adicionar ou alterar o webhook depois.

   

4. Adicione

   Clique em Adicionar número. Você vê "Número adicionado – os chats dele começam a sincronizar em poucos minutos." Se você informou uma URL de webhook, abre Seu segredo do webhook: clique em Copiar e guarde o segredo onde o seu servidor possa lê-lo. Você pode mostrá-lo de novo depois em Configurações do webhook.

• Só mensagens novas. Um número é sincronizado a partir do momento em que você o adiciona: mensagens anteriores não são importadas nem enviadas.
• Todos os números em uso? A janela diz "Todos os seus números da caixa de entrada estão em uso. Pare ou remova um, ou adicione mais ao add-on Unibox." Pare ou remova um número, ou peça a um Proprietário para aumentar a quantidade do add-on (Ver add-ons).
• Adicionar de novo um número removido traz de volta a caixa de entrada dele ("Número adicionado de novo – os chats dele voltam a sincronizar a partir de agora."); as mensagens do período em que ele ficou removido não são captadas. Com uma URL de webhook, ele mantém o segredo anterior, se tinha um (use Mostrar em Configurações do webhook); caso contrário, Seu segredo do webhook abre com um novo.

O que o cartão de um número mostra#

Cada cartão mostra o número, quando o WbizTool o verificou pela última vez em busca de mensagens ("Última verificação: há 1 min", ou Nunca verificado), as Mensagens e os Contatos sincronizados dele (todos os chats sincronizados a partir dele, incluindo os que não têm mensagens na caixa de entrada), a Última mensagem e o Webhook: a URL e o que ele envia, como "Notifica cada mensagem recebida e enviada · assinado com um segredo", ou "Nenhum – as mensagens só aparecem na caixa de entrada." Um selo Zapier significa que um Zap recebe as mensagens (veja Zapier e os números da caixa de entrada).

O selo no canto superior direito diz o que o número está fazendo:

Alterar a URL do webhook ou as mensagens enviadas#

1. Abra as configurações do webhook

   Clique em Configurações do webhook no cartão do número.

2. Altere as configurações

   Edite a URL do webhook (opcional) e as marcações em Mensagens a notificar. Para desativar o webhook, apague a URL.

3. Salve

   Clique em Salvar. Você vê "Configurações do webhook salvas."

   

• Alterar a URL mantém o segredo. Apagar a URL exclui o segredo; uma URL adicionada depois ganha um segredo novo, mostrado uma vez em Seu segredo do webhook.
• Sem nenhuma caixa marcada, o cartão diz "Nenhum evento selecionado – nada é notificado".

Mostrar ou gerar novamente o segredo#

O segredo tem 32 letras e dígitos. Em Configurações do webhook, em Segredo do webhook, Mostrar o revela com Copiar ao lado. Gerar novamente pergunta "Gerar um novo segredo? O atual deixa de funcionar imediatamente – atualize-o onde quer que você verifique assinaturas." Clique em Gerar novo segredo: ele é salvo na hora ("Novo segredo gerado."), sem Salvar, e todas as requisições a partir de então são assinadas com ele, inclusive as novas tentativas de mensagens anteriores.

Parar, iniciar ou remover um número#

Webhooks aguardando nova tentativa são descartados quando você para ou remove o número ou altera a URL dele.

Como os webhooks são entregues#

• Quando: cada número da caixa de entrada é verificado cerca de uma vez por minuto enquanto está conectado; as verificações pausam enquanto ele envia mensagens, como uma campanha. Uma mensagem é enviada depois da verificação que a encontra, em geral em um ou dois minutos. Não há botão de teste: envie uma mensagem para o número de outro celular.
• Uma requisição por mensagem: message_received para Mensagens recebidas; message_sent para Mensagens enviadas, enviadas pelo celular, pelo WhatsApp Web ou pelo WbizTool (campanhas, API, lembretes). Respostas enviadas pela caixa de entrada Unibox em geral não são enviadas: a caixa de entrada já as tem.
• Sucesso: qualquer status 2xx em até 8 segundos. Redirecionamentos não são seguidos: um 3xx conta como falha.
• Novas tentativas: um timeout, um erro de conexão, 429 ou um 5xx gera 3 novas tentativas, depois de 30 segundos, 1 minuto e 2 minutos. Outras respostas, como 400 ou 404, e um certificado TLS inválido não geram novas tentativas.
• 410 Gone: o WbizTool desativa o webhook do número (URL e segredo removidos; para um hook do Zapier, o seu webhook anterior volta). O número continua sincronizando com a caixa de entrada.
• Ordem e repetições: as requisições podem chegar fora de ordem e, raramente, duas vezes. Ordene por message.whatsapp_timestamp e ignore um message.id que você já tratou para o mesmo whatsapp_client_id. Dois dos seus números em um mesmo grupo enviam cada um a sua própria cópia.
• Mensagens atrasadas: uma mensagem captada com atraso, por exemplo depois que o número se reconecta ou após uma pausa nas verificações, é enviada mesmo assim, com replayed como true se tiver mais de 10 minutos. As mensagens que chegaram enquanto o número estava parado não são enviadas depois de Iniciar (veja Parar, iniciar ou remover um número).
• Verificação do endereço: a URL é verificada de novo antes de cada requisição; um host que agora aponta para uma rede privada, ou que não resolve, não recebe nada, e essa mensagem não tem nova tentativa.

Cabeçalhos#

Verificar a assinatura#

Cada requisição é assinada com o segredo do webhook do número usando HMAC-SHA256 sobre o corpo bruto da requisição, exatamente como recebido. O digest hexadecimal em minúsculas é enviado em X-Wbiztool-Signature como sha256=<digest>. Um webhook configurado na página Números da caixa de entrada sempre tem um segredo, então o cabeçalho está sempre presente.

Calcule a assinatura a partir dos bytes brutos antes de interpretar o JSON. Interpretar e codificar o corpo de novo o altera (espaços, caracteres escapados), e a assinatura não vai bater.

// Express: register this route before app.use(express.json()), or the raw body is lost
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.WBIZTOOL_WEBHOOK_SECRET;

app.post("/wbiztool/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const received = req.get("X-Wbiztool-Signature") || "";

  const a = Buffer.from(received), b = Buffer.from(expected);
  const valid = a.length === b.length && crypto.timingSafeEqual(a, b);
  if (!valid) return res.status(401).send("Invalid signature");

  const data = JSON.parse(req.body.toString("utf8"));
  if (data.event === "message_received") {
    console.log(`New message from ${data.contact.phone}: ${data.message.content}`);
  }
  res.sendStatus(200); // answer quickly; do slow work in the background
});

app.listen(3000);

# Flask
import hashlib
import hmac
import json
import os

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["WBIZTOOL_WEBHOOK_SECRET"].encode()


@app.post("/wbiztool/webhook")
def wbiztool_webhook():
    raw_body = request.get_data()  # raw bytes, before parsing
    expected = "sha256=" + hmac.new(SECRET, raw_body, hashlib.sha256).hexdigest()
    received = request.headers.get("X-Wbiztool-Signature", "")
    if not hmac.compare_digest(expected, received):
        abort(401)

    data = json.loads(raw_body)
    if data["event"] == "message_received":
        print(f"New message from {data['contact']['phone']}: {data['message']['content']}")
    return "", 200

<?php
$secret   = getenv('WBIZTOOL_WEBHOOK_SECRET');
$rawBody  = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$received = $_SERVER['HTTP_X_WBIZTOOL_SIGNATURE'] ?? '';

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($rawBody, true);
if ($data['event'] === 'message_received') {
    error_log('New message from ' . $data['contact']['phone'] . ': ' . $data['message']['content']);
}
http_response_code(200);

Para testar seu receptor antes de chegar uma mensagem real, assine um corpo você mesmo e envie-o:

BODY='{"event":"message_received","message":{"content":"Test"},"contact":{"phone":"12125550120"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WBIZTOOL_WEBHOOK_SECRET" | sed 's/^.* //')
curl -X POST https://your-server.example/wbiztool/webhook -H 'Content-Type: application/json' -H "X-Wbiztool-Signature: sha256=$SIG" -d "$BODY"

A assinatura cobre o corpo, incluindo o timestamp dele, que é novo a cada tentativa. Para recusar requisições repetidas, rejeite um timestamp com mais de 5 minutos e ignore um message.id que você já tratou.

Payload#

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:30:31.482913+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0C1A2B3D4E5F60718",
    "type": "chat",
    "content": "Can I add a gift note to it?",
    "from": "12125550120",
    "from_name": "Emma Thompson",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:30:04+00:00",
    "whatsapp_timestamp": 1792060204,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550120",
    "lid": null,
    "phone_hidden": false,
    "name": "Emma Thompson",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_sent",
  "timestamp": "2026-10-15T10:34:22.117205+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0F9E8D7C6B5A40312",
    "type": "chat",
    "content": "Of course! Send us the text and we'll print it on a card.",
    "from": "12125550120",
    "from_name": "Emma Thompson",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:33:40+00:00",
    "whatsapp_timestamp": 1792060420,
    "direction": "outgoing",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550120",
    "lid": null,
    "phone_hidden": false,
    "name": "Emma Thompson",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:35:48.904311+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0A7B6C5D4E3F20109",
    "type": "image",
    "content": "📸 Image",
    "from": "12125550122",
    "from_name": "Sofia Martinez",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:34:51+00:00",
    "whatsapp_timestamp": 1792060491,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0,
    "media": {
      "filename": "",
      "mimetype": "image/jpeg",
      "size": 245760,
      "url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/unibox/10314/media/false_12125550122%40c.us_3EB0A7B6C5D4E3F20109.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=…&X-Amz-Date=20261015T103548Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=…"
    }
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550122",
    "lid": null,
    "phone_hidden": false,
    "name": "Sofia Martinez",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:39:40.330187+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected][email protected]",
    "type": "chat",
    "content": "Will there be a larger size?",
    "from": "120363041234567890",
    "from_name": "Lumen VIP Club",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:39:02+00:00",
    "whatsapp_timestamp": 1792060742,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0,
    "sender": {
      "phone": "12125550126",
      "name": "Olivia Brooks",
      "phone_hidden": false
    }
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "120363041234567890",
    "lid": null,
    "phone_hidden": false,
    "name": "Lumen VIP Club",
    "is_group": true,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  },
  "group": {
    "name": "Lumen VIP Club"
  }
}

Os números, IDs e nomes acima são exemplos. O corpo real é uma única linha de JSON compacto, e todo caractere não ASCII (letras acentuadas, outros alfabetos, emojis) chega como um escape \uXXXX, como \ud83d\udcf8 para 📸. Mais campos podem ser adicionados; ignore os que você não usa.

Campos de nível superior#

Campos de message#

Campos de contact#

Zapier e os números da caixa de entrada#

O gatilho Incoming WhatsApp Message do WbizTool no Zapier usa esses webhooks. Ativar um Zap adiciona o número à caixa de entrada, se necessário (ocupando um dos seus números da caixa de entrada), e aponta o webhook dele para o Zapier, só para mensagens recebidas, com um segredo próprio; o cartão mostra um selo Zapier. A sua URL de webhook, o seu segredo e as suas marcações voltam quando o Zap é desativado.

Configurações do webhook então avisa: "Este webhook pertence a um Zap do Zapier. Alterar ou remover a URL faz o Zap deixar de receber mensagens." Parar e Remover também avisam: o Zap continua ativo no Zapier, mas não recebe nada, então desative-o no Zapier. Veja Como o gatilho funciona com seus números da caixa de entrada.

Sem o add-on Unibox#

A página diz "Sem add-on Unibox" e "O add-on Unibox não está ativo neste espaço de trabalho.", e Adicionar número à caixa de entrada abre Add-on Unibox obrigatório: "Para adicionar números do WhatsApp à caixa de entrada compartilhada e receber as mensagens deles por webhook, assine o add-on Unibox." Um Proprietário clica em Ver add-ons e adiciona o add-on Número do Unibox em Cobrança e planos, em um plano pago ou vitalício (não no teste grátis).

Quando o add-on termina ou um número se desconecta#

• O add-on termina: todos os números da caixa de entrada são interrompidos, na hora ou em cerca de uma hora. Os cartões mostram Interrompido com "Interrompido porque o add-on Unibox não está ativo neste espaço de trabalho." Proprietários e Editores ficam sabendo quais caixas de entrada foram interrompidas, no email de cobrança ou no alerta "Alguns números ou recursos de … pararam" (Problemas com números e envios em Notificações). Conversas, URLs de webhook e segredos são mantidos: quando o add-on voltar, clique em Iniciar em cada número. As mensagens do período em que ele ficou parado são então adicionadas à caixa de entrada, até 30 dias atrás, mas não são enviadas ao seu webhook.
• O add-on cobre menos números do que os ativos: "Há mais números ativos do que seu add-on permite. Os extras mais recentes são interrompidos automaticamente em cerca de uma hora."
• O número se desconecta: o cartão mostra Número desconectado e nada é sincronizado nem enviado. Depois que você o reconecta, as mensagens que chegaram nesse meio-tempo também são captadas e enviadas; as que têm mais de 10 minutos vêm com replayed como true.
• Ele é reconectado com outro celular: o número da caixa de entrada e o webhook dele continuam para o novo número (mesmo whatsapp_client_id, novo whatsapp_phone) a partir desse momento; os chats antigos ficam na caixa de entrada como histórico.

Solução de problemas#

Relacionados#

• Caixa de entrada Unibox: leia e responda aos chats dos seus números da caixa de entrada
• Integração com Zapier
• Conecte seu número de WhatsApp
• Planos e cobrança
• API de envio de mensagens: o campo webhook dela informa se uma mensagem que você envia saiu (é outro webhook)