WhatsApp Business Oficial (Meta)

PRO

Por que Meta Oficial

Vantagens da Cloud API

A Meta Cloud API é a integração oficial do WhatsApp Business. Você usa direto pela Graph API da Meta, com conformidade total e recursos exclusivos.

SEL VERDE

Numero verificado — clientes confiam

TEMPLATES HSM

Disparo fora da janela 24h, aprovados pela Meta

SEM BANIMENTO

Conformidade total — risco zero

DISPARO EM MASSA

Marketing/transacional em escala

WEBHOOK OFICIAL

Status + mensagens recebidas (HMAC SHA-256)

MIDIA COMPLETA

Imagem, áudio, vídeo, documento, localização

Como funciona: Você conecta seu Business Manager da Meta via painel (wizard OAuth). A APIFacil guarda o token de acesso criptografado (revogável). Você é dono do BM/WABA/número — pode desconectar a qualquer momento.

AUTH

Autenticação

Todas as rotas usam o mesmo token da APIFacil no header Authorization: {seu_token} (sem prefixo "Bearer "). O token é gerado no painel do usuário. A APIFacil autentica você na Meta internamente — você não precisa do token Meta.

BASH

# Header correto: Authorization + token direto (SEM "Bearer")
curl -X POST https://apifacil.dev/api/v1/whatsapp/enviar-mensagem \
  -H "Authorization: SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"mensagem":"Olá","telefone":"5511999999999","instancia":"14"}'

Erro comum: Enviar Authorization: Bearer SEU_TOKEN retorna 401. O middleware valida o token direto — não use prefixo "Bearer ".

Identificador da instância: O campo instancia aceita o ID, código ou public_token da instância Meta Oficial. O roteamento é automático.

FLOW

Como o envio funciona

Fluxo do POST até a Graph API

Quando você chama /enviar-mensagem, /enviar-template ou qualquer endpoint de mídia, a APIFacil valida a credencial Meta e despacha o envio para a Graph API da Meta de forma assíncrona.

1

Sua requisição
POST /enviar-mensagem + dados

→

2

Validar credencial
Número verificado e ativo na Meta

→

3

Fila de envio
Processamento assíncrono

→

4

Graph API Meta
Entrega ao destinatário

→

5

Webhook de status
sent · delivered · read

Pré-requisitos para envio: A instância precisa ser Meta Oficial com credencial ativa (número verificado + token válido). Se a credencial não estiver pronta, o sistema aguarda e retenta automaticamente.

SEND

Envio de Mensagens

Texto via Graph API

POST /api/v1/whatsapp/enviar-mensagem Enviar texto (roteamento automatico) ›

Envia uma mensagem de texto para a Graph API da Meta de forma assíncrona. Retorna 202 imediatamente com o notificação_id para rastrear o status via webhook.

PARAMETRO	TIPO	REQ?	DESCRIÇÃO
mensagem	string	obrigatório	Texto da mensagem
telefone	string	obrigatório	DDI+DDD+número (ex: 5511999999999)
instancia	string	opcional	ID, código ou public_token da instância
grupo	string	ignorado	Nao usado em Meta Oficial

BASH
POST https://apifacil.dev/api/v1/whatsapp/enviar-mensagem
Authorization: SEU_TOKEN
Content-Type: application/json

{
  "mensagem": "Ola, seja bem-vindo!",
  "telefone": "5511999999999",
  "instancia": "14"
}

202 Accepted Mensagem enfileirada para envio via Meta

JSON · RESPOSTA
{
  "error": false,
  "message": "Mensagem enfileirada para envio via Meta",
  "data": {
    "notificação_id": 1234,
    "status": "queued"
  }
}

Assíncrono: O envio é processado em fila. O notificação_id permite rastrear o status via webhook (sent/delivered/read/failed). Em caso de falha temporária, o sistema retenta automaticamente.

HSM

Envio de Template (HSM)

Exclusivo Meta Oficial

Exclusivo Meta: Este endpoint só funciona em instâncias Meta Oficial com credencial operacional. Retorna 422 se a instância não for Meta Oficial.

Templates HSM (Highly Structured Message): Modelos pré-aprovados pela Meta para enviar fora da janela de 24h. Permitem disparos em massa sem limite de horário. Status deve ser APPROVED para uso.

