Entrar
Tutorials

Como Configurar a API WhatsApp Business do Zero (Guia de Integração 2026)

Aprenda como configurar a API WhatsApp Business do zero. Passo a passo para conectar sua conta pela Meta, criar a chave de API e enviar o primeiro modelo.

StartMessaging Team Updated

Integrar as comunicações de sua empresa diretamente com o WhatsApp é o caminho mais curto para aumentar o engajamento e a taxa de conversão no mercado brasileiro. O aplicativo é a ferramenta preferida dos brasileiros para conversar com marcas. No entanto, quando sua empresa cresce e o volume de conversas aumenta, o aplicativo móvel comum torna-se insuficiente. Neste tutorial passo a passo, você aprenderá como configurar a API oficial do WhatsApp Business do zero: conectar a sua conta pela Meta, criar uma chave de API e enviar o seu primeiro modelo de mensagem.

A StartMessaging é um CRM de WhatsApp com API, construído sobre a Cloud API oficial da Meta (a StartMessaging é uma Meta Tech Provider). Você conecta a sua própria Conta do WhatsApp Business (WABA) pelo Cadastro Incorporado (Embedded Signup) da Meta, e o seu sistema conversa com ela por uma API REST em https://waba-api.startmessaging.com/api/v1, autenticada com uma chave enviada no cabeçalho Authorization: Bearer sm_live_..., e por webhooks assinados.

API Oficial do WhatsApp Business vs. App Comum: As Diferenças Cruciais

Muitos empreendedores e desenvolvedores iniciantes confundem o aplicativo móvel gratuito (WhatsApp Business App) com a API Oficial (WhatsApp Business Platform). O aplicativo comum foi projetado para pequenas empresas locais que lidam com baixo volume de mensagens. Ele funciona em um celular principal com alguns aparelhos vinculados, e toda a comunicação depende de digitação manual, sem suporte real a integrações com o seu sistema ou a envios automatizados.

A API Oficial, por outro lado, elimina a dependência de um smartphone ligado. Ela roda na nuvem da Meta, permitindo que vários agentes respondam a partir de uma caixa de entrada compartilhada. Além disso, a API possibilita a integração com seus sistemas (loja virtual, ERP, CRM) e o envio programático de notificações disparadas por eventos: alertas de segurança, confirmações de pagamento via Pix e atualizações de entrega.

Outra diferença crítica está no cumprimento das políticas da Meta. Disparar mensagens de forma robotizada usando aplicativos comuns ou emuladores não oficiais costuma levar ao bloqueio do número. A API Oficial é o canal autorizado pela Meta para automação, desde que você use modelos aprovados e respeite o consentimento dos clientes.

Pré-requisitos para a Configuração Oficial

Antes de começar, separe os itens que a Meta exige. Sem eles, não é possível concluir a conexão nem enviar modelos.

  1. Uma conta do Facebook que administre (ou possa criar) um portfólio empresarial da Meta: é nele que ficam a sua Conta do WhatsApp Business e o seu número. A verificação da empresa na Meta não é obrigatória para começar, mas libera limites de envio maiores.
  2. Um número de telefone da empresa que receba um código de verificação: se o número estiver em uso no WhatsApp ou no WhatsApp Business App, o fluxo de cadastro da Meta explica como migrá-lo.
  3. Uma forma de pagamento (cartão) para cadastrar no Gerenciador do WhatsApp: a Meta exige essa forma de pagamento antes do primeiro envio de modelo, e é nela que a Meta cobra as mensagens. Essa cobrança nunca passa pela StartMessaging.
ItemRequisitoPara que serve
Portfólio empresarial da MetaConta do Facebook com acesso de administradorCriar ou escolher a Conta do WhatsApp Business (WABA) durante o cadastro
Número de telefoneNúmero da empresa que receba SMS ou ligaçãoReceber o código de verificação enviado pela Meta
Forma de pagamento na MetaCartão cadastrado no Gerenciador do WhatsAppPermitir o envio de modelos; a Meta cobra as mensagens diretamente
Workspace na StartMessagingConta criada em waba.startmessaging.comConectar o número, criar modelos, chaves de API e webhooks

Passo a Passo: Conectando o WhatsApp à StartMessaging

