> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skyfree.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Api

The Workspace API lets you manage contacts, labels, custom fields, WhatsApp messaging, and automations programmatically.

## Authentication

All requests require an API key. You can generate one from **Workspace → Account → API Keys**.

Pass the key in of these ways:

| Method       | Example                          |
| ------------ | -------------------------------- |
| Header       | `X-API-Key: your_key`            |
| Bearer token | `Authorization: Bearer your_key` |
| Query string | `?apiKey=your_key`               |
| Request body | `{ "apiKey": "your_key" }`       |

## Base URL

```text theme={null}
/api/workspace/v1/
```

## Request format

Every endpoint accepts **both GET and POST**. Parameters can be passed as URL query strings or as a JSON body — they work identically.

***

## Channels

### List Channels

Returns all channels accessible to your API key.

**Endpoint:** `GET/POST /channels/list`

**Parameters:** none

**Response:**

```json theme={null}
{
  "success": true,
  "data": [
    { "id": "ch_xxx", "name": "My WhatsApp", "phoneNumberId": "1234", "isActive": true }
  ],
  "message": "Found 1 channel(s)"
}
```

***

## Contacts

### Create or Update a Contact

Creates a new contact or updates an existing one matched by `phoneNumber`.

**Endpoint:** `GET/POST /contacts/manage`

| Parameter           | Required | Description                                      |
| ------------------- | -------- | ------------------------------------------------ |
| `phoneNumber`       | ✅        | Contact's phone number (e.g. `+1234567890`)      |
| `channelId`         |          | Channel ID — auto-selected if you only have one  |
| `name`              |          | Display name                                     |
| `email`             |          | Email address                                    |
| `profilePictureUrl` |          | Profile picture URL                              |
| `customFieldsData`  |          | JSON object or comma-separated `key:value` pairs |
| `labelNames`        |          | Comma-separated label names or JSON array        |

**Example:**

```http theme={null}
POST /api/workspace/v1/contacts/manage
X-API-Key: your_key
Content-Type: application/json

{
  "phoneNumber": "+1234567890",
  "name": "Jane Doe",
  "labelNames": "vip,lead",
  "customFieldsData": { "plan": "pro", "source": "website" }
}
```

***

### List Contacts

Returns a paginated list of contacts for a channel.

**Endpoint:** `GET/POST /contacts/list`

| Parameter   | Required | Description                                  |
| ----------- | -------- | -------------------------------------------- |
| `channelId` |          | Auto-selected if only one channel            |
| `page`      |          | Page number (default: `1`)                   |
| `limit`     |          | Results per page (default: `50`, max: `200`) |
| `search`    |          | Search by name or phone number               |

**Response:**

```json theme={null}
{
  "success": true,
  "data": [...],
  "pagination": { "page": 1, "limit": 50, "total": 120, "pages": 3 }
}
```

***

## Custom Fields

### Create or Update a Custom Field

Creates a new custom field definition or updates an existing one matched by `name`.

**Endpoint:** `GET/POST /custom-fields/manage`

| Parameter    | Required | Description                                                                                   |
| ------------ | -------- | --------------------------------------------------------------------------------------------- |
| `name`       | ✅        | Field name / label                                                                            |
| `channelId`  |          | Auto-selected if only one channel                                                             |
| `type`       |          | `text` \| `number` \| `email` \| `phone` \| `date` \| `label` \| `dropdown` (default: `text`) |
| `isRequired` |          | `true` or `false` (default: `false`)                                                          |
| `options`    |          | JSON array of options for `dropdown` type                                                     |

***

### List Custom Fields

Returns all custom field definitions for a channel.

**Endpoint:** `GET/POST /custom-fields/list`

| Parameter   | Required | Description                       |
| ----------- | -------- | --------------------------------- |
| `channelId` |          | Auto-selected if only one channel |

***

## Labels

### Create or Update a Label

Creates a new label or updates an existing one matched by `name`.

**Endpoint:** `GET/POST /labels/manage`

| Parameter      | Required | Description                       |
| -------------- | -------- | --------------------------------- |
| `name`         | ✅        | Label name                        |
| `channelId`    |          | Auto-selected if only one channel |
| `description`  |          | Description text                  |
| `color`        |          | Hex color (e.g. `#FF5733`)        |
| `displayOrder` |          | Sort order integer                |

***

### List Labels

Returns all labels for a channel.

**Endpoint:** `GET/POST /labels/list`

| Parameter   | Required | Description                       |
| ----------- | -------- | --------------------------------- |
| `channelId` |          | Auto-selected if only one channel |

