> For the complete documentation index, see [llms.txt](https://ajuda.digitalsac.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.digitalsac.io/digicrm/operacao-uso-do-sistema/whatsapp-tech-provider-conectar-com-facebook.md).

# WhatsApp Tech Provider (Conectar com Facebook)

Com o **Tech Provider** configurado, os clientes conectam o WhatsApp Business oficial (Cloud API) em poucos cliques pelo botão **Conectar com Facebook** — sem colar token, phone number ID ou qualquer campo manual. Cada número nasce no Business Manager **do próprio cliente**, com o cartão do cliente pagando a Meta diretamente.

Sem o Tech Provider configurado, nada muda: a conexão WABA continua pelo formulário manual de sempre.

**Caminho:** Configurações → **Globais** → aba **WhatsApp Tech Provider** (apenas master) e, para o cliente, Configurações → **Conexões** → Nova conexão → **WABA Oficial**.

### Parte 1 — O que criar na Meta (feito uma única vez pela operação)

1. Tenha um **Business Manager verificado** ([business.facebook.com](https://business.facebook.com) → Configurações → Central de Segurança → Verificação).
2. Crie um **app** em [developers.facebook.com](https://developers.facebook.com) do tipo **Business** e adicione o produto **WhatsApp**.
3. Inscreva-se no programa **Tech Provider** e solicite **Acesso Avançado** para as permissões `whatsapp_business_management` e `whatsapp_business_messaging`.
4. Adicione também o produto **Facebook Login for Business** ao app e, em **Settings → Client OAuth settings**, ligue *Client OAuth login*, *Web OAuth login*, *Enforce HTTPS*, *Embedded Browser OAuth Login*, *Use Strict Mode for redirect URIs* e **Login with the JavaScript SDK**; em *Allowed domains for the JavaScript SDK*, adicione o(s) domínio(s) do painel.
5. Em **Facebook Login for Business → Configurations → Create configuration**: dê um nome, escolha a variação **WhatsApp Embedded Signup**, selecione validade de token **sem expiração** (não use o template de token de 60 dias) e marque apenas as permissões `whatsapp_business_management` e `whatsapp_business_messaging`. Se houver a opção de onboarding de números do app WhatsApp Business (coexistência), habilite. Ao salvar, copie o **Configuration ID** gerado.
6. Em **Configurações do app → Básico**, anote o **App ID** e o **App Secret**.
7. Em **Configurações do app → Básico → Domínios do app** (e nos domínios permitidos do SDK do JavaScript), adicione o(s) domínio(s) do painel — um app atende **várias instalações**: basta listar todos os domínios.

\[\[FOTO: painel da Meta com App ID/Secret]]

### Parte 2 — Configurar no DigitalSac

1. Acesse **Configurações Globais → aba WhatsApp Tech Provider** (apenas o usuário master).
2. Cole **App ID**, **App Secret** e **Config ID**.
3. Clique em **Gerar** no campo *Verify Token* e em **Salvar**.
4. Copie a **URL de callback do webhook** exibida na tela e o *Verify Token*, e cole ambos na Meta em **WhatsApp → Configuração → Webhook** do app. Assine o campo (field) `messages`.
5. Use **Validar credenciais** para conferir que App ID + Secret estão corretos.

> 💡 A mesma revenda com várias instalações usa **o mesmo app** em todas: o sistema assina cada número com webhook próprio da instalação (override por WABA), então os eventos chegam sempre na instalação que conectou o número.

\[\[FOTO: aba WhatsApp Tech Provider preenchida]]

### Parte 3 — Como o cliente conecta

1. Em **Configurações → Conexões → Nova conexão**, escolha o tipo **WABA Oficial**.
2. Clique em **Conectar com Facebook**, faça login e siga o fluxo (escolher/criar o portfólio empresarial, a conta WhatsApp Business e o número).
3. Ao terminar, os campos do formulário são preenchidos automaticamente — confira e clique em **Salvar**.
4. Se o número for novo, o sistema o registra e exibe o **PIN de verificação em duas etapas** gerado — **guarde esse PIN**.

\[\[FOTO: banner Conectar com Facebook no modal de conexão]]

### Coexistência (número no celular + painel ao mesmo tempo)

O sistema suporta o modo **coexistência** da Meta: o número continua funcionando no app WhatsApp Business do celular E no DigitalSac simultaneamente.

* **Conectar**: no mesmo botão *Conectar com Facebook*, o cliente escolhe usar o número que já está no app e escaneia o QR code pelo celular (a opção precisa estar habilitada na configuração do Embedded Signup do app na Meta).
* **Mensagens do celular aparecem no painel**: o que o dono do número responde pelo app chega ao ticket como mensagem enviada (evento `smb_message_echoes`) — incluindo mídia, edição e apagar para todos.
* **Requisito**: no webhook do app na Meta, assine também o campo `smb_message_echoes` (além de `messages`).
* **Limite atual**: a importação do histórico de conversas antigas ainda não é feita — as conversas passam a aparecer do momento da conexão em diante. Os eventos `history` e `smb_app_state_sync` chegam e são reconhecidos no log, mas nada é importado a partir deles.

### Mensagens e erros comuns

Estes códigos aparecem **como estão** na tela — ainda não têm mensagem traduzida.

| Código na tela                        | O que significa                                               | O que fazer                                                                                                 |
| ------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `ERR_META_TP_NOT_CONFIGURED`          | A instalação não tem App ID/Secret/Config ID preenchidos      | Preencher a aba **WhatsApp Tech Provider** nas Globais                                                      |
| `ERR_META_TP_MISSING_CREDENTIALS`     | Validação disparada sem App ID ou App Secret                  | Preencher os dois campos antes de validar                                                                   |
| `ERR_META_TP_MISSING_CODE`            | O fluxo da Meta terminou sem devolver o código de autorização | Refazer o **Conectar com Facebook**; costuma ser janela fechada antes do fim                                |
| `ERR_META_TP_MISSING_SESSION_INFO`    | A Meta não devolveu a conta WhatsApp Business ou o número     | Refazer o fluxo e concluir a escolha do portfólio, da conta e do número                                     |
| `ERR_META_TP_CODE_EXCHANGE`           | A Meta recusou a troca do código pelo token                   | App Secret errado, app sem Acesso Avançado, ou domínio do painel não listado no app                         |
| `ERR_META_TP_SUBSCRIBE`               | O token saiu, mas a assinatura do webhook da conta falhou     | Conferir a URL de callback e o Verify Token na Meta; a conexão pode ser salva e a assinatura refeita depois |
| Registro do número falhou pedindo PIN | O número já tinha verificação em duas etapas                  | Desativar a verificação em duas etapas ou registrar com o PIN existente                                     |

***

### Perguntas frequentes

* **O token expira?** Não — o fluxo gera um token de system user de integração, sem validade. Chega de renovar token.
* **Quem paga as mensagens?** O cliente final, diretamente para a Meta, no cartão cadastrado no Business Manager dele.
* **E as conexões manuais antigas?** Continuam funcionando exatamente como estão, para sempre. O manual também segue disponível como alternativa no próprio modal.
* **O registro do número falhou com aviso de PIN?** O número já tinha verificação em duas etapas ativa. Desative a verificação em duas etapas no WhatsApp Business ou registre com o PIN existente, e salve a conexão normalmente.