Skip to main content
POST
/
user
/
whatsapp
/
send-freeform
curl -X POST "https://suasofia.online/api/user/whatsapp/send-freeform" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": 12,
    "recipient_phone": "+1234567890",
    "message": "Obrigado pela sua consulta! Nossa equipe revisará seu pedido e retornará em até 2 horas."
  }'

{
  "success": true,
  "conversation_id": 1234,
  "message_id": 567,
  "whatsapp_message_id": 890,
  "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "session_status": {
    "is_open": true,
    "can_send_freeform": true,
    "requires_template": false,
    "message": "Sessão aberta (23 hr 45 min restantes). Mensagens freeform ilimitadas permitidas.",
    "minutes_remaining": 1425,
    "expires_at": "2026-02-25T10:30:00+00:00"
  }
}
Este endpoint envia uma mensagem WhatsApp freeform (texto livre) para um destinatário. Diferente de mensagens de template, mensagens freeform pode conter qualquer texto mas requer uma janela de mensagens ativa de 24 horas — significando que o destinatário deve ter enviado uma mensagem para seu remetente WhatsApp dentro das últimas 24 horas.
Mensagens freeform só podem ser enviadas durante uma janela de mensagens ativa de 24 horas. Se a sessão tiver expirado, você deve enviar uma mensagem de template primeiro para reiniciar a conversa. Use o endpoint Session Status para verificar se uma sessão está ativa.
Este endpoint é limitado por taxa para 5 requisições por segundo por usuário.

​
Corpo da Requisição

​
sender_id
integer
required
O ID do remetente WhatsApp para enviar (obtido do endpoint Get Senders)
​
recipient_phone
string
required
O número de telefone do destinatário em formato internacional (ex: +1234567890)
​
message
string
required
O conteúdo da mensagem para enviar (máx 4096 caracteres)

​
Campos de Resposta

​
success
boolean
Se a mensagem foi enviada com sucesso
​
conversation_id
integer
O ID da conversa associada a esta mensagem
​
message_id
integer
O ID do registro da mensagem da conversa
​
whatsapp_message_id
integer
O ID do registro da mensagem WhatsApp
​
message_sid
string
O SID da mensagem Twilio para rastreamento de entrega
​
session_status
object
Status da sessão atualizado após enviar a mensagem

​
Respostas de Erro

​
402 Insufficient Balance
​
403 Session Expired
​
404 Not Found
​
503 Sender Offline
curl -X POST "https://suasofia.online/api/user/whatsapp/send-freeform" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": 12,
    "recipient_phone": "+1234567890",
    "message": "Obrigado pela sua consulta! Nossa equipe revisará seu pedido e retornará em até 2 horas."
  }'

{
  "success": true,
  "conversation_id": 1234,
  "message_id": 567,
  "whatsapp_message_id": 890,
  "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "session_status": {
    "is_open": true,
    "can_send_freeform": true,
    "requires_template": false,
    "message": "Sessão aberta (23 hr 45 min restantes). Mensagens freeform ilimitadas permitidas.",
    "minutes_remaining": 1425,
    "expires_at": "2026-02-25T10:30:00+00:00"
  }
}

​
Janela de Mensagens de 24 Horas

WhatsApp aplica uma política de janela de mensagens de 24 horas:
  1. Quando um cliente envia uma mensagem para seu número WhatsApp Business, uma janela de 24 horas se abre.
  2. Durante esta janela, você pode enviar mensagens freeform sem restrições.
  3. Após a janela expirar, você deve usar uma mensagem de template para reiniciar a conversa.
  4. Cada nova mensagem do cliente reinicia o timer de 24 horas.
Use o endpoint Session Status para verificar se uma sessão está ativa antes de tentar enviar uma mensagem freeform.

​
Notas

  • Comprimento máximo da mensagem é 4,096 caracteres (limite do WhatsApp).
  • O remetente deve estar online. Remetentes offline retornam erro 503.
  • Custos das mensagens são automaticamente deduzidos do saldo da sua conta.
  • Limite de taxa: 5 requisições por segundo por usuário.