Principal Integração com WhatsApp Como conectar um número do WhatsApp com coexistência (App + API)

Como conectar um número do WhatsApp com coexistência (App + API)

Última atualização em May 08, 2026

Quando usar

  • Você já usa o número no WhatsApp Business App (celular) e quer continuar usando

  • Você quer testar a API e automações sem abrir mão do uso manual via celular

  • Seu time (vendedores, consultores, account managers) precisa continuar usando o celular

  • Você quer uma transição gradual para a API sem interromper a operação atual

Limitação importante da coexistência: dispositivos não suportados

A Meta tem uma limitação oficial no modelo de coexistência: mensagens trocadas pelo WhatsApp Desktop (Windows) ou pelo WhatsApp em WearOS não chegam ao Cloud Chat — mesmo que apareçam no celular e também não chegam ao destinatário. Essa limitação só afeta coexistência; no modelo sem coexistência (API exclusiva) o problema não existe.

Relato típico do cliente:

As mensagens enviadas pelo agente não estão chegando para o cliente.

As mensagens do cliente aparecem no celular, mas não no Cloud Chat.

Detalhes técnicos na documentação oficial da Meta — em resumo, esses apps não disparam o webhook smb_message_echoes que a API usa pra espelhar a conversa.

Como contornar

Migrar para o modelo SEM coexistência (API exclusiva): todas as mensagens passam pela API, não há mais conflito entre dispositivos, e o número deixa de funcionar no celular.

Passo a passo: Como conectar um número do WhatsApp via API oficial (sem coexistência).

Pré-requisitos

Iniciar a integração sem validar os pontos abaixo pode resultar em perda do número, bloqueio pela Meta, erros no processo de verificação ou necessidade de refazer toda a configuração.

Migração de número existente? Leia o guia de migração primeiro — leitura obrigatória.

Se o número que você quer conectar já está ativo em outra plataforma de atendimento ou em outro provedor (BSP), NÃO inicie o fluxo de Cadastro Incorporado antes de ler:

Migrando o WhatsApp para o Cloud Chat a partir de outra plataforma de atendimento

Pular essa etapa pode resultar em:

  • Falhas no processo de verificação e migração travada

  • Impossibilidade de liberar o número do provedor anterior

  • Necessidade de refazer toda a configuração do zero

O guia de migração mostra todos os pré-requisitos da Meta (propriedade da WABA, Verificação em Duas Etapas, status do Business Manager, método de pagamento, histórico de mensagens) que precisam ser validados antes de realizar a integração no Cloud Chat.

Número novo? É preciso aquecer antes de tentar integrar.

A Meta avalia o histórico de uso do número antes de liberar a conexão via API. Números recém-criados, sem histórico no WhatsApp Business App, podem ser barrados logo no Cadastro Incorporado — a Meta retorna o erro:

