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

# Send Document Template

## Send Document Template

Use this endpoint to send an approved WhatsApp template that includes a **document**.

The document must be accessible through a public HTTP or HTTPS URL. A custom filename can also be provided.

### 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                                    |
| --------------- | ------ | -------- | ---------------------------------------------- |
| `type`          | String | Yes      | Must be `document`.                            |
| `url`           | String | Yes      | Public HTTP or HTTPS URL of the document file. |
| `filename`      | String | No       | Optional filename to display for the document. |
| `template.name` | String | Yes      | Name of the approved template.                 |
| `code`          | String | Yes      | Language code of the template.                 |

The current Taqnyat API reference documents `filename` as optional and `ar` as the default language code.

### Example Payload

```json
{
  "type": "document",
  "url": "https://example.com/documents/invoice.pdf",
  "filename": "invoice.pdf",
  "template": {
    "name": "invoice_notification"
  },
  "code": "en"
}
```

### Example Request

```bash
curl --location 'https://api.taqnyat.sa/wa/v2/messages/' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "type": "document",
  "url": "https://example.com/documents/invoice.pdf",
  "filename": "invoice.pdf",
  "template": {
    "name": "invoice_notification"
  },
  "code": "en"
}'
```

### Document Requirements

The document URL should:

* Use `HTTP` or `HTTPS`.
* Be publicly accessible.
* Not require authentication or login.
* Point directly to the document file.
* Use a supported document format.

The Taqnyat API supports documents up to **100 MB**, subject to the supported content types listed in the API reference. Supported document types include PDF, TXT, CSV, Microsoft Office formats, and several OpenDocument formats.

### Template Requirements

Before sending:

* The template must already be approved.
* The template must include a document media component.
* The template name must match the approved template exactly.
* The language code must match the configured template language.
* The recipient must meet the applicable opt-in and messaging requirements.

### Response

The current Taqnyat API reference does not document the exact JSON response body for this request.

Add the actual production response after testing the endpoint in Postman.

### Message Status

After the request is accepted, use the **Delivery Status Callback** to track the message status, such as:

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

### Notes

* `filename` is optional.
* If provided, use a clear filename that matches the document being sent.
* Make sure the document remains publicly accessible while the message is being processed.
* If the document cannot be retrieved or does not meet the supported file requirements, delivery may fail.