# Guia Completo de Setup - WhatsApp Business Cloud API > Do zero absoluto ate o envio da primeira mensagem em producao. > Tempo estimado: 1-2 horas (sem verificacao de negocio) | 3-7 dias (com verificacao) --- ## Pre-requisitos - Email valido (preferencialmente corporativo) - Documento de identidade pessoal - Numero de telefone que **NAO esteja registrado** no WhatsApp pessoal - CNPJ ou documento da empresa (para verificacao de negocio) - Navegador atualizado (Chrome recomendado) --- ## Passo 1 - Criar Conta no Meta Business Suite ### URL ``` https://business.facebook.com/overview ``` ### Procedimento 1. Acesse `https://business.facebook.com/overview` 2. Clique em **"Criar conta"** 3. Se voce ja tem Facebook pessoal, faca login primeiro. Caso contrario, sera pedido para criar um 4. Preencha os campos: - **Nome da empresa**: Use o nome oficial/fantasia do seu negocio - **Seu nome**: Nome do administrador da conta - **Email comercial**: Preferencialmente email corporativo (ex: `contato@suaempresa.com.br`) 5. Clique em **"Enviar"** 6. Acesse seu email e clique no link de confirmacao enviado pela Meta 7. Apos confirmar, voce sera redirecionado ao painel do Meta Business Suite ### Erros Comuns | Erro | Solucao | |------|---------| | "Este email ja esta associado a outra conta" | Use outro email ou recupere o acesso da conta existente em `business.facebook.com/settings` | | "Nao foi possivel criar a conta" | Desative extensoes de bloqueio de anuncios (uBlock, AdBlock) e tente novamente | | Nao recebeu email de confirmacao | Verifique pasta de spam. Tente reenviar apos 5 minutos. Se persistir, use outro email | | Conta bloqueada imediatamente apos criacao | Conta nova em perfil Facebook recente pode ser flagrada. Aguarde 24h e tente novamente | ### Pronto Voce deve ter: - Acesso ao painel em `business.facebook.com` - Um **Business ID** visivel em `Business Settings > Business Info` (numero tipo `123456789012345`) - Email confirmado --- ## Passo 2 - Criar App no Meta for Developers ### URL ``` https://developers.facebook.com/apps ``` ### Procedimento 1. Acesse `https://developers.facebook.com/apps` 2. Se for sua primeira vez, clique em **"Comecar"** e aceite os termos de desenvolvedor 3. Clique no botao **"Criar aplicativo"** 4. Selecione o tipo de app: **"Empresa"** (Business) - NAO selecione "Nenhum", "Consumidor" ou "Jogos" 5. Preencha: - **Nome do aplicativo**: Ex: `MeuApp WhatsApp API` - **Email de contato**: Seu email corporativo - **Conta empresarial**: Selecione a conta criada no Passo 1 6. Clique em **"Criar aplicativo"** 7. Pode ser solicitado que voce digite sua senha do Facebook novamente ### Erros Comuns | Erro | Solucao | |------|---------| | "Voce atingiu o limite de aplicativos" | Contas novas tem limite. Delete apps de teste antigos em `developers.facebook.com/apps` | | Tipo "Empresa" nao aparece | Certifique-se de que sua conta Business foi criada corretamente no Passo 1 | | "Conta empresarial nao encontrada" | Volte ao Passo 1 e verifique se a conta Business esta ativa. Tente vincular manualmente em Business Settings > Accounts > Apps | | Erro de permissao ao criar | Verifique se voce e administrador da conta Business | ### Pronto Voce deve ter: - App criado e visivel em `developers.facebook.com/apps` - Um **App ID** (numero tipo `1234567890123456`) - Status do app como **"Em desenvolvimento"** --- ## Passo 3 - Adicionar Produto WhatsApp ### URL ``` https://developers.facebook.com/apps/{SEU_APP_ID}/dashboard/ ``` ### Procedimento 1. No painel do seu app, role a pagina ate a secao **"Adicionar produtos ao seu aplicativo"** 2. Localize o card **"WhatsApp"** e clique em **"Configurar"** 3. Aceite os **Termos de Servico do WhatsApp Business** 4. Selecione a **Conta empresarial** vinculada (a mesma do Passo 1) 5. Clique em **"Continuar"** 6. Voce sera redirecionado para o painel do WhatsApp dentro do seu app ### Erros Comuns | Erro | Solucao | |------|---------| | Card do WhatsApp nao aparece | Verifique se o tipo do app e "Empresa". Se nao for, crie um novo app com o tipo correto | | "Voce nao tem permissao" | Confirme que voce e admin da conta Business vinculada | | Termos de servico nao carregam | Limpe o cache do navegador ou tente em aba anonima | | "WhatsApp Business Account could not be created" | Sua conta Business pode ter restricoes. Verifique notificacoes em `business.facebook.com` | ### Pronto Voce deve ter: - Menu lateral com opcao **"WhatsApp > Configuracao"** (ou "Getting Started") - Uma **WhatsApp Business Account (WABA)** criada automaticamente - Acesso a pagina de Getting Started do WhatsApp --- ## Passo 4 - Obter Phone Number ID e WABA ID ### URL ``` https://developers.facebook.com/apps/{SEU_APP_ID}/whatsapp-business/wa-dev-console/ ``` ### Procedimento 1. No menu lateral do seu app, clique em **"WhatsApp" > "Configuracao da API"** (ou "API Setup") 2. Na secao **"Informacoes do numero de telefone"**, voce encontrara: - **Phone Number ID**: Identificador unico do numero (ex: `109876543210987`) - **WhatsApp Business Account ID (WABA ID)**: Identificador da conta Business do WhatsApp (ex: `102345678901234`) 3. Anote ambos os valores. Voce vai precisar deles para todas as chamadas de API ### Onde encontrar cada ID ``` App Dashboard └── WhatsApp └── Configuracao da API (API Setup) ├── Phone Number ID .... campo "Phone number ID" ou "ID do numero" └── WABA ID ........... campo "WhatsApp Business Account ID" ``` Alternativa para o WABA ID: ``` https://business.facebook.com/settings/whatsapp-business-accounts/ ``` O ID aparece na URL ao clicar na conta ou na coluna de detalhes. ### Erros Comuns | Erro | Solucao | |------|---------| | Phone Number ID nao aparece | Certifique-se de que completou o Passo 3. Tente recarregar a pagina | | WABA ID nao visivel | Acesse via Business Settings > Accounts > WhatsApp Business Accounts | | Valores diferentes em paginas diferentes | Use sempre os IDs que aparecem na pagina de API Setup do seu app | | "No phone numbers" | O numero de teste ainda nao foi provisionado. Aguarde alguns minutos e recarregue | ### Pronto Voce deve ter anotado: - **Phone Number ID**: `___________________________` - **WABA ID**: `___________________________` - **App ID**: `___________________________` (do Passo 2) --- ## Passo 5 - Gerar Token Temporario de Teste ### URL ``` https://developers.facebook.com/apps/{SEU_APP_ID}/whatsapp-business/wa-dev-console/ ``` ### Procedimento 1. Na pagina **"Configuracao da API"** (API Setup), localize a secao **"Token de acesso temporario"** 2. Clique em **"Gerar token de acesso"** (ou o botao ao lado do campo de token) 3. Pode ser solicitado login adicional ou confirmacao 4. O token sera exibido - **copie imediatamente** ### Sobre o Token Temporario ``` IMPORTANTE: - Expira em 24 horas (algumas vezes em 1 hora) - Serve APENAS para testes iniciais - NAO use em producao - Para token permanente, veja o Passo 9 ``` ### Testando o token via cURL ```bash curl -X GET \ "https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}" \ -H "Authorization: Bearer {SEU_TOKEN_TEMPORARIO}" ``` Resposta esperada (resumida): ```json { "id": "109876543210987", "display_phone_number": "+1 555-XXX-XXXX", "verified_name": "Seu Nome de Teste" } ``` ### Erros Comuns | Erro | Solucao | |------|---------| | Token nao aparece apos clicar | Desative pop-up blockers. Tente em outro navegador | | "Error validating access token" | Token expirou. Gere um novo | | "Invalid OAuth access token" | Copie o token novamente, sem espacos extras no inicio/fim | | Botao de gerar desabilitado | Verifique se o produto WhatsApp foi adicionado corretamente (Passo 3) | ### Pronto Voce deve ter: - Um **access token temporario** copiado e salvo em local seguro - Confirmacao via cURL de que o token funciona --- ## Passo 6 - Testar com Numero de Teste (Sandbox) ### URL ``` https://developers.facebook.com/apps/{SEU_APP_ID}/whatsapp-business/wa-dev-console/ ``` ### Procedimento A Meta fornece um **numero de teste** para que voce envie mensagens sem precisar de um numero real. 1. Na pagina de API Setup, localize a secao **"Enviar e receber mensagens"** 2. O campo **"De"** ja deve mostrar o numero de teste da Meta 3. Na secao **"Para"**, clique em **"Gerenciar lista de numeros de telefone"** (ou "Manage phone number list") 4. Clique em **"Adicionar numero de telefone"** 5. Digite o numero do destinatario com codigo do pais (ex: `+5511999998888`) 6. Voce recebera um **codigo de verificacao via WhatsApp** nesse numero 7. Insira o codigo para confirmar 8. Agora envie a mensagem de teste clicando em **"Enviar mensagem"** ### Enviando via cURL ```bash curl -X POST \ "https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/messages" \ -H "Authorization: Bearer {SEU_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "messaging_product": "whatsapp", "to": "5511999998888", "type": "template", "template": { "name": "hello_world", "language": { "code": "en_US" } } }' ``` Resposta esperada: ```json { "messaging_product": "whatsapp", "contacts": [ { "input": "5511999998888", "wa_id": "5511999998888" } ], "messages": [ { "id": "wamid.XXXXXXXXXXXXXXXX" } ] } ``` ### Limitacoes do Sandbox - Maximo de **5 numeros de destinatario** cadastrados - Apenas templates pre-aprovados (como `hello_world`) - Numero remetente e o numero de teste da Meta (nao personalizavel) - Mensagens podem demorar ate 1 minuto para chegar ### Erros Comuns | Erro | Solucao | |------|---------| | `131030` - "User's phone number is part of an experiment" | Numero do destinatario pode ter restricao. Tente outro numero | | `131026` - "Message failed to send" | Verifique se o numero do destinatario tem WhatsApp ativo | | `100` - "Invalid parameter" | Confira o formato do numero: apenas digitos, com codigo do pais, sem `+` no JSON | | `130429` - "Rate limit hit" | Aguarde 1 minuto e tente novamente. Sandbox tem limites rigorosos | | Codigo de verificacao nao chega | O numero destino deve ter WhatsApp instalado e ativo | | Template `hello_world` nao encontrado | Verifique se o idioma esta como `en_US`. Esse template vem pre-instalado | ### Pronto Voce deve ter: - Recebido a mensagem de teste no WhatsApp do destinatario - Um `message_id` (wamid) retornado pela API - Confianca de que a API esta funcionando corretamente --- ## Passo 7 - Adicionar Numero de Telefone Real ### URL ``` https://business.facebook.com/settings/whatsapp-business-accounts/{WABA_ID}/phone-numbers ``` Ou via App Dashboard: ``` https://developers.facebook.com/apps/{SEU_APP_ID}/whatsapp-business/wa-dev-console/ ``` ### Pre-requisito Critico ``` O numero de telefone que voce vai adicionar: - NAO pode estar registrado no WhatsApp pessoal - NAO pode estar registrado no WhatsApp Business App - DEVE ser capaz de receber SMS ou chamada de voz - PODE ser fixo (verificacao por chamada) ou movel (SMS ou chamada) Se o numero esta no WhatsApp pessoal: 1. Abra o WhatsApp no celular 2. Va em Configuracoes > Conta > Excluir conta 3. Confirme a exclusao 4. Aguarde 5 minutos antes de prosseguir ``` ### Procedimento 1. Na pagina de API Setup, clique em **"Adicionar numero de telefone"** (ou va pela URL do Business Settings) 2. Preencha as informacoes do perfil comercial: - **Nome de exibicao**: Nome que aparecera no WhatsApp (ex: `Minha Empresa`) - **Categoria**: Selecione a categoria do seu negocio - **Descricao** (opcional): Breve descricao da empresa 3. Clique em **"Proximo"** 4. Digite o numero com codigo do pais: `+55 11 99999-8888` 5. Selecione o metodo de verificacao (Passo 8) ### Regras do Nome de Exibicao - Deve representar sua empresa de forma clara - Nao pode conter apenas caracteres genericos ("Teste", "Admin") - Nao pode violar marcas registradas - Deve ter entre 3 e 512 caracteres - A Meta pode rejeitar e pedir alteracao ### Erros Comuns | Erro | Solucao | |------|---------| | "Este numero ja esta registrado" | O numero ainda esta no WhatsApp pessoal. Exclua a conta conforme descrito acima e aguarde | | "Numero invalido" | Use formato internacional completo com codigo do pais | | "Nome de exibicao rejeitado" | Use o nome oficial da empresa. Evite abreviacoes excessivas | | "Limite de numeros atingido" | Contas nao verificadas podem ter apenas 2 numeros. Complete o Passo 10 | | Numero fixo nao aceito | Numeros fixos sao aceitos. Selecione "Chamada de voz" como metodo de verificacao | ### Pronto Voce deve ter: - Numero adicionado na lista de telefones da WABA - Proximo passo: verificacao via OTP (Passo 8) --- ## Passo 8 - Verificar Numero via OTP ### Procedimento Continuando diretamente do Passo 7: 1. Selecione o metodo de verificacao: - **Mensagem de texto (SMS)**: Recomendado para numeros moveis - **Chamada de voz**: Necessario para numeros fixos 2. Clique em **"Enviar codigo"** 3. Aguarde receber o codigo de 6 digitos 4. Digite o codigo no campo de verificacao 5. Clique em **"Verificar"** ### Verificacao via API (alternativa) Solicitar codigo: ```bash curl -X POST \ "https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/request_code" \ -H "Authorization: Bearer {SEU_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "code_method": "SMS", "language": "pt_BR" }' ``` Confirmar codigo: ```bash curl -X POST \ "https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/verify_code" \ -H "Authorization: Bearer {SEU_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "code": "123456" }' ``` ### Erros Comuns | Erro | Solucao | |------|---------| | Codigo nao chega por SMS | Tente "Chamada de voz". Verifique se o numero nao bloqueia mensagens de servicos | | "Codigo invalido" | Verifique se digitou corretamente. Codigos expiram em 10 minutos | | "Muitas tentativas" | Aguarde 1 hora antes de tentar novamente. Limite de tentativas por periodo | | Chamada de voz nao chega | Verifique se o numero aceita chamadas de numeros internacionais | | "Phone number verification failed" | Certifique-se de que o numero nao esta em outro WhatsApp Business Account | ### Pronto Voce deve ter: - Numero com status **"Verificado"** (ou "Connected") no painel - Novo **Phone Number ID** para o numero real (diferente do numero de teste) - Capacidade de enviar mensagens usando seu proprio numero --- ## Passo 9 - Criar System User e Token Permanente ### URL ``` https://business.facebook.com/settings/system-users ``` ### Por que System User? O token temporario do Passo 5 expira rapidamente. Para producao, voce precisa de um **token permanente** vinculado a um **System User** (usuario de sistema), que nao depende de um login pessoal. ### Procedimento #### 9.1 - Criar System User 1. Acesse `https://business.facebook.com/settings` 2. No menu lateral, clique em **"Usuarios" > "Usuarios do sistema"** (System Users) 3. Clique em **"Adicionar"** 4. Preencha: - **Nome**: Ex: `whatsapp-api-bot` - **Funcao**: Selecione **"Admin"** (necessario para permissoes completas) 5. Clique em **"Criar usuario do sistema"** #### 9.2 - Atribuir Ativos ao System User 1. Clique no System User criado 2. Clique em **"Atribuir ativos"** (Assign Assets) 3. Selecione **"Apps"** no menu lateral 4. Encontre seu app (criado no Passo 2) e selecione-o 5. Ative **"Controle total"** (Full Control) 6. Clique em **"Salvar alteracoes"** 7. Repita para **"Contas do WhatsApp"**: - Selecione sua WABA - Ative **"Controle total"** - Salve #### 9.3 - Gerar Token Permanente 1. Na pagina do System User, clique em **"Gerar novo token"** 2. Selecione o **App** (criado no Passo 2) 3. Em **"Permissoes disponíveis"**, marque: - `whatsapp_business_messaging` - Para enviar e receber mensagens - `whatsapp_business_management` - Para gerenciar conta, templates e configuracoes 4. Clique em **"Gerar token"** 5. **COPIE O TOKEN IMEDIATAMENTE** - Ele so sera exibido uma vez 6. Armazene em local seguro (gerenciador de senhas, variavel de ambiente, vault) ### Seguranca do Token ``` ATENCAO: - O token NUNCA deve ser commitado em repositorios Git - Use variaveis de ambiente (.env) ou servicos de secrets - Rotacione o token periodicamente - Se o token for comprometido, revogue imediatamente em Business Settings ``` ### Testando o Token Permanente ```bash curl -X GET \ "https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}" \ -H "Authorization: Bearer {TOKEN_PERMANENTE}" ``` ### Erros Comuns | Erro | Solucao | |------|---------| | "Usuarios do sistema" nao aparece no menu | Voce precisa ser Admin da conta Business. Verifique suas permissoes | | Permissoes `whatsapp_*` nao aparecem na lista | O produto WhatsApp nao foi adicionado ao app (volte ao Passo 3) | | "Insufficient permissions" ao usar o token | Verifique se os ativos (App + WABA) foram atribuidos corretamente ao System User | | Token nao funciona apos gerar | Aguarde 1-2 minutos para propagacao. Tente novamente | | "User does not have permission" | Confira se o System User tem funcao "Admin" e controle total nos ativos | ### Pronto Voce deve ter: - System User criado com nome descritivo - Ativos (App + WABA) atribuidos com controle total - **Token permanente** copiado e armazenado com seguranca - Token validado via chamada de API --- ## Passo 10 - Verificacao de Negocio ### URL ``` https://business.facebook.com/settings/security ``` ### Por que Verificar? Sem verificacao de negocio: - Limite de **250 conversas iniciadas por empresa** em periodo de 24h - Nao pode solicitar aumento de limites - Algumas funcionalidades ficam restritas Com verificacao: - Limites podem ser aumentados ate **ilimitado** (progressivamente) - Acesso a funcionalidades avancadas - Maior confiabilidade perante a Meta ### Procedimento 1. Acesse `https://business.facebook.com/settings` 2. No menu lateral, clique em **"Central de seguranca"** (Security Center) 3. Localize a secao **"Verificacao de negocio"** e clique em **"Comecar verificacao"** 4. Preencha os dados da empresa: - **Nome legal da empresa**: Conforme consta no CNPJ - **Endereco**: Endereco oficial da empresa - **Telefone da empresa**: Numero comercial - **Site**: URL do site da empresa - **CNPJ**: Numero do cadastro nacional 5. Faca upload dos **documentos comprobatorios** (pelo menos um): - Cartao CNPJ - Conta de utilidade (luz, agua) no nome da empresa - Extrato bancario com nome e endereco da empresa - Alvara de funcionamento - Contrato social 6. Selecione o **metodo de verificacao de contato**: - Email do dominio da empresa (mais rapido) - Telefone da empresa - Documento adicional 7. Clique em **"Enviar"** ### Dicas para Aprovacao Rapida - Use email com dominio da empresa (ex: `admin@suaempresa.com.br`) em vez de Gmail/Hotmail - Certifique-se de que o nome da empresa no cadastro Meta corresponde EXATAMENTE ao nome nos documentos - O site da empresa deve estar ativo e acessivel - Documentos devem ser legíveis e em formato PDF ou imagem - Documentos devem ter menos de 90 dias de emissao (para contas e extratos) ### Prazos | Cenario | Prazo Estimado | |---------|---------------| | Documentacao correta + email corporativo | 1-3 dias uteis | | Documentacao correta + verificacao por telefone | 3-5 dias uteis | | Documentacao incompleta / rejeicao + reenvio | 5-14 dias uteis | ### Erros Comuns | Erro | Solucao | |------|---------| | "Documentos rejeitados" | Verifique se o nome no documento corresponde ao nome cadastrado. Envie documentos mais recentes | | "Nao foi possivel verificar" | Tente outro tipo de documento. Adicione mais de um documento | | Verificacao travada ha mais de 7 dias | Abra um ticket de suporte em `business.facebook.com/help` | | "Dominio nao verificado" | Adicione o registro TXT de verificacao no DNS do seu dominio | | Email de verificacao nao chega | Verifique spam. Tente o metodo por telefone | ### Pronto Voce deve ter: - Status de verificacao como **"Verificado"** (badge verde) no Security Center - Acesso a limites de mensagens progressivos - Possibilidade de escalar para 1K, 10K, 100K e ilimitado --- ## Niveis de Limite de Mensagens (Pos-Verificacao) | Nivel | Conversas Iniciadas (24h) | Como Alcancar | |-------|---------------------------|---------------| | Nao verificado | 250 | Padrao inicial | | Nivel 1 | 1.000 | Verificacao de negocio completa | | Nivel 2 | 10.000 | Enviar 2x o limite atual em 7 dias com qualidade boa | | Nivel 3 | 100.000 | Manter qualidade e volume | | Nivel 4 | Ilimitado | Manter qualidade consistente | --- ## Checklist Pos-Setup Apos completar todos os 10 passos, voce deve ter os seguintes valores. Preencha e armazene em um arquivo `.env`: ```bash # =================================== # WhatsApp Cloud API - Variaveis de Ambiente # =================================== # Passo 1 - Meta Business Suite META_BUSINESS_ID= # ID da conta Business (15 digitos) # Passo 2 - App no Meta for Developers META_APP_ID= # ID do aplicativo META_APP_SECRET= # Segredo do app (em App Settings > Basic) # Passo 4 - IDs do WhatsApp WHATSAPP_PHONE_NUMBER_ID= # Phone Number ID (do numero real, nao do teste) WHATSAPP_WABA_ID= # WhatsApp Business Account ID # Passo 9 - Token Permanente WHATSAPP_API_TOKEN= # Token do System User (permanente) # Configuracoes da API WHATSAPP_API_VERSION=v21.0 WHATSAPP_API_URL=https://graph.facebook.com # Webhook (configurar separadamente) WEBHOOK_VERIFY_TOKEN= # Token que VOCE define para validar o webhook WEBHOOK_URL= # URL publica do seu servidor (HTTPS obrigatorio) ``` ### Validacao Final Execute este comando para validar que tudo esta funcionando: ```bash # Substitua as variaveis pelos seus valores reais curl -X POST \ "https://graph.facebook.com/v21.0/${WHATSAPP_PHONE_NUMBER_ID}/messages" \ -H "Authorization: Bearer ${WHATSAPP_API_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "messaging_product": "whatsapp", "to": "NUMERO_DESTINATARIO", "type": "template", "template": { "name": "hello_world", "language": { "code": "en_US" } } }' ``` Se voce receber um JSON com `"messages": [{"id": "wamid.XXXX"}]`, seu setup esta completo. --- ## Links Uteis | Recurso | URL | |---------|-----| | Documentacao oficial | `https://developers.facebook.com/docs/whatsapp/cloud-api` | | Referencia da API | `https://developers.facebook.com/docs/whatsapp/cloud-api/reference` | | Status da plataforma | `https://metastatus.com` | | Suporte Business | `https://business.facebook.com/help` | | Comunidade de desenvolvedores | `https://developers.facebook.com/community` | | Changelog da API | `https://developers.facebook.com/docs/whatsapp/cloud-api/changelog` | | Guia de templates | `https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates` | | Guia de webhooks | `https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks` | --- > **Proximo passo**: Configure os webhooks para receber mensagens. Consulte o guia de webhooks na documentacao do projeto.