> For the complete documentation index, see [llms.txt](https://docs.taqnyat.sa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.taqnyat.sa/api-reference/templates/create-template/general-structure.md).

# General Structure

Use this endpoint to create a standard WhatsApp message template with supported components such as a body, header, footer, and buttons.

### Endpoint

```
POST /templates/
```

Full URL:

```
https://api.taqnyat.sa/wa/v2/templates/
```

### Authentication

Include your API token in the request header:

```
Authorization: <YOUR_TOKEN>Content-Type: application/json
```

### Request Parameters

| Parameter    | Type   | Required | Description                                                    |
| ------------ | ------ | -------- | -------------------------------------------------------------- |
| `name`       | String | Yes      | Unique name of the template.                                   |
| `language`   | String | Yes      | Language code of the template.                                 |
| `category`   | String | Yes      | Template category, such as `UTILITY` or `MARKETING`.           |
| `components` | Array  | Yes      | Contains the content and interactive elements of the template. |

### Components

The `components` array defines the structure of the template.

Supported components in the general structure include:

* `BODY`
* `HEADER`
* `FOOTER`
* `BUTTONS`

#### Body

Use the `BODY` component for the main message content.

```json
{
  "type": "BODY",
  "text": "Your message text"
}
```

#### Header

Use the `HEADER` component to add a text header.

```json
{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Header text"
}
```

#### Footer

Use the `FOOTER` component to add optional footer text.

```json
{
  "type": "FOOTER",
  "text": "Footer text"
}
```

#### Buttons

Use the `BUTTONS` component to add supported interactive buttons.

The current Postman structure includes:

* URL button
* Phone Number button
* Quick Reply button

### Example Payload

```json
{
  "name": "order_update",
  "language": "en",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Your order has been confirmed."
    },
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Order Update"
    },
    {
      "type": "FOOTER",
      "text": "Thank you for choosing us."
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "View Order",
          "url": "https://example.com/order"
        },
        {
          "type": "PHONE_NUMBER",
          "text": "Call Us",
          "phone_number": "+966XXXXXXXXX"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Contact Support"
        }
      ]
    }
  ]
}
```

### Example Request

```bash
curl --location 'https://api.taqnyat.sa/wa/v2/templates/' \
--header 'Content-Type: application/json' \
--header 'Authorization: <YOUR_TOKEN>' \
--data '{
  "name": "order_update",
  "language": "en",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Your order has been confirmed."
    },
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Order Update"
    },
    {
      "type": "FOOTER",
      "text": "Thank you for choosing us."
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "View Order",
          "url": "https://example.com/order"
        },
        {
          "type": "PHONE_NUMBER",
          "text": "Call Us",
          "phone_number": "+966XXXXXXXXX"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Contact Support"
        }
      ]
    }
  ]
}'
```

### Button Structure

#### URL Button

```json
{
  "type": "URL",
  "text": "View Order",
  "url": "https://example.com/order"
}
```

#### Phone Number Button

```json
{
  "type": "PHONE_NUMBER",
  "text": "Call Us",
  "phone_number": "+966XXXXXXXXX"
}
```

#### Quick Reply Button

```json
{
  "type": "QUICK_REPLY",
  "text": "Contact Support"
}
```

### Template Category

Set `category` according to the actual purpose and wording of the template.

Common values include:

```
UTILITY
MARKETING
AUTHENTICATION
```

Meta reviews the submitted template and determines its final category and approval status.

### Response

Use the exact response returned by the production API when documenting the response schema.

If the Postman request includes a saved response, we can add it here exactly as returned.

### Notes

* `name`, `language`, `category`, and `components` are part of the template creation structure.
* The body contains the main message text.
* Header and footer components are optional depending on the template design.
* Buttons are defined inside a `BUTTONS` component.
* Only include components required by the template you are creating.
* The template must be approved before it can be used for sending messages.