> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aifocus.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Cloud API (Oficial)

> Configure WhatsApp usando a API oficial da Meta - Embedded Signup ou Manual

# 📱 WhatsApp Cloud API - API Oficial da Meta

Configure o **WhatsApp Business** usando a API oficial da Meta (Facebook). Duas formas de configuração: **rápida via Embedded Signup** ou **manual** com credenciais.

***

## 📋 Visão Geral

**WhatsApp Cloud API** é a solução oficial da Meta para integrar WhatsApp Business:

<CardGroup cols={2}>
  <Card title="Embedded Signup" icon="bolt">
    ⚡ Configuração automática via Meta

    ✅ Recomendado para iniciantes
  </Card>

  <Card title="Manual" icon="wrench">
    🔧 Configuração com credenciais

    ✅ Mais controle técnico
  </Card>
</CardGroup>

***

## ✨ Recursos da API Oficial

### Funcionalidades

✅ **Mensagens de Texto** - Envio e recebimento

✅ **Mídia** - Imagens, vídeos, áudios, documentos

✅ **Localização** - Compartilhar/receber localização

✅ **Contatos** - Enviar vCard

✅ **Templates** - Mensagens pré-aprovadas pela Meta

✅ **Mensagens Interativas** - Botões e listas

✅ **Respostas** - Reply (responder mensagem específica)

✅ **Reações** - Emoji reactions

✅ **Indicadores** - Digitando, lido, entregue

### Limitações

⚠️ **Janela de 24 horas**: Após 24h da última mensagem do cliente, só pode enviar templates aprovados

⚠️ **Templates**: Precisam aprovação da Meta (leva 1-24h)

⚠️ **Limites de mensagem**: Baseado na qualidade da conta

***

## 🚀 Método 1: Embedded Signup (Recomendado)

**Configuração automática em 3 cliques!**

### Pré-requisitos

* Conta Facebook Business
* Ser **administrador** do Facebook Business Manager
* Navegador moderno (Chrome, Edge, Firefox)

### Passo a Passo

1. **Acessar Criar Inbox**

   * Vá em **"Configurações"** → **"Inboxes"**
   * Clique em **"Adicionar Inbox"**
   * Escolha **"WhatsApp"**

2. **Escolher Embedded Signup**

   * Na lista de provedores, selecione: **"WhatsApp Business - Configuração rápida com Meta"**
   * Clique em **"Continuar"**

3. **Conectar com Meta**

   * Clique em **"Conecte-se com WhatsApp Business"**
   * Uma janela pop-up da Meta abrirá
   * Faça login na sua conta Facebook Business

4. **Autorizar Acesso**

   * **Selecione WhatsApp Business Account** ou crie novo
   * **Escolha número de telefone** ou adicione novo
   * **Autorize permissões**: Gerenciar mensagens, Enviar mensagens, Gerenciar templates
   * Clique em **"Continuar"**

5. **Configuração Automática**

   O Chatwoot automaticamente configura tudo para você:

   * ✅ Obtém credenciais da API
   * ✅ Configura webhook
   * ✅ Registra número de telefone
   * ✅ Sincroniza templates

6. **Concluído!**

   * Inbox criada com sucesso ✅
   * Número pronto para usar 📱
   * Templates sincronizados 📋

***

## 🔧 Método 2: Configuração Manual

**Para usuários avançados que querem mais controle.**

### Pré-requisitos

* Conta Facebook Developer
* App Facebook criado
* WhatsApp Business Account (WABA)
* Número de telefone verificado

### Passo 1: Obter Credenciais

**No Facebook Developer Console:**

