Chaves de API e Client ID

Uma chave de API permite que o seu próprio software, e ferramentas como Zapier, n8n, Make e o plugin do WordPress, enviem mensagens de WhatsApp pelos números do seu espaço de trabalho. O seu próprio código envia a chave em um cabeçalho Authorization: Bearer; as integrações pedem dois valores da página Chaves de API: o Client ID do seu espaço de trabalho e uma das chaves dele. A mesma página tem o segredo que assina nossos webhooks.

Quem pode fazer isso: só Proprietários – todos os Proprietários do espaço de trabalho, não apenas o criador. Os Proprietários veem, criam, copiam e excluem todas as chaves do espaço de trabalho, não importa quem as criou. Editores e Analistas não veem Chaves de API na barra lateral nem na página Configurações, e um link para ela abre Perfil para eles (veja Funções e permissões). As chaves funcionam em todos os planos, inclusive no teste grátis; o que você envia com elas usa as mensagens do espaço de trabalho.

Abra Chaves de API em Integrações na barra lateral ou acesse Configurações → Chaves de API.

Cada chave mostra o nome, quando foi criada (Criada em …), os quatro últimos caracteres da chave (como •••• 7f3a), Copiar chave e Excluir. A chave mais recente aparece primeiro.

Criar uma chave de API#

1. Clique em Criar chave

   Em Configurações → Chaves de API, clique em Criar chave no canto superior direito do cartão.

2. Dê um nome (opcional)

   Em Nome (opcional), digite o app que vai usá-la, como n8n ou Website (até 50 caracteres). Se ficar vazio, ela recebe um nome como "API Key 3", como diz a dica abaixo do campo.

3. Crie a chave

   Clique em Criar chave.

   

4. Copie a chave

   Sua nova chave de API mostra a chave completa: "Copie agora – você não verá a chave completa de novo. Depois, “Copiar chave” a copia sem exibi-la." Clique em Copiar ("Chave copiada."), cole a chave no seu app ou integração e depois clique em Concluído.

   

• Até 10 chaves por espaço de trabalho. Com 10, Criar chave fica cinza, e passar o cursor sobre ele mostra "Você pode ter até 10 chaves de API. Exclua uma para criar outra."
• As chaves não expiram e não podem ser renomeadas nem desativadas: uma chave funciona até ser excluída.
• Uma chave por app. Dê a cada chave o nome do app que a usa, para poder substituir ou excluir uma sem quebrar as outras.
• Qual espaço de trabalho: uma chave pertence ao espaço de trabalho que estava selecionado quando você a criou, e cada requisição feita com ela age sobre esse espaço de trabalho: os números, as mensagens e o plano dele. Para enviar de outro espaço de trabalho, troque para ele e crie uma chave lá.

O que informar no seu app#

Onde eles entram:

• Seu próprio código: em um cabeçalho Authorization: Bearer YOUR_API_KEY em cada requisição (recomendado). A chave identifica o espaço de trabalho dela, então o client_id pode ficar de fora; se você enviar, ele ainda precisa ser o deste espaço de trabalho. Veja Enviar a chave em um cabeçalho e, para uma primeira mensagem em cURL, Python, Node.js e PHP, Enviar mensagem.
• Zapier: o Client ID e a chave de API, quando você conecta sua conta.
• n8n: Client ID, API Key e WhatsApp Client ID da credencial do WbizTool.
• Make, Pabbly Connect e outras ferramentas: o corpo de uma requisição HTTP.
• WordPress: WbizTool → Settings, em API Configuration.

O Google Sheets e a Shopify são configurados no painel e não precisam de chave.

Enviar a chave em um cabeçalho#

Todo endpoint /api/v1/ aceita a chave em um cabeçalho Authorization, do jeito que a futura API v2 vai aceitar:

Authorization: Bearer YOUR_API_KEY

• O client_id é opcional com o cabeçalho: a chave define o espaço de trabalho. Se você também enviar client_id, ele precisa ser o Client ID deste espaço de trabalho, como antes.
• Envie a chave em um só lugar. Com o cabeçalho, deixe api_key fora do corpo ou envie a mesma chave. Se forem diferentes, a chave do cabeçalho é usada quando é uma chave válida; se o cabeçalho tiver outra coisa (o token de outra ferramenta, por exemplo), a api_key do corpo é usada.
• Chaves no corpo continuam funcionando (client_id e api_key como JSON ou campos de formulário), então nada muda para apps e integrações que as enviam assim. O cabeçalho é melhor porque o corpo das requisições vai parar em logs, proxies e históricos de criadores de formulários com mais frequência do que os cabeçalhos.
• Campos de formulário, uploads multipart e corpos JSON funcionam todos com o cabeçalho.

curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whatsapp_client": 101, "phone": "919876543210", "msg": "Hello from WbizTool"}'

Testar sua chave#

Chame Verificar credenciais (POST /api/v1/me/) com sua chave e, se quiser, um whatsapp_client. "status": 1 com "message": "Okay" significa que eles funcionam juntos. Nada é enviado e nenhuma mensagem é usada, mas a chamada não verifica se ainda há mensagens nem se o número está conectado.

curl -X POST https://wbiztool.com/api/v1/me/ -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" -d '{"whatsapp_client": 101}'

Uma chave que funciona responde {"status": 1, "message": "Okay", "name": "…"}.

Copiar uma chave de novo#

Clique em Copiar chave ao lado da chave. A chave completa vai para a área de transferência sem aparecer na página; você vê, por exemplo, "“Zapier” copiada." e o botão mostra Copiado ✓ por um instante. Você não precisa de uma chave nova por ter perdido a antiga.

Para descobrir qual chave um app usa, compare os quatro últimos caracteres da chave dele com a lista.

Excluir uma chave#

1. Clique em Excluir

   Clique em Excluir ao lado da chave.

2. Confirme

   A janela "Excluir “…”?" avisa: "Tudo o que usa esta chave para de funcionar na hora: Zaps no Zapier, cenários do n8n e do Make, o plugin do WordPress e suas próprias chamadas à API. Dê outra chave a eles antes. Isso não pode ser desfeito." Clique em Excluir chave. Você vê "“…” excluída."

A partir daí, requisições com essa chave recebem Auth Error: invalid api key. O que ela fez antes continua valendo: as mensagens que ela colocou na fila ainda são enviadas (cancele-as em Relatórios se precisar), e os lembretes que ela criou continuam rodando. Um gatilho Incoming WhatsApp Message do Zapier configurado com ela também continua recebendo mensagens, porque o webhook dele já está no número: desative o Zap no Zapier para interrompê-lo.

Substituir uma chave#

Substitua uma chave quando ela pode ter vazado, quando sai alguém que podia copiá-la, ou de tempos em tempos. Não há botão de rotação: crie a nova chave primeiro, para que nada pare no meio do caminho.

1. Crie uma nova chave

   Crie uma chave e copie-a. Com 10 chaves, exclua antes uma que você não usa mais.

2. Atualize seus apps

   Cole a nova chave em todos os apps e integrações que usavam a antiga e confira cada um, por exemplo com Verificar credenciais.

3. Exclua a chave antiga

   Exclua-a. Ela para de funcionar na hora.

4. Procure uso indevido (depois de um vazamento)

   Procure em Relatórios mensagens que você não enviou e cancele as que ainda estão em espera. Em Lembretes, exclua os lembretes que você não criou, porque eles continuam rodando. Remova em Números do WhatsApp os números que você não adicionou. Com o add-on Unibox, procure em Números da caixa de entrada um selo Zapier ou um webhook que você não reconhece.

Mantenha suas chaves seguras#

Uma chave não tem permissões próprias: qualquer pessoa que tenha uma pode fazer no seu espaço de trabalho tudo o que a API permite, seja qual for a função dela. Isso inclui enviar mensagens de qualquer um dos números dele (usando as mensagens dele), ler o histórico de mensagens, cancelar mensagens em espera, gerenciar lembretes e arquivos de mídia, verificar números e conectar números novos.

• Guarde as chaves no seu servidor, em uma variável de ambiente ou no repositório de credenciais da sua integração. Nunca coloque uma no JavaScript de um site, em um app de celular, em uma planilha compartilhada ou em código que você publica.
• Não envie chaves por e-mail nem por chat. Cole-as direto no app que precisa delas.
• Use uma chave por app e exclua as chaves que você não usa mais.
• Substitua as chaves de tempos em tempos, e na hora se uma delas pode ter vazado.

O Client ID sozinho não é segredo, mas trate cada chave como uma senha.

