# Referencia de la API

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

> Una sola API para controlarlo todo de forma programática: números, plantillas, mensajes, campañas y tu suscripción.

Construye tu propio producto sobre ella.

> [!NOTE]
> **Especificación OpenAPI**
>
> Toda la API está descrita en OpenAPI 3.1 en
> [`https://wa.genuka.com/openapi.json`](https://wa.genuka.com/openapi.json): impórtala en
> Postman o Insomnia, o dásela a un agente de programación con IA. Para los agentes,
> [`/llms.txt`](https://wa.genuka.com/llms.txt) indexa toda la documentación.

## Autenticación

Todas las solicitudes usan una clave API del lado del servidor. Genera una en tu panel, en
**Claves API**: tiene la forma `pk_live_…` y se muestra una sola vez. Envíala como bearer token:

```http title="Encabezado"
Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

> [!WARNING]
> **Mantén las claves del lado del servidor**
>
> Una clave puede enviar mensajes desde todos los números que cubre. Nunca la expongas en un
> navegador ni en una app móvil: llama a la API únicamente desde tu backend.

### Alcance de la clave

Una clave abarca toda la cuenta o está vinculada a una sola empresa conectada. Elige la empresa al
generar la clave en **Claves API**. Una clave con alcance restringido solo resuelve esa empresa: las
listas devuelven únicamente sus filas, los ids que pertenecen a otra responden `404` y
`GET /api/v1/subscription` responde 403; así puedes entregársela a esa empresa (o ejecutar su
integración) sin exponer el resto de tu cuenta. Las claves de toda la cuenta llegan a todos los
números que conectaste.

## Convenciones

URL base `https://wa.genuka.com/api/v1`. Los cuerpos y las respuestas son JSON. Los endpoints de
listado devuelven `{ "data": [...] }`. Todo queda automáticamente limitado a tu cuenta. Los errores
usan códigos de estado HTTP con `{ "error": "code", "message": "…" }`.

Llama a `wa.genuka.com` por **https** y sin barra final: `http://` devuelve un `301` hacia https,
`/api/v1/messages/` un `308` hacia la forma sin barra, y algunos clientes HTTP descartan el
encabezado `Authorization` al seguir una redirección. Ningún otro nombre de host sirve esta API.

> [!WARNING]
> **Envía un User-Agent**
>
> Nuestra CDN rechaza algunas firmas de bots conocidas antes de que lleguen a la API. La que más
> encuentran nuestros integradores es `Python-urllib/3.x`, el encabezado que `urllib` envía por
> defecto: responde `403` con el cuerpo `error code: 1010`, que no proviene de nosotros y por lo
> tanto no lleva JSON. Envía un `User-Agent` que identifique tu integración, que es además lo que te
> permitirá encontrarte en tus propios registros:
>
> ```python
> request.add_header("User-Agent", "acme-crm/1.4 (+https://example.com)")
> ```
>
> `requests`, `curl`, `axios`, `node-fetch` y los clientes de Go y Java pasan sin ningún cambio.

## Empresas (negocios conectados)

| Método | Endpoint                 | Descripción                                      |
| ------ | ------------------------ | ------------------------------------------------ |
| `GET`  | `/api/v1/companies`      | Lista las empresas conectadas con sus conexiones |
| `GET`  | `/api/v1/companies/{id}` | Una empresa + conexiones + conteos               |

```bash title="GET /api/v1/companies"
curl https://wa.genuka.com/api/v1/companies -H "Authorization: Bearer pk_live_xxx"

{
  "data": [
    {
      "id": "cmp_123",
      "name": "Acme Coffee",
      "onboardedAt": "2026-06-01T10:12:00.000Z",
      "connections": [
        { "id": "con_1", "wabaId": "1029…", "phoneNumberId": "1065…",
          "displayPhoneNumber": "+237 6 90 …", "qualityRating": "GREEN", "status": "connected" }
      ],
      "_count": { "templates": 4 }
    }
  ]
}
```

## Conexiones (números)

| Método | Endpoint              | Descripción                                                                |
| ------ | --------------------- | -------------------------------------------------------------------------- |
| `GET`  | `/api/v1/connections` | Lista las conexiones de WhatsApp (opcional `?companyId=`, `?externalRef=`) |

Una conexión es una WABA + un número de teléfono. Su `id` es lo que pasas al crear plantillas,
campañas o al enviar mensajes.

## Plantillas

Las plantillas son formatos de mensaje aprobados previamente. Necesitas una para *iniciar* una
conversación (es decir, escribirle a un cliente fuera de la ventana de 24 horas; consulta
[Mensajes](#mensajes)). Creas una plantilla aquí, Meta la revisa, y la aprobación o el rechazo
llega automáticamente a `GET /templates/{id}` (y a tus [webhooks](https://wa.genuka.com/es/docs/webhooks)).

| Método   | Endpoint                 | Descripción                                   |
| -------- | ------------------------ | --------------------------------------------- |
| `GET`    | `/api/v1/templates`      | Lista las plantillas (opcional `?companyId=`) |
| `POST`   | `/api/v1/templates`      | Crea y envía una plantilla a Meta             |
| `GET`    | `/api/v1/templates/{id}` | Una plantilla + su historial de estados       |
| `POST`   | `/api/v1/templates/sync` | Vuelve a leer todos los estados desde Meta    |
| `DELETE` | `/api/v1/templates/{id}` | Elimina en Meta y localmente                  |

### Cómo funciona la creación

Pasas el arreglo `components` de Meta **tal cual**. Eso mantiene este endpoint ligero y te permite
construir *cualquier* plantilla que Meta admita: texto, encabezados multimedia, botones, OTP, etc.
Los únicos campos obligatorios son `connectionId`, `name` y `components`. `category` es uno de
`MARKETING`, `UTILITY` o `AUTHENTICATION` (por defecto `MARKETING`); `language` es una configuración
regional de Meta como `en_US` o `fr` (por defecto `en`).

### Referencia de componentes

Una plantilla es una lista ordenada de componentes. Cada uno tiene un `type`:

| Tipo      | Forma                                                    | Descripción                                                                             |
| --------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `HEADER`  | `format: TEXT \| IMAGE \| VIDEO \| DOCUMENT \| LOCATION` | Opcional. Uno por plantilla. Los encabezados multimedia necesitan un handle de ejemplo. |
| `BODY`    | `text` + `example`                                       | Obligatorio (excepto en AUTHENTICATION). Contiene las variables `{{1}}`… o `{{name}}`.  |
| `FOOTER`  | `text`                                                   | Pie de página corto opcional. Sin variables.                                            |
| `BUTTONS` | `QUICK_REPLY \| URL \| PHONE_NUMBER \| COPY_CODE \| OTP` | Opcional. Hasta 10 botones (las reglas varían según el tipo).                           |

> [!NOTE]
> **Los ejemplos son obligatorios**
>
> Todo componente con variables (o un encabezado multimedia) debe incluir un `example` para que Meta
> pueda revisarlo: `"example": { "body_text": [["Alice", "#1024"]] }` para el cuerpo,
> `"example": { "header_handle": ["<id>"] }` para un encabezado multimedia.

### Plantilla de utilidad / marketing (encabezado + cuerpo + botones)

```bash title="POST /api/v1/templates"
curl -X POST https://wa.genuka.com/api/v1/templates \
  -H "Authorization: Bearer pk_live_xxx" -H "Content-Type: application/json" \
  -d '{
    "connectionId": "con_1",
    "name": "order_shipped",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      { "type": "HEADER", "format": "IMAGE",
        "example": { "header_handle": ["4::aW1hZ2Uv..."] } },
      { "type": "BODY",
        "text": "Hi {{1}}, order {{2}} just shipped. Track it any time.",
        "example": { "body_text": [["Alice", "#1024"]] } },
      { "type": "FOOTER", "text": "Reply STOP to opt out" },
      { "type": "BUTTONS", "buttons": [
        { "type": "URL", "text": "Track order",
          "url": "https://example.com/track/{{1}}", "example": ["https://example.com/track/1024"] },
        { "type": "QUICK_REPLY", "text": "Need help" }
      ] }
    ]
  }'

{ "data": { "id": "tpl_123", "status": "pending", "providerId": "12534…" } }
```

El `example.header_handle` del encabezado multimedia es el handle de carga reanudable que devuelve
la carga de multimedia de Meta; en el momento del *envío* proporcionas la imagen real por URL o por
media id (consulta [Mensajes → plantilla](#mensajes)).

### Parámetros con nombre

¿Prefieres `{{name}}` en lugar del posicional `{{1}}`? Define `parameterFormat: "NAMED"` y asigna a
cada variable un `parameter_name` en el ejemplo.

```json title="POST /api/v1/templates (con nombre)"
{
  "connectionId": "con_1",
  "name": "appointment_reminder",
  "language": "en_US",
  "category": "UTILITY",
  "parameterFormat": "NAMED",
  "components": [
    { "type": "BODY",
      "text": "Hi {{customer_name}}, your appointment is on {{date}}.",
      "example": { "body_text_named_params": [
        { "param_name": "customer_name", "example": "Alice" },
        { "param_name": "date", "example": "June 20" }
      ] } }
  ]
}
```

### Plantilla de autenticación (OTP)

Las plantillas de autenticación entregan códigos de un solo uso. El texto del cuerpo y del botón
**los fija WhatsApp**: tú no redactas el texto. Solo eliges el tipo de botón y algunas opciones. No
se permiten encabezados, multimedia, URLs ni emojis.

| Tipo        | Forma                 | Descripción                                                                              |
| ----------- | --------------------- | ---------------------------------------------------------------------------------------- |
| `COPY_CODE` | `otp_type: COPY_CODE` | El cliente toca para copiar el código. Lo más simple, funciona en todas partes.          |
| `ONE_TAP`   | `otp_type: ONE_TAP`   | Autocompletado en Android. Requiere `package_name` + `signature_hash`.                   |
| `ZERO_TAP`  | `otp_type: ZERO_TAP`  | El código se entrega de forma silenciosa a la app. Requiere el mismo vínculo con la app. |

```json title="POST /api/v1/templates (autenticación)"
{
  "connectionId": "con_1",
  "name": "verification_code",
  "language": "en_US",
  "category": "AUTHENTICATION",
  "messageSendTtlSeconds": 600,
  "components": [
    { "type": "BODY", "add_security_recommendation": true },
    { "type": "FOOTER", "code_expiration_minutes": 10 },
    { "type": "BUTTONS", "buttons": [
      { "type": "OTP", "otp_type": "COPY_CODE", "text": "Copy code" }
    ] }
  ]
}
```

Para `ONE_TAP` / `ZERO_TAP`, agrega el vínculo con la app al botón OTP: `"autofill_text": "Autofill"`,
`"supported_apps": [{ "package_name": "com.example.app", "signature_hash": "K8a..." }]`.

> [!NOTE]
> **Enviar el código**
>
> Crear la plantilla nunca envía nada. Para entregar un código, envías un mensaje `template` con el
> atajo `otp`: consulta [Mensajes → plantilla de autenticación](#mensajes).

### Actualizar los estados

El resultado de una revisión te llega como [webhook](https://wa.genuka.com/es/docs/webhooks): esa es la vía sobre la que
debes construir. Pero un webhook que nunca se entregó (un endpoint caído, una integración agregada
después) deja la plantilla en `pending` aquí mucho después de que Meta la aprobó, y una campaña que
se niega a lanzarse sin motivo visible. `POST /api/v1/templates/sync` vuelve a leer la verdad desde
Meta y la escribe de nuevo.

```bash title="POST /api/v1/templates/sync"
curl -X POST https://wa.genuka.com/api/v1/templates/sync \
  -H "Authorization: Bearer pk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "companyId": "cmp_1" }'
```

El cuerpo es opcional: sin ningún campo, la actualización cubre todas las cuentas de WhatsApp a las
que llega tu clave; `companyId` la limita a un cliente y `connectionId` a la WABA de un solo número.
La respuesta nombra cada cuenta de WhatsApp que procesó (así, una cuenta inaccesible se informa en
lugar de ocultarse) y devuelve las filas recién escritas, lo que te ahorra un `GET` posterior.

```json title="200 OK"
{
  "data": {
    "wabas": [{ "wabaId": "1029…", "companyId": "cmp_1", "ok": true }],
    "synced": 1,
    "failed": 0,
    "templates": [
      { "id": "tpl_1", "name": "order_shipped", "language": "fr", "status": "approved", "…": "…" }
    ]
  }
}
```

Una actualización en la que *todas* las cuentas se negaron responde `502 meta_rejected` con los
mismos `results` en el cuerpo; un fallo parcial sigue siendo un `200` que debes leer.
`GET /api/v1/templates?sync=true` hace la misma actualización en línea antes de listar, y acepta los
mismos filtros `companyId` / `connectionId`.

> [!NOTE]
> **Es una vía de reparación, no un bucle de sondeo**
>
> Cada llamada consume una lectura de Meta por cuenta de WhatsApp. Ejecútala de forma programada si
> quieres (cada hora es más que suficiente), pero conserva el webhook como la forma normal en que
> llegan los estados.

## Campañas

| Método | Endpoint                            | Descripción                                     |
| ------ | ----------------------------------- | ----------------------------------------------- |
| `GET`  | `/api/v1/campaigns`                 | Lista las campañas (opcional `?companyId=`)     |
| `POST` | `/api/v1/campaigns`                 | Crea una campaña con destinatarios              |
| `GET`  | `/api/v1/campaigns/{id}`            | Una campaña con estadísticas de entrega         |
| `GET`  | `/api/v1/campaigns/{id}/recipients` | Estado por destinatario (`?status=`, `?limit=`) |
| `POST` | `/api/v1/campaigns/{id}/launch`     | Envía a todos los destinatarios pendientes      |

### Crear una campaña

Cada destinatario lleva sus propias `variables`. La forma simple es un arreglo posicional para los
parámetros del cuerpo `{{1}}, {{2}}…`. Para encabezados multimedia, botones o códigos OTP, pasa en
su lugar un objeto enriquecido (`{ "body": [...], "header": {...}, "buttons": [...] }`), con la misma
forma que acepta [Mensajes → plantilla](#mensajes). La plantilla debe estar `approved` antes del
lanzamiento. A continuación, `tpl_124` es una plantilla con solo cuerpo; `tpl_123` (`order_shipped`
más arriba, con encabezado de imagen y botón URL) necesitaría la forma enriquecida para cada
destinatario.

```bash title="POST /api/v1/campaigns"
curl -X POST https://wa.genuka.com/api/v1/campaigns \
  -H "Authorization: Bearer pk_live_xxx" -H "Content-Type: application/json" \
  -d '{
    "connectionId": "con_1",
    "templateId": "tpl_124",
    "name": "June promo",
    "recipients": [
      { "to": "+237690000001", "variables": ["Alice", "#1024"] },
      { "to": "+237690000002", "variables": ["Bob", "#1025"] }
    ]
  }'

{ "data": { "id": "cmp_9", "name": "June promo", "status": "draft", "_count": { "recipients": 2 } } }
```

### Lanzar

```bash title="POST /api/v1/campaigns/{id}/launch"
curl -X POST https://wa.genuka.com/api/v1/campaigns/cmp_9/launch \
  -H "Authorization: Bearer pk_live_xxx"

{ "data": { "sent": 2, "failed": 0, "skipped": 0 } }
```

> [!NOTE]
> **Límites**
>
> Nunca cobramos por mensaje: Meta factura directamente a tu WABA. Los destinatarios sí cuentan
> contra la cuota de mensajes de tu plan para el período, y toda la lista se verifica antes del
> primer envío, de modo que un lanzamiento que no cabría se rechaza de entrada con
> `402 plan_limit_messages` en lugar de detenerse a la mitad. Solo se consumen los destinatarios que
> Meta realmente aceptó. La V1 envía de forma síncrona: mantén listas moderadas; el envío en cola
> para listas grandes está en la hoja de ruta.

## Multimedia

Sube un archivo una vez y envíalo tantas veces como necesites. El almacenamiento es **privado**:
nada de lo que se guarda aquí es accesible desde una URL pública, y Meta nunca descarga el archivo;
le entregamos los bytes de servidor a servidor en el momento del envío.

```bash title="POST /api/v1/media (multipart)"
curl -X POST https://wa.genuka.com/api/v1/media \
  -H "Authorization: Bearer pk_live_xxx" \
  -F "companyId=cmp_1" \
  -F "file=@briefing.pdf"

{ "data": {
    "id": "ast_1",
    "url": "https://wa.genuka.com/api/v1/media/ast_1/content",
    "expiresAt": "2026-09-18T09:12:00.000Z",
    "mimeType": "application/pdf",
    "kind": "document",
    "sizeBytes": 481203,
    "filename": "briefing.pdf"
  },
  "deduplicated": false }
```

> [!NOTE]
> **Dos límites, anunciados de entrada**
>
> **Retención: 30 días.** Cada archivo se elimina de forma permanente 30 días después de su carga, y
> `expiresAt` indica exactamente cuándo. Es la propia ventana de Meta: pasado ese plazo, su copia
> desaparece de todos modos. Un envío que hace referencia a un archivo vencido responde
> `404 media_not_found`.
>
> **Almacenamiento: según el plan.** 1 GB en Starter, 3 GB en Growth, 5 GB en Scale, a medida en
> Enterprise, sumando todos los clientes. El límite se aplica a lo que está *guardado*: eliminar un
> archivo libera el espacio de inmediato. Una carga que lo superaría responde `402 plan_limit_media`
> antes de almacenar un solo byte. `GET /api/v1/media` devuelve la cifra actual en `storage`.

`url` es un endpoint de esta API, no un enlace para compartir: requiere tu clave y rechaza cualquier
llamada fuera de su alcance. Los bytes idénticos ya almacenados para este cliente se devuelven tal
cual con un `200` y `deduplicated: true`, en lugar de almacenarse dos veces.

| Ruta                               | Descripción                                                                                                                                                                     |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /api/v1/media`               | Carga. Multipart: `file` (obligatorio), `companyId` (obligatorio con una clave de socio de alcance global), `filename` (opcional).                                              |
| `GET /api/v1/media`                | Listado. Filtros `kind`, `companyId`, paginación por cursor, además de la cifra `storage`.                                                                                      |
| `GET /api/v1/media/{id}`           | Los metadatos de un archivo.                                                                                                                                                    |
| `GET /api/v1/media/{id}/content`   | Los bytes, autenticados con tu clave.                                                                                                                                           |
| `DELETE /api/v1/media/{id}`        | Elimina ahora, sin esperar al vencimiento.                                                                                                                                      |
| `POST /api/v1/media/header-handle` | Genera el `header_handle` para el encabezado de una plantilla. Multipart: `file` (obligatorio), `connectionId` **o** `companyId` (ninguno de los dos con una clave de cliente). |

### El encabezado multimedia de una plantilla: el `header_handle`

Crear una plantilla cuyo encabezado es IMAGE, VIDEO o DOCUMENT requiere un `example.header_handle`,
que Meta solo emite a través de su Resumable Upload API. **No** es lo mismo que un `assetId`: un
handle se consume una sola vez, al crear la plantilla, y un envío lo rechaza. A la inversa, un
`assetId` no sirve de nada al momento de la creación.

```bash title="POST /api/v1/media/header-handle (multipart)"
curl -X POST https://wa.genuka.com/api/v1/media/header-handle \
  -H "Authorization: Bearer pk_live_xxx" \
  -F "connectionId=con_1" \
  -F "file=@catalogue.pdf"

{ "data": {
    "handle": "4::YXBwbGljYXRpb24vcGRm…",
    "filename": "catalogue.pdf",
    "mimeType": "application/pdf",
    "sizeBytes": 481203
  } }
```

Indica el cliente como lo espera cualquier otra ruta `/media` (`-F "companyId=cmp_1"`) o un número
específico (`-F "connectionId=con_1"`); una clave de cliente no necesita ninguno de los dos. El
handle es el mismo en ambos casos: la sesión de carga pertenece a la app de Meta, no a un número.

Lleva ese `handle` a la definición de la plantilla:

```json title="POST /api/v1/templates"
{
  "connectionId": "con_1",
  "name": "morning_brief",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    { "type": "HEADER", "format": "DOCUMENT",
      "example": { "header_handle": ["4::YXBwbGljYXRpb24vcGRm…"] } },
    { "type": "BODY", "text": "Hi {{1}}, your brief for {{2}} is attached.",
      "example": { "body_text": [["Ana", "March 12"]] } }
  ]
}
```

Formatos aceptados: `image/jpeg`, `image/png`, `video/mp4`, `video/3gpp`, `application/pdf`. Tamaño
máximo de 4 MB; por encima, la respuesta es `413 media_too_large`. No guardamos nada de nuestro
lado: el handle es de un solo uso, así que archivarlo no serviría de nada.

### Enviar un archivo almacenado

Pasa `assetId` en cualquier lugar donde se espere un objeto multimedia, incluidos los encabezados de
plantilla. Resolvemos el `media_id` de Meta para el número de teléfono correcto y lo renovamos a
medida que envejece.

```json title="POST /api/v1/messages"
{
  "connectionId": "con_1",
  "to": "+237600000000",
  "document": { "assetId": "ast_1", "filename": "briefing.pdf" }
}
```

`id` (un `media_id` de Meta que generaste tú mismo) y `link` (una URL pública que Meta descarga)
siguen aceptándose. `assetId` es el preferible: es el único que no expone el archivo en ninguna URL
y el único que no vence a tus espaldas a los 30 días.

## Mensajes

| Método | Endpoint           | Descripción                             |
| ------ | ------------------ | --------------------------------------- |
| `POST` | `/api/v1/messages` | Envía un solo mensaje de cualquier tipo |

Un solo endpoint envía todos los tipos de mensaje de WhatsApp. Pasa siempre `connectionId` y `to`, y
luego **exactamente un** campo de contenido de la tabla siguiente. Agrega `replyTo` (el `wamid` de
un mensaje recibido) para citar o responder a un mensaje.

| Campo                                                | Ventana    | Descripción                                                                                                                                                        |
| ---------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `template`                                           | facturable | Plantilla aprobada previamente. La única forma de iniciar una conversación fuera de la ventana de 24 h.                                                            |
| `text`                                               | gratis\*   | `{ "text": "Hi" }` o `{ "text": { "body": "…", "previewUrl": true } }`                                                                                             |
| `image` / `video` / `audio` / `document` / `sticker` | gratis\*   | `{ "image": { "assetId": "ast_1" } }` (recomendado), `{ "link": "…" }` o `{ "id": "<media-id>" }`; `caption`/`filename` opcionales                                 |
| `location`                                           | gratis\*   | `{ "location": { "latitude": …, "longitude": …, "name": "…", "address": "…" } }`                                                                                   |
| `contacts`                                           | gratis\*   | `{ "contacts": [ … objetos de contacto de Meta … ] }`                                                                                                              |
| `reaction`                                           | gratis\*   | `{ "reaction": { "messageId": "wamid…", "emoji": "👍" } }`                                                                                                         |
| `buttons` / `list` / `cta`                           | gratis\*   | Botones de respuesta interactivos, un menú de lista o un botón URL de llamada a la acción.                                                                         |
| `locationRequest`                                    | gratis\*   | `{ "locationRequest": { "body": "Where should we deliver?" } }` — muestra un botón para enviar la ubicación.                                                       |
| `callPermissionRequest`                              | gratis\*   | `{ "callPermissionRequest": { "body": "Can we call you back?" } }` — pide permiso al cliente para llamarlo por WhatsApp (`body` opcional). Growth o superior.      |
| `voiceCall`                                          | gratis\*   | `{ "voiceCall": { "body": "Call us on WhatsApp", "displayText": "Call", "ttlMinutes": 120 } }` — un botón que llama a este número por WhatsApp. Growth o superior. |
| `raw`                                                | gratis\*   | Vía de escape para todo lo demás (Flows, dirección, catálogo): un fragmento completo de tipo de la Cloud API.                                                      |

> [!NOTE]
> **La ventana de 24 horas**
>
> Solo los envíos `template` pueden iniciar una conversación. Todo lo marcado como `free*` es un
> mensaje de *sesión* libre: solo se entrega si el cliente le escribió a la empresa en las últimas
> 24 horas. Fuera de esa ventana, usa un `template`. Todos los envíos devuelven
> `{ "data": { "messageId": "wamid…" } }`.

Un `200` significa que Meta *aceptó* el mensaje, no que se haya entregado. El estado final
(`sent` → `delivered` → `read`, o `failed`) llega de forma asíncrona a tus
[webhooks](https://wa.genuka.com/es/docs/webhooks). En `to`, incluye siempre el `+` y el código de país (por ejemplo,
`+237690000001`): omitirlo puede enrutar mal el mensaje. Meta guarda en caché durante \~10 minutos
la multimedia pasada por `link`, así que reutiliza la misma URL para el mismo recurso (o agrega una
query string única para invalidar la caché).

### Mensaje de plantilla

El caso simple es una plantilla cuyas únicas variables están en el cuerpo, como `order_update` a
continuación (sin encabezado multimedia ni botón dinámico). `variables` es un arreglo posicional;
también puedes usar `bodyNamed` para plantillas con nombre, `header` para un encabezado multimedia o
de texto, y `buttons` para los parámetros de botones dinámicos. Un envío debe completar todos los
parámetros que declara la plantilla: `order_shipped`, más arriba, tiene un encabezado de imagen y un
botón URL dinámico, así que necesita la segunda forma; solo con las variables del cuerpo, Meta lo
rechaza.

```bash title="POST /api/v1/messages (plantilla, simple)"
curl -X POST https://wa.genuka.com/api/v1/messages \
  -H "Authorization: Bearer pk_live_xxx" -H "Content-Type: application/json" \
  -d '{
    "connectionId": "con_1",
    "to": "+237690000001",
    "template": { "name": "order_update", "language": "en_US", "variables": ["Alice", "#1024"] }
  }'

{ "data": { "messageId": "wamid.HBg…" } }
```

```json title="POST /api/v1/messages (plantilla, encabezado + cuerpo + botón)"
{
  "connectionId": "con_1",
  "to": "+237690000001",
  "template": {
    "name": "order_shipped",
    "language": "en_US",
    "header": { "image": { "link": "https://example.com/orders/1024.png" } },
    "variables": ["Alice", "#1024"],
    "buttons": [
      { "type": "url", "text": "1024" }
    ]
  }
}
```

El `buttons[].text` completa la parte dinámica de un botón URL (el `{{1}}` de
`https://example.com/track/{{1}}`). Para una respuesta rápida usa
`{ "type": "quick_reply", "payload": "…" }`; para un código de cupón usa
`{ "type": "copy_code", "code": "SAVE20" }`. Parámetros de cuerpo con nombre:
`"bodyNamed": { "customer_name": "Alice" }`.

### Plantilla de autenticación

Pasa el código una sola vez con el atajo `otp`: completamos por ti tanto el cuerpo como el botón OTP
(el formato que exige Meta).

```json title="POST /api/v1/messages (autenticación)"
{
  "connectionId": "con_1",
  "to": "+237690000001",
  "template": { "name": "verification_code", "language": "en_US", "otp": "472913" }
}
```

### Mensajes de sesión libres

```json title="texto"
{ "connectionId": "con_1", "to": "+237690000001", "text": "Thanks, talk soon!" }
```

```json title="imagen (con pie de foto)"
{ "connectionId": "con_1", "to": "+237690000001",
  "image": { "link": "https://example.com/promo.jpg", "caption": "New arrivals 🎉" } }
```

```json title="documento"
{ "connectionId": "con_1", "to": "+237690000001",
  "document": { "link": "https://example.com/invoice.pdf", "filename": "invoice-1024.pdf" } }
```

```json title="botones de respuesta interactivos"
{
  "connectionId": "con_1",
  "to": "+237690000001",
  "buttons": {
    "body": "Confirm your order?",
    "footer": "Acme Coffee",
    "buttons": [
      { "id": "yes", "title": "Confirm" },
      { "id": "no",  "title": "Cancel" }
    ]
  }
}
```

```json title="lista interactiva"
{
  "connectionId": "con_1",
  "to": "+237690000001",
  "list": {
    "body": "Pick a delivery slot",
    "button": "Choose",
    "sections": [
      { "title": "Today", "rows": [
        { "id": "t1", "title": "12:00–14:00" },
        { "id": "t2", "title": "14:00–16:00", "description": "Most popular" }
      ] }
    ]
  }
}
```

```json title="botón URL de llamada a la acción"
{
  "connectionId": "con_1",
  "to": "+237690000001",
  "cta": { "body": "Your receipt is ready.", "displayText": "View receipt", "url": "https://example.com/r/1024" }
}
```

```json title="respuesta en el hilo + reacción"
{ "connectionId": "con_1", "to": "+237690000001", "replyTo": "wamid.HBg…", "text": "On its way!" }

{ "connectionId": "con_1", "to": "+237690000001",
  "reaction": { "messageId": "wamid.HBg…", "emoji": "👍" } }
```

## Llamadas de WhatsApp

Plan Growth o superior. Tu propio stack (un agente de voz, un softphone WebRTC) realiza y contesta
las llamadas; Genuka WA retransmite la señalización a Meta y te devuelve los webhooks `call.*`. El
audio nunca pasa por nosotros: el SDP describe una ruta entre Meta y tu stack. Consulta la guía
[Conectar un agente de voz](https://wa.genuka.com/es/docs/guides/voice-agent) para ver los flujos de principio a fin.

| Método  | Endpoint                                          | Descripción                                                                                                                   |
| ------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `GET`   | `/api/v1/numbers/{id}/calling`                    | Configuración de llamadas de un número: `status`, `callIconVisibility`, `callHours`, `callbackPermissionStatus`, `sipEnabled` |
| `PATCH` | `/api/v1/numbers/{id}/calling`                    | La modifica. Un patch real: el resto se conserva.                                                                             |
| `POST`  | `/api/v1/calls`                                   | Una acción de llamada, retransmitida a Meta: `connect`, `pre_accept`, `accept`, `reject`, `terminate`                         |
| `GET`   | `/api/v1/calls/permissions?waId=…&connectionId=…` | Si puedes llamar a este usuario ahora (`canCall`) y si puedes pedírselo (`canRequestPermission`)                              |

```json title="PATCH /api/v1/numbers/con_1/calling — activar las llamadas, en horario de oficina"
{
  "status": "ENABLED",
  "callHours": {
    "status": "ENABLED",
    "timezoneId": "Africa/Douala",
    "weeklyOperatingHours": [{ "dayOfWeek": "MONDAY", "openTime": "0800", "closeTime": "1800" }],
    "holidaySchedule": []
  }
}
```

```json title="POST /api/v1/calls — contestar una llamada entrante"
{ "action": "accept", "callId": "wacid.HBgL…", "sdp": "v=0\r\no=- 8236… (tu respuesta SDP)" }
```

```json title="POST /api/v1/calls — llamar a un cliente que dio su permiso"
{ "connectionId": "con_1", "action": "connect", "to": "+237690000001", "sdp": "v=0\r\n… (tu oferta SDP)" }
```

* `sdp` es solo el SDP: su tipo se deduce de la acción (oferta en `connect`, respuesta en
  `pre_accept` / `accept`). `connect` devuelve `{ "data": { "action": "connect", "callId": "wacid…" } }`.
* `connectionId` se puede omitir cuando `callId` designa una llamada que Genuka WA ya vio (el webhook
  de una llamada entrante, o un `connect` hecho aquí).
* Una llamada entrante suena durante unos 30 segundos: `pre_accept` tiene que salir dentro de ese
  plazo.

| Estado | `error`                                            | Cuándo                                                                                                 |
| ------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `403`  | `plan_feature_unavailable`                         | El plan no incluye llamadas (Starter).                                                                 |
| `409`  | `calling_unavailable_coexistence`                  | El número está compartido con la app WhatsApp Business: WhatsApp no permite llamadas por la API en él. |
| `409`  | `calling_sip_configured`                           | El número señaliza sus llamadas por SIP, configurado fuera de Genuka WA (solo `PATCH`).                |
| `409`  | `number_offboarded`                                | El número salió de la plataforma: vuelve a conectarlo.                                                 |
| `404`  | `call_not_found`                                   | `callId` sin `connectionId`, y ninguna llamada conocida con ese id: pasa el `connectionId`.            |
| `400`  | `invalid_call_action` / `invalid_calling_settings` | Todos los problemas del cuerpo, de una vez, en `issues`.                                               |
| `422`  | `meta_error`                                       | Meta lo rechazó: número no elegible, sin permiso de llamada, país excluido… con las palabras de Meta.  |

Webhooks: `call.connect` (con `data.session.sdp`), `call.status_changed`, `call.terminated` y
`call.permission_replied` (consulta [Webhooks](https://wa.genuka.com/es/docs/webhooks)).

## Suscripción

| Método | Endpoint               | Descripción                |
| ------ | ---------------------- | -------------------------- |
| `GET`  | `/api/v1/subscription` | Plan actual, límites y uso |

```json title="GET /api/v1/subscription"
{
  "plan": { "code": "growth", "name": "Growth" },
  "interval": "monthly",
  "currency": "XAF",
  "status": "active",
  "currentPeriodEnd": "2026-07-18T00:00:00.000Z",
  "billedNumbers": 9,
  "usage": { "numbers": 9, "messages": 12480, "seats": 3 },
  "limits": { "maxNumbers": 9, "monthlyMessages": 45000, "maxSeats": 5 }
}
```

## Errores

```text title="Ejemplos"
401 { "error": "missing_bearer_token" }      // sin encabezado Authorization
401 { "error": "invalid_token" }             // clave desconocida / revocada, o cuenta inactiva
403 { "error": "account_deactivated", "message": "Deactivated Account" }
                                             // esa empresa está suspendida: su propia clave deja
                                             // de funcionar, y toda solicitud que la nombre se
                                             // rechaza, incluso con una clave de toda la cuenta
400 { "error": "missing_fields", "message": "…" }
400 { "error": "missing_content", "message": "…" }  // ningún campo de contenido en un envío
400 { "error": "invalid_media", "message": "…" }    // multimedia sin assetId, id ni link
402 { "error": "plan_limit_media", "message": "…" } // se alcanzó el límite de almacenamiento del plan
404 { "error": "media_not_found", "message": "…" }  // assetId desconocido, o con más de 30 días
402 { "error": "plan_limit_numbers" }        // todos los números que pagó el plan están en uso
402 { "error": "plan_limit_messages" }       // se agotó la cuota de mensajes del período
402 { "error": "subscription_past_due" }     // la prueba o el período pagado venció sin renovación
404 { "error": "connection_not_found" }
404 { "error": "template_not_found" }
409 { "error": "template_exists" }
413 { "error": "media_too_large", "message": "…" } // encabezado de plantilla de más de 4 MB
422 { "error": "meta_rejected", "message": "…", "meta": { … } }
                                             // Meta leyó el payload y lo rechazó
502 { "error": "meta_rejected", "message": "…" }   // Graph inaccesible o con fallas
```

### Lo que Meta rechazó devuelve 422, no 502

Cuando Graph lee un payload y lo rechaza (una plantilla mal formada, una variable sin ejemplo, un
número no aprovisionado), la respuesta es un **422**, y su cuerpo lleva un objeto `meta` con el
propio código de error de Meta, su `traceId` y su clase:

```json title="422 — rechazado por Meta"
{
  "error": "meta_rejected",
  "message": "Invalid parameter",
  "meta": {
    "errorClass": "template",
    "retryable": false,
    "code": 100,
    "details": "body_text example count does not match the number of variables",
    "traceId": "AbC…"
  }
}
```

`traceId` es lo que pide el soporte de Meta: cítalo tal cual.

Un **502** queda reservado para lo que la palabra describe: Graph inaccesible, o Graph mismo con
fallas. Devolver un payload rechazado como 502 lo hacía imposible de diagnosticar: nuestra CDN
responde a los 5xx del origen con su propia página de error, que reemplaza ese cuerpo JSON por la
única línea `error code: 502`. El motivo del rechazo nunca te llegaba. Los cuerpos 4xx pasan sin
modificarse.

## Registros de solicitudes

Cada respuesta lleva un encabezado `x-request-id`. El mismo id identifica la llamada en tu panel, en
Registros, donde cada solicitud se conserva con su estado, su duración, su cuerpo y, cuando falló,
la respuesta que devolvimos. Las entregas de webhooks aparecen al lado, con su payload firmado exacto
y un botón para reenviarlas.

Hasta dónde llega el registro depende de tu plan: 7 días en Starter, 30 en Growth, 90 en Scale.

> [!NOTE]
> **Campos ocultados**
>
> Los cuerpos se almacenan para que un fallo sea reproducible, salvo todo lo que parezca una
> credencial: los valores `password`, `token`, `secret` y `api_key` se reemplazan antes de escribir
> la fila.