1. Acesse [developers.facebook.com](https://developers.facebook.com)
2. Vá em seu App
3. Adicione produto **"WhatsApp"**
4. Anote as seguintes informações:

```
Phone Number ID: 1234567890
Business Account ID: 9876543210
API Key (Permanent Token): EAAxxxxxxxxxxxxx
```

### Passo 2: Criar Inbox no Chatwoot

1. **Configurações** → **Inboxes** → **Adicionar Inbox**
2. Escolha **"WhatsApp"**
3. Selecione **"WhatsApp Cloud"** (manual)
4. Preencha:

**Nome da Inbox:**

```
WhatsApp Suporte
```

**Número de Telefone:**

```
+5511999999999
```

**Phone Number ID:**

```
1234567890
```

**Business Account ID:**

```
9876543210
```

**API Key:**

```
EAAxxxxxxxxxxxxx
```

5. Clique em **"Criar Inbox"**

### Passo 3: Configurar Webhook na Meta

1. No Facebook Developer Console, vá em **WhatsApp** → **Configuration**

2. **Webhook URL:**

```
https://seu-chatwoot.com/webhooks/whatsapp/+5511999999999
```

3. **Verify Token:**

   * Copie o token gerado pelo Chatwoot (mostrado após criar inbox)

4. **Subscribe to fields:**

   * ✅ messages
   * ✅ message\_template\_status\_update
   * ✅ message\_echoes

5. Clique em **"Verify and Save"**

***

## 📋 Templates de Mensagem

Templates são mensagens pré-aprovadas pela Meta necessárias para iniciar conversas.

### Criar Template

1. Acesse [business.facebook.com](https://business.facebook.com)
2. **WhatsApp Manager** → **Message Templates**
3. **Create Template**

**Exemplo de Template:**

```
Nome: saudacao_inicial
Categoria: UTILITY
Idioma: Portuguese (BR)

Conteúdo:
Olá {{1}}, tudo bem?

Recebemos sua mensagem e já vamos te atender!

Aguarde um momento.

Atenciosamente,
{{2}}
```

4. Envie para aprovação
5. Aguarde aprovação (1-24h)

### Usar Template no Chatwoot

Após aprovado, o template aparece automaticamente no Chatwoot:

1. Abra conversa
2. Clique em **"Templates"**
3. Selecione template
4. Preencha variáveis: `{{1}}` = Nome cliente, `{{2}}` = Nome empresa
5. Enviar

***

## 🔍 Solução de Problemas

### Não Recebo Mensagens

**Possíveis causas:**

1. **Webhook não configurado**

   * Verifique URL do webhook
   * Confirme Verify Token correto
   * Teste webhook no Meta Console

2. **Número não verificado**

   * Vá em WhatsApp Manager
   * Verifique status do número
   * Complete verificação se necessário

3. **Permissões insuficientes**

   * Revise permissões do token
   * Token precisa: `whatsapp_business_messaging`, `whatsapp_business_management`

### Não Consigo Enviar Mensagens

**Possíveis causas:**

1. **Janela de 24h expirou**

   * Use template aprovado
   * Cliente precisa enviar nova mensagem

2. **Template não aprovado**

   * Verifique status no WhatsApp Manager
   * Aguarde aprovação

3. **Limite de mensagens atingido**

   * Veja limites da conta
   * Aumente tier da conta (melhore qualidade)

### Mensagens com Erro

**Códigos comuns:**

* **131000**: Conta restrita
* **131026**: Template não existe
* **131047**: Limite de mensagens excedido
* **131051**: Número do destinatário inválido
* **133000**: API Key inválida

**Solução:**

* Consulte [Meta Developer Docs](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes)

***

## 📊 Qualidade da Conta

A Meta monitora a qualidade da sua conta com base em:

* Taxa de bloqueio de usuários
* Relatórios de spam
* Feedback negativo
* Taxa de resposta

**Status da Conta:**

* 🟢 **Verde**: Excelente - Limite completo
* 🟡 **Amarelo**: Atenção - Limite reduzido
* 🔴 **Vermelho**: Crítico - Risco de suspensão

**Como melhorar:**

✅ Responda rápido (\< 24h)

✅ Não envie spam

✅ Use opt-in explícito

✅ Respeite preferências do usuário

✅ Conteúdo relevante e útil

***

## 🚀 Próximos Passos

<CardGroup cols={2}>
  <Card title="Templates" icon="file-lines" href="/pt-br/guia-usuario/conversas">
    Aprenda a criar templates efetivos
  </Card>

  <Card title="Automações" icon="robot" href="/pt-br/guia-usuario/automacoes">
    Automatize respostas no WhatsApp
  </Card>
</CardGroup>