WhatsApp Business API
Envie mensagens via WhatsApp Business com templates aprovados, mídia rica e botões interativos.
WhatsApp Business oferece: Templates aprovados • Confirmação de leitura • Mídia rica • Botões interativos • Conversas bidirecionais • Alta taxa de engajamento
Por que usar WhatsApp Business?
Vantagens
- 98% de taxa de abertura
- Aplicativo mais usado no Brasil
- Conversas bidirecionais
- Confirmação de leitura
- Suporte a mídia rica
- Perfil business verificado
Requisitos
- Templates pré-aprovados pelo WhatsApp
- Número business registrado
- Opt-in do destinatário
- Janela de 24h para respostas
- Aprovação da Meta
Enviar Mensagem WhatsApp
POST
/api/v1/integration/send
Parâmetros
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
to |
String | Sim | Número WhatsApp com código do país |
message |
String | Sim | Conteúdo da mensagem ou nome do template |
type |
String | Sim | Deve ser "WHATSAPP" |
templateId |
String | Condicional | ID do template aprovado (obrigatório para nova conversa) |
templateParams |
Array | Não | Valores para variáveis do template |
Exemplo Básico
{
"to": "5511999999999",
"message": "Olá! Sua mensagem via WhatsApp Business.",
"type": "WHATSAPP"
}
Resposta (200 OK)
{
"message": "Requisição recebida com sucesso. A campanha foi enviada para análise e processamento.",
"details": {
"campaignId": "6584b123c2d3e4f5a6b7c999",
"status": "UNDER_APPROVAL",
"type": "WHATSAPP",
"routeName": "Rota WhatsApp Business",
"content": "Olá! Sua mensagem via WhatsApp Business.",
"recipients": 1,
"cost": {
"perUnit": 0.55,
"total": 0.55,
"currency": "BRL"
}
}
}
Nota sobre custos: Os valores apresentados nos exemplos são meramente ilustrativos. Os custos reais variam por rota e são definidos individualmente. Consulte seu gerente de conta para informações específicas sobre precificação.
Templates WhatsApp
Templates são mensagens pré-aprovadas pela Meta. Necessários para iniciar conversas:
Estrutura de Template
{
"to": "5511999999999",
"type": "WHATSAPP",
"templateId": "welcome_message",
"templateParams": ["João", "Premium", "30 dias"]
}
Template Exemplo (Aprovado)
Olá {{1}}! 🎉
Seja bem-vindo ao plano {{2}}!
Você tem {{3}} de trial gratuito para testar todos os recursos.
Aproveite!
Resultado após Substituição
Olá João! 🎉 Seja bem-vindo ao plano Premium! Você tem 30 dias de trial gratuito para testar todos os recursos. Aproveite!
Categorias de Templates
| Categoria | Uso | Tempo de Aprovação |
|---|---|---|
| Autenticação | OTP, códigos de verificação | Instantâneo |
| Transacional | Pedidos, entregas, pagamentos | 24-48h |
| Marketing | Promoções, ofertas | 48-72h |
Enviar Mídia
Envie imagens, vídeos, documentos e áudios via WhatsApp:
Imagem
{
"to": "5511999999999",
"type": "WHATSAPP",
"media": {
"type": "image",
"url": "https://sua-cdn.com/imagem.jpg",
"caption": "Confira nossa nova coleção!"
}
}
Documento PDF
{
"to": "5511999999999",
"type": "WHATSAPP",
"media": {
"type": "document",
"url": "https://sua-cdn.com/contrato.pdf",
"filename": "Contrato_Servicos.pdf",
"caption": "Seu contrato está anexado"
}
}
Vídeo
{
"to": "5511999999999",
"type": "WHATSAPP",
"media": {
"type": "video",
"url": "https://sua-cdn.com/tutorial.mp4",
"caption": "Tutorial de uso"
}
}
Formatos Suportados
- Imagem: JPG, PNG (máx. 5 MB)
- Vídeo: MP4, 3GP (máx. 16 MB)
- Áudio: MP3, AAC, OGG (máx. 16 MB)
- Documento: PDF, DOC, XLS, PPT (máx. 100 MB)
Botões Interativos e Listas
Botões de Resposta Rápida
{
"to": "5511999999999",
"type": "WHATSAPP",
"message": "Deseja confirmar seu agendamento para amanhã às 14h?",
"buttons": [
{
"type": "reply",
"text": "Confirmar"
},
{
"type": "reply",
"text": "Cancelar"
},
{
"type": "reply",
"text": "📅 Reagendar"
}
]
}
Botões de Ação
{
"to": "5511999999999",
"type": "WHATSAPP",
"message": "Precisa de ajuda? Entre em contato:",
"buttons": [
{
"type": "url",
"text": "Visitar Site",
"url": "https://www.exemplo.com"
},
{
"type": "phone",
"text": "Ligar",
"phoneNumber": "+5511999999999"
}
]
}
Lista de Opções
{
"to": "5511999999999",
"type": "WHATSAPP",
"interactive": {
"type": "list",
"header": "Escolha um departamento",
"body": "Como podemos ajudar você hoje?",
"buttonText": "Ver Opções",
"sections": [
{
"title": "Suporte",
"rows": [
{
"id": "tech_support",
"title": "Suporte Técnico",
"description": "Problemas técnicos"
},
{
"id": "billing",
"title": "Financeiro",
"description": "Dúvidas sobre pagamento"
}
]
},
{
"title": "Vendas",
"rows": [
{
"id": "new_sale",
"title": "Nova Compra",
"description": "Fazer um pedido"
}
]
}
]
}
}
Playground - Teste WhatsApp
Experimente enviar via WhatsApp diretamente pela documentação (simulação):
Modo Simulação: Este playground apenas simula as respostas da API. Nenhuma mensagem real é enviada e nenhuma requisição é feita ao backend.
Testar Envio WhatsApp
Limites e Restrições
| Limite | Valor | Observação |
|---|---|---|
| Tamanho da Mensagem | 4096 caracteres | Texto puro |
| Botões por Mensagem | 3 botões | Resposta rápida |
| Opções em Lista | 10 itens | Por lista |
| Janela de Conversa | 24 horas | Após última mensagem do cliente |
| Imagem | 5 MB | JPG, PNG |
| Vídeo | 16 MB | MP4 |
| Documento | 100 MB | PDF, DOC, XLS |
Janela de Mensagens (24h)
WhatsApp permite dois tipos de mensagens:
Mensagem de Template
Quando usar: Iniciar uma conversa ou fora da janela de 24h
Requer: Template aprovado pela Meta
Custo: Pago por mensagem
Mensagem de Sessão
Quando usar: Dentro de 24h após resposta do cliente
Requer: Nada, texto livre
Custo: Confirmar custo
Boas Práticas
- Sempre obtenha opt-in do cliente antes de enviar
- Use templates para primeira mensagem
- Responda dentro da janela de 24h quando possível
- Personalize mensagens com variáveis de template
- Use botões para facilitar interação
- Envie mídia relevante e de qualidade
- Não envie spam ou mensagens promocionais em excesso
- Configure webhooks para capturar respostas
Importante: O descumprimento das políticas do WhatsApp pode resultar em banimento do número business. Sempre siga as diretrizes oficiais da Meta.