> ## Documentation Index
> Fetch the complete documentation index at: https://developer.zapsterapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Conectando uma instância WABA
> Como criar e conectar uma instância usando a API oficial do WhatsApp
Existem duas formas de conectar uma instância WABA na Zapster: pelo dashboard (Embedded Signup) ou pela API (token manual). O Embedded Signup é o método recomendado para a maioria dos usuários.
## Método 1: Embedded Signup (recomendado)
O Embedded Signup é o jeito mais rápido de conectar. Você faz login na sua conta do Facebook, seleciona o número e pronto.
No dashboard da Zapster, clique em **Criar instância** e selecione a opção **WhatsApp Business (Oficial)**.
Clique no botão de conexão. Uma janela do Facebook vai abrir pedindo login.
Escolha a conta WhatsApp Business que deseja conectar. Se você não tem uma, pode criar durante o processo.
Escolha o número que será conectado à instância. O número precisa estar verificado na Meta.
Confirme a autorização. A Zapster vai configurar tudo automaticamente: webhook, credenciais, e a instância já estará pronta para uso.
Depois de conectar, você já pode enviar mensagens pelo mesmo endpoint `POST /v1/wa/messages` que usa para instâncias não oficiais. Não precisa mudar nada na integração.
## Método 2: Token manual (avançado)
Se você já tem um System User Token da Meta e prefere criar a instância via API, pode usar o endpoint de criação diretamente.
### O que você vai precisar
Antes de começar, você precisa de três informações do [Meta Business Manager](https://business.facebook.com/settings). Abaixo mostramos onde encontrar cada uma.
O System User Token precisa ter as permissões `whatsapp_business_management` e `whatsapp_business_messaging`. Sem elas, a criação vai falhar.
#### System User Token
O token é gerado na área de Usuários do sistema dentro das Configurações do Meta Business Manager.
1. No menu lateral, clique em **Usuários** e depois em **Usuários do sistema**
2. Selecione o usuário que vai se conectar (ou crie um novo clicando em **Adicionar**)
3. Clique no usuário e gere um novo token com as permissões necessárias
#### Phone Number ID
O Phone Number ID é o identificador interno que a Meta usa para o seu número. Não é o número de telefone em si.
1. No menu lateral, clique em **Contas de WhatsApp**
2. Selecione a conta que contém o número desejado
3. Clique no número de telefone para abrir os detalhes. O **Phone Number ID** aparece no painel lateral direito, abaixo do nome de exibição
#### WABA ID
O WABA ID é o identificador da conta WhatsApp Business como um todo (não do número individual).
1. No menu lateral, clique em **Contas de WhatsApp**
2. Selecione a conta desejada
3. Clique na aba **Phone Numbers** (ou **Números de telefone**). O **WABA ID** aparece no topo da página, ao lado do nome da conta
### Criando a instância via API
```bash cURL theme={null}
curl -X POST https://api.zapsterapi.com/v1/wa/instances \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"connection_type": "waba",
"name": "Meu WhatsApp Oficial",
"waba": {
"access_token": "EAAxxxxxxx...",
"phone_number_id": "1016102021584086",
"waba_id": "419378847918255"
}
}'
```
```javascript JavaScript theme={null}
const response = await fetch('https://api.zapsterapi.com/v1/wa/instances', {
method: 'POST',
headers: {
'Authorization': 'Bearer SEU_TOKEN',
'Content-Type': 'application/json',
},
body: JSON.stringify({
connection_type: 'waba',
name: 'Meu WhatsApp Oficial',
waba: {
access_token: 'EAAxxxxxxx...',
phone_number_id: '1016102021584086',
waba_id: '419378847918255',
},
}),
});
const instance = await response.json();
console.log(instance);
```
Se tudo der certo, a resposta inclui a instância criada com status `connected`. A Zapster registra o webhook na Meta automaticamente.
#### Usando o seu próprio app Meta (BYO-app)
Se o seu System User Token pertence ao **seu próprio app Meta** (e não ao app da Zapster), os webhooks de entrada são assinados com o **App Secret do seu app**. Para que a Zapster verifique a autenticidade desses eventos, informe os campos opcionais abaixo no objeto `waba`:
* `app_secret`: App Secret do seu app Meta. Quando informado, a assinatura HMAC (`X-Hub-Signature-256`) dos webhooks é validada contra ele, garantindo a verificação completa de autenticidade dos eventos. É armazenado **criptografado em repouso** (AES-256), igual ao `access_token`.
* `app_id`: ID do seu app Meta. Usado apenas para identificação/auditoria — não é segredo e não participa da validação de assinatura.
* `webhook_verify_token`: token de verificação do webhook. Se omitido, a Zapster gera um aleatório. Também armazenado criptografado em repouso.
Sempre que o seu System User Token pertencer ao seu próprio app Meta, informe o `app_secret`. Como os webhooks são assinados com o segredo do seu app, é ele que permite à Zapster fazer a verificação completa da assinatura HMAC e garantir a autenticidade de cada evento recebido.
## Segurança dos dados
Seus dados sensíveis são protegidos em todas as etapas:
* **Token de acesso**: armazenado com criptografia AES-256-CBC, o mesmo padrão usado por bancos e fintechs. O token original nunca é salvo em texto puro.
* **Sem exposição**: o token não aparece em logs, webhooks, respostas da API nem no dashboard. Nem a equipe da Zapster tem acesso ao valor original.
* **Webhooks da Meta**: todos os eventos recebidos da Meta são validados por assinatura HMAC-SHA256 antes de serem processados. Eventos com assinatura inválida são descartados.
Se você precisar trocar o token (por exemplo, se o anterior expirou), crie uma nova instância WABA. O token antigo é removido junto com a instância.
## O que muda no uso da API?
Nada. Depois que a instância WABA está criada, os endpoints são os mesmos:
* `POST /v1/wa/messages` para enviar mensagens
* `DELETE /v1/wa/messages/:id` para cancelar agendadas
* `GET /v1/wa/messages` para listar histórico
A Zapster detecta automaticamente o tipo da instância e roteia para a Cloud API da Meta ou para a conexão não oficial.
A única diferença é que instâncias WABA suportam **templates de mensagem** (campo `template` no body) e **não suportam envio para grupos**.
## Próximos passos
* [Entenda as diferenças entre WABA e não oficial](/pt-BR/v1/guides/waba-vs-unofficial)
* [Veja como enviar mensagens](/pt-BR/v1/api-reference/messages/sending)
* [Configure webhooks para receber eventos](/pt-BR/v1/webhooks/setting-up-webhook)