# Conectar o WhatsApp

> Como ligar um número de WhatsApp em coexistência ou só pela API, pelo cadastro oficial da Meta.

## Escolha o modo

O Messajo conecta números pelo cadastro oficial da Meta (Embedded Signup), em dois modos. A escolha é feita na hora de conectar e muda o que o número consegue fazer:

| | Coexistência ("Manter meu WhatsApp Business") | Só API ("Número novo, só pela API") |
|---|---|---|
| App WhatsApp Business no celular | Continua funcionando, com as mensagens enviadas pelo celular chegando à API (`message.echo`) | O número fica dedicado à integração |
| Velocidade de envio | Fixa em 20 msg/s | 80 msg/s, ou 1.000 msg/s quando a Meta libera vazão alta |
| Histórico de 6 meses e contatos | Sincronizados uma vez, dentro de 24 h | Não há |
| Perfil, nome exibido e username | Editados no app do celular | Editados pelo painel ou pela API |
| Registro do número | O número não é registrado de novo | Registrado com um PIN aleatório de 6 dígitos, guardado cifrado |
| Parceiros ao mesmo tempo | Só um | Vários |

Use a coexistência quando o atendimento continua no celular. Use o modo só API para volume ou para um número novo.

## Requisitos

- Um portfólio de negócios na Meta e acesso de admin a ele.
- Um número de telefone para conectar.
- Na coexistência: o número já ativo no app WhatsApp Business **2.24.17 ou mais novo**.
- No modo só API: um número que possa receber o código de verificação por SMS ou ligação e que não esteja em uso no app.
- No painel, o papel de dono ou admin, com o 2FA ligado.

## Passo a passo no painel

