## Visão geral

A **caixa híbrida** une, em **uma única conversa**, uma caixa de **Coexistência (Cloud)** e uma caixa de
**WhatsApp Web** que compartilham **o mesmo número físico**. Em vez de duas caixas separadas para o mesmo
contato, você atende em um só lugar e a plataforma escolhe automaticamente **por qual transporte enviar**.

- **A Cloud (Coexistência) é autoritativa para a entrada**: as conversas ficam na caixa Cloud.
- **O WhatsApp Web é um transporte de envio + fallback**: usado, por exemplo, **fora da janela de 24h**
  para enviar uma mensagem de sessão gratuita em vez de pagar um template.
- As duas caixas **continuam existindo** — o pareamento é um **vínculo**, nunca uma fusão.

Cada mensagem enviada recebe um **selo de transporte** ("via Coexistência (Cloud)" ou "via WhatsApp Web",
com marca de *fallback* quando aplicável), então você sempre sabe por onde a mensagem saiu.

> **A ordem de conexão importa e é única.** Conecte **primeiro** a caixa de **Coexistência (Cloud)**,
> **aguarde a sincronização da Meta** (pode levar até **~24 horas**) e **só então** conecte/pareie a caixa
> do **WhatsApp Web**. A ativação da Coexistência **desconecta todos os aparelhos conectados** do app
> WhatsApp Business — inclusive uma caixa do WhatsApp Web que já estivesse pareada nesse número.

## Pré-requisitos

- O recurso **Caixa híbrida** habilitado na conta (fale com o operador da plataforma).
- Uma caixa de **Coexistência (Cloud)** conectada pelo **Embedded Signup** com o número — **esta é a
  primeira conexão, sempre**.
- A **sincronização da Meta concluída** para esse número (pode levar até **~24 horas** após a ativação).
- O app **WhatsApp Business** instalado no celular do número, com internet, para ler o QR do WhatsApp Web
  depois da sincronização.
- Perfil de **administrador** para criar caixas, parear/desparear e alterar o roteamento.

> **Não conecte o WhatsApp Web antes da Coexistência.** Se já existir uma caixa do WhatsApp Web nesse
> número, ela **será desconectada** quando a Coexistência for ativada e precisará ser **pareada
> novamente** (leitura de um novo QR). O repareamento **não perde nada**: a **mesma caixa** é
> reaproveitada — número, conversas, contatos e histórico de mensagens permanecem. Só a sessão do
> gateway é refeita.

## Passo a passo

### 1. Conecte a Coexistência (Cloud) — sempre primeiro

1. Em **Configurações → Caixas de Entrada**, crie uma caixa **WhatsApp** e escolha o provedor
   **WhatsApp Cloud** com **Embedded Signup**.
2. No fluxo da Meta, selecione o número que já é usado no **WhatsApp Business** e conclua a ativação da
   **coexistência** para esse número.
3. Ao ativar, a Meta **desconecta todos os aparelhos conectados** do WhatsApp Business. Isso é esperado —
   é exatamente por isso que o WhatsApp Web vem depois.

### 2. Aguarde a sincronização da Meta

4. A Meta sincroniza histórico e contatos do número para a caixa Cloud. Isso pode levar **até ~24 horas**.
5. **Não avance** enquanto a caixa Cloud não estiver recebendo e enviando mensagens normalmente.

### 3. Conecte (ou repareie) a caixa do WhatsApp Web

6. Só agora crie a caixa **WhatsApp Web** com **o mesmo número** — ou, se ela já existia, abra a caixa e
   gere um novo QR na tela de conexão.
7. No celular: WhatsApp → **Aparelhos conectados** → **Conectar um aparelho** e aponte a câmera para o QR.
8. Aguarde a caixa Web entrar no estado **conectado**.

### 4. Pareie as duas caixas

9. Abra **Configurações da caixa** da caixa **Cloud (Coexistência)** e vá até a aba **Híbrido**.
10. Em **Caixa do WhatsApp Web para parear**, selecione a caixa Web com o mesmo número.
11. Clique em **Parear caixas**. A plataforma valida (mesma conta, mesmo número, um Cloud + um Web) e cria
    o vínculo. Bots, flows, automações e membros necessários são **espelhados de forma aditiva** na
    caixa Cloud, sem retirar os vínculos da caixa Web. Campanhas Web continuam ativas e na mesma caixa;
    o HistorySync Web continua habilitado para preservar grupos, newsletters e outras superfícies que a
    Coexistência não entrega. Apenas o histórico 1:1 duplicável é filtrado.
12. Na caixa **Web**, a aba Híbrido passa a ser um **espelho somente leitura** ("configure na caixa Cloud").

## Configurações & opções

Na aba **Híbrido** (na caixa Cloud) você define o roteamento:

- **Recebe (autoridade de entrada)**: quem controla a entrada (v1: Cloud/Coexistência).
- **Transporte de envio padrão**: dentro da janela de 24h (padrão: Cloud).
- **Transporte de envio fora da janela**: quando a janela fecha (padrão: WhatsApp Web — sessão gratuita).
- **Fallback automático**: se o transporte escolhido falhar, tenta uma vez no transporte irmão.
- **Permitir seleção no compositor**: os agentes escolhem o transporte por conversa (Automático / Cloud / Web).

