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

# Send Text Template

Use this endpoint to send an approved text-based WhatsApp template to a recipient.

Template messages are used when your business initiates a conversation or when the 24-hour customer service window is not active.

### Endpoint

```http
POST /messages/
```

Full URL:

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

### Authentication

Include your Bearer Token in the request header:

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

### Request Parameters

| Parameter       | Type   | Required | Description                                            |
| --------------- | ------ | -------- | ------------------------------------------------------ |
| `to`            | String | Yes      | Recipient phone number or supported user ID.           |
| `template.name` | String | Yes      | Name of the approved template in your Taqnyat account. |
| `code`          | String | Yes      | Language code of the selected template.                |

The endpoint accepts one recipient per request.

### Example Payload

```json
{
  "to": "9665XXXXXXXX",
  "template": {
    "name": "order_update"
  },
  "code": "en"
}
```

> Use the exact approved template name and language code configured for the template.

### Example Request

```bash
curl --location 'https://api.taqnyat.sa/wa/v2/messages/' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "to": "9665XXXXXXXX",
  "template": {
    "name": "order_update"
  },
  "code": "en"
}'
```

### Recipient Format

The `to` value should follow the international phone-number format used by the Taqnyat WhatsApp API.

Example:

```
9665XXXXXXXX
```

Do not include `+`, `00`, spaces, or dashes.

### Template Requirements

Before sending the request:

* The template must already exist in your Taqnyat account.
* The template must be approved.
* The template name must match the approved template exactly.
* The language code must match the language configured for that template.
* The recipient must meet the applicable opt-in requirements.

### Response

The current public Taqnyat reference does not document the exact JSON response body for the text-template endpoint.

Once you test this request in Postman, add the exact production response here rather than using an assumed response.

### Message Status

After the request is accepted, delivery updates can be received through the **Delivery Status Callback**.

Use the returned message identifier, when provided by the API response, to associate future status callbacks with the original message.

### Notes

* This endpoint sends one template message to one recipient per request.
* The template must already be approved before sending.
* Use **Dynamic Template** when the approved template contains variables that require values at send time.
* Delivery acceptance does not necessarily mean the message has reached the recipient; use webhook delivery statuses to track `sent`, `delivered`, `read`, or `failed`.