ChatbotX Agent Documentation

ChatbotX is an open-source omnichannel chatbot platform for managing contacts, conversations, flows, broadcasts, and sequences across channels like WhatsApp, Messenger, Telegram, and more.

Key Highlights

Two Critical Rules:

1. Authenticate before executing any commands — every API call requires a workspace token
2. Always resolve IDs first — commands like contacts tag add require both a contactId and a tagId; fetch them with list commands before using them

Integration Modes:

• CLI (chatbotx) — terminal-based automation and scripting
• MCP Server — gives AI agents (Claude, Cursor, ChatGPT) direct tool access via Model Context Protocol

Authentication

CLI

Save credentials once — they persist across all future runs:

chatbotx config set --apiKey <your-workspace-token> --apiUrl https://app.chatbotx.io/api

Or via environment variables (no config file needed):

export CHATBOTX_API_KEY=your_workspace_token
export CHATBOTX_API_URL=https://app.chatbotx.io/api

For local instances with self-signed certificates:

export CHATBOTX_ALLOW_SELF_SIGNED_CERT=true

Find your workspace token at: Settings → Developer → API Keys

MCP Server (stdio — recommended for local use)

claude mcp add chatbotx \
  -e CHATBOTX_API_KEY=<your-token> \
  -e CHATBOTX_API_URL=https://your-instance.com \
  -e CHATBOTX_MCP_TRANSPORT=stdio \
  -s user \
  -- node /path/to/dist/index.mjs

MCP Server (SSE — for shared/remote access)

claude mcp add chatbotx \
  -t sse \
  -H "x-workspace-token: <your-token>" \
  -s user \
  "https://your-mcp-server.com/sse"

Core Workflow

The platform follows a six-step pattern:

1. Authenticate — set API key and URL
2. Discover — list channels, tags, custom fields, flows, sequences to get IDs
3. Find contacts — list or search contacts to get contactId
4. Act — create, update, tag, message, block/unblock contacts
5. Monitor — check conversations, broadcasts, error logs
6. Automate — trigger flows or sequences for a contact via messaging commands

CLI Commands

Config

chatbotx config set --apiKey <key> --apiUrl <url>

Workspace & Members

chatbotx workspaces get
chatbotx members list                                # [--page --perPage --sort --keyword]
chatbotx members get <memberId>
chatbotx channels list                               # [--includes --page --perPage]
chatbotx teams list

Tags

chatbotx tags list
chatbotx tags create --name <name>
chatbotx tags get <idOrName>                         # accepts id or name
chatbotx tags update <id> --name <name>
chatbotx tags delete <id>

Custom Fields

chatbotx custom-fields list
chatbotx custom-fields create --name <name> --type <type>
chatbotx custom-fields get <idOrName>                # accepts id or name
chatbotx custom-fields update <id> --name <name>     # [--description --folderId]
chatbotx custom-fields delete <id>

Bot Fields

chatbotx bot-fields list
chatbotx bot-fields create --name <name> --type <type> --value <value> --description <description>
chatbotx bot-fields update --fields <fields>         # set multiple values
chatbotx bot-fields get <idOrName>                   # accepts id or name
chatbotx bot-fields update <idOrName> --value <value> # set single value by id or name
chatbotx bot-fields delete <idOrName>

Contacts

# CRUD
chatbotx contacts list                               # [--page --perPage --sort --keyword ...]
chatbotx contacts create --phoneNumber <p> --email <e> --gender <g>  # [--firstName --lastName]
chatbotx contacts get <identifier>
chatbotx contacts upsert <identifier>                    # insert or update; [--firstName --lastName --email --phoneNumber --avatar --gender]
chatbotx contacts update <identifier>
chatbotx contacts delete <identifier>
chatbotx contacts find-by-custom-field               # [--customFieldId --value]
chatbotx contacts import --fileId <id> --channel <ch> --inboxId <id>

# Tags on a contact
chatbotx contacts tags list <identifier>
chatbotx contacts tag add <identifier> --tagIds <ids>
chatbotx contacts tag delete <identifier> --tagIds <ids>

# Custom fields on a contact
chatbotx contacts custom-fields list <identifier>
chatbotx contacts custom-fields update <identifier> --fields <fields>
chatbotx contacts custom-field get <identifier> <customFieldId>
chatbotx contacts custom-field add <identifier> <customFieldId> --value <value>
chatbotx contacts custom-field delete <identifier> <idOrName>

# Block / Unblock
chatbotx contacts block <identifier>
chatbotx contacts unblock <identifier>

# Messaging & Automation
chatbotx contacts messages list <identifier>          # [--perPage --cursor]
chatbotx contacts message get <identifier> <messageId>
chatbotx contacts message send <identifier>           # [--text --files --flowId --nodeId --inboxId]
chatbotx contacts flow add <identifier> --flowId <id> # [--inboxId]
chatbotx contacts auto-replies add <identifier> --keyword <kw>  # [--inboxId]

Conversations & Broadcasts

chatbotx conversations list                          # [--botCategory --assignedId --channel --status --keyword]
chatbotx broadcasts list
chatbotx broadcasts get <idOrName>                   # accepts id or name
chatbotx broadcasts audience get <idOrName>          # [--page --perPage]

Flows & Sequences

chatbotx flows list
chatbotx sequences list                              # [--page --perPage --sort]
chatbotx sequences get <id>

Other

chatbotx saved-replies list
chatbotx template-messages list                      # [--inboxId --integrationWhatsappId --status]
chatbotx ai-agents list
chatbotx integrations list
chatbotx keywords list
chatbotx triggers list
chatbotx webhooks list
chatbotx error-logs list                             # [--page --perPage --sort --keyword]

MCP Tools (for AI agents)

Tool names are the OpenAPI operationId converted to snake_case.

Tools are auto-generated from the OpenAPI spec — new API endpoints appear automatically on server restart.

Common Patterns

Tag a contact by name (not ID):

TAG_ID=$(chatbotx tags get "vip" --json | jq -r '.id')
chatbotx contacts tag add <identifier> --tagIds $TAG_ID

Send a flow to a contact:

FLOW_ID=$(chatbotx flows list --json | jq -r '.[] | select(.name=="Welcome") | .id')
chatbotx contacts flow add <identifier> --flowId $FLOW_ID

Set a custom field value on a contact:

FIELD_ID=$(chatbotx custom-fields get "plan" --json | jq -r '.id')
chatbotx contacts custom-field add <identifier> $FIELD_ID --value "premium"

Caching

The CLI caches the API spec at ~/.chatbotX/openapi-cache.json for 1 hour. Force refresh when new APIs are available:

chatbotx --refresh-spec <command>
# or
rm ~/.chatbotX/openapi-cache.json

Getting Help

chatbotx --help
chatbotx contacts --help
chatbotx contacts message --help
chatbotx contacts message send --help