# Plantillas: crear y enviar

> Crea plantillas de WhatsApp con POST /v1/templates, sigue la aprobación de Meta y envía con type template, con variables, encabezado multimedia y botón de URL.

Una plantilla es un mensaje con texto fijo y variables que **Meta debe aprobar antes de que puedas usarla**. En WhatsApp es la única forma de iniciar una conversación, o de escribir a un contacto cuando ya se cerró la ventana de 24 horas (consulta [Ventanas de conversación](/es/start/concepts/#ventanas-de-conversación)). Dentro de la ventana puedes enviar [texto libre](/es/send/text/) o cualquier otro tipo.

Esta página cubre plantillas de cualquier categoría. Para códigos de verificación, consulta [Plantillas de autenticación](/es/guides/authentication-templates/); para envíos masivos, [Campañas](/es/guides/campaigns/).

## Crear

`POST /v1/templates` crea la plantilla en la cuenta de WhatsApp de la conexión y la envía a revisión de Meta. Requiere una clave con el permiso `templates`. En el panel: **Plantillas → Nueva plantilla**.

| Campo | Regla |
| --- | --- |
| `connection_id` | Opcional con clave de conexión (`mjc_…`); obligatorio con clave de organización (`mj_…`) |
| `name` | Letras minúsculas, números y `_` |
| `language` | Código de idioma de Meta, como `pt_BR`, `en_US` o `es` |
| `category` | `MARKETING`, `UTILITY` o `AUTHENTICATION` |
| `parameter_format` | Opcional: `POSITIONAL` (`{{1}}`) o `NAMED` |
| `components` | Lista con como máximo uno de cada: `HEADER`, `BODY` (con `text`, obligatorio), `FOOTER` y `BUTTONS` |

- `HEADER` acepta `format` `TEXT`, `IMAGE`, `VIDEO`, `DOCUMENT` o `LOCATION`.
- `BUTTONS` acepta botones `QUICK_REPLY`, `URL`, `PHONE_NUMBER`, `COPY_CODE`, `OTP`, `FLOW`, `CATALOG`, `MPM` y `VOICE_CALL`.
- Los componentes siguen el formato de creación de Meta. Las variables del texto necesitan un `example`, como en el cuerpo de abajo.
- Un **encabezado multimedia** (`IMAGE`, `VIDEO`, `DOCUMENT`) exige un archivo de ejemplo: `components.HEADER.example.header_handle`, el identificador que devuelve la subida reanudable de Meta. Sin él la llamada devuelve `400` [`validation_failed`](/es/errors#validation_failed). En el panel, Messajo hace esa subida cuando eliges el archivo.

Ejemplo: cuerpo con dos variables, pie y un botón de respuesta rápida.

**cURL**

```bash
curl https://api.messajo.com/v1/templates \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "connection_id": "conn_...",
  "name": "pedido_enviado",
  "language": "es",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Hola {{1}}, tu pedido {{2}} salió para entrega.",
      "example": {
        "body_text": [
          [
            "Ana",
            "12345"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Gracias por comprar con nosotros"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Hablar con la tienda"
        }
      ]
    }
  ]
}'
```

**TypeScript**

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

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

const template = await messajo.templates.create({
  connection_id: "conn_...",
  name: "pedido_enviado",
  language: "es",
  category: "UTILITY",
  components: [
    {
      type: "BODY",
      text: "Hola {{1}}, tu pedido {{2}} salió para entrega.",
      example: {
        body_text: [
          [
            "Ana",
            "12345"
          ]
        ]
      }
    },
    {
      type: "FOOTER",
      text: "Gracias por comprar con nosotros"
    },
    {
      type: "BUTTONS",
      buttons: [
        {
          type: "QUICK_REPLY",
          text: "Hablar con la tienda"
        }
      ]
    }
  ]
});
```

**n8n**

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

```json
{
  "connection_id": "conn_...",
  "name": "pedido_enviado",
  "language": "es",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Hola {{1}}, tu pedido {{2}} salió para entrega.",
      "example": {
        "body_text": [
          [
            "Ana",
            "12345"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Gracias por comprar con nosotros"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Hablar con la tienda"
        }
      ]
    }
  ]
}
```

La respuesta es `201` con la plantilla: `id` (`tpl_…`), `status`, `category`, `components` y `rejected_reason` cuando fue rechazada.

## Ciclo de vida

Una vez creada, la plantilla pasa a la revisión de Meta. Cada cambio de estado llega en el evento [`template.status`](/es/webhooks/events/); también puedes consultar `GET /v1/templates/{id}`.

| Estado | Qué significa |
| --- | --- |
| `PENDING` | En revisión. Todavía no se puede enviar. |
| `APPROVED` | Aprobada. Se puede enviar. |
| `REJECTED` | Meta la rechazó; el motivo viene en `rejected_reason`. Edítala y vuelve a enviarla a revisión. |
| `PAUSED` | Meta la pausó por baja calidad. No se envía hasta que vuelva. |
| `DISABLED` | Meta la desactivó. |

También existen `IN_APPEAL`, `PENDING_DELETION`, `DELETED`, `ARCHIVED`, `LIMIT_EXCEEDED`, `LOCKED`, `FLAGGED` y `REINSTATED`, que llegan de Meta tal cual.

- **Listar y consultar:** `GET /v1/templates` (con filtros y paginación) y `GET /v1/templates/{id}`, con el permiso `read`.
- **Editar:** `PATCH /v1/templates/{id}` cambia `components` o `category`. Meta solo permite editar una plantilla `APPROVED`, `REJECTED` o `PAUSED`, y una plantilla aprobada no cambia de categoría.
- **Eliminar:** `DELETE /v1/templates/{id}` la elimina en Meta y en Messajo.
- **Sincronizar:** Messajo vuelve a leer las plantillas de Meta cada día. `POST /v1/templates/sync` lo hace ahora; la plantilla que desapareció de Meta queda marcada como eliminada.

## Enviar

`POST /v1/messages` con `type: "template"`:

| Campo | Regla |
| --- | --- |
| `template.name` | Nombre de la plantilla, de 1 a 512 caracteres |
| `template.language` | Código de idioma, como `es` |
| `template.components` | Opcional. Valores de las variables, **en el formato de envío de Meta**: Messajo los pasa tal como los escribes |

Los campos comunes (`to`, `reply_to`, `typing`…) están en [Campos comunes](/es/send/text/#campos-comunes). Una plantilla no depende de la ventana de 24 horas: sale en cualquier momento.

### Variables del cuerpo

**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": "template",
  "template": {
    "name": "pedido_enviado",
    "language": "es",
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Ana"
          },
          {
            "type": "text",
            "text": "12345"
          }
        ]
      }
    ]
  }
}'
```

**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: "template",
  template: {
    name: "pedido_enviado",
    language: "es",
    components: [
      {
        type: "body",
        parameters: [
          {
            type: "text",
            text: "Ana"
          },
          {
            type: "text",
            text: "12345"
          }
        ]
      }
    ]
  }
});
```

**n8n**

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

```json
{
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "pedido_enviado",
    "language": "es",
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Ana"
          },
          {
            "type": "text",
            "text": "12345"
          }
        ]
      }
    ]
  }
}
```

### Encabezado de imagen

Para una plantilla con encabezado de imagen, pasa la imagen por un enlace público.

**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": "template",
  "template": {
    "name": "promo_de_la_semana",
    "language": "es",
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://ejemplo.com/promo.jpg"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Ana"
          }
        ]
      }
    ]
  }
}'
```

