Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xpressbot.org/llms.txt

Use this file to discover all available pages before exploring further.

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:
MethodExample
HeaderX-API-Key: your_key
Bearer tokenAuthorization: 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
ParameterRequiredDescription
phoneNumber✅Contact’s phone number (e.g. +1234567890)
channelIdChannel ID — auto-selected if you only have one
nameDisplay name
emailEmail address
profilePictureUrlProfile picture URL
customFieldsDataJSON object or comma-separated key:value pairs
labelNamesComma-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
ParameterRequiredDescription
channelIdAuto-selected if only one channel
pagePage number (default: 1)
limitResults per page (default: 50, max: 200)
searchSearch 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
ParameterRequiredDescription
name✅Field name / label
channelIdAuto-selected if only one channel
typetext | number | email | phone | date | label | dropdown (default: text)
isRequiredtrue or false (default: false)
optionsJSON array of options for dropdown type

​
List Custom Fields

Returns all custom field definitions for a channel. Endpoint: GET/POST /custom-fields/list
ParameterRequiredDescription
channelIdAuto-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
ParameterRequiredDescription
name✅Label name
channelIdAuto-selected if only one channel
descriptionDescription text
colorHex color (e.g. #FF5733)
displayOrderSort order integer

​
List Labels

Returns all labels for a channel. Endpoint: GET/POST /labels/list
ParameterRequiredDescription
channelIdAuto-selected if only one channel

​
WhatsApp

​
List Templates

Returns all approved WhatsApp templates for a channel. Endpoint: GET/POST /whatsapp/templates/list
ParameterRequiredDescription
channelIdAuto-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
ParameterRequiredDescription
to✅Recipient phone number
templateName✅Exact template name
channelIdAuto-selected if only one channel
languageCodeLanguage code (default: auto-resolved or en)
variablesComma-separated body variables: variables=Hello,World
body1, body2, …Body variables by index (alternative to variables)
headerHeader text variable
imageHeader image URL
videoHeader video URL
documentHeader document URL
mediaUrlGeneric media URL (use with mediaType)
mediaTypeimage | video | document
apiReferenceCustom 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
ParameterRequiredDescription
to✅Recipient phone number
typetext | image | video | document | audio (default: text)
body✅ for textMessage text
url✅ for mediaMedia URL
captionCaption for media messages
filenameFilename for document messages
channelIdAuto-selected if only one channel
apiReferenceCustom 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
ParameterRequiredDescription
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
ParameterRequiredDescription
channelIdAuto-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
ParameterRequiredDescription
phoneNumber✅Contact’s phone number
automationId✅ (or name)Automation ID
automationName✅ (or ID)Automation name (case-insensitive)
channelIdAuto-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"
}
StatusMeaning
400Missing or invalid parameters
401Missing or invalid API key
403Access denied (e.g. wrong channel)
404Resource not found
500Server error
Last modified on May 3, 2026