# Manage templates

Use these endpoints to create new templates and add language variants to existing ones.
Before making requests, ensure you have configured [authentication](/products/whatsapp/enterprise-documentation/developer-documentation/authentication).

For the full technical reference, see the [OpenAPI specification](/products/whatsapp/openapi/template/createtemplate).

## Create a template

Creates a new template. The template will be submitted to Meta for approval and will have status `PENDING` until approved.

#### Endpoint


```
POST /api/template/create
```

#### Headers

| Name | Required | Description |
|  --- | --- | --- |
| `Authorization` | Yes | Basic Auth credentials. See [Authentication](/products/whatsapp/enterprise-documentation/developer-documentation/authentication). |
| `X-Api-Key` | Yes | API key for the account. See [Authentication](/products/whatsapp/enterprise-documentation/developer-documentation/authentication). |
| `Content-Type` | Yes | Must be `application/json`. |


#### Body parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `language` | string | Yes | Default template language. See [supported languages](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages) |
| `category` | string | Yes | Template category: `UTILITY` or `MARKETING` |
| `name` | string | Yes | Template name. Only alphabetic characters and underscores (max 100 characters) |
| `description` | string | Yes | Template description |
| `body` | object | Yes | Body text with optional placeholders (`{{1}}`, `{{2}}`, ...) and default parameter values |
| `urlButtons` | array | Depends | URL buttons. Each entry: `index`, `text` (button label), `url` (base URL with optional `{{1}}` placeholder), `urlPath` (default path). Max 2 buttons. |
| `textHeader` | object | No | Header text (preset, no placeholders) |
| `footer` | object | No | Footer text (preset, no placeholders) |


Template variable rules
Common rejection reasons from Meta:

- Variable parameters must use the format `{{1}}`, `{{2}}`, etc.
- Parameters cannot contain special characters like `#`, `$`, or `%`
- Parameters must be sequential — no gaps (e.g. `{{1}}`, `{{2}}`, `{{4}}` without `{{3}}` is invalid)
- Templates cannot start or end with a variable parameter
- Too many parameters relative to message length


#### Request example


```json
{
  "body": {
    "text": "Hello *{{1}}*, your signature is required for a document. Open by using following link:",
    "parameters": [
      { "text": "John Smith" }
    ]
  },
  "urlButtons": [
    {
      "index": 0,
      "urlPath": "sign",
      "url": "https://yourendpoint.com/{{1}}",
      "text": "Open Document"
    }
  ],
  "textHeader": {
    "text": "Document signing request"
  },
  "footer": {
    "text": "The link expires in 10 minutes"
  },
  "language": "en",
  "name": "signature_template",
  "category": "UTILITY",
  "description": "sign a doc using a link"
}
```

#### Response examples

**200 — Template created (pending approval)**


```json
{
  "body": {
    "text": "Hello *{{1}}*, your signature is required for a document. Open by using following link:",
    "parameters": [
      { "text": "John Smith" }
    ]
  },
  "urlButtons": [
    {
      "index": 0,
      "urlPath": "sign",
      "url": "https://yourendpoint.com/{{1}}",
      "text": "Open Document"
    }
  ],
  "textHeader": {
    "text": "Document signing request"
  },
  "footer": {
    "text": "The link expires in 10 minutes"
  },
  "language": "en",
  "status": "PENDING",
  "category": "UTILITY",
  "name": "signature_template",
  "description": "sign a doc using a link",
  "templateId": "802",
  "default": true
}
```

The response returns the full template object. See [Get template by language](/products/whatsapp/enterprise-documentation/developer-documentation/api-references/template-management/get-template#get-template-by-language) for a description of the response fields.

**400 — Invalid input**


```json
{
  "type": "ConstraintViolationException",
  "code": 3,
  "message": "Allowed category are: UTILITY, MARKETING"
}
```

#### Error codes

| HTTP Status | Error code | Error type | Solution |
|  --- | --- | --- | --- |
| `400` | 3 | `ConstraintViolationException` | Check the request parameters against the API documentation |


For authentication errors (code 1, 6, 9), see [Authentication](/products/whatsapp/enterprise-documentation/developer-documentation/authentication).

## Add a template language

Adds a new language version to an existing template.

#### Endpoint


```
POST /api/template/{templateId}/language
```

#### Headers

| Name | Required | Description |
|  --- | --- | --- |
| `Authorization` | Yes | Basic Auth credentials. See [Authentication](/products/whatsapp/enterprise-documentation/developer-documentation/authentication). |
| `X-Api-Key` | Yes | API key for the account. See [Authentication](/products/whatsapp/enterprise-documentation/developer-documentation/authentication). |
| `Content-Type` | Yes | Must be `application/json`. |


#### Path parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `templateId` | integer | Yes | The existing template ID |


#### Body parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `language` | string | Yes | The new language to add. See [supported languages](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages) |
| `body` | object | Yes | Body text in the new language with optional placeholders and default parameter values |
| `urlButtons` | array | No | URL buttons for the new language version |
| `textHeader` | object | No | Header text in the new language |
| `footer` | object | No | Footer text in the new language |


#### Request example


```json
{
  "body": {
    "text": "Ciao *{{1}}*, la tua firma è richiesta per un documento. Aprilo usando il seguente link:",
    "parameters": [
      { "text": "Mario Rossi" }
    ]
  },
  "urlButtons": [
    {
      "index": 0,
      "urlPath": "sign",
      "url": "https://yourendpoint.com/{{1}}",
      "text": "Apri documento"
    }
  ],
  "textHeader": {
    "text": "Richiesta di firma documento"
  },
  "footer": {
    "text": "Il link scade in 10 minuti"
  },
  "language": "it"
}
```

#### Response examples

**200 — Language added**


```json
{
  "body": {
    "text": "Ciao *{{1}}*, la tua firma è richiesta per un documento. Aprilo usando il seguente link:",
    "parameters": [
      { "text": "Mario Rossi" }
    ]
  },
  "urlButtons": [
    {
      "index": 0,
      "urlPath": "sign",
      "url": "https://yourendpoint.com/{{1}}",
      "text": "Apri documento"
    }
  ],
  "textHeader": {
    "text": "Richiesta di firma documento"
  },
  "footer": {
    "text": "Il link scade in 10 minuti"
  },
  "language": "it",
  "status": "PENDING",
  "category": "UTILITY",
  "name": "signature_template",
  "description": "sign a doc using a link",
  "templateId": "802",
  "default": false
}
```

The response returns the full template object for the new language variant. See [Get template by language](/products/whatsapp/enterprise-documentation/developer-documentation/api-references/template-management/get-template#get-template-by-language) for a description of the response fields.

**400 — Language already exists**


```json
{
  "type": "InvalidLanguageException",
  "code": 14,
  "message": "The language 'en' already exists for template '61'"
}
```

**400 — Language not supported**


```json
{
  "type": "ClientWebApplicationException",
  "code": 12,
  "message": "Invalid parameter"
}
```

**404 — Template not found**


```json
{
  "type": "UnavailableTemplateException",
  "code": 7,
  "message": "Template not found"
}
```

#### Error codes

| HTTP Status | Error code | Error type | Solution |
|  --- | --- | --- | --- |
| `400` | 12 | `ClientWebApplicationException` | The language code is not supported by Meta. See [supported languages](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#supported-languages) |
| `400` | 14 | `InvalidLanguageException` | The language already exists for this template |
| `404` | 7 | `UnavailableTemplateException` | Verify that the `templateId` exists |


For authentication errors (code 1, 6, 9), see [Authentication](/products/whatsapp/enterprise-documentation/developer-documentation/authentication).