Você não precisa criar um app no console de desenvolvedores da Meta nem copiar IDs de número manualmente. A conexão é feita pelo Cadastro Incorporado da Meta, dentro do painel.

Passo 1: Fale com vendas para abrir seu workspace

Fale com nosso time de vendas e nós abrimos o seu workspace. Ele começa com um teste grátis de 14 dias do plano Business, para até 3 pessoas, 1.000 contatos e 1.000 mensagens de API, com a API de desenvolvedor incluída.

Passo 2: Conectar o WhatsApp pelo Cadastro Incorporado

Abra Connect no menu do workspace e clique em Connect with Facebook. Na janela da Meta, entre com o Facebook, escolha ou crie o portfólio empresarial, a Conta do WhatsApp Business e o número. Verifique o número com o código que a Meta envia por SMS ou ligação e, de volta à StartMessaging, defina um PIN de verificação em duas etapas de 6 dígitos para registrar o número na Cloud API.

Passo 3: Cadastrar a forma de pagamento na Meta

Na página Connect aparece o item Payment method added in Meta. Clique em Open WhatsApp Manager → e cadastre um cartão na sua Conta do WhatsApp Business. Sem isso, a Meta recusa envios de modelos e a API responde 402 META_PAYMENT_REQUIRED.

Passo 4: Criar e aprovar um modelo

Para iniciar uma conversa (ou falar com um cliente cuja janela de 24 horas fechou), o WhatsApp só permite modelos aprovados. Em Templates → Create template, escolha a categoria (Marketing, Utility ou Authentication), o idioma (pt_BR) e o texto, com um exemplo para cada variável, e clique em Submit to Meta. A Meta revisa cada modelo e define o prazo.

Passo 5: Criar a chave de API

Em Developers → API keys, clique em Create key, dê um nome e escolha o acesso (Full access, Send only, Read only ou escopos personalizados). A chave começa com sm_live_ e aparece uma única vez: guarde-a em uma variável de ambiente ou em um cofre de segredos, nunca no código do navegador ou do app.

Integração Prática: Enviando sua Primeira Mensagem via API

Comece testando a chave com GET /api/v1/me, que não exige escopo e mostra o workspace, o plano, os escopos da chave e o uso do mês:

curl https://waba-api.startmessaging.com/api/v1/me \
  -H "Authorization: Bearer sm_live_sua_chave"

Em seguida, envie o modelo aprovado com POST /api/v1/messages. Use o nome do modelo exatamente como a Meta aprovou e o código de idioma. O número do destinatário vai em formato E.164 (+55, DDD e número):

/**
 * Envia um modelo aprovado pela API da StartMessaging.
 * Requer a variável de ambiente SM_API_KEY com uma chave sm_live_...
 */
