# Templates: create and send

> Create WhatsApp templates with POST /v1/templates, follow Meta's review, and send with type template, with variables, a media header and a URL button.

A template is a message with fixed text and variables that **Meta must approve before you can use it**. On WhatsApp it is the only way to start a conversation, or to reach a contact once the 24-hour window has closed (see [Conversation windows](/en/start/concepts/#conversation-windows)). Inside the window you can send [free-form text](/en/send/text/) or any other type.

This page covers templates of any category. For verification codes see [Authentication templates](/en/guides/authentication-templates/); for bulk sends see [Campaigns](/en/guides/campaigns/).

## Create

`POST /v1/templates` creates the template in the connection's WhatsApp account and sends it to Meta for review. It needs a key with the `templates` permission. In the panel: **Templates → New template**.

| Field | Rule |
| --- | --- |
| `connection_id` | Optional with a connection key (`mjc_…`); required with an organization key (`mj_…`) |
| `name` | Lowercase letters, digits and `_` |
| `language` | Meta language code, such as `pt_BR`, `en_US` or `es` |
| `category` | `MARKETING`, `UTILITY` or `AUTHENTICATION` |
| `parameter_format` | Optional: `POSITIONAL` (`{{1}}`) or `NAMED` |
| `components` | List with at most one of each: `HEADER`, `BODY` (with `text`, required), `FOOTER` and `BUTTONS` |

- `HEADER` accepts `format` `TEXT`, `IMAGE`, `VIDEO`, `DOCUMENT` or `LOCATION`.
- `BUTTONS` accepts `QUICK_REPLY`, `URL`, `PHONE_NUMBER`, `COPY_CODE`, `OTP`, `FLOW`, `CATALOG`, `MPM` and `VOICE_CALL` buttons.
- Components follow Meta's creation format. Variables in the text need an `example`, as in the body below.
- A **media header** (`IMAGE`, `VIDEO`, `DOCUMENT`) requires an example file: `components.HEADER.example.header_handle`, the identifier returned by Meta's resumable upload. Without it the call returns `400` [`validation_failed`](/en/errors#validation_failed). In the panel, Messajo does that upload when you pick the file.

Example: a body with two variables, a footer and a quick-reply button.

**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": "order_shipped",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Hi {{1}}, your order {{2}} is out for delivery.",
      "example": {
        "body_text": [
          [
            "Ana",
            "12345"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Thanks for shopping with us"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Talk to the store"
        }
      ]
    }
  ]
}'
```

**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: "order_shipped",
  language: "en_US",
  category: "UTILITY",
  components: [
    {
      type: "BODY",
      text: "Hi {{1}}, your order {{2}} is out for delivery.",
      example: {
        body_text: [
          [
            "Ana",
            "12345"
          ]
        ]
      }
    },
    {
      type: "FOOTER",
      text: "Thanks for shopping with us"
    },
    {
      type: "BUTTONS",
      buttons: [
        {
          type: "QUICK_REPLY",
          text: "Talk to the store"
        }
      ]
    }
  ]
});
```

**n8n**

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

```json
{
  "connection_id": "conn_...",
  "name": "order_shipped",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Hi {{1}}, your order {{2}} is out for delivery.",
      "example": {
        "body_text": [
          [
            "Ana",
            "12345"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Thanks for shopping with us"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Talk to the store"
        }
      ]
    }
  ]
}
```

The response is `201` with the template: `id` (`tpl_…`), `status`, `category`, `components`, and `rejected_reason` when it was rejected.

## Lifecycle

Once created, the template goes to Meta's review. Every status change arrives as the [`template.status`](/en/webhooks/events/) event; you can also call `GET /v1/templates/{id}`.

| Status | Meaning |
| --- | --- |
| `PENDING` | Under review. Cannot be sent yet. |
| `APPROVED` | Approved. Can be sent. |
| `REJECTED` | Meta rejected it; the reason is in `rejected_reason`. Edit it and send it for review again. |
| `PAUSED` | Meta paused it for low quality. It will not send until it is back. |
| `DISABLED` | Meta disabled it. |

There are also `IN_APPEAL`, `PENDING_DELETION`, `DELETED`, `ARCHIVED`, `LIMIT_EXCEEDED`, `LOCKED`, `FLAGGED` and `REINSTATED`, which come from Meta as they are.

- **List and read:** `GET /v1/templates` (with filters and pagination) and `GET /v1/templates/{id}`, with the `read` permission.
- **Edit:** `PATCH /v1/templates/{id}` changes `components` or `category`. Meta only allows editing a template that is `APPROVED`, `REJECTED` or `PAUSED`, and an approved template cannot change category.
- **Delete:** `DELETE /v1/templates/{id}` deletes it at Meta and in Messajo.
- **Sync:** Messajo re-reads the templates from Meta every day. `POST /v1/templates/sync` does it right now; a template that vanished from Meta is marked as deleted.

## Send

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

| Field | Rule |
| --- | --- |
| `template.name` | Template name, 1 to 512 characters |
| `template.language` | Language code, such as `en_US` |
| `template.components` | Optional. Variable values, **in Meta's send format**: Messajo passes them through as written |

The common fields (`to`, `reply_to`, `typing`…) are in [Common fields](/en/send/text/#common-fields). A template does not depend on the 24-hour window: it can go out at any time.

### Body variables

**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": "order_shipped",
    "language": "en_US",
    "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: "order_shipped",
    language: "en_US",
    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": "order_shipped",
    "language": "en_US",
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Ana"
          },
          {
            "type": "text",
            "text": "12345"
          }
        ]
      }
    ]
  }
}
```

### Image header

For a template with an image header, pass the image as a public link.

**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": "weekly_promo",
    "language": "en_US",
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://example.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: "weekly_promo",
    language: "en_US",
    components: [
      {
        type: "header",
        parameters: [
          {
            type: "image",
            image: {
              link: "https://example.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": "weekly_promo",
    "language": "en_US",
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://example.com/promo.jpg"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Ana"
          }
        ]
      }
    ]
  }
}
```

### URL button with a dynamic suffix

When the button URL ends in `{{1}}`, send the suffix in a `button` component with `sub_type: "url"`. `index` is the button position, starting at `"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": "track_order",
    "language": "en_US",
    "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: "track_order",
    language: "en_US",
    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": "track_order",
    "language": "en_US",
    "components": [
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {
            "type": "text",
            "text": "12345"
          }
        ]
      }
    ]
  }
}
```

The response is the same as for a text message (`201`, `status: "queued"`); see [Response](/en/send/text/#response).

## Costs

Meta charges for each template message, by category. See [Meta costs](/en/guides/costs/).

## Errors

| Error | When | What to do |
| --- | --- | --- |
| `422` [`template_error`](/en/errors#template_error) | Meta rejected the template or its parameters (codes 132000, 132001, 132005, 132007, 132012, 132015, 132016, 132068, 132069) | Read `details[].message`: it says which item failed |
| `404` [`template_not_found`](/en/errors#template_not_found) | The template does not exist | Check `name` and `language`; run `POST /v1/templates/sync` |
| `422` [`marketing_limit_reached`](/en/errors#marketing_limit_reached) | Meta limited marketing for this contact (131049) | Do not resend right away |
| `429` [`meta_spam_rate_limited`](/en/errors#meta_spam_rate_limited) | Spam rate limit (131048) | Never resend |
| `402` [`meta_payment_required`](/en/errors#meta_payment_required) | Payment problem on the Meta account (131042) | Fix the payment method |

More steps in [Send failures](/en/troubleshooting/send-failures/).