1. Abra **Conexões** e clique em **Conectar WhatsApp**.
2. Escolha o modo: **Manter meu WhatsApp Business** (coexistência) ou **Número novo, só pela API**. Na coexistência, o painel mostra a lista de [limites](#limites-da-coexistência) antes de seguir. Clique em **Continuar**.
3. Clique em **Abrir o popup da Meta**. O popup abre em outra janela: não feche a página do painel. Se o navegador bloquear, libere popups do endereço do painel e tente de novo.
4. No popup, faça login no Facebook, escolha (ou crie) o portfólio e a conta de mensagens, e escolha o número.
5. Na coexistência, confirme no app do celular lendo o QR code que a Meta mostra. No modo só API, confirme o número com o código por SMS ou ligação.
6. Ao fechar o popup, o painel mostra **Concluindo a conexão…** e, em seguida, **WhatsApp conectado.** A conexão aparece como **Ativa** e sai o evento `connection.created`.

Na conclusão, o servidor troca o código do popup pelo token da conta (guardado cifrado), confere que a conta escolhida é mesmo a que o popup autorizou, inscreve o app nos webhooks da conta, registra o número (só API) e lê a saúde do número. Contas banidas ou sinalizadas pela Meta são recusadas antes de qualquer alteração na Meta, com o erro [`account_flagged`](/errors#account_flagged).

### Quando falta um passo

Se um passo depois da inscrição falhar, a conexão fica **Pendente** e o painel mostra o motivo, por exemplo "O registro do número na Meta falhou.". Na página da conexão:

- **Tentar registrar de novo** refaz só o registro do número (só API). A Meta aceita até 10 registros por número em 72 h.
- **Concluir conexão** refaz o que faltou, sem abrir o popup de novo.

Cada passo, do popup e do servidor, fica gravado na aba **Histórico** da conexão. Um cancelamento no popup aparece lá com a etapa em que a pessoa parou.

## Convidar o cliente por link

Agências podem conectar o número de um cliente sem que ele crie conta no Messajo. Em **Links de conexão**, clique em **Criar link** e configure (o botão **Criar link de conexão**, em **Conexões**, leva para lá):

| Campo | O que é |
|---|---|
| **Rótulo** | Nome do link, só a sua equipe vê |
| **Canal** | WhatsApp. Instagram e Messenger chegam na `0.2.0-alpha` |
| **Modo** | Coexistência, só API ou "escolhido por quem abrir" |
| **Validade** | 1 hora, 24 horas, 3, 7, 14 ou 30 dias. Padrão: 7 dias |
| **Reaproveitável** | Desligado, o link vale para um número só; ligado, para vários |
| **Senha (opcional)** | De 8 a 128 caracteres, pedida antes de abrir o cadastro |
| **Idioma da página** | Idioma da página e do e-mail: português, inglês ou espanhol |
| **Reconectar uma conexão (opcional)** | Faz do link uma reconexão: herda o modo da conexão e vale uma vez só |
| **Enviar por e-mail para (opcional)** | Manda o link por e-mail já na criação |

A URL do link (`https://<painel>/c/<token>`) aparece **uma única vez**, na criação: o Messajo guarda só o hash do token. Copie e envie por onde quiser, ou mande pelo e-mail da plataforma. **Enviar por e-mail** gera um token novo, e a URL anterior deixa de valer. A senha nunca vai no e-mail: combine com o cliente por outro canal.

A página do convite não pede login. Ela mostra o nome e o logo da sua organização, deixa trocar o idioma, explica os modos e os limites da coexistência e abre o mesmo popup da Meta. Ao terminar, mostra "Conexão feita. Pode fechar esta página." A conexão fica com a sua organização: o cliente não ganha acesso a nada.

- Cinco senhas erradas seguidas bloqueiam o link por 15 minutos ([`link_locked`](/errors#link_locked)).
- Link de uso único já usado responde [`link_used`](/errors#link_used); vencido, [`link_expired`](/errors#link_expired). Para tirar um link do ar antes do prazo, use **Revogar**.
- O logo vem de **Configurações → Organização**.

Os links também podem ser criados pela API, em `POST /v1/connection-links` (permissão `admin`). Veja a [referência da API](/reference).

## Limites da coexistência

A Meta impõe estas regras a todo número em coexistência:

- velocidade fixa de 20 msg/s;
- grupos não sincronizam;
- listas de transmissão ficam só leitura;
- mensagens temporárias e de visualização única são desligadas;
- o app precisa ser aberto a cada ~14 dias;
- exige WhatsApp Business 2.24.17 ou mais novo;
- só um parceiro por vez.

## Sincronização da coexistência

Logo depois de conectar em coexistência, o Messajo pede à Meta os contatos do app e, em seguida, até 6 meses de conversas. A aba **Sincronização** da conexão mostra cada um:

| Status | O que quer dizer |
|---|---|
| **Na fila** | Ainda não foi pedida, ou vai ser pedida de novo depois de uma falha |
| **Pedida à Meta** | A Meta aceitou o pedido e está mandando os dados |
| **Concluída** | Tudo chegou. O histórico mostra o progresso em % por fase |
| **Recusada** | A pessoa recusou o compartilhamento do histórico no celular |
| **Prazo de 24 h vencido** | A Meta só aceita o pedido até 24 h depois da conexão |

Cada sincronização acontece uma vez só. Se o pedido falhar, o Messajo tenta de novo em 1 min, 5 min, 15 min, 1 h, 3 h e 6 h, sempre dentro das 24 h. Uma falha aqui nunca derruba a conexão. Os contatos chegam como evento `contacts.sync` e as conversas como `history.batch`, e as mensagens importadas aparecem nos logs com a origem `history`.

## Trocar de parceiro na coexistência

Na coexistência o número aceita um parceiro por vez. Para trazer um número que já está com outro provedor:

1. Faça backup das conversas no app.
2. No app, vá em **Configurações > Conta > Plataforma Business > Desconectar**.
3. Conecte de novo pelo Messajo, como no passo a passo acima.

O parceiro antigo recebe o aviso `PARTNER_REMOVED` da Meta. Se aparecer um erro de linha de crédito do parceiro anterior, siga o [guia da Meta para coexistência](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users).

## Depois de conectar

A aba **Visão geral** da conexão mostra a **Saúde** do número:

- **Qualidade**: Alta, Média, Baixa ou Sem nota, como a Meta mede;
- **Faixa de envio**: quantos contatos novos por 24 h o portfólio pode alcançar (veja [Limites](/api/limits#limite-de-mensagens-da-meta));
- **Velocidade**: 20, 80 ou 1.000 msg/s, a vazão usada no envio;
- **Envio**: Liberado, Limitado ou Bloqueado;
- a restrição, quando a Meta restringe a conta, com o prazo.

O Messajo lê a saúde a cada 15 minutos. **Atualizar saúde** lê na hora. A aba **Perfil** edita o perfil do negócio, pede a troca do nome exibido e define o username (só no modo só API).

Cada mudança de status gera um evento `connection.*` nos seus [destinos de eventos](/webhooks/events/), com o motivo em `reason`, e um e-mail para donos e admins, no idioma de cada um.

## Quando a conexão cai

| Status | Quando | O que fazer |
|---|---|---|
| **Precisa reconectar** | A Meta invalidou o token (erro `190`), numa leitura de saúde ou num envio | Reconectar |
| **Restrita** | A Meta restringiu a conta por um prazo, ou bloqueou o envio por política | Esperar o prazo e corrigir a causa no Gerenciador do WhatsApp. O envio continua liberado onde a Meta deixar |
| **Desativada** | Violação de política ou banimento | Recorrer na Meta. Se ela reativar, a conexão volta a **Ativa** sozinha |
| **Desconectada** | O app foi removido da conta, a conta ou o número foi apagado, ou alguém desconectou pelo painel | Conectar de novo |

No erro `190`, o e-mail para donos e admins traz um **link de reconexão**. Na página da conexão, **Reconectar** abre o popup de novo, e **Gerar link de reconexão** cria um link para mandar a quem administra o número. A reconexão precisa ser do **mesmo número** ([`reconnect_mismatch`](/errors#reconnect_mismatch)) e mantém o `id` da conexão, o histórico e os destinos.

Reconectar uma conexão **Desconectada** conta como conexão nova na cobrança; reconectar uma em **Precisa reconectar** não. Uma conta do WhatsApp Business (WABA) pertence a uma organização só: conectá-la em outra devolve [`waba_owned_by_other_org`](/errors#waba_owned_by_other_org). Uma conexão **Desconectada** nunca volta a **Ativa** sozinha: só reconectando pelo painel.

**Desconectar** para de receber e enviar pelo número. No modo só API, dá para também cancelar o registro do número na Meta. Na coexistência, o painel mostra como remover o acesso no app do celular.