POST /api/v1/whatsapp/enviar-template Enviar template HSM aprovado ›

Envia um template HSM aprovado. O template deve existir na instância e ter status APPROVED. Os components preenchem os placeholders {{1}}, {{2}} do template.

PARAMETRO	TIPO	REQ?	DESCRIÇÃO
instancia	string	obrigatório	ID, código ou public_token da instância Meta
telefone	string	obrigatório	DDI+DDD+número
template	string	obrigatório	Nome do template (ex: boas_vindas_v1)
language	string	opcional	Código do idioma (default: pt_BR)
components	object	opcional	Parâmetros do template (header/body/buttons)

BASH · TEMPLATE SIMPLES (body)
POST https://apifacil.dev/api/v1/whatsapp/enviar-template
Authorization: SEU_TOKEN
Content-Type: application/json

{
  "instancia": "14",
  "telefone": "5511999999999",
  "template": "boas_vindas_v1",
  "components": {
    "body": ["Joao", "APIFacil"]
  }
}

BASH · COMPLETO (header+body+button URL)
POST https://apifacil.dev/api/v1/whatsapp/enviar-template
Authorization: SEU_TOKEN
Content-Type: application/json

{
  "instancia": "14",
  "telefone": "5511999999999",
  "template": "promocao_v1",
  "components": {
    "header": ["Promo Julho"],
    "body": ["Joao", "50%"],
    "buttons": ["julho50"]
  }
}

202 Accepted Template enfileirado para envio

JSON · RESPOSTA
{
  "error": false,
  "message": "Template enfileirado para envio",
  "data": {
    "notificação_id": 1235,
    "template": "boas_vindas_v1",
    "status": "queued"
  }
}

422 Instância não é Meta Oficial

404 Template não encontrado ou não aprovado

Formato dos components: A APIFacil mapeia automaticamente para o formato da Graph API. Você passa arrays simples — header[0] preenche {{1}}, body[0] preenche {{1}}, etc. Não precisa montar o payload completo da Meta.

MID

Envio de Mídia

Foto, vídeo, áudio, documento — URL ou base64

Para instâncias Meta Oficial, todos os endpoints de mídia roteiam automaticamente para a Graph API. A URL da mídia deve ser publicamente acessível (a Meta faz download para enviar).

MÉTODO	ENDPOINT	TIPO	OBSERVAÇÃO
POST	/api/v1/whatsapp/enviar-foto	image	URL pública + caption opcional
POST	/api/v1/whatsapp/enviar-audio	audio	URL pública (MP3/OGG)
POST	/api/v1/whatsapp/enviar-video	video	URL pública + caption opcional
POST	/api/v1/whatsapp/enviar-arquivo	document	URL pública + caption + nome do arquivo
POST	/api/v1/whatsapp/enviar-foto-64	image	Base64 — upload para S3, depois Meta
POST	/api/v1/whatsapp/enviar-audio-64	audio	Base64 — upload para S3, depois Meta
POST	/api/v1/whatsapp/enviar-arquivo-64	document	Base64 — upload para S3, depois Meta

Enviar foto (URL)

POST /api/v1/whatsapp/enviar-foto

PARÂMETRO	TIPO	OBRIG.	DESCRIÇÃO
instancia	string	sim	ID, código ou public_token
telefone	string	sim	DDI+DDD+número
link	string	sim	URL pública da imagem (JPG/PNG)
nome	string	sim	Nome do arquivo
mensagem	string	não	Legenda (caption) da imagem

POST https://apifacil.dev/api/v1/whatsapp/enviar-foto
-H "Authorization: SEU_TOKEN" \
-d '{
    "instancia": "A1B2C3",
    "telefone": "5511999999999",
    "link": "https://meudominio.com.br/foto.jpg",
    "nome": "produto.jpg",
    "mensagem": "Veja nosso produto"
}'

Enviar áudio (URL)

POST /api/v1/whatsapp/enviar-audio

PARÂMETRO	TIPO	OBRIG.	DESCRIÇÃO
instancia	string	sim	ID, código ou public_token
telefone	string	sim	DDI+DDD+número
audio_url	string	sim	URL pública (MP3/OGG)

