Configurar Canal WABA (WhatsApp Business API)

Este guia mostra o passo a passo completo para configurar um canal WABA (WhatsApp Business API) na Ogmma, desde a obtencao das credenciais no Meta Business ate o envio da primeira mensagem.

Pre-requisitos

Antes de comecar, voce precisa ter:

• Uma conta na Ogmma API com uma API Key ativa
• Uma conta no Meta Business Suite
• Um App do Meta com o produto WhatsApp ativado
• Um numero de telefone dedicado para o WhatsApp Business (nao pode estar vinculado a uma conta WhatsApp pessoal)

---

Passo 1: Obter credenciais no Meta Business

1.1 Criar um App no Meta for Developers

1. Acesse developers.facebook.com/apps
2. Clique em "Criar App"
3. Selecione o tipo "Empresa" (Business)
4. Preencha o nome do app e vincule a sua conta Business
5. No dashboard do app, clique em "Adicionar produto" e selecione "WhatsApp"

1.2 Obter o Phone Number ID

1. No menu lateral do app, va em WhatsApp > Configuracao da API
2. Na secao "De", voce vera o numero de teste ou pode adicionar seu proprio numero
3. O Phone Number ID aparece logo abaixo do numero selecionado
4. Copie esse valor (ex: 106540012345678)

Numero de producao

Para producao, adicione seu proprio numero clicando em "Adicionar numero de telefone". O numero passara por verificacao via SMS ou ligacao.

1.3 Obter o Business Account ID

1. No menu lateral, va em WhatsApp > Configuracao da API
2. O WhatsApp Business Account ID aparece no topo da pagina
3. Copie esse valor (ex: 102030405060708)

1.4 Gerar o Access Token permanente

O token temporario do painel expira em 24 horas. Para producao, crie um token permanente:

1. Va em Configuracoes do App > Basico e anote o App ID e App Secret
2. No menu lateral, va em WhatsApp > Configuracao da API
3. Na secao de tokens, clique em "Gerar token de acesso"
4. Selecione as permissoes: whatsapp_business_management e whatsapp_business_messaging
5. Copie o token gerado (comeca com EAABsbCS...)

Importante

Salve o token em local seguro. Ele so e exibido uma vez. Se perder, sera necessario gerar outro.

1.5 Obter o App Secret

1. Va em Configuracoes do App > Basico
2. Na secao "Chave Secreta do App", clique em "Mostrar"
3. Copie o valor (ex: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6)

O App Secret e usado para validar a assinatura dos webhooks recebidos do Meta.

---

Passo 2: Criar o canal WABA na Ogmma

Com as 4 credenciais em maos, crie o canal via API:

curl -X POST "https://oapi.ogmma.com.br/v1/channels/waba" \
  -H "Authorization: Bearer {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Atendimento WhatsApp",
    "color": "#25D366",
    "phoneNumberId": "106540012345678",
    "businessAccountId": "102030405060708",
    "accessToken": "EAABsbCS...",
    "appSecret": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
  }'

Resposta (201):

{
  "data": {
    "id": "6650a1b2c3d4e5f6a7b8c9d0",
    "name": "Atendimento WhatsApp",
    "type": "WHATSAPP_WABA",
    "status": "PENDING_WEBHOOK",
    "waba": {
      "phoneNumberId": "106540012345678",
      "businessAccountId": "102030405060708",
      "webhookConfigured": false,
      "verifyToken": "ogmma_vt_abc123def456"
    }
  }
}

Status PENDING_WEBHOOK

O canal fica com status PENDING_WEBHOOK ate que o webhook do Meta seja configurado e verificado (Passo 3).

---

Passo 3: Configurar o Webhook no Meta

O webhook permite que o Meta envie eventos (mensagens recebidas, status de entrega, etc.) para a Ogmma.

3.1 Obter as informacoes do webhook

curl -X GET "https://oapi.ogmma.com.br/v1/channels/{channelId}/waba/webhook-info" \
  -H "Authorization: Bearer {SUA_API_KEY}"

Resposta:

{
  "data": {
    "webhookUrl": "https://oapi.ogmma.com.br/v1/webhooks/meta",
    "verifyToken": "ogmma_vt_abc123def456",
    "webhookConfigured": false
  }
}

3.2 Configurar no painel do Meta

