---
title: "Migrar da API oficial para a não oficial sem reescrever"
description: "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."
url: "https://api-wa.me/blog/migrar-api-oficial-para-nao-oficial-sem-reescrever"
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)/Migrar da API oficial para a não oficial do WhatsApp sem reescrever o sistema

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

Compartilhar

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

Copiar para LLM[Ver como Markdown](https://api-wa.me/blog/migrar-api-oficial-para-nao-oficial-sem-reescrever.md)

**Migrar da API oficial para a não oficial do WhatsApp sem reescrever o sistema é possível quando a API de destino fala o mesmo formato da Cloud API. Na WAME (api-wa.me), o envio aceita o mesmo corpo JSON, a resposta vem no mesmo envelope e o webhook sai no padrão da Meta — então a migração é trocar URL e autenticação e ajustar três pontos: mídia enviada, mídia recebida e templates.** Este guia mostra cada passo com o código de antes e de depois.

> 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

- **Não muda:** corpo de envio, envelope de resposta, envelope de erro, estrutura do webhook, `messages[]`, `statuses[]`, `context`, `interactive`.
- **Muda:** URL base, autenticação, `object` do webhook, mídia enviada (só `link`), mídia recebida (baixar pela `url` da WAME) e templates (viram texto livre).
- **Tempo típico:** uma tarde para o código, mais o planejamento do número.

## Por que migrar agora?

Porque a partir de **1º de outubro de 2026** a Meta passa a cobrar toda mensagem de serviço e toda Utility de resposta dentro da janela de 24h, desde a primeira, sem faixa mensal grátis. Para quem atende muito, cada resposta vira custo. O contexto completo está em [WhatsApp API mais cara em outubro de 2026](https://api-wa.me/blog/mudanca-cobranca-whatsapp-api-outubro-2026) e as alternativas em [alternativa à API oficial depois de outubro](https://api-wa.me/blog/alternativa-api-oficial-whatsapp-outubro-2026).

A API não oficial da WAME cobra por instância, não por mensagem. E, como fala o formato da Meta, o custo de trocar é baixo.

## Passo 1: o que muda no envio?

Só a URL e a autenticação. O corpo é o mesmo.

**Antes (Cloud API):**

javascript

Copiar

```
const res = await fetch(
  `https://graph.facebook.com/v21.0/${PHONE_NUMBER_ID}/messages`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${META_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to: '5511999999999',
      type: 'text',
      text: { body: 'Seu pedido saiu para entrega.' },
    }),
  }
);
```

**Depois (WAME):**

javascript

Copiar

```
const res = await fetch(
  `https://us.api-wa.me/${WAME_KEY}/message`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to: '5511999999999',
      type: 'text',
      text: { body: 'Seu pedido saiu para entrega.' },
    }),
  }
);
```

A key da instância vai na URL e já autentica a chamada. Se você quiser uma camada extra, dá para exigir um token de acesso, ativado no painel da instância.

A dica para fazer isso sem espalhar mudança pelo código é isolar a URL numa variável de ambiente:

javascript

Copiar

```
// Antes: https://graph.facebook.com/v21.0/PHONE_NUMBER_ID/messages
// Depois: https://us.api-wa.me/SUA_KEY/message
const MESSAGES_URL = process.env.WHATSAPP_MESSAGES_URL;
```

## Passo 2: a resposta muda?

Não. O sucesso vem no mesmo formato da Cloud API:

json

Copiar

```
{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "5511999999999", "wa_id": "5511999999999" }],
  "messages": [{ "id": "3EB0C767D26A1D8E4B2A" }]
}
```

E o erro também:

json

Copiar

```
{
  "error": {
    "message": "\"text.body\" is required",
    "type": "invalid_request",
    "code": 100,
    "error_data": { "messaging_product": "whatsapp", "details": "\"text.body\" is required" }
  }
}
```

Quem guarda `messages[0].id` para casar com os status do webhook continua fazendo exatamente o mesmo.

## Passo 3: o parser de webhook precisa mudar?

Quase nada. Primeiro, configure a instância para entregar no 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": "meta"
  }'
```

O parser que você já tem continua lendo `entry[0].changes[0].value.messages` e `value.statuses`. A única diferença estrutural é o campo `object`, que vem como `wame` em vez de `whatsapp_business_account`:

javascript

Copiar

```
// Antes
if (body.object !== 'whatsapp_business_account') return;

// Depois (aceita as duas origens)
if (!['whatsapp_business_account', 'wame'].includes(body.object)) return;
```