**Templates aprovados, interativas nativas da Meta, WhatsApp Flows e catálogo saem pela Cloud.** As
interativas exclusivas do WazMeow e conversas de grupos/newsletters continuam saindo pelo Web.

### Caixa operacional única (opcional)

Quando o operador habilitar também o recurso **Caixa operacional única**, um administrador pode ativá-lo
na aba **Híbrido**:

- a caixa Cloud passa a ser a única entrada nas listas operacionais e seletores do dia a dia;
- a caixa Web física **não é apagada, mesclada nem desativada** e continua disponível em configurações,
  relatórios e auditoria;
- grupos, newsletters, chamadas, HistorySync, lista de ignorados, campanhas e envios exclusivos do Web
  continuam usando o canal Web;
- conversas 1:1 antigas da caixa Web são resolvidas e recebem um link para a conversa Cloud; mensagens e
  chamadas permanecem nas linhas originais;
- antes de congelar qualquer conversa, a plataforma **tenta reconciliar sozinha** o estado de controle do
  Maestro daquela conversa (pausa para atendimento humano, Robô específico e autonomia definida só ali)
  para a conversa Cloud. Só uma **aprovação humana pendente** exige decisão sua;
- a ativação mostra progresso e, se falhar, volta automaticamente ao modo visível de duas caixas.

Ao desativar, a caixa Web volta às listas operacionais. Os links e históricos já resolvidos permanecem
intactos; não existe reversão destrutiva nem mesclagem automática de histórico.

### O que cada transporte cobre

| Superfície | Coexistência (Cloud) | WhatsApp Web |
|---|---|---|
| Conversas 1:1 | Sim (autoritativa) | Transporte de envio / fallback |
| Templates, interativas, flows, catálogo | Sim | Não |
| Grupos, comunidades, canais, status, listas de transmissão | Não | Sim |
| Chamadas nativas do WhatsApp Web | Não | Sim |

### Custos e moeda

Na mesma aba, a seção **Custos** mostra o custo real de mensagens (Meta *pricing analytics*) por categoria,
na moeda de cobrança da WABA e na sua **moeda de exibição** (conversão por câmbio). Contas de **Coexistência**
não podem migrar a moeda de cobrança na Meta — por isso a **conversão de moeda de exibição** é a resposta, e
um link para a documentação oficial da Meta é exibido.

## Casos de uso

- **Reduzir custo fora da janela**: responder após 24h por uma sessão gratuita do WhatsApp Web em vez de
  um template pago.
- **Continuidade**: se um transporte cair, o fallback entrega pelo outro.
- **Grupos, comunidades, canais e status**: manter tudo o que a Coexistência **não** cobre funcionando no
  mesmo número, pela caixa Web.
- **Chamadas do WhatsApp Web**: manter as chamadas nativas do WhatsApp Web funcionando no número, mesmo com
  a Coexistência ativa (veja abaixo).

## Dicas, limites e boas práticas

- **A ordem é obrigatória**: Coexistência (Cloud) → sincronização da Meta (~24h) → WhatsApp Web →
  pareamento. Inverter a ordem faz a caixa Web ser desconectada quando a Coexistência for ativada.
- **Abra o app WhatsApp Business pelo menos uma vez a cada ~14 dias** no celular do número. Sem isso, a
  Coexistência perde a saúde e pode parar de sincronizar.
- **Toda chamada híbrida usa a sinalização e a mídia do WhatsApp Web**, inclusive quando sua bolha aparece
  na conversa Cloud da caixa operacional única. O pareamento não altera a configuração de chamadas.
- Chamadas de saída continuam pelo Web. Para chamadas recebidas 1:1, a plataforma só pode tocar o agente
  quando a Meta/gateway entrega um evento `CallOffer` ao dispositivo companion. Em alguns números de
  Coexistência a Meta faz a chamada tocar apenas no celular; nesse caso não existe retry local capaz de
  recriar uma oferta que não chegou.
- Grupos, comunidades, canais e status do WhatsApp Web **continuam** como conversas próprias da caixa Web.
- Não remova os vínculos Web de bots, flows, automações ou campanhas: eles continuam necessários para
  grupos, newsletters e recursos exclusivos do Web. O pareamento espelha apenas o que a Cloud precisa.
- A v1 opera no modo **Cloud-primário** (a Coexistência é a receptora autoritativa).

## Solução de problemas

- **A caixa do WhatsApp Web ficou "desconectada da conta" depois de ativar a Coexistência**: é o
  comportamento esperado — a ativação desconecta todos os aparelhos conectados do WhatsApp Business. A
  caixa Web informa a causa (**desconectado por outro aparelho** — o caso normal aqui —, **o aparelho
  principal foi desconectado** ou **motivo desconhecido**); nos três a correção é a mesma. Abra a caixa
  Web, gere um novo QR na tela de conexão e **pareie novamente**. **Nada se perde**: número, conversas,
  contatos e histórico continuam na mesma caixa; só a sessão do gateway é refeita.
