# API Documentation v1.0

Modern, RESTful, and highly performant API designed for seamless integrations.
Base URL: /api/v1/

## Authentication
API requests require a Bearer Token. This can be passed in two ways:
1. HTTP Header (Recommended): `Authorization: Bearer YOUR_API_TOKEN`
2. Query Parameter: Append `?token=YOUR_API_TOKEN` to the URL.

## Profile
### GET /me
Retrieves the authenticated user and company profile.
Response Example:
```json
{
  "status": "success",
  "message": "Profile retrieved successfully",
  "data": { "id": 1, "name": "John Doe", "email": "admin@example.com", "company_id": 1 }
}
```

## Messages
### POST or GET /messages/text
Send a standard text or media message to a phone number.
Payload/Query parameters:
- phone (Required): Recipient's phone number with country code.
- message (Optional): Text content of the message.
- media_url (Optional): Public URL for sending an image/video/document.

### POST or GET /messages/template
Send a pre-approved WhatsApp template message.
Payload/Query parameters:
- phone (Required): Recipient's phone number.
- template_name (Required): The exact name of the template.
- template_language (Optional): Language code (e.g. en). Default is en. (Alias: language)
- components (Optional): Array of component parameters for dynamic variables (Standard WhatsApp Cloud API format).

Legacy / Simple Parameters (Alternative to components):
- variables (Optional): JSON Array of strings to replace {{1}} variables in the body text. Example: ["John", "Doe"]
- header_variables (Optional): JSON Array of strings for header text variables.
- document, image, video, audio (Optional): Public URL for sending media in the template header. (Provide only one).

### POST or GET /messages/list
Send an interactive list message.
Payload/Query parameters:
- phone (Required): Recipient's phone number.
- message (Required): Main body text.
- action (Required): List action definition.
- header (Optional): Header text.
- footer (Optional): Footer text.

## Contacts
### GET /contacts
Retrieve a paginated list of contacts. Add ?update_from=YYYY-MM-DD HH:MM:SS to filter recently modified contacts.

### POST /contacts
Create or upsert a contact by phone number.
Payload parameters:
- phone (Required): Contact phone number.
- name (Optional): Full name.
- email (Optional): Email address.
- groups (Optional): Comma-separated string or array of group names.
- custom (Optional): Key-value object of custom fields.
- enabled_ai_bot (Optional): Enable (1) or disable (0) AI Bot.

### PUT /contacts/{id}
Fully update an existing contact by its database ID. Uses the exact same payload structure as the POST route.

### GET /contacts/{id}
Retrieve details of a specific contact by ID.

### GET /contacts/{id}/groups-and-fields
Retrieve all associated groups and custom fields for a specific contact.

### GET /contacts/{id}/notes
Retrieve all notes associated with a specific contact.

### POST /contacts/check-phone
Verify if a phone number exists on WhatsApp. Limited to 60 checks per minute.
Response Example:
```json
{
  "status": "success",
  "data": { "phone": "1234567890", "is_valid": true, "wa_id": "1234567890" }
}
```

## Templates
### GET /templates
List all available templates. Use ?name=TEMPLATE_NAME to filter by exact name.

### GET /templates/{id}
Retrieve details of a specific template by ID.

## Campaigns
### GET /campaigns
List campaigns. Filter using ?type=bot|api|regular.

### POST /campaigns/send
Dispatch a campaign message to a contact dynamically.
Payload parameters:
- phone (Required): Contact's phone number.
- campaign_id (Required): ID of the campaign. (Alias: campaing_id)
- data (Optional): Dynamic variables mapping to the template.

## Conversations
### GET /conversations
Get a list of active chat conversations. Use ?lastmessagetime=YYYY-MM-DD HH:MM:SS to sync new conversations.

### GET /conversations/{id}/messages
Fetch the message timeline for a specific conversation ID. Supports ?lastmessagetime filter.

## Groups
### GET /groups
Retrieve contact groups. Use ?showContacts=yes to eagerly load all assigned contacts.