# Enviar mensajes

URL: https://wa.genuka.com/es/docs/messages
Language: Spanish

> Un solo endpoint que cubre toda la superficie de la Cloud API.

```http
POST /api/v1/messages
```

Un envío siempre lleva tres cosas: la conexión desde la que se envía, el destinatario y **exactamente
un campo de contenido**.

```json
{
  "connectionId": "cnx_...",
  "to": "+237699001122",
  "text": "Hello 👋"
}
```

El número va en formato internacional. Obtén `connectionId` con `GET /api/v1/connections`. Agrega
`replyTo` con el `wamid` de un mensaje entrante para citarlo en tu respuesta.

## Campos de contenido

> [!WARNING]
> **Un campo a la vez**
>
> Enviar dos campos de contenido en la misma solicitud no envía dos mensajes: solo se usa el primero
> que se reconoce. Haz dos llamadas.

### Texto y multimedia

| Campo      | Contenido                            | Límites                              |
| ---------- | ------------------------------------ | ------------------------------------ |
| `text`     | Una cadena, o `{ body, previewUrl }` | 4096 caracteres                      |
| `image`    | JPEG, PNG                            | 5 MB, pie de foto de 1024 caracteres |
| `video`    | MP4, 3GPP (H.264 + AAC)              | 16 MB                                |
| `audio`    | AAC, AMR, MP3, M4A, OGG              | 16 MB, **sin pie de foto**           |
| `document` | PDF, DOC(X), XLS(X), PPT(X), TXT     | 100 MB                               |
| `sticker`  | WebP estático o animado              | 100 KB / 500 KB                      |

### Ubicación, contactos, reacción

| Campo             | Contenido                                                     |
| ----------------- | ------------------------------------------------------------- |
| `location`        | `{ latitude, longitude, name, address }`                      |
| `locationRequest` | `{ body }` — muestra un botón "Enviar ubicación"              |
| `contacts`        | Un arreglo de tarjetas de contacto                            |
| `reaction`        | `{ messageId, emoji }` — una cadena vacía elimina la reacción |

### Mensajes interactivos

```json
{
  "connectionId": "cnx_...",
  "to": "+237699001122",
  "buttons": {
    "body": "How can we help?",
    "footer": "Genuka",
    "buttons": [
      { "id": "order", "title": "My order" },
      { "id": "support", "title": "A problem" }
    ]
  }
}
```

| Campo     | Descripción                      | Límites                                     |
| --------- | -------------------------------- | ------------------------------------------- |
| `buttons` | Botones de respuesta rápida      | **3 como máximo**, títulos de 20 caracteres |
| `list`    | Secciones y filas                | 10 secciones, **10 filas en total**         |
| `cta`     | Un único botón que lleva una URL | `url` + `displayText`                       |

La respuesta del usuario llega por webhook, con el `id` del botón o de la fila que eligió.

## Plantillas

Fuera de la ventana de 24 horas, solo se entregará una plantilla aprobada.

```json
{
  "connectionId": "cnx_...",
  "to": "+237699001122",
  "template": {
    "name": "order_confirmation",
    "language": "en",
    "body": ["Awa", "ORD-1042"]
  }
}
```

> [!NOTE]
> Un envío de plantilla abre una conversación facturable de Meta en la propia WABA del cliente: Meta
> le factura directamente al cliente. Los mensajes de servicio enviados dentro de la ventana de
> 24 horas son gratuitos.

Crea y sigue tus plantillas mediante `/api/v1/templates`. Una plantilla en estado `PAUSED` o
`REJECTED` no se puede usar: verifica su estado antes de lanzar una campaña.

## Vía de escape

Si un tipo de mensaje aún no está expuesto, `raw` reenvía un fragmento de la Cloud API tal cual:

```json
{
  "connectionId": "cnx_...",
  "to": "+237699001122",
  "raw": { "type": "interactive", "interactive": { "type": "flow" } }
}
```

No se aplica ninguna validación a `raw`: los errores vuelven de Meta tal como llegan.

## Errores comunes

| Código de Meta | Significado                                             | Qué hacer                                  |
| -------------- | ------------------------------------------------------- | ------------------------------------------ |
| `131047`       | Han pasado más de 24 h desde el último mensaje entrante | Envía una plantilla                        |
| `131026`       | Destinatario inaccesible o sin WhatsApp                 | No reintentes                              |
| `131050`       | El usuario se dio de baja del marketing                 | No vuelvas a enviarle marketing nunca      |
| `131049`       | Se alcanzó el límite de marketing por usuario           | Reintenta más tarde                        |
| `132001`       | Plantilla inexistente o no aprobada en ese idioma       | Verifica el nombre y el idioma             |
| `130429`       | Se superó el ritmo de envío                             | Reduce la velocidad, reintenta con backoff |
