# Como configurar a API Oficial do WhatsApp (WABA)

Esta documentação detalha o processo completo para configurar a API Oficial do WhatsApp (também conhecida como WABA ou Cloud API) e conectá-la à plataforma Z-PRO.

Seguir os passos na ordem correta é fundamental para garantir uma instalação bem-sucedida. 

### Live - Criação de App no facebook developers e integração com a API Oficial, Instagram e Facebook

{% embed url="<https://youtu.be/MpMQsRT6ba4>" %}

## Tutorial passo-a-passo:

### Vídeo 1: Criar número de telefone

{% embed url="<https://youtu.be/tS1vTy_x1Oc>" %}

### Vídeo 2: Configurando número na Meta

{% embed url="<https://youtu.be/F4K-X0-nx7s>" %}

### Vídeo 3: Configurando WABA no Z-PRO

{% embed url="<https://youtu.be/iTkpUxweMYM>" %}

### Vídeo 4: Configurando Webhook de callback

{% embed url="<https://youtu.be/w6UL_EEUKKg>" %}

### Vídeo 5: Registrar o número e criar templates de mensagens

{% embed url="<https://youtu.be/i55tBINrYfw>" %}

***

## Documentação das etapas:

## Etapa 1: Pré-requisitos e Preparação

Antes de começar, você precisará de dois itens essenciais:

1. **Uma conta no Facebook.**
2. **Um número de telefone** (pode ser virtual ou um chip físico).

{% hint style="danger" %}
**AVISO SOBRE O NÚMERO DE TELEFONE**

* Você **não pode** usar o mesmo número no aplicativo normal do WhatsApp e na API Oficial.
* Se você deseja usar um número que já possui uma conta de WhatsApp, é **obrigatório excluir permanentemente a conta** de WhatsApp associada a ele antes de continuar. Não basta apenas deletar o aplicativo.
* Para testes, recomendamos fortemente a compra de um número virtual.
  {% endhint %}

***

## Etapa 2: Criação e Configuração do Aplicativo na Meta

Nesta etapa, vamos criar o aplicativo no ambiente da Meta que será responsável por gerenciar a API.

1. **Acesse o Facebook for Developers:** Faça o login com sua conta do Facebook em <https://developers.facebook.com/>&#x20;

<figure><img src="/files/GscKwoi4d6Z5O4PSuPe7" alt=""><figcaption></figcaption></figure>

2. **Crie um Novo Aplicativo:**

* Clique em "Criar Aplicativo".

<figure><img src="/files/Jr01G18kgEUnksUnrQd7" alt=""><figcaption></figcaption></figure>

* Selecione "Outros"
* Selecione o tipo **"Business"**.

<figure><img src="/files/DDHBv5Bvre405QUDgHfE" alt=""><figcaption></figcaption></figure>

* Dê um nome ao seu aplicativo (ex: "Waba Cloud API") e associe-o à sua conta do Gerenciador de Negócios (BM).

3. **Adicione o Produto WhatsApp:** No painel do seu novo aplicativo, encontre e adicione o produto "WhatsApp".

<figure><img src="/files/iQGRqhrsRxj5XrEVxg5h" alt="" width="231"><figcaption></figcaption></figure>

4. **Configure as Informações Básicas:**

* Acesse **"Configurações do app" > "Básico"**.

<figure><img src="/files/YsEAibM18Yp1iZFNnMA6" alt="" width="205"><figcaption></figcaption></figure>

* Preencha os campos **"URL da Política de Privacidade"** e **"URL dos Termos de Serviço"**.

5. **Ative o Aplicativo:** No topo da página, mude o status do aplicativo de "Em desenvolvimento" para **"Ao vivo"**.

<figure><img src="/files/znDMyDdQ1q5ghlNZY51Y" alt="" width="267"><figcaption></figcaption></figure>

***

## Etapa 3: Cadastrando e Verificando seu Número de Telefone

Agora, vamos adicionar e verificar o número de telefone que será usado pela API.

1. No menu do seu aplicativo, vá para **"WhatsApp" > "Configuração da API"**.

