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

/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:

{
  "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:

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:

{
  "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

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:

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:

{
  "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:

{
  "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

Overview

Contacts

Inbox

Automation

WhatsApp

Instagram

Web Chat

Authentication

Base URL

Request format

Channels

List Channels

Contacts

Create or Update a Contact

List Contacts

Custom Fields

Create or Update a Custom Field

List Custom Fields

Labels

Create or Update a Label

List Labels

WhatsApp

List Templates

Send a Template

Send a Message

Get Message Status

Automations

List Automations

Trigger an Automation

Error responses

​Authentication

​Base URL

​Request format

​Channels

​List Channels

​Contacts

​Create or Update a Contact

​List Contacts

​Custom Fields

​Create or Update a Custom Field

​List Custom Fields

​Labels

​Create or Update a Label

​List Labels

​WhatsApp

​List Templates

​Send a Template

​Send a Message

​Get Message Status

​Automations

​List Automations

​Trigger an Automation

​Error responses

Authentication

Base URL

Request format

Channels

List Channels

Contacts

Create or Update a Contact

List Contacts

Custom Fields

Create or Update a Custom Field

List Custom Fields

Labels

Create or Update a Label

List Labels

WhatsApp

List Templates

Send a Template

Send a Message

Get Message Status

Automations

List Automations

Trigger an Automation

Error responses