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

# OTP Template

Use this endpoint to create a WhatsApp **Authentication template** for one-time passwords (OTP) and verification use cases.

### 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 authentication template.                                        |
| `language`                    | String  | Yes      | Language code of the template.                                                     |
| `category`                    | String  | Yes      | Must be `AUTHENTICATION`.                                                          |
| `components`                  | Array   | Yes      | Contains the authentication template components.                                   |
| `add_security_recommendation` | Boolean | Yes      | Controls whether the security recommendation is included in the OTP template body. |
| `code_expiration_minutes`     | Integer | Yes      | Defines the OTP expiration time in minutes.                                        |
| `buttons`                     | Array   | Yes      | Contains the OTP interaction button.                                               |
| `otp_type`                    | String  | Yes      | Defines the OTP button behavior. In this example, use `COPY_CODE`.                 |
| `text`                        | String  | Yes      | Text displayed on the OTP button.                                                  |

### Example Payload

```json
{
  "name": "login_otp",
  "language": "en",
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 5
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE",
          "text": "Copy Code"
        }
      ]
    }
  ]
}
```

### Example Request

```bash
curl --location 'https://api.taqnyat.sa/wa/v2/templates/' \
--header 'Content-Type: application/json' \
--header 'Authorization: <YOUR_TOKEN>' \
--data '{
  "name": "login_otp",
  "language": "en",
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 5
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE",
          "text": "Copy Code"
        }
      ]
    }
  ]
}'
```

### Component Structure

#### Body

The `BODY` component can include the security recommendation:

```json
{
  "type": "BODY",
  "add_security_recommendation": true
}
```

#### Footer

The `FOOTER` component defines the OTP expiration period:

```json
{
  "type": "FOOTER",
  "code_expiration_minutes": 5
}
```

In this example, the OTP expires after **5 minutes**.

#### OTP Button

The `BUTTONS` component defines how the user interacts with the OTP:

```json
{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "OTP",
      "otp_type": "COPY_CODE",
      "text": "Copy Code"
    }
  ]
}
```

`COPY_CODE` provides a button that allows the user to copy the OTP code.

### Template Category

OTP templates use:

```
AUTHENTICATION
```

This template type is intended for verification and authentication use cases.

### Response

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

If Postman contains a saved response for this request, we can add it directly to the page.

### Notes

* `category` must be `AUTHENTICATION`.
* `BODY`, `FOOTER`, and `BUTTONS` are used in the OTP structure shown in the current Postman collection.
* `code_expiration_minutes` controls how long the OTP is considered valid.
* `otp_type: "COPY_CODE"` creates a Copy Code button.
* The template must be approved before it can be used with the OTP sending endpoint.
* The language used when sending the OTP should match the approved template language.