# Mensajes

> Enviar un mensaje a un lead en WhatsApp a través del motor anti-ban, o en Instagram y Messenger dentro de la ventana de 24 horas, con reintentos seguros.

Source: https://docs.whatsetter.com/es/developers/guides/messages/

`POST /messages` escribe a un lead en su propio canal, como si un compañero hubiera respondido en el dashboard. En WhatsApp sale del número de su campaña y las reglas anti-ban se aplican en el servidor. En Instagram y Messenger sale de la cuenta o de la página, dentro de la ventana de 24 horas de Meta ([más abajo](#instagram-y-messenger)).

## Endpoints

| Método | Ruta | Scope |
|---|---|---|
| POST | [`/messages`](/api-reference/operations/sendmessage/) | `messages:send` |

## Enviar un mensaje

**cURL**

```bash
curl -X POST "https://app.whatsetter.com/api/v1/messages" \
  -H "Authorization: Bearer ws_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8c3d2f9e-7b1a-4e6f-9c0d-2a1b3c4d5e6f" \
  -d '{"lead_id":"66f1a2b3c4d5e6f7a8b9c0d1","text":"¿Confirmamos mañana a las 14h?"}'
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ws_live_…',
    'Content-Type': 'application/json',
    'Idempotency-Key': '8c3d2f9e-7b1a-4e6f-9c0d-2a1b3c4d5e6f',
  },
  body: JSON.stringify({
    lead_id: '66f1a2b3c4d5e6f7a8b9c0d1',
    text: '¿Confirmamos mañana a las 14h?',
  }),
});
const { data: message } = await res.json();
```

**Python**

```python
import requests

r = requests.post(
    "https://app.whatsetter.com/api/v1/messages",
    headers={
        "Authorization": "Bearer ws_live_…",
        "Idempotency-Key": "8c3d2f9e-7b1a-4e6f-9c0d-2a1b3c4d5e6f",
    },
    json={
        "lead_id": "66f1a2b3c4d5e6f7a8b9c0d1",
        "text": "¿Confirmamos mañana a las 14h?",
    },
)
message = r.json()["data"]
```

```json
{
  "data": {
    "id": "66f1a2b3c4d5e6f7a8b9c0e5",
    "message_id": "true_34612345678@c.us_3EB0C8F2A1D4B5E6F7A8",
    "lead_id": "66f1a2b3c4d5e6f7a8b9c0d1",
    "text": "¿Confirmamos mañana a las 14h?",
    "sent_at": "2026-09-19T08:12:04.000Z",
    "humanized": true,
    "typing_ms": 3210,
    "quota": {
      "limit": 250,
      "used": 41,
      "remaining": 209,
      "resets_at": "2026-09-20T00:00:00.000Z"
    }
  }
}
```

| Campo | Significado |
|---|---|
| `id` | El id de la fila de conversación en WhatSetter, o `null` si la fila no se pudo escribir tras el envío. |
| `message_id` | El id del mensaje de WhatsApp. |
| `lead_id` | El lead al que escribiste. |
| `text` | El texto enviado. |
| `sent_at` | Cuándo lo aceptó el motor. |
| `humanized` | Si se reprodujo la coreografía humana. |
| `typing_ms` | El retraso de escritura simulado, `0` cuando `humanize` es `false`. |
| `quota` | El presupuesto diario del número tras este envío. |

`201` significa que el motor de WhatsApp aceptó el mensaje. La entrega final es asíncrona, como en cualquier API de WhatsApp. El mensaje aparece en la conversación del dashboard como una respuesta manual.

## Las reglas

### Sin prospección en frío

El lead ya debe tener una conversación: al menos un mensaje intercambiado. Si no, recibes `409 lead_not_contacted`. El primer contacto pasa por una [lista y una campaña](/es/developers/guides/lists-import/) o por un [lead opt-in](/es/developers/guides/campaigns/).

### Cuota diaria por número

Cada envío consume el mismo presupuesto diario que el motor de campaña para ese número de WhatsApp (250 mensajes al día cuando no hay una cuota específica configurada). Al alcanzarlo: `429 quota_exceeded`, se reinicia a medianoche UTC.

Cada `201` y cada `429` llevan el presupuesto en las cabeceras:

```
X-Quota-Limit: 250
X-Quota-Remaining: 209
X-Quota-Reset: 2026-09-20T00:00:00.000Z
```

### El número debe estar conectado

Si la campaña no tiene número de WhatsApp, o el número está desconectado, recibes `503 agent_disconnected`. Comprueba `whatsapp_connected` en [`GET /campaigns`](/api-reference/operations/listcampaigns/) y reconéctalo desde el dashboard.

### Envío humanizado

Por defecto (`humanize: true`), el envío reproduce una coreografía humana: confirmación de lectura, indicador «escribiendo», un retraso de escritura proporcional a la longitud del mensaje, y después el envío. Cuenta con 3 a 15 segundos por petición. Es el modo recomendado.

`"humanize": false` envía al instante, siempre bajo cuota. Resérvalo para confirmaciones urgentes.

### El texto

`text` es obligatorio, de 1 a 4096 caracteres, solo texto.

## Instagram y Messenger

La misma llamada, el mismo cuerpo, en un lead cuyo `channel` es `instagram` o `facebook` (Messenger). El mensaje sale por el camino de la bandeja de entrada del dashboard y aparece en el hilo como una respuesta manual.

- **Solo en las 24 horas que siguen al último mensaje de la persona.** Es la regla de Meta para una empresa. Después recibes `409 messaging_window_closed` con `window_closes_at` (cuándo se cerró), y no se envía nada: espera a que la persona vuelva a escribir. WhatSetter nunca usa por la API la etiqueta que alarga la ventana a 7 días; está reservada a una respuesta que una persona escribe en la bandeja de entrada.
- **Como una respuesta escrita en la bandeja de entrada, pone al agente en pausa** en este lead durante el `human_pause_hours` de la cuenta ([guía de Instagram](/es/developers/guides/instagram/)), para que no responda encima de ti. La respuesta dice hasta cuándo en `agent_paused_until`. [`POST /leads/{id}/resume`](/es/developers/guides/leads/) termina la pausa.
- **El texto**: 1000 caracteres en Instagram, 2000 en Messenger. No se aplican ni la cuota de WhatsApp ni el envío humanizado: `humanize` se ignora, `quota` es `null`.

```json
{
  "error": {
    "code": "messaging_window_closed",
    "message": "Instagram lets a business answer only within 24 hours of the person's last message. Wait for them to write again.",
    "window_closes_at": "2026-10-29T18:42:10.000Z"
  }
}
```

`GET /conversations?channel=instagram&needs_reply=true` lista los hilos que esperan una respuesta ([Conversaciones](/es/developers/guides/conversations/)).

## Reintentar sin riesgo con Idempotency-Key

Una API de mensajes debe poder reintentarse sin peligro: un timeout nunca debe convertirse en un segundo mensaje real de WhatsApp. Pasa una cabecera `Idempotency-Key` en cada envío, única por intención (un UUID, un id de pedido…), hasta 200 caracteres. WhatSetter la recuerda 15 minutos.

| Situación | Qué obtiene un reintento con la misma clave |
|---|---|
| La primera llamada respondió `201` | El mismo cuerpo `201`, con la cabecera `X-Idempotent-Replay: true`. Sin segundo mensaje. |
| La primera llamada sigue en curso | `409 request_in_flight`. Espera y reintenta. |
| La primera llamada falló limpiamente (`422`, `409`, `429`, `503`) | La clave se libera: tu reintento es un intento nuevo de verdad. |
| La primera llamada caducó (`502 send_failed`) | `409 request_in_flight` hasta el final de la ventana: puede que el mensaje haya salido. Comprueba la [transcripción](/es/developers/guides/conversations/) antes de volver a enviar. |

> **Sin clave, un reintento puede enviar dos veces**
Un `502` sin `Idempotency-Key` es ambiguo: puede que el mensaje se haya entregado. No reintentes a ciegas; mira primero la transcripción.

## Errores que encontrarás

| HTTP | `code` | Cuándo |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Clave ausente, desconocida o revocada. |
| 403 | `insufficient_scope` | La clave no tiene `messages:send`. |
| 404 | `not_found` | Lead desconocido, o lead de otro espacio de trabajo. |
| 409 | `lead_not_contacted` | El lead nunca fue contactado. Pasa por una lista o un lead opt-in. |
| 409 | `request_in_flight` | La misma `Idempotency-Key` sigue procesándose, o un intento anterior con ella caducó. |
| 409 | `messaging_window_closed` | Instagram o Messenger: más de 24 horas desde el último mensaje de la persona. Mira `window_closes_at`. |
| 409 | `recipient_unreachable` | Instagram o Messenger: la persona no recibe mensajes de la cuenta ahora mismo (la bloqueó, o desactivó sus mensajes). |
| 409 | `instagram_reconnect_required`, `facebook_reconnect_required`, `facebook_page_required`, `instagram_account_not_found` | Instagram o Messenger: la cuenta o la página debe volver a conectarse desde el dashboard. |
| 403 | `instagram_not_enabled` | Un lead de Instagram, e Instagram no está activado en el espacio. |
| 422 | `validation_error` | `lead_id` ausente, `text` vacío o demasiado largo, `humanize` que no es booleano, clave de más de 200 caracteres. |
| 429 | `quota_exceeded` | Presupuesto diario del número alcanzado. Ver `X-Quota-Reset`. |
| 429 | `rate_limited` | Demasiadas peticiones este minuto. Respeta `Retry-After`. |
| 500 | `internal_error` | Motor de mensajería no configurado por nuestra parte. |
| 502 | `send_failed` | El motor rechazó o no confirmó el envío. Reintenta con la misma clave. |
| 503 | `agent_disconnected` | Sin número en la campaña, o número desconectado. |

## Relacionado

- [Leads: pasar una conversación a una persona](/es/developers/guides/leads/)
- [Conversaciones y transcripciones](/es/developers/guides/conversations/)
- [Instagram: cuentas, mensajes privados, automatizaciones, publicaciones](/es/developers/guides/instagram/)
- [Protección anti-ban](/es/dashboard/anti-ban/)
- [Autenticación y límites de peticiones](/es/developers/authentication/)
