# Template Management API

URL: https://developers.cuedesk.com/api/template_management_api

> Create, list, retrieve and delete WhatsApp message templates in your workspace with the Template Management API.

The Template Management API allows you to create, list, retrieve, and delete WhatsApp message templates in your workspace programmatically.

<Callout type="idea" title="See Also">
Looking to **send** templates to contacts? See the [Templates API](/api/templates/templates_api_v2) for sending pre-approved templates via the Messages API.
</Callout>

See the [authentication](/api/authentication) page for how to obtain a bearer token. All endpoints require a Bearer token in the `Authorization` header:

```text
Authorization: Bearer <token>
```

## JSON Field Casing [#json-field-casing]

All request and response bodies use **snake_case** field names exclusively.

## Error Responses [#error-responses]

All endpoints return errors in a consistent envelope format:

```json
{
  "error": {
    "message": "422 UNPROCESSABLE ENTITY",
    "details": "Template content failed validation",
    "violations": [
      {
        "field": "content.body.text",
        "rule": "REQUIRED",
        "message": "Body text is required"
      }
    ]
  }
}
```

The `violations` array is present on validation errors (422) and provides field-level detail about what failed. Each violation contains:

| Field     | Type   | Description                                  |
| --------- | ------ | -------------------------------------------- |
| `field`   | string | Dot-notation path to the invalid field       |
| `rule`    | string | Violation rule code (e.g. `REQUIRED`, `IMMUTABLE`, `INVALID_FORMAT`) |
| `message` | string | Human-readable description of the violation  |

Common error status codes:

| Status | Meaning |
| ------ | ------- |
| 400    | Bad request -- malformed input |
| 401    | Unauthorized -- invalid or missing token |
| 403    | Forbidden -- insufficient permissions |
| 404    | Not found -- template does not exist in your workspace |
| 409    | Conflict -- duplicate template name/locale combination |
| 422    | Unprocessable entity -- validation error with violations |
| 429    | Too many requests -- rate limit exceeded (check `Retry-After` header) |
| 500    | Internal server error |

## Pagination [#pagination]

The list endpoint uses offset-based pagination:

| Parameter | Type    | Default | Min | Max |
| --------- | ------- | ------- | --- | --- |
| `limit`   | integer | 50      | 1   | 100 |
| `offset`  | integer | 0       | 0   | --  |

```json
{
  "templates": [...],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 142
  }
}
```

## Create Template [#create-template]

```text
POST https://api.cuedesk.com/v1/templates
```

Creates a new WhatsApp message template. The template will be submitted to Meta for approval.

**Headers:**

| Header            | Required | Description                                      |
| ----------------- | -------- | ------------------------------------------------ |
| `Authorization`   | Yes      | Bearer token                                     |
| `Idempotency-Key` | No       | Unique key to prevent duplicate template creation |

<Tabs items={["Request","Request (Media Header)","Request (Carousel)","Response (201)","Errors"]}>
<Tab value="Request">

```json
{
  "name": "order_confirmation",
  "locale": "en",
  "category": "UTILITY",
  "template_type": "STANDARD",
  "content": {
    "header": {
      "format": "TEXT",
      "text": "Order Confirmed"
    },
    "body": {
      "text": "Hi {{1}}, your order #{{2}} has been confirmed and will be delivered by {{3}}. Thank you for shopping with us!",
      "example": ["John", "12345", "25 Jan 2025"]
    },
    "footer": {
      "text": "Thank you for your purchase"
    },
    "buttons": [
      {
        "type": "URL",
        "text": "Track Order",
        "url": "https://example.com/track/{{1}}",
        "example": ["12345"]
      },
      {
        "type": "PHONE_NUMBER",
        "text": "Call Support",
        "phone_number": "+14155551234"
      }
    ]
  },
  "enabled_in_livechat": true,
  "continue_session": false
}
```

