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

# Enviar Mensaje de Texto

> Envía mensajes de texto simple a WhatsApp

El endpoint principal para enviar mensajes. Esta página cubre mensajes de texto. Para otros tipos, consulta:

<CardGroup cols={2}>
  <Card title="Media" icon="image" href="/api-reference/messages/send-media">
    Imágenes, videos, audio, documentos, stickers
  </Card>

  <Card title="Templates" icon="table-layout" href="/api-reference/messages/send-templates">
    Templates pre-aprobados por Meta
  </Card>

  <Card title="Interactive" icon="hand-pointer" href="/api-reference/messages/send-interactive">
    Botones y listas interactivas
  </Card>

  <Card title="Ubicación" icon="location-dot" href="/api-reference/messages/send-location">
    Coordenadas GPS y direcciones
  </Card>
</CardGroup>

***

## Formato Híbrido

Whaapy acepta **dos estilos** de request, dándote flexibilidad:

<Tabs>
  <Tab title="Estilo Whaapy (Simplificado)">
    Formato minimalista para casos comunes:

    ```json theme={null}
    {
      "to": "+5215512345678",
      "content": "¡Hola! Gracias por contactarnos."
    }
    ```
  </Tab>

  <Tab title="Estilo Meta (Compatible)">
    100% compatible con WhatsApp Cloud API:

    ```json theme={null}
    {
      "messaging_product": "whatsapp",
      "to": "+5215512345678",
      "type": "text",
      "text": { 
        "body": "¡Hola! Gracias por contactarnos.",
        "preview_url": true
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  El estilo Whaapy es más corto y fácil de usar. El estilo Meta es útil si ya tienes código funcionando con la API oficial de WhatsApp.
</Tip>

***

## Campos de Destino

Debes proporcionar **al menos uno** de estos campos para identificar el destinatario:

<ParamField body="to" type="string">
  Número de teléfono con código de país. Ejemplo: `+5215512345678`
</ParamField>

<ParamField body="phone_number" type="string">
  Alias de `to`. Mismo formato.
</ParamField>

<ParamField body="conversationId" type="string">
  UUID de una conversación existente en Whaapy. Útil para responder en conversaciones activas.
</ParamField>

<Note>
  Si proporcionas `conversationId`, Whaapy obtiene automáticamente el número de teléfono de esa conversación.
</Note>

***

## Campos de Contenido (Texto)

<ParamField body="content" type="string">
  **Estilo Whaapy**. El texto del mensaje a enviar.
</ParamField>

<ParamField body="text" type="object">
  **Estilo Meta**. Objeto con las siguientes propiedades:

  * `body` (string, requerido): El texto del mensaje
  * `preview_url` (boolean, opcional): Si mostrar vista previa de URLs
</ParamField>

***

## Ejemplos

### Texto Simple (Estilo Whaapy)

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.whaapy.com/messages/v1 \
    -H "Authorization: Bearer wha_TU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+5215512345678",
      "content": "¡Hola! Gracias por tu mensaje. Te responderemos pronto."
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.whaapy.com/messages/v1', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer wha_TU_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '+5215512345678',
      content: '¡Hola! Gracias por tu mensaje. Te responderemos pronto.'
    })
  });

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

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

  response = requests.post(
      'https://api.whaapy.com/messages/v1',
      headers={
          'Authorization': 'Bearer wha_TU_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'to': '+5215512345678',
          'content': '¡Hola! Gracias por tu mensaje. Te responderemos pronto.'
      }
  )

  print(response.json())
  ```

  ```php PHP theme={null}
  $ch = curl_init('https://api.whaapy.com/messages/v1');
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer wha_TU_API_KEY',
      'Content-Type: application/json'
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'to' => '+5215512345678',
      'content' => '¡Hola! Gracias por tu mensaje. Te responderemos pronto.'
  ]));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  echo $response;
  ```
</RequestExample>

### Texto con Vista Previa de URL (Estilo Meta)

<RequestExample>
  ```json Request theme={null}
  {
    "to": "+5215512345678",
    "type": "text",
    "text": {
      "body": "Mira nuestro catálogo: https://whaapy.com/productos",
      "preview_url": true
    }
  }
  ```
