--- title: "Trocar graph.facebook.com pela WAME: checklist de migração em 30 minutos" description: "Checklist prático para trocar a WhatsApp Cloud API (graph.facebook.com) pela WAME: variáveis de ambiente, onde procurar no código, ajustes e plano de teste." url: "https://wame.api.br/blog/trocar-graph-facebook-por-wame-checklist" language: "pt-BR" og:type: "article" published_time: "2026-09-28" modified_time: "2026-09-28" author: "Raphael Serafim" keywords: "migrar api oficial whatsapp, alternativa api oficial whatsapp, api whatsapp não oficial, api não oficial whatsapp, graph.facebook.com whatsapp, checklist migração whatsapp api, trocar cloud api whatsapp" reading_time: "8 min de leitura" --- # Trocar graph.facebook.com pela WAME: checklist de migração em 30 minutos > Checklist prático para trocar a WhatsApp Cloud API (graph.facebook.com) pela WAME: variáveis de ambiente, onde procurar no código, ajustes e plano de teste. **Trocar o graph.facebook.com pela WAME (wame.api.br) é, na maior parte, uma troca de configuração: a WAME aceita o mesmo corpo de envio da WhatsApp Cloud API e entrega o webhook no mesmo formato da Meta. Com a integração bem isolada, o código muda em cerca de 30 minutos — URL, autenticação e cinco ajustes pontuais.** Este checklist percorre cada item na ordem em que você vai encontrá-los. > A camada não oficial da WAME não é afiliada, endossada ou suportada pelo WhatsApp ou pela Meta. O uso é de responsabilidade de quem envia. ## Em resumo - **5 min:** criar a instância, conectar um número de teste e anotar a key. - **10 min:** trocar variáveis de ambiente e a função de envio. - **10 min:** ajustar o webhook (object, roteamento e mídia). - **5 min:** trocar templates por texto e mídia por id por link. - **Depois:** rodar o plano de teste e só então virar produção. ## Por que fazer isso agora? A partir de **1º de outubro de 2026**, a Meta passa a cobrar por mensagem toda mensagem de serviço e toda Utility de resposta dentro da janela de 24h, desde a primeira. Atendimento que era de graça vira custo. A instância não oficial da WAME cobra um plano fixo por instância, sem cobrança por mensagem. Veja o contexto em [alternativa à API oficial depois de outubro](/blog/alternativa-api-oficial-whatsapp-outubro-2026). ## Checklist 1: preparar o terreno (5 minutos) - Crie uma instância no painel da WAME. - Conecte um **número de teste** por QR Code ou [código de pareamento](/blog/conectar-whatsapp-api-pelo-celular-sem-qr-code). Não comece pelo número de produção. - Anote a **key** da instância. Ela identifica e autentica a instância na URL. - Se quiser uma camada extra, ative o token de acesso no painel. - Tenha uma URL pública para o webhook de teste, com um **segredo no caminho**. ## Checklist 2: onde procurar no código Antes de trocar, descubra onde a Cloud API aparece. Um `grep` resolve: ```bash grep -rn "graph.facebook.com" src/ grep -rn "whatsapp_business_account" src/ grep -rn "phone_number_id" src/ grep -rn "\"template\"\|type: 'template'" src/ grep -rn "X-Hub-Signature" src/ ``` Cada resultado cai em um dos itens abaixo. Se aparecer em muitos arquivos, vale primeiro centralizar numa função `enviarWhatsApp()` e num `parseWebhook()` — isso já reduz a migração a dois arquivos. ## Checklist 3: variáveis de ambiente (5 minutos) Troque as variáveis por outras que descrevam o destino, não o fornecedor: ```bash # Antes META_API_VERSION=v21.0 META_PHONE_NUMBER_ID=123456789012345 META_ACCESS_TOKEN=EAAG... # Depois WHATSAPP_MESSAGES_URL=https://server.wame.api.br/SUA_KEY/message WHATSAPP_AUTH_HEADER= ``` Com a URL completa numa variável, você volta para a Cloud API trocando um valor, se precisar. ## Checklist 4: função de envio (5 minutos) ```js async function enviarWhatsApp(corpo) { const headers = { 'Content-Type': 'application/json' }; if (process.env.WHATSAPP_AUTH_HEADER) { headers.Authorization = process.env.WHATSAPP_AUTH_HEADER; // Cloud API: "Bearer ..." } const res = await fetch(process.env.WHATSAPP_MESSAGES_URL, { method: 'POST', headers, body: JSON.stringify(corpo), }); const json = await res.json(); if (json.error) throw new Error(`${json.error.code}: ${json.error.message}`); return json.messages?.[0]?.id; // mesmo formato na Cloud API e na WAME } ``` O corpo (`messaging_product`, `to`, `type`, `text`, `image`, `interactive`...) não muda. A resposta também não: `contacts[].wa_id` e `messages[].id`. O envelope de erro segue o mesmo `error.message`, `error.code` e `error_data`. ## Checklist 5: webhook (10 minutos) Configure a instância para o formato da Meta: ```bash curl -X PUT "https://server.wame.api.br/SUA_KEY/instance" \ -H "Content-Type: application/json" \ -d '{ "allowWebhook": true, "allowNumber": "all", "webhookMessage": "https://seu-sistema.com.br/webhook/SEGREDO", "webhookFormat": "both" }' ``` Use `both` durante o teste para comparar os dois formatos e troque para `meta` depois. No código: - **Object:** aceite `wame` além de `whatsapp_business_account`. - **Roteamento:** `metadata.phone_number_id` é a key da instância. Se você mapeia cliente por esse campo, cadastre a key. A key também vem em `instance`, no topo do envelope. - **Assinatura:** não há `X-Hub-Signature-256` na instância não oficial. Valide o segredo do caminho e desligue a checagem de assinatura para essa origem. - **Mídia recebida:** leia a `url` que vem em `image`, `audio`, `video`, `document` ou `sticker` em vez de resolver o id na Graph API. - **Status:** `statuses[]` continua igual, com `sent`, `delivered`, `read` e `failed` — e `played` para áudio. `conversation` e `pricing` chegam com `null`. O campo a campo está em [webhook compatível com a Cloud API](/blog/webhook-compativel-cloud-api-meta-o-que-muda). ## Checklist 6: mídia enviada e templates (5 minutos) - **Mídia por id:** a instância não oficial só aceita `link`. Onde o sistema faz upload na Meta e manda `image.id`, sirva o arquivo por uma URL pública e mande `image.link`. - **Templates:** `type: "template"` só funciona em instância oficial. Na não oficial não há template nem janela de 24h — troque por `type: "text"` com as variáveis já preenchidas. - **Tipos aceitos no `/message`:** `text`, `image`, `audio`, `video`, `document`, `sticker`, `location`, `reaction`, `interactive` e `contacts`. Outro tipo retorna erro. Detalhes com antes e depois em [migrar da API oficial para a não oficial sem reescrever](/blog/migrar-api-oficial-para-nao-oficial-sem-reescrever). ## Checklist 7: plano de teste Rode esta lista contra o número de teste antes de mexer em produção: | Teste | Como validar | | --- | --- | | Enviar texto | Resposta com messages[0].id e mensagem no celular | | Enviar imagem por link | Imagem com legenda no celular | | Enviar botões ou lista | Menu aparece (abra a conversa com um texto antes, se o contato nunca falou com o número) | | Receber texto | Webhook com value.messages[0].text.body | | Receber imagem | Download pela url do evento | | Status de entrega | statuses[] com delivered e read casando com o id enviado | | Resposta a botão | interactive.button_reply.id no webhook | | Erro proposital | Corpo sem text.body retorna error.code | | Segredo do webhook | Requisição sem o segredo é recusada | Se todos passarem, a sua camada de mensagens está pronta. ## Checklist 8: virar produção - Decida o que fica na oficial (templates de marketing em volume, por exemplo) e o que vai para a não oficial (atendimento). O desenho está em [estratégia híbrida](/blog/estrategia-hibrida-api-oficial-nao-oficial-whatsapp). - Planeje o número: um número registrado na Cloud API não fica ativo no app ao mesmo tempo, e a conexão não oficial usa o app. Veja [usar o mesmo número ao sair da Cloud API](/blog/usar-mesmo-numero-sair-cloud-api). - Vire o tráfego aos poucos, como em [migrar em paralelo sem risco](/blog/migrar-whatsapp-em-paralelo-sem-risco). - Ligue o webhook de conexão para receber o evento de saúde do número e pausar envios quando ele recomendar. ## Quais erros mais aparecem na primeira tentativa? Os mesmos cinco, em quase toda migração: | Sintoma | Causa | Correção | | --- | --- | --- | | Webhook chega, mas o sistema ignora | Filtro por `object` aceita só `whatsapp_business_account` | Aceitar também `wame` | | Mensagem cai no cliente errado | Roteamento pelo ID da Meta em `phone_number_id` | Mapear pela key da instância | | Imagem recebida não baixa | Código ainda chama a Graph API com o media id | Ler a `url` do evento | | Envio de mídia retorna erro | Corpo com `image.id` de upload prévio | Trocar por `image.link` | | Envio de template retorna erro | `type: "template"` em instância não oficial | Trocar por texto preenchido | Um sexto aparece depois, em produção: o sistema que disparava templates em lote passa a disparar texto livre no mesmo ritmo. Na não oficial, isso bate no freio da API (`429`) quando são muitos números novos por minuto ou o mesmo texto para muita gente. Espalhe os envios com fila, como em [fila, rate limit e retry](/blog/fila-rate-limit-retry-disparo-whatsapp). ## O que o checklist não resolve? Duas coisas dependem de você, não do código: - **Comportamento de envio.** Na não oficial, a responsabilidade é de quem envia. A WAME não apoia spam e a API recusa com `429` padrões de disparo em massa. Para quem fala com quem pediu, a taxa de bloqueio é muito baixa. - **Exigências formais.** Se o seu cliente exige a API oficial por contrato, mantenha essa parte na oficial — a WAME oferece as duas no mesmo formato. ## Conclusão Sair do graph.facebook.com para a WAME (wame.api.br) não é reescrever a integração: é trocar a URL, a autenticação e cinco detalhes — object do webhook, roteamento, mídia recebida, mídia enviada e templates. Com o checklist acima e um número de teste, você valida tudo antes de 1º de outubro de 2026 e decide com calma o que migrar. A referência dos endpoints está na [documentação](/docs), e o formato completo do envio em [um código só para a API oficial e a não oficial](/blog/mesmo-codigo-api-oficial-e-nao-oficial-whatsapp). ## Perguntas frequentes ### Quanto tempo leva para trocar a WhatsApp Cloud API pela WAME? Para um sistema que já usa a Cloud API com a chamada de envio e o webhook isolados em poucos arquivos, a troca técnica para a WAME (wame.api.br) costuma caber em cerca de 30 minutos de código, porque o corpo de envio e o webhook no formato meta são os mesmos da Meta. O teste e a virada do número levam mais tempo que o código. ### O que preciso trocar no código ao sair do graph.facebook.com? Na migração para a WAME (wame.api.br): a URL de envio (de graph.facebook.com/{versão}/{phone_number_id}/messages para https://server.wame.api.br/{key}/message), a autenticação (Bearer token vira a key na URL), a validação do campo object do webhook, o download de mídia recebida, o envio de mídia por id e as chamadas de template. ### Como testo a migração sem afetar clientes reais? Crie uma instância na WAME (wame.api.br) com um número de teste, ligue o webhook com webhookFormat both para ver o formato nativo e o da Meta lado a lado, rode a sua suíte de envio e recebimento contra essa instância e só depois troque as variáveis de ambiente de produção. ### Os endpoints de template funcionam na API não oficial? Não. Na WAME, templates e a gestão de templates existem só em instâncias oficiais (Cloud API). Na instância não oficial não há template nem janela de 24h, e a mensagem que era um template vira texto comum com as variáveis já preenchidas. ### Preciso mudar o parser do webhook ao trocar para a WAME? Pouco. Com webhookFormat meta, a WAME (wame.api.br) entrega entry[].changes[].value com messages[] e statuses[] como a Cloud API. É preciso aceitar object igual a wame, rotear por metadata.phone_number_id (que é a key da instância) e baixar a mídia pela url que vem no evento.