| Field                | Type    | Required | Description |
| -------------------- | ------- | -------- | ----------- |
| `name`               | string  | Yes      | Template name. Alphanumeric, underscores, and spaces. Max 500 chars. |
| `locale`             | string  | Yes      | Language code, e.g. `en`, `es_ES`. Format: `xx` or `xx_XX`. |
| `category`           | string  | Yes      | One of: `MARKETING`, `UTILITY`, `AUTHENTICATION` |
| `template_type`      | string  | Yes      | One of: `STANDARD`, `CAROUSEL`, `AUTHENTICATION` |
| `content`            | object  | Yes      | Template content structure (see [Content Object](#content-object)) |
| `enabled_in_livechat`| boolean | Yes      | Whether agents can send this template from the live chat UI |
| `continue_session`   | boolean | Yes      | Whether sending this template continues an existing conversation session |

</Tab>
<Tab value="Request (Media Header)">

```json
{
  "name": "vacation_promo",
  "locale": "en",
  "category": "MARKETING",
  "template_type": "STANDARD",
  "content": {
    "header": {
      "format": "IMAGE",
      "example": ["https://example.com/images/vacation-promo.jpg"]
    },
    "body": {
      "text": "Hi {{1}},\n\nWould you like to join our team on their next vacation?",
      "example": ["John"]
    },
    "footer": {
      "text": "Reply STOP to unsubscribe"
    },
    "buttons": [
      {
        "type": "QUICK_REPLY",
        "text": "I'm interested"
      },
      {
        "type": "QUICK_REPLY",
        "text": "No thanks"
      }
    ]
  },
  "enabled_in_livechat": false,
  "continue_session": false
}
```

<Callout type="info">
For media headers (`IMAGE`, `VIDEO`, `DOCUMENT`), provide the media URL in the `example` array. The `text` field is only used with `TEXT` format headers.
</Callout>

</Tab>
<Tab value="Request (Carousel)">

```json
{
  "name": "product_showcase",
  "locale": "en",
  "category": "MARKETING",
  "template_type": "CAROUSEL",
  "content": {
    "body": {
      "text": "Hi {{1}}, check out our latest products!",
      "example": ["John"]
    },
    "cards": [
      {
        "header": {
          "format": "IMAGE",
          "example": ["https://example.com/images/product-a.jpg"]
        },
        "body": {
          "text": "{{1}} - only ${{2}}! Limited stock available.",
          "example": ["Wireless Headphones", "49.99"]
        },
        "buttons": [
          {
            "type": "URL",
            "text": "View product",
            "url": "https://example.com/products/{{1}}",
            "example": ["wireless-headphones"]
          },
          {
            "type": "QUICK_REPLY",
            "text": "Add to cart"
          }
        ]
      },
      {
        "header": {
          "format": "IMAGE",
          "example": ["https://example.com/images/product-b.jpg"]
        },
        "body": {
          "text": "{{1}} - only ${{2}}! Free shipping today.",
          "example": ["Smart Watch", "129.99"]
        },
        "buttons": [
          {
            "type": "URL",
            "text": "View product",
            "url": "https://example.com/products/{{1}}",
            "example": ["smart-watch"]
          },
          {
            "type": "QUICK_REPLY",
            "text": "Add to cart"
          }
        ]
      }
    ]
  },
  "enabled_in_livechat": false,
  "continue_session": false
}
```

<Callout type="info">
Carousel templates require 2–10 cards. Each card must have a `header` with `IMAGE` or `VIDEO` format. Top-level `header`, `footer`, and `buttons` are not used - those fields exist only per-card.
</Callout>

<Callout type="warn">
Carousel templates are not supported in the live chat UI. `enabled_in_livechat` must be set to `false`.
</Callout>

</Tab>
<Tab value="Response (201)">

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "workspace_uuid": "11111111-2222-3333-4444-555555555555",
  "name": "order_confirmation",
  "canonical_name": "order_confirmation",
  "locale": "en",
  "category": "UTILITY",
  "template_type": "STANDARD",
  "status": "PENDING",
  "rejection_reason": null,
  "content": {
    "header": {
      "format": "TEXT",
      "text": "Order Confirmed"
    },
    "body": {
      "text": "Hi {{1}}, your order #{{2}} has been confirmed and will be delivered by {{3}}. Thank you for shopping with us!",
      "example": ["John", "12345", "25 Jan 2025"]
    },
    "footer": {
      "text": "Thank you for your purchase"
    },
    "buttons": [
      {
        "type": "URL",
        "text": "Track Order",
        "url": "https://example.com/track/{{1}}",
        "example": ["12345"]
      }
    ],
    "cards": null,
    "auth": null
  },
  "enabled_in_livechat": true,
  "continue_session": false,
  "created_at": "2025-01-15T10:30:00.000Z",
  "updated_at": "2025-01-15T10:30:00.000Z"
}
```

</Tab>
<Tab value="Errors">

**409 Conflict** -- A template with the same name and locale already exists:

```json
{
  "error": {
    "message": "409 CONFLICT",
    "details": "Template with name 'order_confirmation' and locale 'en' already exists",
    "violations": []
  }
}
```

**422 Validation Error** -- Content failed validation:

```json
{
  "error": {
    "message": "422 UNPROCESSABLE ENTITY",
    "details": "Template content failed validation",
    "violations": [
      {
        "field": "content.body.text",
        "rule": "REQUIRED",
        "message": "Body text is required for STANDARD templates"
      }
    ]
  }
}
```

</Tab>
</Tabs>

## List Templates [#list-templates]

```text
GET https://api.cuedesk.com/v1/templates
```

Returns a paginated list of templates in your workspace with optional filtering.

**Query parameters:**

| Parameter  | Type    | Required | Description |
| ---------- | ------- | -------- | ----------- |
| `limit`    | integer | No       | Results per page (1–100, default 50) |
| `offset`   | integer | No       | Offset for pagination (default 0) |
| `status`   | string  | No       | Filter by status (see [TemplateStatus](#templatestatus)) |
| `category` | string  | No       | Filter by category: `MARKETING`, `UTILITY`, `AUTHENTICATION` |
| `search`   | string  | No       | Search by template name (1–200 chars) |

<Tabs items={["Request","Response (200)"]}>
<Tab value="Request">

```text
GET https://api.cuedesk.com/v1/templates?status=APPROVED&category=UTILITY&limit=10
Authorization: Bearer <token>
```

</Tab>
<Tab value="Response (200)">

```json
{
  "templates": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "workspace_uuid": "11111111-2222-3333-4444-555555555555",
      "name": "order_confirmation",
      "canonical_name": "order_confirmation",
      "locale": "en",
      "category": "UTILITY",
      "template_type": "STANDARD",
      "status": "APPROVED",
      "rejection_reason": null,
      "content": { ... },
      "enabled_in_livechat": true,
      "continue_session": false,
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-16T08:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 1
  }
}
```

</Tab>
</Tabs>

## Get Template [#get-template]

```text
GET https://api.cuedesk.com/v1/templates/{template_uuid}
```

Retrieves a single template by its UUID.

<Tabs items={["Request","Response (200)","Errors"]}>
<Tab value="Request">

```text
GET https://api.cuedesk.com/v1/templates/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Bearer <token>
```

</Tab>
<Tab value="Response (200)">

Returns a single [Template Object](#template-object).

</Tab>
<Tab value="Errors">

**404 Not Found:**

```json
{
  "error": {
    "message": "404 NOT FOUND",
    "details": "Template not found",
    "violations": []
  }
}
```

</Tab>
</Tabs>

## Delete Template [#delete-template]

```text
DELETE https://api.cuedesk.com/v1/templates/{template_uuid}
```

Deletes a template. This operation is asynchronous - a `202 Accepted` response indicates the deletion has been initiated.

<Tabs items={["Request","Response (202)","Errors"]}>
<Tab value="Request">

```text
DELETE https://api.cuedesk.com/v1/templates/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Bearer <token>
```

</Tab>
<Tab value="Response (202)">

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PENDING_DELETION"
}
```

