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

# Send OTP Template

Use this endpoint to send an approved **authentication template** containing a one-time password (OTP).

OTP templates are used for verification and authentication scenarios and must already be approved under the **Authentication** category.

### 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. |
| `template.name` | String | Yes      | Name of the approved authentication template.   |
| `code`          | String | Yes      | Language code of the template.                  |
| `otp`           | String | Yes      | One-time password value sent to the recipient.  |

### Example Payload

```json
{
  "to": "9665XXXXXXXX",
  "template": {
    "name": "login_verification"
  },
  "code": "en",
  "otp": "548921"
}
```

### Example Request

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

### OTP Template Requirements

Before sending:

* The template must already be approved.
* The template category must be **Authentication**.
* The template name must match the approved template exactly.
* The language code must match the configured template language.
* The `otp` value should contain the verification code that will be delivered to the recipient.

### Response

### Message Status

After the request is accepted, use the **Delivery Status Callback** to track the message status.

Possible delivery states may include:

* `sent`
* `delivered`
* `read`
* `failed`

### Notes

* OTP templates should only be used for authentication and verification purposes.
* Generate a new OTP for each authentication attempt according to your application's security logic.
* Do not reuse expired or previously consumed OTP values.
* Delivery confirmation does not mean the recipient successfully completed the authentication process.