Guia de Migração: WhatsApp QR Code para API Oficial

A migração do WhatsApp QR Code para a API Oficial do WhatsApp oferece mais estabilidade, segurança e previsibilidade para sua operação.
No entanto, algumas funcionalidades funcionam de maneira diferente após a migração e podem exigir ajustes em gatilhos, chatbots, workflows e templates.

Neste artigo, você entenderá as principais diferenças entre as modalidades, o que muda na operação e quais configurações precisam ser realizadas após a migração.

Entendendo a diferença entre WhatsApp QR Code e API Oficial

Antes de iniciar a migração, é importante compreender como cada modalidade funciona.

O WhatsApp QR Code utiliza a conexão do WhatsApp Web para integrar o número à plataforma. Nesse modelo, a conexão é realizada através da leitura de um QR Code e depende de uma sessão ativa do WhatsApp para funcionar corretamente.

Já a API Oficial do WhatsApp é a solução empresarial homologada pela Meta. A comunicação ocorre diretamente pela infraestrutura oficial do WhatsApp Business Platform, sem depender de um aparelho conectado, proporcionando maior estabilidade, escalabilidade e segurança operacional.

Embora ambas as modalidades permitam o envio e recebimento de mensagens pelo WhatsApp, existem diferenças importantes que impactam a operação, os recursos disponíveis e as regras de envio.

Comparativo entre WhatsApp QR Code e API Oficial

Vantagens da API Oficial

Ao migrar para a API Oficial, sua empresa passa a contar com diversos benefícios:

• Maior estabilidade nos envios;
• Menor risco de desconexões;
• Canal homologado pela Meta;
• Melhor escalabilidade para grandes volumes de mensagens;
• Gestão de reputação do número;
• Maior segurança operacional;
• Recursos oficiais do WhatsApp Business Platform.

Por que considerar a migração para a API Oficial?

As conexões via WhatsApp QR Code utilizam tecnologias que dependem da conexão com o WhatsApp Web e não operam diretamente através da infraestrutura oficial da Meta.

Nos últimos anos, o WhatsApp vem fortalecendo suas políticas de segurança e controle da plataforma, tornando bloqueios, restrições temporárias e desconexões eventos cada vez mais comuns para operações que utilizam esse tipo de conexão em todo o mercado.

Embora a adoção de boas práticas reduza significativamente os riscos — como manter uma operação saudável, respeitar os limites de envio, evitar práticas abusivas e utilizar mensagens adequadas ao perfil dos contatos — não existe uma forma de eliminar completamente a possibilidade de bloqueios ou restrições nesse modelo de conexão.

Por esse motivo, empresas que dependem do WhatsApp como um canal estratégico de atendimento, vendas e relacionamento costumam migrar para a API Oficial do WhatsApp em busca de maior previsibilidade operacional.

Com a API Oficial, a comunicação passa a ocorrer através da infraestrutura homologada pela Meta, proporcionando:

• Maior estabilidade nas conexões;
• Menor risco de interrupções operacionais;
• Melhor controle de reputação do número;
• Maior segurança para operações de médio e grande porte;
• Escalabilidade para crescimento do volume de mensagens;
• Conformidade com as políticas oficiais do WhatsApp.

Como funciona a cobrança na API Oficial?

Diferente do WhatsApp QR Code, a API Oficial segue o modelo de cobrança da Meta para mensagens enviadas através de templates.

O valor cobrado pode variar de acordo com:

• A categoria do template aprovado pela Meta;
• O país do destinatário da mensagem;
• As regras de precificação vigentes da Meta.

Categorias de templates

As categorias mais comuns são:

• Marketing: Mensagens promocionais, campanhas, ofertas, recuperação de vendas e ações comerciais.
• Utilitário: Atualizações relacionadas a uma transação ou serviço já solicitado pelo cliente, como confirmação de pedido, atualização de entrega e lembretes operacionais.

A classificação do template é definida pela própria Meta durante o processo de aprovação. Não é possível escolher manualmente se um template será aprovado como Marketing ou Utilitário.

Para atendimentos realizados pela central de atendimento, o conceito utilizado é o da janela de atendimento de 24 horas, explicado abaixo.

Como funciona a janela de atendimento na API Oficial?

Além das regras de cobrança, a API Oficial do WhatsApp utiliza o conceito de janela de atendimento de 24 horas, definida pela Meta.

Essa janela é aberta sempre que o cliente envia uma mensagem para sua empresa. Enquanto ela estiver ativa, sua equipe pode responder normalmente através da API Oficial, sem a necessidade de utilizar templates aprovados pela Meta.

Ou seja, durante esse período, é possível responder o cliente livremente, com mensagens manuais e sem cobrança por envio de template.

A cada nova mensagem enviada pelo cliente, o período de atendimento é renovado automaticamente por mais 24 horas. Isso significa que, enquanto houver interação do contato, a conversa poderá continuar de forma livre dentro da janela ativa.

Caso o cliente permaneça mais de 24 horas sem enviar novas mensagens, a janela de atendimento será encerrada. A partir desse momento, para retomar o contato de forma ativa, será necessário utilizar um template previamente aprovado pela Meta.

O que muda para quem utilizava WhatsApp QR Code?

No WhatsApp QR Code não existe a regra de janela de atendimento da API Oficial. Por isso, alguns fluxos, campanhas, automações e mensagens transacionais poderão precisar de ajustes após a migração para garantir conformidade com as políticas da Meta.