"Seu número de telefone não está qualificado para se conectar à plataforma do WhatsApp Business. Mais atividades no app WhatsApp Business são necessárias para ajudar a determinar a qualificação." (#3441045)

Como aquecer antes de integrar:

  • Use o número no WhatsApp Business App (celular) por alguns dias / semanas, recebendo conversas reais

  • Divulgue o número nos seus canais (site, redes sociais, e-mail) para gerar entrada orgânica

  • Responda dentro da janela de 24h, sem spam, sem mensagens repetidas, sem links suspeitos

Depois do aquecimento, o número entra na API com tier e Quality Rating melhores e o Cadastro Incorporado passa sem o erro acima.

Documentação oficial da Meta: Messaging Limits · Quality Rating.

Validando o Status do Portfólio Empresarial

O Portfólio Empresarial (Business Portfolio) precisa estar com o status "Verificada" na Meta. Isso significa que a Meta reconheceu e validou a identidade da sua empresa.

Por que isso importa? Sem a verificação, você está sujeito a limites muito baixos de envio (até 250 mensagens/dia), não pode migrar números de outros provedores e pode ter restrições em funcionalidades da API. A verificação é o primeiro requisito para uma operação saudável na plataforma da Meta.

Como verificar:

  1. Acesse business.facebook.com/settings/info

  2. Verifique o campo Status da verificação

  3. Deve estar como "Verificada" ✅

Se estiver como "Não verificada" ou "Pendente", clique em Iniciar verificação e siga o processo com documentos e domínio da empresa antes de continuar.

Não usa WhatsApp Business App no celular?

A coexistência foi feita pra quem mantém o número ativo no celular (WhatsApp Business App) em paralelo à API. Se você não vai usar o número no celular — só no Cloud Chat / API — esse modelo não faz sentido. Use o método sem coexistência:

Como conectar um número do WhatsApp via API oficial (sem coexistência)

Número já cadastrado e ativo no WhatsApp Business App (celular) antes de iniciar — a coexistência só funciona se o número já estiver vinculado e em uso no app antes do Cadastro Incorporado. Se o número ainda não está no WhatsApp Business App, instale o app e cadastre o número.

Passo a passo da integração com coexistência

Com todos os pré-requisitos acima validados, você já pode iniciar a integração. Para isso, tenha em mãos:

  • Ser administrador da conta no Cloud Chat

  • Acesso de administrador ao Portfólio Empresarial na Meta (necessário para autorizar a conexão no fluxo de Embedded Signup)

  • Ter o celular com o WhatsApp Business App em mãos para ler o QR code na sincronização

  • Cartão de crédito habilitado para pagamento em dólar — obrigatório em migração de plataforma de atendimento ou para disparos proativos

Etapa 1 — Acessar as Configurações do Cloud Chat

  1. No Cloud Chat, acesse Configurações

  1. Vá até a seção Caixas de Entrada

Etapa 2 — Iniciar a criação da caixa de entrada de WhatsApp

  1. Clique em Adicionar Caixa de Entrada

  1. Selecione WhatsApp

  1. Na tela do Canal do WhatsApp, escolha o provedor Cadastro Incorporado (Embedded Signup) e preencha o nome desejado para a caixa de entrada. Depois, clique em Entrar via WhatsApp

Etapa 3 — Autenticar na Meta

No pop-up da Meta que será aberto, faça login com a conta pessoal do Facebook da pessoa que tem acesso de administrador ao Portfólio Empresarial (Business Portfolio) da empresa na Meta.

O login não é feito com um e-mail corporativo genérico nem com uma "conta da empresa" — é com o Facebook pessoal de quem é admin do portfólio empresarial da Meta. Sem essa permissão administrativa, o fluxo de Cadastro Incorporado não consegue autorizar a conexão e a integração trava nesta etapa.

  1. Após o login, clique em Continuar

Etapa 4 — Selecionar Business Portfolio e ativar coexistência

  1. Escolha o Business Portfolio na Meta e clique em Avançar

  1. Selecione Conectar WhatsApp Business App existente e clique em Avançar

Etapa 5 — Verificar o número

  1. Selecione Adicionar um novo número, insira o número de telefone e verifique-o

Se o número for um telefone fixo ou número digital, a verificação deverá ser feita por chamada telefônica, não SMS.

Etapa 6 — Sincronizar com o WhatsApp Business App via QR code

  1. Após a verificação, clique em Concluir para iniciar a sincronização com o WhatsApp Business App

  2. Abra o WhatsApp Business no celular, leia o QR code e siga as instruções no aparelho

Importação do histórico de contatos e mensagens

No momento da integração, o celular receberá uma notificação solicitando a importação do histórico do número. Ao confirmar, a Meta sincroniza automaticamente o histórico de mensagens e contatos dos últimos 6 meses para o Cloud Chat.

Embora a importação esteja prevista na documentação oficial da Meta, em integrações recentes observamos que a Meta pode não enviar o histórico completo no momento da sincronização. É comum que parte das mensagens ou alguns contatos não sejam importados.

Esse comportamento é intermitente e fora do controle do Cloud Chat, pois depende da entrega da Meta. Mantenha registros paralelos se necessário.

Etapa 7 — Configurar pagamento (se aplicável)

Quando o cadastro do método de pagamento é OBRIGATÓRIO:

  • Migração de número existente — sempre obrigatório, sem exceção. Sem método de pagamento válido, a Meta não conclui a migração da WABA.

  • Disparo proativo (template / campanha / mensagem unitária via API) — obrigatório, porque a Meta cobra por template enviado fora da janela de 24h.

  • Reabertura da janela de 24h da Meta — obrigatório. Para iniciar uma nova conversa com um cliente fora da janela ativa, é preciso disparar um template, e isso tem custo direto cobrado pela Meta no cartão cadastrado.

  • Pesquisa de satisfação (CSAT) — a mensagem de CSAT também é um template da Meta. Se ela for disparada fora da janela de 24h (caso comum quando o cliente não responde logo após o atendimento), sem método de pagamento cadastrado a CSAT não é enviada — o cliente não recebe a pergunta de avaliação e a métrica fica vazia.

Sem cartão válido cadastrado na WABA, nenhuma mensagem proativa sai, nenhuma janela é reaberta e nenhum CSAT é entregue fora da janela — o número fica restrito a responder dentro das 24h após a última mensagem do cliente.

  1. Clique em Adicionar método de pagamento para ir adicionar o método de pagamento na WABA. Para atendimento puramente reativo (responder mensagens dentro da janela de 24h, sem disparos proativos e sem migração), clique em "Finish".

Etapa 8 — Adicionar agentes à caixa de entrada

  1. Configure os agentes que terão acesso à nova caixa de entrada

  1. Clique em Adicionar agentes

A caixa de entrada com coexistência está integrada e pronta para uso. ✅

Observações

O Cloud Chat aparece no celular como dispositivo conectado, em WhatsApp Business App → Dispositivos Conectados

Se alguém remover o Cloud Chat da lista de dispositivos no celular, a integração será desfeita e será necessário refazer todo o processo.