Chaves de API v2#

A API v2 tem chaves próprias, criadas no cartão Chaves de API v2 da mesma aba. Elas são mais seguras que as chaves acima:

• Exibidas uma única vez. A chave completa (wbz_live_…) só aparece quando você a cria; o WbizTool guarda apenas uma impressão digital dela. Se você perdê-la, revogue-a e crie uma nova.
• Só o que ela precisa. Marque o que a chave pode fazer (enviar mensagens, ler mensagens, lembretes, números, mídia, verificação de números), limite-a a alguns dos seus números e, se quiser, defina uma data de expiração.
• Chaves de teste. Uma chave de teste (wbz_test_…) verifica cada requisição como uma chave real, mas não envia nada – para criar e testar uma integração.
• Último uso. Cada chave mostra quando e de onde foi usada pela última vez. Revogar a desativa na hora, junto com os endpoints de webhook que foram configurados com ela.

As chaves acima funcionam só com a API v1, e as chaves de API v2 só com a v2. Veja Migrar da v1 para a v2.

Assinaturas de webhook#

O WbizTool assina cada webhook que envia a você, para que o seu endpoint possa verificar que a requisição veio mesmo de nós e não foi alterada no caminho: o webhook de status da mensagem (enviada, com falha, cancelada, expirada), os eventos de conexão do número e os webhooks da caixa de entrada. Os corpos são os mesmos de antes; dois cabeçalhos são adicionados:

A assinatura cobre exatamente os bytes que enviamos: os campos de formulário como chegam, o corpo multipart inteiro quando uma imagem de QR code vai anexada, e o JSON dos webhooks da caixa de entrada. Receptores que ignoram os cabeçalhos continuam funcionando.

Obter o segredo de assinatura#

Em Configurações → Chaves de API, o cartão Segredo de assinatura dos webhooks, abaixo das suas chaves, mostra os quatro últimos caracteres do segredo, como •••• b70d. Cada espaço de trabalho tem um segredo para todos os seus webhooks; ele é criado com o primeiro webhook que enviamos a você.

1. Clique em Revelar novo segredo

   Clique em Revelar novo segredo (ou em Criar segredo se o espaço de trabalho ainda não tiver um). A caixa de diálogo "Substituir o segredo de assinatura?" avisa que o segredo atual para de funcionar na hora. Clique em Gerar novo segredo.

2. Copie o segredo

   Seu segredo de assinatura dos webhooks mostra o segredo completo uma única vez. Clique em Copiar e guarde-o onde o seu receptor de webhooks consiga lê-lo, como uma variável de ambiente. Você não vai vê-lo de novo: se perdê-lo, gere um novo.

Só Proprietários veem o cartão. Gerar um novo segredo substitui o anterior na hora, então atualize seus receptores logo em seguida; webhooks enviados nesse meio-tempo falham na sua verificação.

Verificar um webhook#

Calcule a assinatura a partir do corpo bruto (antes de o seu framework interpretá-lo), compare-a com o cabeçalho em tempo constante e recuse timestamps com mais de 5 minutos, para que uma requisição antiga não possa ser repetida:

import hashlib, hmac, time

def verify(secret: str, body: bytes, headers) -> bool:
    ts, sig = headers["WbizTool-Timestamp"], headers["WbizTool-Signature"]
    mac = "v1=" + hmac.new(secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(ts)) < 300 and hmac.compare_digest(mac, sig)

const crypto = require("crypto");

function verify(secret, rawBody, headers) {
  const ts = headers["wbiztool-timestamp"], sig = String(headers["wbiztool-signature"]);
  const mac = "v1=" + crypto.createHmac("sha256", secret).update(ts + ".").update(rawBody).digest("hex");
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300 && sig.length === mac.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(mac));
}

Responda 2xx quando a verificação passar e 401 quando falhar. Webhooks da caixa de entrada com o próprio segredo do número continuam trazendo também X-Wbiztool-Signature; WbizTool-Signature é o mesmo esquema em todos os webhooks.

Solução de problemas#

Relacionados#

• Primeiros passos com a API
• Visão geral da API v2
• API para verificar credenciais
• API de envio de mensagens
• Apps e integrações
• Configurações do espaço de trabalho, membros da equipe e funções
• Conecte seu número de WhatsApp