- **A caixa diz que pareou, mas nada chega**: o número pode ter ficado preso em um **número provisório
  (placeholder)** porque **outra caixa já usa esse número** — na mesma conta (mesmo provedor) ou em outra
  conta. A aba **Híbrido** e a tela de pareamento mostram o motivo. Libere ou remova a caixa que retém o
  número e pareie de novo.
- **Não aparece caixa para parear**: confirme a ordem — Coexistência (Cloud) primeiro, sincronização da
  Meta concluída, e só então a caixa do WhatsApp Web conectada com **o mesmo número**.
- **A ativação da caixa única parou por conflito de configuração**: a plataforma agora recusa no próprio
  clique, com **422**, dizendo **qual** configuração está em conflito entre a caixa Cloud e a Web (política
  de atribuição, roteamento, CSAT, bot, integração de caixa, conversão de anúncios, entre outras). Antes o
  pedido era aceito, entrava na fila e só falhava minutos depois. Resolva o conflito na caixa indicada e
  ative de novo.
- **A ativação da caixa única parou por estado do Maestro**: ter o Maestro configurado não bloqueia a
  ativação. Antes de congelar qualquer histórico, a plataforma **tenta reconciliar** o estado de controle da
  conversa Web para a conversa Cloud que vai passar a valer e depois **relê** o que ficou gravado. Só continua
  bloqueando o que realmente não migrou:
  - **Resolve sozinho, sem ação do operador**: a **pausa para atendimento humano** (o robô foi mandado ficar
    quieto naquela conversa), o **Robô específico** escolhido para aquela conversa (reaplicado pelo nome) e a
    **autonomia daquela conversa** (piloto automático, copiloto ou híbrido definidos só ali). Os três são
    reaplicados na conversa Cloud e deixam de aparecer como impedimento.
  - **Precisa de decisão sua**: uma **aprovação humana pendente** — uma ação parada esperando alguém aprovar
    ou recusar. Ela **não é movida**, porque aprovar reexecuta a ação parada e reexecutá-la em outra conversa
    não é verificável. A conversa Web é preservada exatamente por isso: abra a conversa apontada na tela,
    aprove ou recuse a pendência e ative de novo.
  - **Não foi possível LER o estado** (Maestro inacessível ou desligado): é falha de comunicação, não estado
    de controle. A mensagem pede para verificar o acesso ao Maestro; não adianta procurar aprovação pendente,
    porque a plataforma nem conseguiu consultar. A verificação para na primeira conversa, então o contador
    não repete o mesmo bloqueio dezenas de vezes.

  Quando algo continua bloqueando, a tela **nomeia as conversas exatas**, com link para abrir cada uma, e
  oferece **ativar mesmo assim**. Essa confirmação vale **somente para as conversas listadas naquele
  momento** — se um novo impedimento aparecer depois, ele bloqueia de novo. Não existe liberação geral. Em
  qualquer bloqueio, as duas caixas continuam visíveis e nenhum histórico do lote é alterado.
- **O progresso mostra "0 · 0 · 0" mesmo com conversas bloqueadas**: corrigido. A linha de progresso agora
  tem segmentos separados para **congeladas e vinculadas**, **já vinculadas**, **ignoradas com segurança** e
  — em destaque — **bloqueadas**, com quantas conversas foram verificadas. Bloqueada não é o mesmo que
  ignorada com segurança.
- **Este número já tem outra caixa de WhatsApp**: se a caixa Web subir em um número que já tem uma caixa
  Cloud na mesma conta **sem par entre elas**, a tela de conexão mostra um aviso. Isso é permitido, mas as
  duas caixas recebem as mesmas conversas de forma independente e o histórico fica dividido. O aviso some
  sozinho quando você pareia as duas na aba **Híbrido**. É um aviso, não um bloqueio.
- **Mensagem duplicada após um envio Web**: confirme que as caixas permanecem pareadas. A reconciliação usa
  o identificador Web embutido no `wamid`; não apague o selo de transporte nem recrie a mensagem à mão.
- **Custos zerados**: a sincronização roda periodicamente; use **Sincronizar agora** na seção Custos.
- **Chamada recebida não toca no painel**: verifique a conexão/engine Web e os logs de `CallOffer`. Se não
  houver oferta no gateway, a limitação é upstream e a chamada pode tocar somente no celular. Uma chamada
  de saída na mesma sessão ajuda a confirmar que a sinalização Web local está saudável.

## Veja também

- [Coexistence do WhatsApp Cloud](/hc/ajuda/articles/inboxes-channels-whatsapp-coexistence-pt-br)
- [WhatsApp Cloud com Embedded Signup](/hc/ajuda/articles/inboxes-channels-whatsapp-cloud-embedded-signup-pt-br)
- [WhatsApp Web](/hc/ajuda/articles/inboxes-channels-whatsapp-web-wazmeow-pt-br)
- [WhatsApp Hub: grupos, comunidades, canais e status](/hc/ajuda/articles/inboxes-channels-whatsapp-hub-grupos-comunidades-canais-status-pt-br)