---
title: "Enviar mensajes con plantilla"
method: POST
path: "/v1/whatsapp/{channelId}/template-messages"
tags: ["WhatsApp"]
---

# Enviar mensajes con plantilla

`POST /v1/whatsapp/{channelId}/template-messages`

Envía una plantilla HSM aprobada a uno o más destinatarios. La plantilla se resuelve
por nombre y se valida `APPROVED` antes de consumir saldo.

`variables` es un array posicional: el elemento en índice 0 reemplaza `{{1}}`,
el elemento en índice 1 reemplaza `{{2}}`, etc.

### Reglas de `mediaUrl` / `mediaType`

- **`mediaUrl`** es requerido **solo si la plantilla resuelta tiene header
  `IMAGE`, `VIDEO` o `DOCUMENT`** (lo determina la plantilla, no el request). Si falta
  en ese caso, devuelve `409 / 400 INVALID_BODY` antes de consumir saldo. Para plantillas
  de texto se ignora.
- **`mediaType`** es **opcional** y actúa como override del tipo de header de la plantilla;
  si se omite, se usa el tipo propio de la plantilla. No está acoplado a `mediaUrl`: enviar
  uno sin el otro **no** dispara un error de validación cruzada (el único gate es el de
  `mediaUrl` descrito arriba). Valores inválidos de `mediaType` se ignoran y se cae al tipo
  de la plantilla.

## Path parameters

- `channelId` string, required

## Request body

- object
  - `templateName` string, required — Nombre de la plantilla aprobada en Meta/Gupshup.
  - `to` object[], required — Lista de destinatarios. Mínimo 1.
    - `phone` string, required — Teléfono en formato E.164 (con o sin `+`).
    - `variables` string[] — Valores posicionales para los placeholders `{{1}}`, `{{2}}`, ...
  - `mediaUrl` string, uri — URL pública del media para plantillas con header IMAGE/VIDEO/DOCUMENT.
  - `mediaType` 'IMAGE' | 'VIDEO' | 'DOCUMENT' — Tipo de media. Debe coincidir con el header de la plantilla.

## Response `200`

Mensajes procesados. Incluye `successfulMessages` y `failedMessages`.

- object
  - `successfulMessages` object[]
    - `id` integer
    - `destination` string
    - `status` string
    - `providerMessageId` string, nullable
  - `failedMessages` object[]
    - `destination` string
    - `status` string
    - `errorMessage` string
    - `providerMessageId` string, nullable

## Other responses

- `400` — Body inválido (templateName faltante, `to` vacío, phone inválido, etc.)
- `401` — JWT faltante o inválido.
- `409` — Template no aprobado (`INVALID_TEMPLATE_STATUS`) o saldo insuficiente.

---

[API](https://skmtc.net/cliengo/apis/cliengo-public-api.md) · [All operations](https://skmtc.net/cliengo/apis/cliengo-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cliengo/cliengo-public-api/versions/94c7ba7d6a11/schema)