POST https://apifacil.dev/api/v1/whatsapp/enviar-audio
-H "Authorization: SEU_TOKEN" \
-d '{
    "instancia": "A1B2C3",
    "telefone": "5511999999999",
    "audio_url": "https://meudominio.com.br/audio.mp3"
}'

Enviar vídeo (URL)

POST /api/v1/whatsapp/enviar-video

PARÂMETRO	TIPO	OBRIG.	DESCRIÇÃO
instancia	string	sim	ID, código ou public_token
telefone	string	sim	DDI+DDD+número
video_url	string	sim	URL pública (MP4/3GP)
nome	string	sim	Nome do arquivo
mensagem	string	não	Legenda (caption)

POST https://apifacil.dev/api/v1/whatsapp/enviar-video
-H "Authorization: SEU_TOKEN" \
-d '{
    "instancia": "A1B2C3",
    "telefone": "5511999999999",
    "video_url": "https://meudominio.com.br/video.mp4",
    "nome": "demo.mp4",
    "mensagem": "Assista ao demo"
}'

Enviar documento (URL)

POST /api/v1/whatsapp/enviar-arquivo

PARÂMETRO	TIPO	OBRIG.	DESCRIÇÃO
instancia	string	sim	ID, código ou public_token
telefone	string	sim	DDI+DDD+número
link	string	sim	URL pública do arquivo
nome	string	sim	Nome com extensão (ex: contrato.pdf)
mensagem	string	não	Legenda (caption)

Detecção automática: O tipo é detectado pela extensão do nome: jpg/png/gif → image, mp3/ogg/aac → audio, mp4/3gp/mov → video, demais → document.

Endpoints base64: Os endpoints /enviar-foto-64, /enviar-audio-64 e /enviar-arquivo-64 aceitam o binário em base64. A APIFacil faz upload para S3 e então envia a URL pública para a Meta. Mesmos parâmetros dos endpoints URL, trocando link/audio_url/video_url por foto_base64/audio_base64/arquivo_base64 + tipo_arquivo (extensão).

Resposta

{
    "error": false,
    "data": {
        "notificacao_id": 12345,
        "message": "Image enfileirado para envio via Meta",
        "status": "queued"
    }
}

Template com mídia no header: Templates com header IMAGE/VIDEO/DOCUMENT são suportados via /enviar-template. Passe components.header.url com a URL pública da mídia. O sistema preenche o header automaticamente.

TIP

Tipos de Mensagem

Tudo que você pode enviar e receber

A Meta Cloud API suporta diversos tipos de mensagem além de texto. Todos os tipos abaixo são suportados pela APIFacil — no envio (via API) e na recepção (via webhook).

TIPO	ENVIAR	RECEBER	ENDPOINT / OBSERVAÇÃO
text	SIM	SIM	/enviar-mensagem
image	SIM	SIM	/enviar-foto
audio	SIM	SIM	/enviar-audio
video	SIM	SIM	/enviar-video
document	SIM	SIM	/enviar-arquivo
sticker	SIM	SIM	WebP animado — via /enviar-arquivo com extensão .webp
location	SIM	SIM	Lat/long + nome + endereço
template (HSM)	SIM	—	/enviar-template
interactive (buttons)	SIM	SIM	Botões de resposta — cliente clica e você recebe via webhook
interactive (list)	SIM	SIM	Lista de opções — cliente seleciona e você recebe via webhook
reaction	NÃO	SIM	Emoji reagido a uma mensagem — recebido via webhook
contacts	NÃO	SIM	Cartão de contato recebido — nome + telefone + email
system	NÃO	SIM	Mensagem do sistema (ex: usuário mudou de número)

Janela de 24h: Mensagens livres (texto, imagem, áudio, vídeo, documento, localização, botões) só podem ser enviadas se o cliente enviou uma mensagem nas últimas 24h. Fora da janela, use /enviar-template com template HSM aprovado.

TPL

Templates HSM

Gestão no painel, não via API

A criação, edição, sincronização e deleção de templates HSM é feita dentro do painel da APIFacil, não via API. O cliente usa a biblioteca de modelos prontos (31 templates em 9 segmentos, pt_BR + en_US) ou cria do zero — tudo visual, sem código.

BIBLIOTECA

31 modelos prontos · 9 segmentos · pt_BR + en_US

CRIAR DO ZERO