***

## WhatsApp

### List Templates

Returns all approved WhatsApp templates for a channel.

**Endpoint:** `GET/POST /whatsapp/templates/list`

| Parameter   | Required | Description                       |
| ----------- | -------- | --------------------------------- |
| `channelId` |          | Auto-selected if only one channel |

***

### Send a Template

Sends an approved WhatsApp template message to a phone number. The language code is automatically resolved from the stored template if not provided.

**Endpoint:** `GET/POST /whatsapp/templates/send`

| Parameter           | Required | Description                                             |
| ------------------- | -------- | ------------------------------------------------------- |
| `to`                | ✅        | Recipient phone number                                  |
| `templateName`      | ✅        | Exact template name                                     |
| `channelId`         |          | Auto-selected if only one channel                       |
| `languageCode`      |          | Language code (default: auto-resolved or `en`)          |
| `variables`         |          | Comma-separated body variables: `variables=Hello,World` |
| `body1`, `body2`, … |          | Body variables by index (alternative to `variables`)    |
| `header`            |          | Header text variable                                    |
| `image`             |          | Header image URL                                        |
| `video`             |          | Header video URL                                        |
| `document`          |          | Header document URL                                     |
| `mediaUrl`          |          | Generic media URL (use with `mediaType`)                |
| `mediaType`         |          | `image` \| `video` \| `document`                        |
| `apiReference`      |          | Custom reference ID for tracking                        |

**Example:**

```http theme={null}
POST /api/workspace/v1/whatsapp/templates/send
X-API-Key: your_key

{
  "to": "+1234567890",
  "templateName": "order_confirmation",
  "variables": "John,ORD-1234,29.99"
}
```

***

### Send a Message

Sends a regular WhatsApp message (text or media) within a 24-hour session window.

**Endpoint:** `GET/POST /whatsapp/message/send`

| Parameter      | Required    | Description                                                             |
| -------------- | ----------- | ----------------------------------------------------------------------- |
| `to`           | ✅           | Recipient phone number                                                  |
| `type`         |             | `text` \| `image` \| `video` \| `document` \| `audio` (default: `text`) |
| `body`         | ✅ for text  | Message text                                                            |
| `url`          | ✅ for media | Media URL                                                               |
| `caption`      |             | Caption for media messages                                              |
| `filename`     |             | Filename for document messages                                          |
| `channelId`    |             | Auto-selected if only one channel                                       |
| `apiReference` |             | Custom reference ID for tracking                                        |

***

### Get Message Status

Returns the delivery status of a sent WhatsApp message by its WAMID.

**Endpoint:** `GET/POST /whatsapp/message/status`

| Parameter | Required | Description                                    |
| --------- | -------- | ---------------------------------------------- |
| `wamid`   | ✅        | WhatsApp message ID (e.g. `wamid.HBgM...AA==`) |

**Response fields:** `status`, `direction`, `type`, `content`, `timestamp`, `deliveredAt`, `readAt`, `error`

***

## Automations

### List Automations

Returns all automations for a channel.

**Endpoint:** `GET/POST /automations/list`

| Parameter   | Required | Description                       |
| ----------- | -------- | --------------------------------- |
| `channelId` |          | Auto-selected if only one channel |

***

### Trigger an Automation

Manually triggers an automation for a contact. Creates the contact and conversation automatically if they don't exist.

**Endpoint:** `GET/POST /automations/trigger`

| Parameter        | Required    | Description                        |
| ---------------- | ----------- | ---------------------------------- |
| `phoneNumber`    | ✅           | Contact's phone number             |
| `automationId`   | ✅ (or name) | Automation ID                      |
| `automationName` | ✅ (or ID)   | Automation name (case-insensitive) |
| `channelId`      |             | Auto-selected if only one channel  |

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "executionId": "exec_xxx",
    "automationId": "auto_xxx",
    "automationName": "Welcome Flow",
    "contactId": "contact_xxx",
    "conversationId": "conv_xxx",
    "status": "triggered"
  }
}
```

***

## Error responses

All errors return a consistent shape:

```json theme={null}
{
  "success": false,
  "error": "Short error reason",
  "message": "Human-readable detail"
}
```

| Status | Meaning                            |
| ------ | ---------------------------------- |
| `400`  | Missing or invalid parameters      |
| `401`  | Missing or invalid API key         |
| `403`  | Access denied (e.g. wrong channel) |
| `404`  | Resource not found                 |
| `500`  | Server error                       |