> For the complete documentation index, see [llms.txt](https://bolten.gitbook.io/bolten-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bolten.gitbook.io/bolten-docs/ativacao-da-marca/whatsapp-cloud-api-oficial.md).

# Whatsapp Cloud API (Oficial)

Existem duas formas de conectar o WhatsApp ao CRM da Bolten. Antes de seguir qualquer passo a passo, entenda a diferença entre elas:

{% embed url="<https://youtu.be/uerVhR90M_s?si=G65UhnBY_3kdRX3o>" %}

|                   | QR Code (não oficial)                | Cloud API (oficial) ✅                   |
| ----------------- | ------------------------------------ | --------------------------------------- |
| Como funciona     | Escaneia um QR Code com o celular    | Conecta direto pela API oficial da Meta |
| Estabilidade      | Pode cair ou ser bloqueada sem aviso | Estável, com suporte contínuo da Meta   |
| Custo de mensagem | Nenhum                               | Cobrado pela Meta por mensagem enviada  |
| Templates         | Não precisa                          | Obrigatório para iniciar conversas      |
| Recomendação      | Testes ou uso temporário             | **Uso profissional e contínuo**         |

***

### Conexão via QR Code (não oficial)

Essa é a forma mais simples: basta escanear um QR Code com o celular e o número já aparece no CRM.

> :warning: **Atenção:** essa modalidade **não é oficial e não tem suporte da Meta**. A conexão pode ser bloqueada ou descontinuada a qualquer momento, sem aviso prévio e sem recurso. Use com cautela.

[**→ Passo a passo para conectar via QR Code**](#conexao-via-qr-code-nao-oficial)

***

### Conexão via WhatsApp Cloud API (oficial) :white\_check\_mark:

Essa é a forma recomendada. A conexão é feita diretamente com a API oficial do WhatsApp, garantindo estabilidade e suporte contínuo.

#### O que você precisa antes de começar

* **Um número cadastrado no Meta Business Manager**\
  O número de WhatsApp precisa estar vinculado a um portfólio no [Meta Business Manager](https://business.facebook.com/). Não basta ser um número comum — ele precisa estar registrado como número de WhatsApp Business API dentro desse portfólio.
* **Verificação de negócio na Meta (recomendado)**\
  Não é obrigatório para começar, mas amplia os limites de envio de mensagem e dá mais credibilidade à conta.
* **Um PIN de 6 dígitos**\
  Durante o registro do número na API, a Meta pede a criação de um PIN de verificação em duas etapas. Esse PIN será solicitado no momento da conexão e também caso você precise migrar ou reativar a conta. **Guarde-o em um lugar seguro.**

***

### 🔄 Conexão tradicional vs. Coexistência

Ao conectar um número via WhatsApp Cloud API, você pode escolher entre dois modos:

* **Conexão tradicional (Cloud API oficial):** o número passa a operar **exclusivamente** pela API. Indicado para números novos ou dedicados ao atendimento.
* **Coexistência:** conecta um número que **já está em uso no app do WhatsApp Business**, permitindo continuar usando o **app e a API ao mesmo tempo**, sem perder o histórico de conversas.

Este guia mostra como fazer a conexão no modo tradicional. Para ver o guia de coexistência, veja [Whatsapp Cloud API (Oficial) - Modo Coexistência](/bolten-docs/ativacao-da-marca/whatsapp-cloud-api-oficial-modo-coexistencia.md).

#### Passo a passo

**1)** Acesse o componente de WhatsApp do seu projeto

**2)** Selecione a opção **"É usuário do WhatsApp Business API? Clique aqui para conectar"**

<figure><img src="https://462218826-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAwAM8hC6256ptjRLGE61%2Fuploads%2FqmP5DXtkZMY17015bfrw%2Fimage.png?alt=media&amp;token=caaf5c4f-4886-4f4a-a8d0-8eaefa756d49" alt=""><figcaption></figcaption></figure>

**3)** Digite o seu PIN de 6 dígitos e clique em **Conectar via Meta**

<figure><img src="https://462218826-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAwAM8hC6256ptjRLGE61%2Fuploads%2F1PzIyALbFuMJtcNEoVnR%2Fimage.png?alt=media&amp;token=e5e3b865-4cb5-4745-97ea-22ffa454bf06" alt=""><figcaption></figcaption></figure>

Você será redirecionado para o login da Meta. Entre com a conta que tem acesso ao portfólio onde o número está cadastrado.

> Pelo fato de a Meta exigir um domínio pré-cadastrado para liberar a conexão com Whatsapp Business, durante essa etapa a URL apresentada no navegador será da própria Bolten, mesmo para projetos com domínio próprio. Após a autenticação, o usuário será redirecionado de volta para o domínio do seu projeto.

**4)** Siga o fluxo da Meta e selecione o número que deseja conectar

