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

# Enviar mensaje de texto libre de WhatsApp

> Envía un mensaje de texto libre de WhatsApp dentro de una sesión activa de 24 horas a través de Famulor

<Warning>
  **API de Famulor 1.0 (legado).** Esta página se aplica únicamente a Famulor 1.0 (`app.famulor.de`) y se conserva por compatibilidad. Para la plataforma actual, usa la [referencia de la API de Famulor 2.0](/es/api-reference/introduction).
</Warning>

Envía un mensaje de WhatsApp de texto libre a un destinatario usando tu remitente de WhatsApp de Famulor. A diferencia de los mensajes de plantilla, los mensajes de texto libre pueden contener cualquier texto, pero **requieren una ventana de mensajería de 24 horas activa** — es decir, el destinatario debe haber enviado un mensaje a tu remitente de WhatsApp en las últimas 24 horas.

<Warning>
  Los mensajes de texto libre solo se pueden enviar durante una ventana de mensajería de 24 horas activa. Si la sesión ha expirado, primero debes enviar un [mensaje de plantilla](/es/api-v1/whatsapp/send-template) para reiniciar la conversación. Usa el endpoint [Estado de sesión](/es/api-v1/whatsapp/session-status) para comprobar si una sesión está activa.
</Warning>

<Note>
  Este endpoint está limitado a **5 solicitudes por segundo** por usuario.
</Note>

### Cuerpo de la solicitud

<ParamField body="sender_id" type="integer" required>
  El ID del remitente de WhatsApp desde el que enviar (obtenido del endpoint [Obtener remitentes](/es/api-v1/whatsapp/get-senders))
</ParamField>

<ParamField body="recipient_phone" type="string" required>
  El número de teléfono del destinatario en formato internacional (p. ej., `+1234567890`)
</ParamField>

<ParamField body="message" type="string" required>
  El contenido del mensaje a enviar (máx. 4096 caracteres)
</ParamField>

### Campos de la respuesta

<ResponseField name="success" type="boolean">
  Indica si el mensaje se envió correctamente
</ResponseField>

<ResponseField name="conversation_id" type="integer">
  El ID de la conversación asociada a este mensaje
</ResponseField>

<ResponseField name="message_id" type="integer">
  El ID del registro de mensaje de la conversación
</ResponseField>

<ResponseField name="whatsapp_message_id" type="integer">
  El ID del registro de mensaje de WhatsApp
</ResponseField>

<ResponseField name="message_sid" type="string">
  El SID de mensaje de Twilio para el seguimiento de la entrega
</ResponseField>

<ResponseField name="session_status" type="object">
  Estado de la sesión actualizado después de enviar el mensaje

  <Expandable title="Propiedades de session_status">
    <ResponseField name="is_open" type="boolean">
      Indica si la ventana de mensajería de 24 horas está abierta actualmente
    </ResponseField>

    <ResponseField name="can_send_freeform" type="boolean">
      Indica si se pueden enviar mensajes de texto libre en este momento
    </ResponseField>

    <ResponseField name="requires_template" type="boolean">
      Indica si se requiere un mensaje de plantilla
    </ResponseField>

    <ResponseField name="message" type="string">
      Descripción legible para humanos del estado de la sesión
    </ResponseField>

    <ResponseField name="minutes_remaining" type="integer">
      Minutos restantes de la ventana de 24 horas
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      Marca de tiempo ISO 8601 de cuándo expira la sesión
    </ResponseField>
  </Expandable>
</ResponseField>

### Respuestas de error

<ResponseField name="402 Insufficient Balance">
  <Expandable title="Respuesta de error">
    <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="Respuesta de error">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">Mensaje que indica que la ventana de mensajería de 24 horas ha expirado</ResponseField>
    <ResponseField name="error_code" type="string">`SESSION_EXPIRED`</ResponseField>

    <ResponseField name="session_status" type="object">
      Estado actual de la sesión con los campos `is_open`, `can_send_freeform`, `requires_template` y `message`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="404 Not Found">
  <Expandable title="Respuesta de error">
    <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="Respuesta de error">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">Mensaje que indica que el remitente está desconectado actualmente</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_OFFLINE`</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null} theme={null}
  curl -X POST "https://app.famulor.de/api/user/whatsapp/send-freeform" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sender_id": 12,
      "recipient_phone": "+1234567890",
      "message": "Thank you for your inquiry! Our team will review your request and get back to you within 2 hours."
    }'
  ```

  ```javascript JavaScript theme={null} theme={null}
  const response = await fetch(
    'https://app.famulor.de/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: 'Thank you for your inquiry! Our team will review your request and get back to you within 2 hours.'
      })
    }
  );

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

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

  response = requests.post(
      'https://app.famulor.de/api/user/whatsapp/send-freeform',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'sender_id': 12,
          'recipient_phone': '+1234567890',
          'message': 'Thank you for your inquiry! Our team will review your request and get back to you within 2 hours.'
      }
  )

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

<ResponseExample>
  ```json 200 Success theme={null} 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": "Session open (23 hr 45 min remaining). Unlimited free-form messages allowed.",
      "minutes_remaining": 1425,
      "expires_at": "2026-02-25T10:30:00+00:00"
    }
  }
  ```

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

  ```json 403 Session Expired theme={null} theme={null}
  {
    "success": false,
    "error": "The 24-hour messaging window is closed. Customer must reply first, or use a template message.",
    "error_code": "SESSION_EXPIRED",
    "session_status": {
      "is_open": false,
      "can_send_freeform": false,
      "requires_template": true,
      "message": "Session expired. Send a template or wait for customer to reply.",
      "expired_at": "2026-02-23T10:30:00+00:00"
    }
  }
  ```

  ```json 404 Sender Not Found theme={null} theme={null}
  {
    "success": false,
    "error": "Sender not found or does not belong to you",
    "error_code": "SENDER_NOT_FOUND"
  }
  ```

  ```json 422 Invalid Phone theme={null} theme={null}
  {
    "success": false,
    "error": "Invalid phone number format. Use E.164 format (e.g., +14155551234).",
    "error_code": "INVALID_PHONE"
  }
  ```

  ```json 503 Sender Offline theme={null} theme={null}
  {
    "success": false,
    "error": "Sender is not online. Current status: Offline",
    "error_code": "SENDER_OFFLINE"
  }
  ```
</ResponseExample>

### Ventana de mensajería de 24 horas

WhatsApp aplica una política de **ventana de mensajería de 24 horas**:

1. Cuando un cliente envía un mensaje a tu número de WhatsApp Business, se abre una ventana de 24 horas.
2. Durante esta ventana, puedes enviar mensajes de texto libre sin restricciones.
3. Una vez que la ventana expira, debes usar un [mensaje de plantilla](/es/api-v1/whatsapp/send-template) para reiniciar la conversación.
4. Cada nuevo mensaje del cliente reinicia el temporizador de 24 horas.

Usa el endpoint [Estado de sesión](/es/api-v1/whatsapp/session-status) para comprobar si una sesión está activa antes de intentar enviar un mensaje de texto libre.

### Notas

* La longitud máxima del mensaje es de **4096 caracteres** (límite de WhatsApp).
* El remitente debe estar `online`. Los remitentes desconectados devuelven un error `503`.
* El coste de los mensajes se deduce automáticamente del saldo de tu cuenta de Famulor.
* Límite de frecuencia: 5 solicitudes por segundo por usuario.