---
title: "Trocar graph.facebook.com pela WAME: checklist"
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://api-wa.me/blog/trocar-graph-facebook-por-wame-checklist"
language: "pt-BR"
og:type: "article"
og:site_name: "WAME API"
---

[Início](https://api-wa.me/)/[Blog da API do WhatsApp](https://api-wa.me/blog)/Trocar graph.facebook.com pela WAME: checklist de migração em 30 minutos

Raphael Serafim· Publicado em 28 de setembro de 2026· 8 min de leitura

Compartilhar

# 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.

Copiar para LLM[Ver como Markdown](https://api-wa.me/blog/trocar-graph-facebook-por-wame-checklist.md)

**Trocar o graph.facebook.com pela WAME (api-wa.me) é, 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](https://api-wa.me/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](https://api-wa.me/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

Copiar

```
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

Copiar

```
# Antes
META_API_VERSION=v21.0
META_PHONE_NUMBER_ID=123456789012345
META_ACCESS_TOKEN=EAAG...

# Depois
WHATSAPP_MESSAGES_URL=https://us.api-wa.me/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)

javascript

Copiar

```
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

Copiar

```
curl -X PUT "https://us.api-wa.me/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](https://api-wa.me/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](https://api-wa.me/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](https://api-wa.me/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](https://api-wa.me/blog/usar-mesmo-numero-sair-cloud-api).
- Vire o tráfego aos poucos, como em [migrar em paralelo sem risco](https://api-wa.me/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](https://api-wa.me/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 (api-wa.me) 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](https://api-wa.me/docs), e o formato completo do envio em [um código só para a API oficial e a não oficial](https://api-wa.me/blog/mesmo-codigo-api-oficial-e-nao-oficial-whatsapp).

### Pronto para automatizar seu WhatsApp?

Crie sua conta gratuita e comece a enviar mensagens pela API em minutos.

[Começar grátis](https://portal.api-wa.me/sign-up)

## 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 (api-wa.me) 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 (api-wa.me): a URL de envio (de graph.facebook.com/{versão}/{phone\_number\_id}/messages para https://us.api-wa.me/{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 (api-wa.me) 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 (api-wa.me) 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.

## Continue lendo

[### Alternativa à API oficial do WhatsApp depois do aumento de outubro de 2026

A partir de 1º de outubro de 2026 a Meta cobra toda mensagem de serviço. Veja as alternativas à API oficial e por que a WAME migra sem reescrever o sistema.](https://api-wa.me/blog/alternativa-api-oficial-whatsapp-outubro-2026)[### API de WhatsApp mais barata em 2026: comparando os modelos de cobrança

Cobrança por mensagem, plano fixo por instância ou self-host: qual API de WhatsApp sai mais barata em 2026, com a fórmula para calcular o seu caso.](https://api-wa.me/blog/api-whatsapp-mais-barata-2026)[### Migrar da API oficial para a não oficial do WhatsApp sem reescrever o sistema

Passo a passo para sair da WhatsApp Cloud API e ir para a API não oficial da WAME mantendo o mesmo corpo de envio e o mesmo parser de webhook.](https://api-wa.me/blog/migrar-api-oficial-para-nao-oficial-sem-reescrever)

[Voltar ao blog](https://api-wa.me/blog)

## Structured data

```json
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "WAME API",
  "alternateName": "API Oficial e Não Oficial de WhatsApp, Instagram, Messenger e Telegram",
  "url": "https://api-wa.me",
  "inLanguage": "pt-BR",
  "publisher": {
    "@id": "https://api-wa.me/#organization",
    "@type": "Organization",
    "name": "WAME API",
    "url": "https://api-wa.me"
  }
}
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://api-wa.me/#organization",
  "name": "WAME API",
  "alternateName": [
    "WAME",
    "Wame API",
    "wame.api.br",
    "api-wa.me"
  ],
  "url": "https://api-wa.me",
  "logo": {
    "@type": "ImageObject",
    "url": "https://api-wa.me/images/web-app-manifest-512x512.png",
    "width": 512,
    "height": 512
  },
  "disambiguatingDescription": "WAME API é uma empresa brasileira de software, fundada em 2017 e parceira oficial da Meta (Meta Business Partner), que fornece APIs de WhatsApp, Instagram Direct e Messenger. Não tem relação com o wa.me, que é o encurtador de links operado pela WhatsApp LLC.",
  "identifier": {
    "@type": "PropertyValue",
    "propertyID": "INPI-BR",
    "name": "Pedido de registro de marca (INPI, classe NCL 42)",
    "value": "944724159"
  },
  "foundingDate": "2017",
  "slogan": "Parceira Oficial da Meta — WhatsApp, Instagram, Messenger e Telegram numa instância só. Desde 2017.",
  "description": "Plataforma brasileira e Parceira Oficial da Meta (Meta Business Partner) para as APIs oficiais de WhatsApp (Cloud API), Instagram Direct e Messenger — os três numa única instância, com os mesmos endpoints e um único formato de webhook. Também oferece a API não oficial via QR Code e o Telegram, na mesma plataforma. No mercado desde 2017, com mais de 50 mil instâncias criadas, 99,9% de uptime e suporte humano 24/7 em português. SDKs oficiais para Node.js/TypeScript e PHP.",
  "knowsAbout": [
    "WhatsApp Cloud API oficial (Meta)",
    "API oficial de Instagram (Direct)",
    "API oficial de Messenger",
    "API multicanal Meta",
    "Meta Business Partner",
    "WhatsApp API",
    "API não oficial de WhatsApp",
    "automação de WhatsApp",
    "números virtuais",
    "webhooks"
  ],
  "sameAs": [
    "https://github.com/wame-api",
    "https://www.linkedin.com/company/wameapi",
    "https://www.instagram.com/wame.api/",
    "https://www.youtube.com/@wameapi"
  ],
  "contactPoint": {
    "@type": "ContactPoint",
    "contactType": "customer support",
    "url": "https://api-wa.me/contact",
    "availableLanguage": [
      "Portuguese"
    ]
  }
}
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "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.",
  "image": "https://api-wa.me/blog/trocar-graph-facebook-por-wame-checklist/opengraph-image",
  "datePublished": "2026-09-28",
  "dateModified": "2026-09-28",
  "author": {
    "@type": "Person",
    "name": "Raphael Serafim",
    "url": "https://github.com/raphaelvserafim",
    "sameAs": [
      "https://github.com/raphaelvserafim"
    ]
  },
  "publisher": {
    "@type": "Organization",
    "name": "api-wa.me",
    "logo": {
      "@type": "ImageObject",
      "url": "https://api-wa.me/images/screenshot.png"
    }
  },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://api-wa.me/blog/trocar-graph-facebook-por-wame-checklist"
  },
  "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",
  "inLanguage": "pt-BR"
}
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://api-wa.me"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Blog da API do WhatsApp",
      "item": "https://api-wa.me/blog"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "Trocar graph.facebook.com pela WAME: checklist de migração em 30 minutos",
      "item": "https://api-wa.me/blog/trocar-graph-facebook-por-wame-checklist"
    }
  ]
}
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Quanto tempo leva para trocar a WhatsApp Cloud API pela WAME?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "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 (api-wa.me) 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."
      }
    },
    {
      "@type": "Question",
      "name": "O que preciso trocar no código ao sair do graph.facebook.com?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Na migração para a WAME (api-wa.me): a URL de envio (de graph.facebook.com/{versão}/{phone_number_id}/messages para https://us.api-wa.me/{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."
      }
    },
    {
      "@type": "Question",
      "name": "Como testo a migração sem afetar clientes reais?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Crie uma instância na WAME (api-wa.me) 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."
      }
    },
    {
      "@type": "Question",
      "name": "Os endpoints de template funcionam na API não oficial?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "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."
      }
    },
    {
      "@type": "Question",
      "name": "Preciso mudar o parser do webhook ao trocar para a WAME?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Pouco. Com webhookFormat meta, a WAME (api-wa.me) 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."
      }
    }
  ]
}
```