O `metadata.phone_number_id` traz a key da instância — se você roteia por esse campo para descobrir de qual cliente é a mensagem, basta mapear a key no lugar do phone number id. O campo a campo completo está em [webhook compatível com a Cloud API](https://api-wa.me/blog/webhook-compativel-cloud-api-meta-o-que-muda).

Um cuidado de segurança: o webhook da Cloud API vem assinado com `X-Hub-Signature-256`; o da instância não oficial, não. Proteja a URL com um segredo no caminho, como no exemplo acima, e não deixe o endpoint aceitar qualquer origem. Veja [segurança da API: token e webhook](https://api-wa.me/blog/seguranca-api-whatsapp-token-webhook).

## Passo 4: como fica a mídia enviada?

Na Cloud API, dá para enviar mídia por `link` ou por `id` de um upload prévio. Na instância não oficial, só por `link`:

javascript

Copiar

```
// Continua funcionando
{ type: 'image', image: { link: 'https://cdn.seusite.com/nota.jpg', caption: 'Sua nota' } }

// Não funciona na não oficial: troque o upload por uma URL pública
{ type: 'image', image: { id: '1234567890' } }
```

Se o seu sistema sobe o arquivo para a Meta e guarda o id, a troca é servir o arquivo por uma URL (seu storage, S3, CDN) e mandar o `link`.

## Passo 5: como fica a mídia recebida?

Na Cloud API, o webhook traz só o `id` da mídia, e você consulta a Graph API para obter a URL e depois baixa. Na WAME, o webhook já traz a URL de download:

json

Copiar

```
{
  "type": "image",
  "image": {
    "id": "3EB0A1B2C3D4",
    "url": "https://us.api-wa.me/SUA_KEY/message/3EB0A1B2C3D4/media",
    "mime_type": "image/jpeg",
    "caption": "comprovante"
  }
}
```

A mudança no código é trocar a função que resolvia o media id pela leitura direta de `image.url`. Detalhes de tamanho e formatos em [mídia no webhook do WhatsApp](https://api-wa.me/blog/midia-webhook-whatsapp-baixar-limites).

## Passo 6: o que fazer com os templates?

Na API não oficial não existe template nem janela de 24h. Qualquer mensagem pode ser texto livre, a qualquer hora. Na migração, a chamada de template vira uma mensagem comum:

javascript

Copiar

```
// Antes: template aprovado com variáveis
{
  type: 'template',
  template: {
    name: 'pedido_enviado',
    language: { code: 'pt_BR' },
    components: [{ type: 'body', parameters: [{ type: 'text', text: 'Carla' }] }],
  },
}

// Depois: texto com as variáveis já preenchidas
{ type: 'text', text: { body: 'Oi, Carla! Seu pedido saiu para entrega.' } }
```

Liberdade traz responsabilidade: sem template, o filtro contra mensagem indesejada passa a ser você. Mande só para quem pediu. A diferença está explicada em [API sem template e sem janela de 24h](https://api-wa.me/blog/api-whatsapp-sem-template-texto-livre).

## O que é idêntico e o que muda: tabela de referência

| Item | Cloud API | WAME não oficial |
| --- | --- | --- |
| URL de envio | `graph.facebook.com/{versão}/{phone_number_id}/messages` | `us.api-wa.me/{key}/message` |
| Autenticação | Bearer token | Key na URL (token opcional) |
| Corpo de envio | messaging\_product, to, type... | Igual |
| Resposta de sucesso | contacts\[\].wa\_id, messages\[\].id | Igual |
| Envelope de erro | error.message, code, error\_data | Igual |
| Webhook object | whatsapp\_business\_account | wame |
| messages\[\] e statuses\[\] | Formato Meta | Igual |
| Mídia enviada | link ou id | Só link |
| Mídia recebida | id → consulta na Graph | id + url de download |
| Templates | Obrigatórios fora da janela | Não existem (texto livre) |
| Assinatura do webhook | X-Hub-Signature-256 | Segredo na URL |
| Grupos, status, ligações | Não da mesma forma | Disponíveis |

## E o número?

Esse é o ponto que exige planejamento. Um número registrado na Cloud API não fica ativo no app do WhatsApp ao mesmo tempo, e a conexão não oficial usa o número como aparelho vinculado do app. Para usar o mesmo número, ele precisa sair da Cloud API e voltar para o app — templates e o histórico de qualidade da Cloud API não vão junto. Em instâncias oficiais da WAME, a saída é feita pelo endpoint de descadastro (`POST /{key}/instance/official/deregister`).

Muita gente prefere não mexer no número principal no primeiro momento: conecta um número novo pela não oficial, move o atendimento aos poucos e compara. O roteiro está em [migrar em paralelo sem risco](https://api-wa.me/blog/migrar-whatsapp-em-paralelo-sem-risco) e o passo a passo do número em [usar o mesmo número ao sair da Cloud API](https://api-wa.me/blog/usar-mesmo-numero-sair-cloud-api).

## Conclusão

Migrar da API oficial para a não oficial costumava significar reescrever envio, webhook e tratamento de status. Na WAME (api-wa.me), significa trocar a URL, trocar a autenticação e ajustar mídia e templates — o resto do sistema continua falando o formato da Cloud API. Com a cobrança por mensagem de serviço a partir de 1º de outubro de 2026, essa troca deixou de ser detalhe técnico e virou decisão de custo. Faça num ambiente de teste, rode em paralelo e só então vire o tráfego. Os endpoints estão na [documentação](https://api-wa.me/docs), e o roteiro rápido em [checklist para trocar graph.facebook.com pela WAME](https://api-wa.me/blog/trocar-graph-facebook-por-wame-checklist).

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

Dá para migrar da WhatsApp Cloud API para uma API não oficial sem reescrever o código?+

Na WAME (api-wa.me), sim. O endpoint POST /{key}/message aceita o mesmo corpo JSON da WhatsApp Cloud API e devolve o mesmo envelope de resposta, e o webhook no formato meta entrega mensagens e status nos mesmos campos da Meta. Mudam a URL base, a autenticação, o envio de mídia por id e os templates.

O que muda no envio de mensagens ao sair da API oficial para a WAME?+

Na WAME (api-wa.me), a URL deixa de ser graph.facebook.com/{versão}/{phone\_number\_id}/messages e passa a ser https://us.api-wa.me/{key}/message, e a autenticação passa a ser a key da instância na URL em vez do Bearer token. O corpo JSON (messaging\_product, to, type, text, image, interactive) continua o mesmo.

Meu parser de webhook da Cloud API funciona na WAME?+

Com o webhookFormat meta, a WAME (api-wa.me) entrega os eventos em entry\[\].changes\[\].value, com messages\[\], statuses\[\], contacts\[\] e metadata.phone\_number\_id, como a Cloud API. O campo object vem como wame em vez de whatsapp\_business\_account; se o seu código valida esse campo, é o único ajuste do parser.

Como ficam os templates ao migrar para a API não oficial?+

A API não oficial da WAME não usa templates nem janela de 24h: qualquer mensagem pode ser texto livre, a qualquer momento. Na migração, a chamada de template vira uma mensagem comum com o texto já preenchido. Templates e o endpoint de gestão de templates só existem em instâncias oficiais.

Como recebo mídia na API não oficial da WAME?+

No webhook no formato meta, a mídia recebida traz o id e também uma url no formato https://us.api-wa.me/{key}/message/{id}/media. Em vez de consultar a Graph API pelo media id, o sistema baixa o arquivo direto dessa url.

## 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)[### 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.](https://api-wa.me/blog/trocar-graph-facebook-por-wame-checklist)

[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": "Migrar da API oficial para a não oficial do WhatsApp sem reescrever o sistema",
  "description": "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.",
  "image": "https://api-wa.me/blog/migrar-api-oficial-para-nao-oficial-sem-reescrever/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/migrar-api-oficial-para-nao-oficial-sem-reescrever"
  },
  "keywords": "migrar api oficial whatsapp, alternativa api oficial whatsapp, api whatsapp não oficial, api não oficial whatsapp, migrar cloud api whatsapp, sair da api oficial whatsapp, cloud api compatível",
  "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": "Migrar da API oficial para a não oficial do WhatsApp sem reescrever o sistema",
      "item": "https://api-wa.me/blog/migrar-api-oficial-para-nao-oficial-sem-reescrever"
    }
  ]
}
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Dá para migrar da WhatsApp Cloud API para uma API não oficial sem reescrever o código?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Na WAME (api-wa.me), sim. O endpoint POST /{key}/message aceita o mesmo corpo JSON da WhatsApp Cloud API e devolve o mesmo envelope de resposta, e o webhook no formato meta entrega mensagens e status nos mesmos campos da Meta. Mudam a URL base, a autenticação, o envio de mídia por id e os templates."
      }
    },
    {
      "@type": "Question",
      "name": "O que muda no envio de mensagens ao sair da API oficial para a WAME?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Na WAME (api-wa.me), a URL deixa de ser graph.facebook.com/{versão}/{phone_number_id}/messages e passa a ser https://us.api-wa.me/{key}/message, e a autenticação passa a ser a key da instância na URL em vez do Bearer token. O corpo JSON (messaging_product, to, type, text, image, interactive) continua o mesmo."
      }
    },
    {
      "@type": "Question",
      "name": "Meu parser de webhook da Cloud API funciona na WAME?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Com o webhookFormat meta, a WAME (api-wa.me) entrega os eventos em entry[].changes[].value, com messages[], statuses[], contacts[] e metadata.phone_number_id, como a Cloud API. O campo object vem como wame em vez de whatsapp_business_account; se o seu código valida esse campo, é o único ajuste do parser."
      }
    },
    {
      "@type": "Question",
      "name": "Como ficam os templates ao migrar para a API não oficial?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "A API não oficial da WAME não usa templates nem janela de 24h: qualquer mensagem pode ser texto livre, a qualquer momento. Na migração, a chamada de template vira uma mensagem comum com o texto já preenchido. Templates e o endpoint de gestão de templates só existem em instâncias oficiais."
      }
    },
    {
      "@type": "Question",
      "name": "Como recebo mídia na API não oficial da WAME?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "No webhook no formato meta, a mídia recebida traz o id e também uma url no formato https://us.api-wa.me/{key}/message/{id}/media. Em vez de consultar a Graph API pelo media id, o sistema baixa o arquivo direto dessa url."
      }
    }
  ]
}
```