Estratégia híbrida: API oficial do WhatsApp para template, não oficial para atendimento

A estratégia híbrida é usar a API oficial do WhatsApp só para templates — notificação, marketing, autenticação — e fazer o atendimento por uma API não oficial com plano fixo. Com a cobrança de toda mensagem de serviço a partir de 1º de outubro de 2026, é a forma de manter o que só a Meta oferece sem pagar por cada resposta. Na WAME (api-wa.me) as duas rodam na mesma plataforma, com o mesmo corpo de envio e o mesmo webhook no padrão da Meta.

A ideia é simples; o que faz ela funcionar é o desenho. Este guia mostra quais mensagens vão para cada lado, como o cliente passa de um número para o outro e como escrever um código só para os dois.

Por que dividir, em vez de sair da oficial?

Porque a API oficial tem coisas que a não oficial não substitui, e a mudança de preço atingiu a parte que a não oficial resolve melhor.

Os detalhes da mudança estão em WhatsApp API mais cara em outubro de 2026. O resumo que importa aqui: o custo novo está na conversa, e conversa é exatamente o que a não oficial faz com custo fixo.

Quantos números e quais instâncias?

Dois números, duas instâncias:

• Instância oficial: o número registrado na Cloud API. Envia templates. Na WAME, você conecta em minutos, sem criar app na Meta — veja API oficial sem virar Tech Provider.
• Instância não oficial: o número de atendimento, conectado por QR Code ou código de pareamento. Recebe e responde.

Um mesmo número não fica nas duas ao mesmo tempo: o número da Cloud API não pode estar ativo como aparelho conectado no app. Se você quer levar o número atual para o lado não oficial, veja dá para usar o mesmo número ao sair da Cloud API?.

O ponto que mais gente erra: para onde vai a resposta?

A resposta do cliente sempre vai para o número que mandou a mensagem. Se o template sai do número oficial e o cliente responde ali, essa conversa acontece na Cloud API — e cada resposta sua é mensagem de serviço cobrada.

Por isso o template precisa encaminhar o cliente para o número de atendimento:

• Botão de link no template apontando para https://wa.me/NUMERO_DE_ATENDIMENTO?text=... com o assunto já preenchido (por exemplo, o número do pedido).
• Texto claro: "Dúvidas sobre o pedido? Fale com a gente pelo botão abaixo."
• Resposta automática curta no número oficial para quem responder ali mesmo, com o mesmo link — uma mensagem, não uma conversa.

Como o cliente é quem inicia a conversa no número de atendimento, o primeiro contato ali é iniciado por ele, o que é também o uso mais seguro do lado não oficial. Para montar o link com mensagem pronta, veja como criar link do WhatsApp.

Um código só para os dois lados

Na WAME, o mesmo POST /{key}/message aceita o corpo da Cloud API nas duas instâncias. O que muda é a key:

const BASE = 'https://us.api-wa.me';
const KEY_OFICIAL = process.env.WAME_KEY_OFICIAL;       // templates
const KEY_ATENDIMENTO = process.env.WAME_KEY_ATENDIMENTO; // conversa

async function enviar(key, corpo) {
  const r = await fetch(`${BASE}/${key}/message`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ messaging_product: 'whatsapp', ...corpo }),
  });
  const json = await r.json();
  if (json.error) throw new Error(`${json.error.code}: ${json.error.message}`);
  return json.messages[0].id; // mesma resposta da Cloud API
}

// Resposta de atendimento: sempre pela instância não oficial.
function responder(to, texto) {
  return enviar(KEY_ATENDIMENTO, { to, type: 'text', text: { body: texto } });
}

Template continua sendo recurso exclusivo da oficial e tem endpoint próprio, POST /{key}/message/template, com to, name, language e components:

async function notificar(to, pedido) {
  await fetch(`${BASE}/${KEY_OFICIAL}/message/template`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      to,
      name: 'pedido_enviado',
      language: 'pt_BR',
      components: [
        { type: 'body', parameters: [{ type: 'text', text: pedido }] },
        { type: 'button', sub_type: 'url', index: '0', parameters: [{ type: 'text', text: pedido }] },
      ],
    }),
  });
}

O botão de URL do template aponta para o link wa.me do número de atendimento; o parâmetro completa o texto pré-preenchido.

Um webhook só, sabendo de onde veio

Configure as duas instâncias com webhookFormat: "meta" apontando para a mesma URL. Todo evento chega no envelope da Cloud API, com dois campos extras no topo que resolvem o roteamento:

• instance: a key da instância que gerou o evento.
• official: true para eventos da instância oficial, false para a não oficial.

app.post('/webhook/wame', (req, res) => {
  res.sendStatus(200);
  const { instance, official, entry } = req.body;
  const value = entry?.[0]?.changes?.[0]?.value;
  const msg = value?.messages?.[0];
  if (!msg) return; // status de entrega também chega aqui

  if (official) {
    // Alguém respondeu no número de templates: uma única resposta
    // com o link do atendimento, sem abrir conversa aqui.
    return redirecionarParaAtendimento(msg.from);
  }
  return atender(instance, msg); // fluxo normal do bot ou da equipe
});

O redirecionarParaAtendimento também é uma mensagem de serviço cobrada — por isso é uma mensagem, não uma conversa. O custo real desse desvio é uma resposta por cliente que erra o caminho, contra todas as respostas da conversa inteira.

O webhook não oficial não traz assinatura X-Hub-Signature; proteja a URL com um token secreto no caminho, como explicado em webhook em produção.

Regras de roteamento: o que vai para cada lado

E o risco do lado não oficial?

A camada não oficial não é afiliada à Meta, e o uso é responsabilidade de quem envia. No híbrido, porém, o lado não oficial faz o uso de menor risco que existe: responde quem chamou. O cliente chega pelo link, inicia a conversa e você responde. A taxa de bloqueio nesse perfil é muito baixa para quem usa do jeito certo; a WAME não apoia spam, freia envio para muitos números novos por minuto e avisa pelo webhook de conexão quando o número dá sinal de risco. Mais em sinais de que o número está em risco.

Em resumo

• Oficial para template, autenticação e campanha para quem optou; não oficial para a conversa.
• Dois números, duas instâncias, uma plataforma e um formato de API.
• O template precisa levar o cliente ao número de atendimento; resposta no número oficial é cobrada.
• Um webhook só: os campos instance e official dizem de onde veio o evento.
• O lado não oficial fica no uso mais seguro possível — responder quem chamou.

Conclusão

O híbrido é a resposta para quem não pode abrir mão da API oficial, mas não quer pagar por cada resposta depois de outubro de 2026. O segredo não está na infraestrutura, está no caminho do cliente: o template sai do número oficial e leva a conversa para o número de atendimento, onde a WAME cobra por instância, não por mensagem. Como as duas instâncias usam o mesmo corpo de envio da Cloud API e o mesmo webhook no padrão da Meta, montar o híbrido é escolher a key certa em cada fluxo. Para ver a lógica completa de código único, leia um código só para a API oficial e a não oficial e a documentação.