> 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/api-integration-guide/getting-started.md).

# Getting Started

The Taqnyat WhatsApp API enables businesses to integrate WhatsApp messaging directly with their applications, websites, CRM systems, and other platforms.

Using the API, you can programmatically send and receive WhatsApp messages, manage templates and media, and receive message delivery and inbound-message updates through callbacks.

### Before You Start

Before integrating with the API, make sure you have:

* An active Taqnyat account.
* An activated WhatsApp Business number connected to your account.
* A valid API Bearer Token with access to the WhatsApp service.
* Basic knowledge of REST APIs and JSON.
* Customer opt-in before initiating business messages where required.

Recipient phone numbers must be provided in **international format without `+` or `00`**.

Example:

`9665XXXXXXXX`

### Base URL

All WhatsApp API requests use the following base URL:

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

Make sure the base URL ends with `/` when constructing your requests.

### Authentication

Taqnyat uses **Bearer Token authentication**.

Your token is generated from the Taqnyat portal and must be included in the `Authorization` header of each API request. Requests with invalid or missing authentication credentials may return an HTTP `401` response.

Example:

```
Authorization: Bearer <YOUR_TOKEN>
```

See **Authentication** for instructions on generating and using your token.

### WhatsApp Message Flow

When integrating with WhatsApp, there are two main messaging scenarios:

#### Business-Initiated Messages

When your business starts a conversation with a customer, an approved **message template** must be used.

Customer opt-in must be obtained before sending business-initiated messages.

#### Customer-Initiated Conversations

When a customer sends a message to your WhatsApp number, a **24-hour customer service window** is opened.

During this window, your application can send supported free-form conversation messages. Each new message from the customer resets the 24-hour window.

Once the window expires, an approved template must be used to initiate communication again.

### What You Can Do with the API

The API Reference covers:

* **Account** — retrieve account information such as balance.
* **Media** — upload and retrieve media files.
* **Templates** — create, retrieve, and delete message templates.
* **Template Messages** — send approved business-initiated templates.
* **Conversation Messages** — send text, image, video, document, audio, contact, location, and interactive messages.
* **Webhooks / Callbacks** — receive delivery statuses and incoming customer messages.

### Next Steps

Start by configuring your integration:

**Authentication**\
Generate your Bearer Token and learn how to authenticate API requests.

**Base URL**\
Understand how API endpoint URLs are structured.

**Phone Number Format**\
Learn the required recipient-number format before sending messages.

After completing these steps, you can continue to **Template Messages** or **Conversation Messages** depending on your use case.