> 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/send-templates/send-catalog-template.md).

# Send Catalog Template

Use this endpoint to send an approved WhatsApp **catalog template** that can include dynamic body values and a catalog button linked to a specific product.

The product is identified using its `thumbnail_product_retailer_id`.

### Endpoint

```
POST /messages/
```

Full URL:

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

### Authentication

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

### Request Parameters

| Parameter                       | Type   | Required           | Description                                               |
| ------------------------------- | ------ | ------------------ | --------------------------------------------------------- |
| `to`                            | String | Yes                | Recipient phone number in international format.           |
| `type`                          | String | Yes                | Must be `template`.                                       |
| `template.name`                 | String | Yes                | Name of the approved catalog template.                    |
| `template.language.code`        | String | Yes                | Language code of the approved template.                   |
| `components`                    | Array  | Yes                | Contains the template components and their parameters.    |
| `components[].type`             | String | Yes                | Component type, such as `body` or `button`.               |
| `parameters[].type`             | String | Yes                | Parameter type, such as `text` or `action`.               |
| `parameters[].text`             | String | When applicable    | Dynamic value used in the template body.                  |
| `sub_type`                      | String | For catalog button | Must be `CATALOG` for the catalog button component.       |
| `index`                         | Number | For catalog button | Index of the catalog button.                              |
| `thumbnail_product_retailer_id` | String | No                 | Product content ID used as the catalog thumbnail product. |

The current Taqnyat API reference lists `thumbnail_product_retailer_id` as optional.

### Example Payload

{% code overflow="wrap" expandable="true" %}

```json
{
  "to": "9665XXXXXXXX",
  "type": "template",
  "template": {
    "name": "product_catalog",
    "language": {
      "code": "en"
    }
  },
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "100"
        },
        {
          "type": "text",
          "text": "400"
        },
        {
          "type": "text",
          "text": "3"
        }
      ]
    },
    {
      "type": "button",
      "sub_type": "CATALOG",
      "index": 0,
      "parameters": [
        {
          "type": "action",
          "action": {
            "thumbnail_product_retailer_id": "34XXXXXXXX"
          }
        }
      ]
    }
  ]
}
```

{% endcode %}

This structure matches the current Taqnyat catalog-template example.

### Example Request

```bash
curl --location 'https://api.taqnyat.sa/wa/v2/messages/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--data '{
  "to": "9665XXXXXXXX",
  "type": "template",
  "template": {
    "name": "product_catalog",
    "language": {
      "code": "en"
    }
  },
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "100"
        },
        {
          "type": "text",
          "text": "400"
        },
        {
          "type": "text",
          "text": "3"
        }
      ]
    },
    {
      "type": "button",
      "sub_type": "CATALOG",
      "index": 0,
      "parameters": [
        {
          "type": "action",
          "action": {
            "thumbnail_product_retailer_id": "34XXXXXXXX"
          }
        }
      ]
    }
  ]
}'
```

### Dynamic Body Values

If the approved catalog template contains variables, provide them in the body component in the same order as the template placeholders.

For example:

```
{{1}} → 100
{{2}} → 400
{{3}} → 3
```

### Catalog Button

The catalog interaction is defined using a button component:

```json
{
  "type": "button",
  "sub_type": "CATALOG",
  "index": 0
}
```

The product used for the catalog thumbnail is supplied inside the action:

```json
{
  "type": "action",
  "action": {
    "thumbnail_product_retailer_id": "34XXXXXXXX"
  }
}
```

### Example Response

A successful request returns a message identifier and recipient:

```json
{
  "type": "template",
  "statuses": {
    "message_id": "<MESSAGE_ID>",
    "recipient": "+9665XXXXXXXX"
  }
}
```

### Common Errors

#### Missing Recipient

```json
{
  "message": "100",
  "reason": "The 'to' parameter is required / متغير 'to' مطلوب"
}
```

#### Template Parameter Count Mismatch

```json
{
  "message": "132000",
  "reason": "(#132000) Template parameters count mismatch / عدد باراميترات القالب غير متطابق"
}
```

#### Invalid Token

```json
{
  "message": "401",
  "reason": "No such bot/bearer combination"
}
```

#### Invalid Recipient

```json
{
  "message": "402",
  "reason": "Invalid recipient"
}
```

### Notes

* The template must already be approved.
* The template must be configured to use a catalog interaction.
* Body variables must match the number and order expected by the approved template.
* `thumbnail_product_retailer_id` should correspond to the product you want displayed as the catalog thumbnail.
* Use the returned `message_id` to track delivery through the **Delivery Status Callback**.