> 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-dynamic-template.md).

# Send Dynamic Template

Use this endpoint to send an approved WhatsApp template that contains dynamic variables.

Dynamic values are supplied at send time and replace the variables defined in the approved template.

### Endpoint

```
POST /messages/
```

Full URL:

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

### Authentication

Include your Bearer Token in the request header:

```
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 template.                                |
| `template.language.code` | String | Yes      | Language code of the approved template.                       |
| `components`             | Array  | Yes      | Contains the dynamic template components and variable values. |
| `components[].type`      | String | Yes      | Component type. For body variables, use `body`.               |
| `parameters`             | Array  | Yes      | Contains the values that replace the template variables.      |
| `parameters[].type`      | String | Yes      | Variable type. For text variables, use `text`.                |
| `parameters[].text`      | String | Yes      | Value that replaces the corresponding template variable.      |

### Example Payload

```json
{
  "to": "9665XXXXXXXX",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": {
      "code": "en"
    }
  },
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "Ahmad"
        },
        {
          "type": "text",
          "text": "ORD-12540"
        },
        {
          "type": "text",
          "text": "27 August 2026"
        }
      ]
    }
  ]
}
```

### Example Request

```json
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": "order_update",
    "language": {
      "code": "en"
    }
  },
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "Ahmad"
        },
        {
          "type": "text",
          "text": "ORD-12540"
        },
        {
          "type": "text",
          "text": "27 August 2026"
        }
      ]
    }
  ]
}'
```

### Variable Order

Dynamic values must follow the same order as the variables in the approved template.

For example, if the template body contains:

```
Hello {{1}}, your order {{2}} will be delivered on {{3}}.
```

Then the values should be sent in the same order:

```json
{{1}} → Ahmad
{{2}} → ORD-12540
{{3}} → 27 August 2026
```

The first object in `parameters` replaces `{{1}}`, the second replaces `{{2}}`, and so on.

### Example Response

A successful request may return a response similar to:

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

The `message_id` can be used to associate later delivery-status callbacks with the original message.

### Template Requirements

Before sending:

* The template must already be approved.
* The template name must match the approved template exactly.
* The language code must match the approved template language.
* The number of supplied parameters should match the variables in the template.
* Variable values must be provided in the correct order.

### Notes

* Use `type: "template"` at the message level.
* For body variables, use `type: "body"` inside `components`.
* For text variables, use `type: "text"` and place the value in `text`.
* Add one parameter object for each variable required by the template.
* Delivery updates can be tracked through the **Delivery Status Callback**.