async function enviarModelo(telefone, nomeCliente, numeroPedido) {
  const res = await fetch('https://waba-api.startmessaging.com/api/v1/messages', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SM_API_KEY}`,
      'Content-Type': 'application/json',
      // Uma chave única por mensagem: uma nova tentativa nunca envia duas vezes
      'Idempotency-Key': `pedido-${numeroPedido}-confirmacao`,
    },
    body: JSON.stringify({
      to: telefone,
      type: 'template',
      template: {
        name: 'confirmacao_pedido',
        language: 'pt_BR',
        parameters: [{ text: nomeCliente }, { text: numeroPedido }],
      },
      clientReference: `pedido-${numeroPedido}`,
    }),
  });

  const body = await res.json();
  if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  console.log('Mensagem aceita pelo WhatsApp:', body.data.id, body.data.status); // "sent"
  return body.data;
}

enviarModelo('+5511999999999', 'Ana', '#1042');

Uma resposta 201 significa que o WhatsApp aceitou a mensagem. Os recibos de entrega e leitura chegam depois pelos webhooks message.*. O destinatário entra automaticamente nos seus contatos e, nos planos com caixa de entrada (Team, Business, Enterprise e o teste grátis), a conversa aparece para a sua equipe responder.

Mensagens de texto livre (type: "text") só podem ser enviadas dentro da janela de atendimento de 24 horas, aberta pela última mensagem do cliente. Fora dela, a API responde 403 MESSAGE_WINDOW_CLOSED e você deve enviar um modelo.

Erros Comuns na Configuração da API e Como Resolvê-los

Os erros seguem um envelope padrão. Trate cada caso pelo campo error.code, não pelo texto da mensagem.

  • 401 INVALID_API_KEY: o cabeçalho Authorization está ausente, mal formado ou a chave foi revogada. Envie Authorization: Bearer sm_live_... sem espaços extras.
  • 403 INSUFFICIENT_SCOPE: a chave é válida, mas não tem o escopo da rota (por exemplo, messages:send). Ajuste os escopos em Developers → API keys.
  • 402 META_PAYMENT_REQUIRED: falta a forma de pagamento na sua Conta do WhatsApp Business. Cadastre-a no Gerenciador do WhatsApp.
  • 422 TEMPLATE_NOT_APPROVED / 404 TEMPLATE_NOT_FOUND: o modelo ainda está em revisão, ou o nome ou o idioma não conferem.
  • 429 RATE_LIMIT_EXCEEDED: você passou do limite de requisições do plano. Espere os segundos indicados em Retry-After e use filas (como Redis e BullMQ) para controlar o ritmo.
  • 400 VALIDATION_ERROR / MOBILE_INVALID: o corpo está incorreto ou o número não é válido. Prefira o formato E.164 (+5511999999999).

A lista completa está em Erros e limites.

Quanto Custa: Planos da StartMessaging e Tarifas da Meta

São duas cobranças separadas:

  • A Meta cobra as mensagens diretamente na forma de pagamento da sua Conta do WhatsApp Business, pelas tarifas publicadas pela Meta. Desde 1º de outubro de 2026, a cobrança é por mensagem entregue: todo modelo entregue é cobrado (marketing, utilidade, mesmo dentro da janela de 24 horas, e autenticação). Respostas de atendimento dentro da janela de 24 horas são gratuitas até uma cota mensal por número. As tarifas por país estão na página oficial de preços da Meta.
  • A StartMessaging cobra apenas a assinatura, sem taxa por mensagem, carteira ou créditos. Os preços são em rúpias indianas (INR), com GST incluído: Developer (API e painel somente leitura) grátis com 100 mensagens de API por mês, ou a partir de ₹100/mês; Team ₹999/mês, com caixa de entrada compartilhada, contatos, campanhas e respostas automáticas; Business ₹2.999/mês, com fluxos de chatbot, WhatsApp Forms e funil de vendas; e Enterprise sob contrato. Veja todos os detalhes na página de preços.

Perguntas Frequentes

Q: Preciso de um número de telefone novo para usar a API oficial do WhatsApp?

A: Não necessariamente. Você pode usar um número novo ou o número atual da empresa. Se ele estiver ativo no WhatsApp ou no WhatsApp Business App, o fluxo de cadastro da Meta explica como migrá-lo para a plataforma.

Q: Existe um ambiente de testes (sandbox)?

A: Não. Você conecta a sua própria Conta do WhatsApp Business desde o início. O teste grátis de 14 dias inclui a API de desenvolvedor (1.000 mensagens de API), o suficiente para construir e testar uma integração completa. Depois dele, o Developer Free mantém a API com 100 mensagens por mês.

Q: Quanto tempo leva a aprovação dos modelos e a verificação da empresa?

A: Quem define os prazos é a Meta. O painel mostra o modelo como Pending review até a decisão, e o webhook template.status_updated avisa o seu sistema quando o status muda.

Q: Há custos ao receber mensagens dos clientes?

A: Receber mensagens não gera cobrança. Quando o cliente escreve, abre-se a janela de atendimento de 24 horas: suas respostas de texto livre, mídia e mensagens interativas são gratuitas até uma cota mensal por número; depois disso, a Meta também as cobra. Modelos enviados dentro da janela continuam sendo cobrados pela Meta. Não há mais cobrança por “conversa” de 24 horas.

Configurar a API oficial do WhatsApp Business de forma correta estabelece um canal direto, seguro e escalável com seus clientes no Brasil. Para ir além, leia o guia de primeiros passos, configure os webhooks do WhatsApp para receber respostas e recibos em tempo real, ou fale com nosso time de vendas para abrir seu workspace com o teste grátis.

S

StartMessaging Team

StartMessaging Team

Related posts