O histórico das conversas será migrado?

Uma limitação da própria Meta é que o histórico de conversas não é disponibilizado através da API Oficial.

Isso significa que:

• As conversas existentes na instância QR Code não serão transferidas para o WABA;
• Apenas novas mensagens recebidas após a conexão do número na API Oficial passarão a aparecer na plataforma;
• O histórico anterior continuará disponível apenas no ambiente onde foi originalmente registrado.

O que precisa ser feito após a migração?

Após migrar o plano e conectar o número na plataforma seguindo as orientações do artigo de configuração do WABA, alguns recursos precisarão ser ajustados para que os envios ocorram através da API Oficial.

Os principais pontos de atenção são:

• Envios transacionais;
• Chatbots;
• Workflows;
• Templates de mensagens.

Posso reaproveitar os fluxos que utilizava no WhatsApp QR Code?
Sim. Grande parte da estrutura utilizada anteriormente poderá ser reaproveitada, porém alguns ajustes serão necessários para adequar os envios às regras da API Oficial.

Veja abaixo como fazer cada um desses processos.

Ajustando os fluxos após a migração do QR Code para API Oficial

Neste tópico, você aprenderá como ajustar os fluxos e recursos necessários após a migração para a API Oficial.

Para aprender a criar atalhos com templates, criar templates e vinculá-los aos gatilhos, acesse o artigo: Usabilidade do WABA no Notificações Inteligentes.

Ajustando os envios transacionais

Para alterar os envios da loja para a API Oficial:

1. Acesse Lojas.
2. Clique na loja desejada.
   
3. Acesse a aba Canais.
4. Vincule o canal WhatsApp Oficial.
   
5. Selecione o tipo de canal e o canal desejado.
   
6. Acesse a aba Gatilhos.
7. Clique no gatilho desejado.
   
8. Desabilite o modo de envio WhatsApp QR Code.
9. Habilite o modo WhatsApp API Oficial.
10. Repita o procedimento em todos os gatilhos utilizados.
    Importante: o gatilho precisa estar habilitado para que os envios ocorram.
    

Ajustando o Chatbot

No chatbot GPT, não é possível realizar a exportação do fluxo.
Sendo assim, será necessário configurá-lo novamente, criando um novo chatbot e selecionando o tipo de canal WhatsApp Oficial.

No caso do chatbot Régua de Ações, é possível exportar o fluxo atual e importá-lo em um novo chatbot compatível com a API Oficial, conforme as orientações abaixo.

Atenção às listas de opções
Se o fluxo possuir o nó Lista de opções, será necessário adaptá-lo.
A Meta não permite esse tipo de interação na API Oficial.
Nesses casos, substitua por Lista de botões.

Exportando o chatbot atual

1. Acesse o chatbot utilizado no QR Code.
2. Clique nos três pontos.
3. Selecione Exportar chatbot.
   

Importando para a API Oficial
4. Crie um novo chatbot.
5. Selecione o canal API Oficial.

5. Adicione o nome e descrição do fluxo e siga as orientações da tela.
6. Clique em Importar chatbot e selecione o arquivo exportado anteriormente.

7. Verifique se todos os nós estão devidamente preenchidos. Se necessário, realize os ajustes no fluxo e salve as alterações.

Pronto!! Lembre-se de ativar o fluxo após as alterações.

Ajustando Workflow

Após a migração para a API Oficial, os nós de envio utilizados no WhatsApp QR Code precisarão ser substituídos por nós compatíveis com o WABA.
Importante: na API Oficial, toda mensagem iniciada fora da janela de atendimento exige o uso de um template previamente aprovado pela Meta.

No WhatsApp QR Code, era comum utilizar o nó “Enviar notificação”, que permite digitar mensagens livremente, sem necessidade de aprovação da Meta. Porém, após a migração, esse tipo de envio deixa de ser compatível, uma vez que depende da janela de atendimento está aberta para ter o envio.

Por isso, será necessário substituir esse nó pelo “Envio de notificação WABA”, que realiza os disparos utilizando templates oficiais aprovados.

Como realizar o ajuste:

Primeira etapa: criar o template e aguardar a aprovação

1. Acesse: WhatsApp QR Code > Contas do WhatsApp > Templates
2. Crie o template desejado e envie para aprovação da Meta.
   Para mais detalhes sobre criação e configuração de templates em workflows, consulte o artigo:
   Usabilidade do WABA no Notificações Inteligentes

Substituindo o nó no fluxo
3. Após a aprovação, acesse o workflow que será ajustado.
4. Localize o nó antigo “Enviar notificação”.
5. Clique no ícone + no ponto em que deseja substituir o envio.

6. Adicione o nó “Envio de notificação WhatsApp Oficial”.
7. Vincule o template aprovado ao novo nó de envio.
   
8. Após configurar o novo nó, exclua o nó antigo referente ao QR Code.
9. Ao clicar em excluir, será exibida uma janela perguntando se deseja remover apenas o bloco selecionado ou também os blocos adjacentes.
   Selecione a opção “Remover apenas o bloco selecionado” para manter o restante da estrutura e do fluxo do workflow intactos.
   
10. Agora basta repetir esse mesmo procedimento nos demais nós do workflow que utilizarem envios pelo QR Code e precisarem ser adaptados para a API Oficial.
    Ao finalizar os ajustes, lembre-se de salvar e habilitar o fluxo para que as alterações entrem em funcionamento.

Atualizado em: 30/06/2026