# Enviar texto

> Envía un mensaje de texto con POST /v1/messages por WhatsApp, Instagram o Messenger, con vista previa de enlace, respuesta, "escribiendo" y retraso.

`POST /v1/messages` con `type: "text"` envía texto libre. Funciona en WhatsApp, Instagram y Messenger.

## Antes de empezar

- Una clave de API con el permiso `send` (consulta [Autenticación](/es/api/authentication/)).
- Una conexión **Activa** del canal que vas a usar.
- El mensaje libre solo sale dentro de las 24 horas posteriores al último mensaje del contacto (consulta [Ventanas](/es/api/limits/#ventanas)). Fuera de ella, usa una plantilla.

## Enviar un texto

**cURL**

```bash
curl https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "connection_id": "conn_...",
    "to": "5511999999999",
    "type": "text",
    "text": { "body": "¡Hola! Tu pedido salió para la entrega." }
  }'
```

**TypeScript**

```ts
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });

const sent = await messajo.messages.send({
  connection_id: "conn_...",
  to: "5511999999999",
  type: "text",
  text: { body: "¡Hola! Tu pedido salió para la entrega." },
});
```

**n8n**

n8n HTTP Request: POST https://api.messajo.com/v1/messages

```json
{
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "text",
  "text": { "body": "¡Hola! Tu pedido salió para la entrega." }
}
```

## Respuesta

La respuesta es `201`:

```json
{
  "id": "msg_...",
  "external_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjQ",
  "status": "queued",
  "meta_status": "accepted",
  "conversation_id": "cnv_...",
  "contact_id": "ctc_...",
  "created_at": "2026-11-09T12:00:00.000Z"
}
```

- `id` es el id del mensaje en Messajo (`msg_…`); `external_id` es el de Meta.
- `status` sale como `queued`. La entrega y la lectura llegan después, en el evento `message.status`.
- `meta_status` es `accepted`, `held_for_quality_assessment`, `paused` o `null`.

## Vista previa de enlace

En WhatsApp, `text.preview_url: true` pide que el enlace del mensaje se muestre con vista previa.

```json
{ "type": "text", "text": { "body": "Sigue tu pedido en https://ejemplo.com/pedido/123", "preview_url": true } }
```

## Responder a un mensaje

`reply_to` cita un mensaje anterior. Acepta el id de Messajo (`msg_…`) o el id de Meta. Un `msg_…` que no existe devuelve `404` [`not_found`](/es/errors#not_found).

## Escribiendo y retraso

- `typing: true` muestra el indicador de "escribiendo" antes de que salga el mensaje.
- `delay_ms` espera de 0 a 20000 milisegundos antes de enviar (por defecto 0).

`typing` también gasta una ficha del balde del número (consulta [Límites](/es/api/limits/)).

## Campos comunes

Valen para todas las páginas de envío.

| Campo | Descripción |
|---|---|
| `connection_id` | Conexión que envía. Opcional con clave de conexión (`mjc_…`); obligatorio con clave de organización (`mj_…`). |
| `to` | Destino. WhatsApp: teléfono con código de país (solo cuentan los dígitos), BSUID, `ctc_…` (contacto) o `grp_…` (grupo). Instagram: IGSID o `ctc_…`. Messenger: PSID o `ctc_…`. |
| `type` | Tipo de mensaje. Aquí, `text`. |
| `reply_to` | Mensaje citado: `msg_…` o id de Meta. |
| `typing` | `true` muestra "escribiendo" antes del envío. Por defecto `false`. |
| `delay_ms` | Espera antes del envío, de 0 a 20000. Por defecto 0. |
| `biz_opaque_callback_data` | WhatsApp: texto de hasta 512 caracteres devuelto junto con el estado. |
| `tag` | `"human_agent"`, solo en Instagram y Messenger. En WhatsApp devuelve `422` [`tag_not_supported_by_channel`](/es/errors#tag_not_supported_by_channel). |
| Encabezado `Idempotency-Key` | Evita envíos duplicados al repetir la llamada; vale 24 horas (consulta [Idempotencia](/es/start/concepts/#idempotencia)). |

Un campo desconocido en el cuerpo se rechaza con `400` [`validation_failed`](/es/errors#validation_failed).

## Límites y canales

| Canal | Tamaño del texto |
|---|---|
| WhatsApp | de 1 a 4096 caracteres |
| Instagram | hasta 1.000 bytes |
| Messenger | hasta 2.000 caracteres |

En Instagram y Messenger, `text.quick_replies` acepta de 1 a 13 elementos `{ "title", "payload" }`, con `title` de hasta 20 y `payload` de hasta 1000 caracteres. `text.preview_url` es solo de WhatsApp.

## Grupos

Con `to: "grp_…"`, WhatsApp acepta texto, multimedia y plantilla. Consulta [Grupos](/es/guides/groups/).

## Errores comunes

- [`outside_service_window`](/es/errors#outside_service_window) (422): fuera de las 24 horas. El fin de la ventana viene en `details[0].message`.
- [`connection_rate_limited`](/es/errors#connection_rate_limited) (429): sin fichas en el balde del número. Espera el `Retry-After` (o `retry_after_ms`) y repite.
- [`pair_rate_limited`](/es/errors#pair_rate_limited) (429): demasiados mensajes al mismo contacto en poco tiempo.
- [`recipient_unavailable`](/es/errors#recipient_unavailable) (422): Meta no pudo entregar a ese destino.
- [`type_not_supported_by_channel`](/es/errors#type_not_supported_by_channel) (422): el canal no acepta ese tipo.
- [`meta_unknown_outcome`](/es/errors#meta_unknown_outcome) (502): no se sabe si el mensaje salió. No reenvíes a ciegas; comprueba primero.
- [`connection_needs_reconnect`](/es/errors#connection_needs_reconnect) (409): la conexión perdió el acceso y debe reconectarse.