Header, body, footer, botões — tudo visual no painel

SINCRONIZAR

Botão no painel espelha templates da Meta automaticamente

APROVAÇÃO

Status APPROVED/REJECTED chega via webhook

Para enviar template via API: Use o endpoint POST /api/v1/whatsapp/enviar-template (abaixo). O template precisa estar APPROVED — crie e gerencie pelo painel.

HOOK

Webhook de Eventos

Formato APIFacil (serializado)

A APIFacil recebe os eventos da Meta, serializa para um formato próprio e limpo e então envia ao seu webhook. Você não recebe o payload cru da Meta — recebe um formato padronizado e fácil de consumir.

Configuração: Configure webhook_url (mensagens recebidas) e webhook_status (status de envio) no painel da instância. Se webhook_status estiver vazio, o sistema usa webhook_url para tudo.

1

Painel da instância
Configurações › Webhook

→

2

Ativar webhook
Ligar toggle de webhook

→

3

Inserir URLs
webhook_url + webhook_status

4

Receber eventos
message_received + message_status

Eventos enviados ao seu webhook:

EVENTO	QUANDO	URL
message_received	Mensagem recebida de um contato	webhook_url
message_status	Status de envio atualizado	webhook_status *

* Se webhook_status estiver vazio, usa webhook_url.

Segurança: A APIFacil valida a assinatura HMAC da Meta internamente. Você não precisa se preocupar com verificação de assinatura — recebe apenas eventos válidos e serializados.

JSON

Formato do Payload (Serializado)

Formato limpo APIFacil

JSON · MESSAGE_RECEIVED (texto)
{
  "event": "message_received",
  "instancia": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message_id": "wamid.HBgLNTU...",
  "tipo": "text",
  "de": "5511999999999",
  "para": "+55 11 8888-8888",
  "contato": null,
  "texto": "Ola, quero saber sobre o pedido",
  "midia": null,
  "localizacao": null,
  "interação": null,
  "resposta_id": null,
  "timestamp": "2026-07-30T12:00:00Z"
}

JSON · MESSAGE_RECEIVED (imagem)
{
  "event": "message_received",
  "instancia": "a1b2c3d4-...",
  "message_id": "wamid.HBgLNTU...",
  "tipo": "image",
  "de": "5511999999999",
  "para": "+55 11 8888-8888",
  "contato": null,
  "texto": "Olha que legal",
  "midia": {
    "id": "123456789",
    "mime_type": "image/jpeg",
    "nome": "foto.jpg",
    "tamanho": 102400,
    "url": "https://app.apifacil.com.br/storage/media/token/foto.jpg"
  },
  "localizacao": null,
  "interação": null,
  "resposta_id": null,
  "timestamp": "2026-07-30T12:00:00Z"
}

JSON · MESSAGE_RECEIVED (botao clicado)
{
  "event": "message_received",
  "instancia": "a1b2c3d4-...",
  "message_id": "wamid.HBgLNTU...",
  "tipo": "interactive",
  "de": "5511999999999",
  "para": "+55 11 8888-8888",
  "contato": null,
  "texto": "Confirmar Pedido",
  "midia": null,
  "localizacao": null,
  "interação": {
    "tipo": "button_reply",
    "id": "btn_confirmar",
    "titulo": "Confirmar Pedido"
  },
  "resposta_id": null,
  "timestamp": "2026-07-30T12:00:00Z"
}

JSON · MESSAGE_STATUS (delivered)
{
  "event": "message_status",
  "instancia": "a1b2c3d4-...",
  "message_id": "wamid.HBgLNTU...",
  "status": "delivered",
  "para": "5511999999999",
  "erro": null,
  "timestamp": "2026-07-30T12:00:01Z"
}

JSON · MESSAGE_STATUS (failed)
{
  "event": "message_status",
  "instancia": "a1b2c3d4-...",
  "message_id": "wamid.HBgLNTU...",
  "status": "failed",
  "para": "5511999999999",
  "erro": {
    "codigo": 131047,
    "titulo": "Receptive number not allowed",
    "detalhe": "Message undeliverable"
  },
  "timestamp": "2026-07-30T12:00:05Z"
}