</RequestExample>

<Info>
  Con `preview_url: true`, WhatsApp mostrará una vista previa enriquecida del enlace (imagen, título, descripción) si la URL lo soporta.
</Info>

### Responder a Conversación Existente

<RequestExample>
  ```json Request theme={null}
  {
    "conversationId": "550e8400-e29b-41d4-a716-446655440000",
    "content": "Gracias por tu paciencia. Ya tenemos tu pedido listo."
  }
  ```
</RequestExample>

***

## Respuesta Exitosa

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "messaging_product": "whatsapp",
    "contacts": [
      { "input": "+5215512345678", "wa_id": "5215512345678" }
    ],
    "messages": [
      { "id": "550e8400-e29b-41d4-a716-446655440000", "wamid": "wamid.HBgLNTIxNTUx..." }
    ],
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "conversationId": "660e8400-e29b-41d4-a716-446655440001",
      "content": "¡Hola! Gracias por tu mensaje.",
      "messageType": "text",
      "direction": "outbound",
      "status": "sent",
      "createdAt": "2026-01-22T10:30:00Z"
    }
  }
  ```
</ResponseExample>

### Campos de Respuesta

| Campo                 | Descripción                                                 |
| --------------------- | ----------------------------------------------------------- |
| `messaging_product`   | Siempre `"whatsapp"`                                        |
| `contacts`            | Array con info del contacto (`wa_id` es el ID de WhatsApp)  |
| `messages`            | Array con IDs del mensaje (`id` de Whaapy, `wamid` de Meta) |
| `data.id`             | UUID del mensaje en Whaapy (usar para retry)                |
| `data.conversationId` | UUID de la conversación                                     |
| `data.status`         | Estado: `sent`, `delivered`, `read`, `failed`               |

***

## Errores Comunes

### Ventana de 24 Horas Expirada

<ResponseExample>
  ```json Error 131047 theme={null}
  {
    "error": "message_delivery_failed",
    "message": "La ventana de conversación de 24 horas ha expirado",
    "code": "131047",
    "action_required": "Usar template message",
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "failed"
    }
  }
  ```
</ResponseExample>

<Warning>
  WhatsApp solo permite enviar mensajes de texto libre dentro de las 24 horas posteriores al último mensaje del usuario. Fuera de esta ventana, debes usar un [template message](/api-reference/messages/send-templates).
</Warning>

Ver [Códigos de Error](/api-reference/errors) para la lista completa de errores.

***

## Control de IA (Opcional)

Puedes controlar el comportamiento del agente IA al enviar mensajes usando el campo `ai`:

<ParamField body="ai.pause" type="boolean">
  Pausar la IA después de enviar este mensaje
</ParamField>

<ParamField body="ai.pauseDuration" type="number">
  Duración de la pausa en minutos (default: 5, máximo: 1440)
</ParamField>

<ParamField body="ai.disable" type="boolean">
  Desactivar la IA permanentemente en esta conversación
</ParamField>

### Ejemplo: Enviar y Pausar IA

```json theme={null}
{
  "to": "+5215512345678",
  "content": "Te atiendo personalmente",
  "ai": { "pause": true, "pauseDuration": 30 }
}
```

<Info>
  Esto es útil cuando integras con sistemas externos (n8n, Zapier, CRMs) y necesitas evitar que la IA responda automáticamente. Ver [Agente IA](/api-reference/agent/overview) para más opciones.
</Info>

***

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Enviar Media" icon="image" href="/api-reference/messages/send-media">
    Imágenes, videos, audio, documentos
  </Card>

  <Card title="Templates" icon="table-layout" href="/api-reference/messages/send-templates">
    Mensajes fuera de ventana de 24h
  </Card>

  <Card title="Reintentar Mensaje" icon="rotate" href="/api-reference/messages/retry">
    Reenviar mensajes fallidos
  </Card>

  <Card title="Subir Media" icon="upload" href="/api-reference/media/upload-media">
    Subir archivos grandes
  </Card>
</CardGroup>