<figure><img src="/files/gRrTRqjzWOTVBJor8dVJ" alt="" width="205"><figcaption></figcaption></figure>

2. **Adicione um Número de Telefone:** Clique no botão para adicionar um novo número.

<figure><img src="/files/lV6XtEQB9EinZHLTKqqg" alt="" width="375"><figcaption></figcaption></figure>

3. **Preencha os Dados:** Insira as informações da sua empresa e o número de telefone que você preparou na Etapa 1.
4. **Verifique o Número:** Escolha receber o código de verificação por SMS ou ligação telefônica e insira o código recebido.
5. **Adicione a forma de pagamento**

<figure><img src="/files/AxawAkF3r6vmQqSaKmoZ" alt="" width="375"><figcaption></figcaption></figure>

6. **Registre o Número com PIN (Passo Obrigatório):**

* Após a verificação, a Meta exige um registro de segurança com um PIN de 6 dígitos. Este passo é realizado via API. (token provisório)

<figure><img src="/files/eJOQDIqZGRANvrlBZfQY" alt=""><figcaption></figcaption></figure>

* Utilize uma ferramenta como o **Postman** e o endpoint **"Registrar Fone"** (disponível em nossa coleção) para enviar o PIN de 6 dígitos ao seu número. <https://www.postman.com/meta/whatsapp-business-platform/request/kkn2spv/register-phone>
* Este passo é crucial para que o número seja ativado com sucesso.

{% hint style="info" %}
A explicação detalhada da etapa do postman está no vídeo <https://www.youtube.com/watch?v=sLp5P9Qb50w>
{% endhint %}

***

## Etapa 4: Gerando um Token de Acesso Permanente

O token gerado pelo painel do desenvolvedor é temporário e expira em 24 horas. Para uma conexão estável com o Z-PRO, você precisa de um token permanente.

1. **Acesse as Configurações do Negócio:** Navegue até seu **Gerenciador de Negócios** (BM).
2. Vá para **"Usuários" > "Usuários do sistema"**.

<figure><img src="/files/hqZ87eFOVCBlqSKSm0px" alt="" width="275"><figcaption></figcaption></figure>

3. **Crie um Usuário do Sistema:** Adicione um novo usuário do sistema com a função de **"Admin"**.
4. **Atribua Ativos:** Com o novo usuário selecionado, clique em **"Atribuir Ativos"**.
5. Selecione **"Aplicativos"**, escolha o aplicativo que você criou na Etapa 2 e conceda a permissão de **"Gerenciar App"**.
6. **Gere o Token:** Ainda com o usuário selecionado, clique em **"Gerar novo token"**.
   * Selecione o seu aplicativo.
   * Defina a expiração como **"Nunca"**.
   * Marque as permissões necessárias (pelo menos `whatsapp_business_management` e `whatsapp_business_messaging`).
   * Clique em "Gerar Token", copie o código e **guarde-o em um local seguro**, pois ele não será exibido novamente.

***

## Etapa 5: Conectando a API no Z-PRO e Ativando Webhooks

Com tudo pronto no ambiente da Meta, o passo final é configurar a conexão dentro do Z-PRO.

Vídeo detalhado na nossa área de membros: <https://portal.zdg.com.br/270021-sistema-zpro/5179477-conectar-api-oficial>

1. **Conecte o Canal no Z-PRO (Para Enviar Mensagens):**

   * No painel Admin do Z-PRO, acesse **"Canais"** e adicione um novo canal do tipo **"WABA"**.

   <figure><img src="/files/p6DsGe7tsn3mWpNNnw65" alt=""><figcaption></figcaption></figure>

   * Preencha os campos com as informações obtidas no painel da Meta: Whatsapp - Configuração da API
     * **ID do número de telefone**
     * **ID da conta do WhatsApp Business**
     * O **Token Permanente** que você gerou na Etapa 4.
   * Clique em Salvar. Neste momento, você já estará apto a **enviar** mensagens.