CAMPO	TIPO	EVENTO	DESCRIÇÃO
event	string	ambos	message_received ou message_status
instancia	string	ambos	Codigo UUID da instancia
message_id	string	ambos	ID da mensagem na Meta
tipo	string	received	text, image, audio, video, document, sticker, location, interactive, button, reaction, contact, system
de	string	received	Número de origem (quem enviou)
para	string	ambos	Número de destino (seu WhatsApp Business)
contato	string	received	Nome do contato (se enviado pela Meta)
texto	string	received	Conteúdo textual ou caption da mídia
midia	object	received	Dados da mídia (id, mime_type, nome, tamanho, url)
localizacao	object	received	latitude, longitude, nome, endereco
interação	object	received	tipo, id, título (button_reply/list_reply/button/reaction)
resposta_id	string	received	ID da mensagem original (se for resposta)
status	string	status	sent, delivered, read, failed, deleted
erro	object	status	código, título, detalhe (quando status=failed)
timestamp	string	ambos	ISO 8601

Vantagem do formato serializado: Você não precisa lidar com a estrutura complexa e verbosa da Meta. O payload é limpo, consistente e fácil de parser. Tipos de mídia, interações e erros são normalizados.

WIZ

Onboarding

Conexão via painel (não API)

O onboarding da Meta é feito via painel (wizard de 5 etapas), não via API. O cliente conecta o Facebook Business, escolhe o número e submete — fica conectado imediatamente (auto-aprovação). A API só é usada após a instância estar operacional.

1

Criar instância
Tipo Meta Oficial

→

2

Abrir wizard
Painel › WhatsApp › Meta

→

3

OAuth Meta (Embedded Signup)
Conecta Facebook Business

→

4

Dados empresa + número
CNPJ, nome, telefone

→

5

Submeter (auto-aprova)
status=verified imediato

Custódia: O cliente é dono do BM/WABA/número. A APIFacil só guarda o token de acesso criptografado (revogável). Botão "Desconectar Meta" no painel. Dados Meta deletados ao fechar conta (LGPD).

STA

Status & Qualidade

STATUS	DESCRIÇÃO	PODE ENVIAR?
verified	Número ativo e operacional	SIM
pending	Aguardando verificação	NÃO
banned	Numero banido pela Meta	NÃO
disconnected	Desconectado pelo cliente	NÃO

QUALIDADE	SIGNIFICADO	AÇÃO
green	Qualidade boa	Normal
yellow	Qualidade baixa	Reduzir volume, revisar templates
red	Critico — risco de banimento	Pausar envios imediatamente

LIM

Limites & Janela 24h

Rate limit: 80 mensagens/segundo por número. A APIFacil controla isso automaticamente — se exceder, aplica uma pequena pausa para respeitar o limite da Meta.

Janela de 24h (Customer Care Window): Após o cliente enviar uma mensagem para você, você tem 24h para responder com mensagens livres (texto, mídia). Após 24h, só pode enviar template HSM aprovado.

CENÁRIO	O QUE ENVIAR
Cliente enviou msg nas últimas 24h	Mensagem livre (texto/mídia) ou template
Cliente não fala há +24h	SÓ template HSM (APPROVED)
Disparo em massa (marketing)	SÓ template HSM (MARKETING)
Notificação de pedido (transacional)	Template HSM (UTILITY)
Autenticação (2FA)	Template HSM (AUTHENTICATION)

ERR

Erros Comuns

STATUS	CÓDIGO	CAUSA	SOLUÇÃO
401	token invalido	Token da APIFacil errado ou com Bearer	Remover "Bearer ", usar token do painel
404	instância não encontrada	ID/código/public_token não pertence ao usuário	Verificar o ID no painel
404	template não aprovado	Template não existe ou status != APPROVED	Sincronizar templates, verificar status
422	não é Meta Oficial	Instância não é Meta Oficial	Verificar o tipo da instância no painel
422	credencial não ativa	Número não verificado ou sem token válido	Reconectar Meta no painel (wizard)
429	rate limit	Mais de 80 envios/segundo	A APIFacil controla automaticamente
500	falha Graph API	Meta rejeitou o envio (número inválido, fora da janela)	Verificar telefone e se cliente está na janela 24h

Suporte: Qualquer duvida, chame no WhatsApp 55 51 9 8033-1519. Nao temos sistema de tickets.