**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: "template",
  template: {
    name: "promo_de_la_semana",
    language: "es",
    components: [
      {
        type: "header",
        parameters: [
          {
            type: "image",
            image: {
              link: "https://ejemplo.com/promo.jpg"
            }
          }
        ]
      },
      {
        type: "body",
        parameters: [
          {
            type: "text",
            text: "Ana"
          }
        ]
      }
    ]
  }
});
```

**n8n**

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

```json
{
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "promo_de_la_semana",
    "language": "es",
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://ejemplo.com/promo.jpg"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Ana"
          }
        ]
      }
    ]
  }
}
```

### Botón de URL con sufijo dinámico

Cuando la URL del botón termina en `{{1}}`, envía el sufijo en un componente `button` con `sub_type: "url"`. `index` es la posición del botón, desde `"0"`.

**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": "template",
  "template": {
    "name": "seguir_pedido",
    "language": "es",
    "components": [
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {
            "type": "text",
            "text": "12345"
          }
        ]
      }
    ]
  }
}'
```

**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: "template",
  template: {
    name: "seguir_pedido",
    language: "es",
    components: [
      {
        type: "button",
        sub_type: "url",
        index: "0",
        parameters: [
          {
            type: "text",
            text: "12345"
          }
        ]
      }
    ]
  }
});
```

**n8n**

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

```json
{
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "seguir_pedido",
    "language": "es",
    "components": [
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {
            "type": "text",
            "text": "12345"
          }
        ]
      }
    ]
  }
}
```

La respuesta es la misma que la del envío de texto (`201`, `status: "queued"`); consulta [Respuesta](/es/send/text/#respuesta).

## Costos

Meta cobra cada mensaje de plantilla según su categoría. Consulta [Costos de Meta](/es/guides/costs/).

## Errores

| Error | Cuándo | Qué hacer |
| --- | --- | --- |
| `422` [`template_error`](/es/errors#template_error) | Meta rechazó la plantilla o sus parámetros (códigos 132000, 132001, 132005, 132007, 132012, 132015, 132016, 132068, 132069) | Lee `details[].message`: indica qué elemento falló |
| `404` [`template_not_found`](/es/errors#template_not_found) | La plantilla no existe | Revisa `name` y `language`; ejecuta `POST /v1/templates/sync` |
| `422` [`marketing_limit_reached`](/es/errors#marketing_limit_reached) | Meta limitó el marketing para este contacto (131049) | No reenvíes enseguida |
| `429` [`meta_spam_rate_limited`](/es/errors#meta_spam_rate_limited) | Límite por spam (131048) | Nunca reenvíes |
| `402` [`meta_payment_required`](/es/errors#meta_payment_required) | Problema de pago en la cuenta de Meta (131042) | Corrige el método de pago |

Más pasos en [Fallos de envío](/es/troubleshooting/send-failures/).