1. No painel do app, va em WhatsApp > Configuracao
2. Na secao "Webhook", clique em "Editar"
3. Preencha:
   • URL de callback: https://oapi.ogmma.com.br/v1/webhooks/meta
   • Token de verificacao: o verifyToken retornado no passo anterior
4. Clique em "Verificar e salvar"

O Meta enviara uma requisicao GET para a URL com o token. A Ogmma validara automaticamente e retornara o challenge.

3.3 Inscrever-se nos campos do webhook

Apos a verificacao, voce precisa selecionar quais eventos receber:

1. Na mesma secao de Webhook, clique em "Gerenciar"

2. Marque os campos:

   • messages - Mensagens recebidas (obrigatorio)
   • message_template_status_update - Status de templates (recomendado)

3. Clique em "Concluido"

3.4 Verificar status do canal

Apos a verificacao do webhook, o canal muda automaticamente para CONNECTED:

curl -X GET "https://oapi.ogmma.com.br/v1/channels/{channelId}" \
  -H "Authorization: Bearer {SUA_API_KEY}"

{
  "data": {
    "id": "6650a1b2c3d4e5f6a7b8c9d0",
    "status": "CONNECTED",
    "type": "WHATSAPP_WABA",
    "phone": "5511988887777"
  }
}

---

Passo 4: Enviar a primeira mensagem

Com o canal CONNECTED, voce ja pode enviar mensagens.

Dentro da janela de 24 horas (mensagem livre)

Se o contato ja enviou uma mensagem nas ultimas 24 horas:

curl -X POST "https://oapi.ogmma.com.br/v1/channels/{channelId}/messages/text" \
  -H "Authorization: Bearer {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999998888",
    "text": "Ola! Como posso ajudar?"
  }'

Fora da janela de 24 horas (template obrigatorio)

Para iniciar uma conversa, use um template aprovado:

curl -X POST "https://oapi.ogmma.com.br/v1/channels/{channelId}/messages/template" \
  -H "Authorization: Bearer {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999998888",
    "templateId": "ID_DO_TEMPLATE",
    "variables": {
      "1": "Joao"
    }
  }'

Janela de 24 horas

O WhatsApp Business API so permite mensagens livres (texto, imagem, etc.) dentro da janela de 24 horas apos a ultima mensagem do contato. Fora dessa janela, apenas templates aprovados podem ser enviados.

---

Passo 5: Receber mensagens

As mensagens recebidas sao entregues automaticamente via webhook. Para recebe-las na sua aplicacao, registre um webhook na Ogmma:

curl -X POST "https://oapi.ogmma.com.br/v1/webhooks" \
  -H "Authorization: Bearer {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://sua-aplicacao.com/webhook",
    "events": ["message.received", "message.sent", "message.delivered", "message.read"],
    "secret": "seu_secret_para_validacao_hmac"
  }'

Consulte a secao Webhooks para detalhes sobre validacao HMAC e tipos de eventos.

---

Resumo das credenciais

Credencial	Onde encontrar	Exemplo
Phone Number ID	WhatsApp > Configuracao da API > secao "De"	106540012345678
Business Account ID	WhatsApp > Configuracao da API > topo da pagina	102030405060708
Access Token	WhatsApp > Configuracao da API > Gerar token	EAABsbCS...
App Secret	Configuracoes do App > Basico > Chave Secreta	a1b2c3d4e5...

---

Troubleshooting

Webhook nao e verificado

• Verifique se a URL esta correta: https://oapi.ogmma.com.br/v1/webhooks/meta
• Verifique se o verifyToken esta exatamente igual ao retornado por /waba/webhook-info
• Certifique-se que o app do Meta esta no modo Live (nao Development)

Canal fica em PENDING_WEBHOOK

• O webhook do Meta ainda nao foi configurado ou a verificacao falhou
• Repita o Passo 3 e verifique os logs no painel do Meta

Mensagens nao sao entregues

• Verifique se o canal esta CONNECTED
• Verifique se o Access Token nao expirou
• Para mensagens fora da janela de 24h, use templates
• Verifique o Quality Rating do numero no Meta Business

Access Token expirou

Atualize o token via API:

curl -X PATCH "https://oapi.ogmma.com.br/v1/channels/{channelId}/waba/credentials" \
  -H "Authorization: Bearer {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "accessToken": "NOVO_TOKEN_AQUI"
  }'

---

Proximos passos

• Enviar diferentes tipos de mensagem
• Enviar templates
• Configurar webhooks
• Integrar com n8n
• Envio em massa