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

# Enviar Mensagem Freeform

> Enviar uma mensagem WhatsApp de texto livre dentro de uma sessão ativa de 24 horas

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.

<Warning>
  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](/api-reference/whatsapp/send-template) primeiro para reiniciar a conversa. Use o endpoint [Session Status](/api-reference/whatsapp/session-status) para verificar se uma sessão está ativa.
</Warning>

<Note>
  Este endpoint é limitado por taxa para **5 requisições por segundo** por usuário.
</Note>

### Corpo da Requisição

<ParamField body="sender_id" type="integer" required>
  O ID do remetente WhatsApp para enviar (obtido do endpoint [Get Senders](/api-reference/whatsapp/get-senders))
</ParamField>

<ParamField body="recipient_phone" type="string" required>
  O número de telefone do destinatário em formato internacional (ex: `+1234567890`)
</ParamField>

<ParamField body="message" type="string" required>
  O conteúdo da mensagem para enviar (máx 4096 caracteres)
</ParamField>

### Campos de Resposta

<ResponseField name="success" type="boolean">
  Se a mensagem foi enviada com sucesso
</ResponseField>

<ResponseField name="conversation_id" type="integer">
  O ID da conversa associada a esta mensagem
</ResponseField>

<ResponseField name="message_id" type="integer">
  O ID do registro da mensagem da conversa
</ResponseField>

<ResponseField name="whatsapp_message_id" type="integer">
  O ID do registro da mensagem WhatsApp
</ResponseField>

<ResponseField name="message_sid" type="string">
  O SID da mensagem Twilio para rastreamento de entrega
</ResponseField>

<ResponseField name="session_status" type="object">
  Status da sessão atualizado após enviar a mensagem

  <Expandable title="Propriedades do status da sessão">
    <ResponseField name="is_open" type="boolean">
      Se a janela de mensagens de 24 horas está atualmente aberta
    </ResponseField>

    <ResponseField name="can_send_freeform" type="boolean">
      Se mensagens freeform podem ser enviadas agora
    </ResponseField>

    <ResponseField name="requires_template" type="boolean">
      Se uma mensagem de template é necessária
    </ResponseField>

    <ResponseField name="message" type="string">
      Descrição legível para humanos do estado da sessão
    </ResponseField>

    <ResponseField name="minutes_remaining" type="integer">
      Minutos restantes na janela de 24 horas
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      Timestamp ISO 8601 quando a sessão expira
    </ResponseField>
  </Expandable>
</ResponseField>

### Respostas de Erro

<ResponseField name="402 Insufficient Balance">
  <Expandable title="Resposta de Erro">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Insufficient balance. Please top up your account.`</ResponseField>
    <ResponseField name="error_code" type="string">`INSUFFICIENT_BALANCE`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="403 Session Expired">
  <Expandable title="Resposta de Erro">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">Mensagem indicando que a janela de mensagens de 24 horas expirou</ResponseField>
    <ResponseField name="error_code" type="string">`SESSION_EXPIRED`</ResponseField>

    <ResponseField name="session_status" type="object">
      Status atual da sessão com campos `is_open`, `can_send_freeform`, `requires_template` e `message`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="404 Not Found">
  <Expandable title="Resposta de Erro">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Sender not found or does not belong to you`</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_NOT_FOUND`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="503 Sender Offline">
  <Expandable title="Resposta de Erro">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">Mensagem indicando que o remetente está atualmente offline</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_OFFLINE`</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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."
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://suasofia.online/api/user/whatsapp/send-freeform',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        sender_id: 12,
        recipient_phone: '+1234567890',
        message: 'Obrigado pela sua consulta! Nossa equipe revisará seu pedido e retornará em até 2 horas.'
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://suasofia.online/api/user/whatsapp/send-freeform',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'sender_id': 12,
          'recipient_phone': '+1234567890',
          'message': 'Obrigado pela sua consulta! Nossa equipe revisará seu pedido e retornará em até 2 horas.'
      }
  )

  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Sucesso theme={null}
  {
    "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"
    }
  }
  ```

  ```json 402 Saldo Insuficiente theme={null}
  {
    "success": false,
    "error": "Insufficient balance. Please top up your account.",
    "error_code": "INSUFFICIENT_BALANCE"
  }
  ```

  ```json 403 Sessão Expirada theme={null}
  {
    "success": false,
    "error": "A janela de mensagens de 24 horas está fechada. O cliente deve responder primeiro, ou use uma mensagem de template.",
    "error_code": "SESSION_EXPIRED",
    "session_status": {
      "is_open": false,
      "can_send_freeform": false,
      "requires_template": true,
      "message": "Sessão expirada. Envie um template ou aguarde o cliente responder.",
      "expired_at": "2026-02-23T10:30:00+00:00"
    }
  }
  ```

  ```json 404 Remetente Não Encontrado theme={null}
  {
    "success": false,
    "error": "Sender not found or does not belong to you",
    "error_code": "SENDER_NOT_FOUND"
  }
  ```

  ```json 422 Telefone Inválido theme={null}
  {
    "success": false,
    "error": "Formato de número de telefone inválido. Use o formato E.164 (ex: +14155551234).",
    "error_code": "INVALID_PHONE"
  }
  ```

  ```json 503 Remetente Offline theme={null}
  {
    "success": false,
    "error": "Remetente não está online. Status atual: Offline",
    "error_code": "SENDER_OFFLINE"
  }
  ```
</ResponseExample>

### 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](/api-reference/whatsapp/send-template) para reiniciar a conversa.
4. Cada nova mensagem do cliente reinicia o timer de 24 horas.

Use o endpoint [Session Status](/api-reference/whatsapp/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.