2. **Ative os Webhooks no Z-PRO (Para Receber Mensagens):**

   * No painel Admin do Z-PRO, vá para **"Configurações" > "Integração Meta"**.
   * Copie a **URL do Webhook** e o **Token de Verificação**.
   * Volte ao painel do seu aplicativo na Meta, em **"WhatsApp" > "Configuração da API"**.

   <figure><img src="/files/pKJzNgX67kLxTifXWdz8" alt=""><figcaption></figcaption></figure>

   * Clique em "Editar" na seção de Webhooks.
   * Cole a **URL** e o **Token** copiados do Z-PRO e clique em "Verificar e Salvar".
   * Após verificar, clique em **"Gerenciar"** e assine (**subscribe**) todos os eventos de webhook disponíveis (especialmente `messages`).

   <figure><img src="/files/ApLoZmwZoOI6e5nYZk6I" alt="" width="375"><figcaption></figcaption></figure>

### Encerramento

Com os webhooks ativos, sua plataforma está pronta para enviar e receber mensagens através da API Oficial do WhatsApp. Esta é a conexão mais estável e segura, recomendada para todas as operações.

### Possíveis erros

**Solução de Problemas: Evite falhas de comunicação com o Webhook da Meta (Erro ETIMEDOUT)**

Os erros `AxiosError` do tipo **"ETIMEDOUT"** registrados no log indicam que a comunicação com o servidor da Meta (Webhook) está sofrendo atraso de resposta — geralmente causado por alta latência de rede.

Isso ocorre quando o ping entre sua VPS e o domínio `graph.facebook.com` ultrapassa 40 ms, resultando em falhas do tipo TIMEDOUT nas requisições.

Para prevenir esse problema, é importante definir uma rota pública estável em sua VPS. Se você utiliza a **Hostinger**, por exemplo, o caminho é:

1. Acesse o painel da Hostinger.
2. Vá até **Configurações → Rede → DNS**.
3. Defina um DNS fixo recomendado, como:
   * `1.1.1.1` (Cloudflare)
   * `8.8.8.8` (Google)

Essas configurações ajudam a garantir uma rota mais direta e estável entre a VPS e a infraestrutura da Meta, reduzindo atrasos e eliminando o erro de timeout nos logs.

<figure><img src="/files/LfxttMErmRGdxT7fL0Ob" alt=""><figcaption></figcaption></figure>

## Links de apoio - Meta API

**Como configurar a API Oficial do WhatsApp (WABA)**

{% embed url="<https://ajuda.zdg.com.br/api-oficial-waba/como-configurar-a-api-oficial-do-whatsapp-waba>" %}

**Guia Verificação do app (tech provider)**

<https://comunidade.zdg.com.br/geral/coexistence-whatsapp/>

**Guia Configuração coexistência:**

{% embed url="<https://ajuda.zdg.com.br/api-oficial-waba/api-oficial-cadastro-incorporado-e-coexistencia-waba-beta>" %}

**Configuração login incorporado:**

{% embed url="<https://ajuda.zdg.com.br/configuracao-superadmin/canais-e-integracoes-superadmin/facebook-login-incorporado-waba-insta-messenger>" %}

**Configuração instagram nativo:**

{% embed url="<https://ajuda.zdg.com.br/configuracao-administrador/administracao-painel-admin/canais-de-comunicacao/facebook-e-instagram-nativo/canal-instagram-nativo-beta>" %}

**Configuração facebook messenger nativo:**

{% embed url="<https://ajuda.zdg.com.br/configuracao-administrador/administracao-painel-admin/canais-de-comunicacao/facebook-e-instagram-nativo/canal-facebook-messenger-nativo-beta>" %}

**Guia da Meta para configuração do login incorporado:**\
[https://developers.facebook.com/docs/facebook-login/facebook-login-for-business/\ <br>](https://developers.facebook.com/docs/facebook-login/facebook-login-for-business/)**Guia da Meta para configuração da coexistência:**\
[https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users<br>](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users)

**Central de ajuda e suporte técnico meta:**

<https://developers.facebook.com/support/>

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ajuda.zdg.com.br/configuracao-administrador/administracao-painel-admin/canais-de-comunicacao/como-configurar-a-api-oficial-do-whatsapp-waba.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.