<figure><img src="https://462218826-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAwAM8hC6256ptjRLGE61%2Fuploads%2FuWJGqQZWOItJxnfumORn%2Fimage.png?alt=media&amp;token=d58b76cf-bc61-4b2f-8c99-5699fad4f8d4" alt=""><figcaption></figcaption></figure>

**5)** Confirme as informações e clique em **Confirmar**

<figure><img src="https://462218826-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAwAM8hC6256ptjRLGE61%2Fuploads%2FEM2LnG3loZt7lI2xp3pk%2Fimage.png?alt=media&amp;token=40c96598-c991-4f5f-a8a9-49b4030b793a" alt=""><figcaption></figcaption></figure>

**6)** Pronto! :tada: Seu número está conectado via API oficial.

Para testar, envie uma mensagem para o número conectado e veja se ela aparece na tela de conversas do CRM.

> :bulb: **Já usava a conexão via QR Code?** Desconecte o número antigo antes de conectar pela Cloud API. O número só pode estar ativo em um método por vez.

***

#### Depois de conectar: Templates de mensagem

Com a API oficial, você **não pode iniciar uma conversa enviando qualquer mensagem**. Para dar o primeiro contato pelo seu número, é obrigatório usar um **Template** — uma mensagem pré-cadastrada e aprovada pela Meta.

> Se o cliente mandar a primeira mensagem, você pode responder livremente por até **24 horas** sem precisar de template.

**Como funciona na prática:**

**1)** Crie o template dentro da Bolten, definindo um **atalho** (ex: `/boas-vindas`)

<figure><img src="https://462218826-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAwAM8hC6256ptjRLGE61%2Fuploads%2FfWpG250una4iZ4X1b2w2%2Fimage.png?alt=media&amp;token=3e334fd4-a58f-4ef2-86aa-44b5a7db13f6" alt=""><figcaption></figcaption></figure>

<figure><img src="https://462218826-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAwAM8hC6256ptjRLGE61%2Fuploads%2F6qYGsxuQnYb8IQxzsiMJ%2Fimage.png?alt=media&amp;token=631eb903-230f-4d46-92fd-2c58435e5814" alt=""><figcaption></figcaption></figure>

**2)** A Meta analisa e aprova (ou reprova) o conteúdo — costuma levar algumas horas

<figure><img src="https://462218826-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAwAM8hC6256ptjRLGE61%2Fuploads%2FwHq5eHLIpZ1yLwhJKEHg%2Fimage.png?alt=media&amp;token=4bf1db6f-5b45-496a-8152-39ac96b46733" alt=""><figcaption></figcaption></figure>

**3)** Após aprovado, use o template digitando `/atalho` na tela de WhatsApp do CRM

<figure><img src="https://462218826-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAwAM8hC6256ptjRLGE61%2Fuploads%2Fi3hlDAxzGUedxvp8sMYH%2Fimage.png?alt=media&amp;token=26f73c1f-617c-4535-a7ce-7be15d76b306" alt=""><figcaption></figcaption></figure>

***

#### Cobrança por mensagens :moneybag:

Ao contrário da conexão via QR Code, a Cloud API tem custos definidos pela Meta. A cobrança é feita **por mensagem enviada**, e os valores variam conforme o país do destinatário e a categoria da mensagem.

Ao conectar sua conta da Meta no CRM, você terá a opção de adicionar uma forma de pagamento na Business Suite:

<figure><img src="https://462218826-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAwAM8hC6256ptjRLGE61%2Fuploads%2F1zrCAH40WkY5wggUQoRQ%2Fimage.png?alt=media&amp;token=486723d5-dba5-4f1e-87a5-0c26ec50d9f9" alt=""><figcaption></figcaption></figure>

#### **Categorias e preços aproximados**

| Categoria               | Tipo de mensagem                    | Exemplo                                | Preço aprox. (USD) |
| ----------------------- | ----------------------------------- | -------------------------------------- | ------------------ |
| :loudspeaker: Marketing | Promoções, campanhas, reengajamento | Cupom, oferta, carrinho abandonado     | \~$0.0625          |
| :package: Utilidade     | Transacional (ação do usuário)      | Confirmação de pedido, entrega, fatura | \~$0.0080          |

> Valores em dólar americano (USD), definidos e cobrados diretamente pela Meta. Consulte a [tabela oficial de preços](https://developers.facebook.com/docs/whatsapp/pricing) para valores atualizados.

**Regras importantes**

| Regra                           | O que significa                                                          |
| ------------------------------- | ------------------------------------------------------------------------ |
| Cobrança por mensagem           | Você paga por template enviado, não por conversa                         |
| Baseado no país do destinatário | O preço depende de onde está quem recebe                                 |
| Janela de 24h                   | Se o cliente iniciar a conversa, suas respostas são grátis nesse período |
| Só paga se entregar             | Cobrança acontece apenas quando a mensagem é efetivamente entregue       |
| Descontos por volume            | Existem faixas de desconto conforme o volume mensal                      |

***