| Field    | Type   | Description |
| -------- | ------ | ----------- |
| `uuid`   | string | The UUID of the deleted template |
| `status` | string | Will be `PENDING_DELETION` while deletion is in progress |

</Tab>
<Tab value="Errors">

**404 Not Found:**

```json
{
  "error": {
    "message": "404 NOT FOUND",
    "details": "Template not found",
    "violations": []
  }
}
```

</Tab>
</Tabs>

## Template Object [#template-object]

The full template object returned by Create, Get, and List endpoints:

| Field                | Type     | Description |
| -------------------- | -------- | ----------- |
| `uuid`               | string   | Unique template identifier (UUID v4) |
| `workspace_uuid`     | string   | Workspace the template belongs to |
| `name`               | string   | Template display name |
| `canonical_name`     | string   | Normalized template name (lowercase, underscored) |
| `locale`             | string   | Language code (e.g. `en`, `pt_BR`) |
| `category`           | string   | Template category (see [TemplateCategory](#templatecategory)) |
| `template_type`      | string   | Template type (see [TemplateType](#templatetype)) |
| `status`             | string   | Current approval status (see [TemplateStatus](#templatestatus)) |
| `rejection_reason`   | string   | Reason for rejection, if applicable |
| `content`            | object   | Template content structure (see [Content Object](#content-object)) |
| `enabled_in_livechat`| boolean  | Whether the template is available in the live chat UI |
| `continue_session`   | boolean  | Whether sending this template continues a session |
| `created_at`         | string   | ISO 8601 timestamp |
| `updated_at`         | string   | ISO 8601 timestamp |

## Content Object [#content-object]

The `content` field contains the template's structural components:

| Field     | Type     | Description |
| --------- | -------- | ----------- |
| `header`  | object   | Header component (`format`, `text`, `example`) |
| `body`    | object   | Body component (`text`, `example`) |
| `footer`  | object   | Footer component (`text`) |
| `buttons` | array    | List of button components |
| `cards`   | array    | Carousel cards (only for `CAROUSEL` type) |
| `auth`    | object   | Authentication config (only for `AUTHENTICATION` type) |

<Callout type="warn" title="Variables cannot start or end template text">
Meta will reject templates where the `body.text` starts or ends with a variable placeholder (e.g. `{{1}}`). Always ensure there is static text before the first variable and after the last variable.
</Callout>

### Header formats [#header-formats]

| Format     | Description |
| ---------- | ----------- |
| `TEXT`     | Text header with optional parameter placeholders |
| `IMAGE`   | Image media header |
| `VIDEO`   | Video media header |
| `DOCUMENT` | Document media header |

### Button types [#button-types]

| Type           | Description |
| -------------- | ----------- |
| `QUICK_REPLY`  | Quick reply button |
| `URL`          | URL button (can contain a parameter) |
| `PHONE_NUMBER` | Call button |
| `OTP`          | One-time password button |

## Enums Reference [#enums-reference]

### TemplateCategory [#templatecategory]

| Value            | Description |
| ---------------- | ----------- |
| `MARKETING`      | Promotional and marketing messages |
| `UTILITY`        | Transactional and utility messages |
| `AUTHENTICATION` | One-time password and verification messages |

### TemplateType [#templatetype]

| Value            | Description |
| ---------------- | ----------- |
| `STANDARD`       | Standard template with header, body, footer, and buttons |
| `CAROUSEL`       | Carousel template with scrollable cards |
| `AUTHENTICATION` | Authentication template with OTP configuration |

### TemplateStatus [#templatestatus]

| Value              | Description |
| ------------------ | ----------- |
| `PREPARING`        | Template is being prepared for submission |
| `PENDING`          | Submitted and awaiting Meta approval |
| `APPROVED`         | Approved and ready to use |
| `REJECTED`         | Rejected by Meta (see `rejection_reason`) |
| `PAUSED`           | Temporarily paused by Meta |
| `FLAGGED`          | Flagged for quality issues |
| `DISABLED`         | Disabled by Meta |
| `IN_APPEAL`        | Rejection is being appealed |
| `PENDING_DELETION` | Deletion in progress |
| `LOCKED`           | Locked and cannot be modified |
| `IN_REVIEW`        | Under review after an update |
| `DELETED`          | Successfully deleted |
| `CREATE_FAILED`    | Template creation failed |
| `UPDATE_FAILED`    | Template update failed |
| `DELETE_FAILED`    | Template deletion failed |
