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 add-tag require both a contactId and a tagId; fetch them with list commands before using them

Integration Modes:

• CLI (chatbotx-cli) — 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 \x3Cyour-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=\x3Cyour-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: \x3Cyour-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 \x3Ckey> --apiUrl \x3Curl>

Workspace & Members

chatbotx workspace list
chatbotx workspace-members list
chatbotx channels list
chatbotx inbox-teams list

Tags

chatbotx tags list
chatbotx tags create --name \x3Cname>
chatbotx tags show \x3Cid-or-name>
chatbotx tags update \x3Cid> --name \x3Cname>
chatbotx tags delete \x3Cid>

Custom Fields

chatbotx custom-fields list
chatbotx custom-fields create --name \x3Cname>
chatbotx custom-fields show \x3Cid-or-name>
chatbotx custom-fields update \x3Cid> --name \x3Cname>
chatbotx custom-fields delete \x3Cid>

Bot Fields

chatbotx bot-fields list
chatbotx bot-fields create
chatbotx bot-fields show \x3Cid-or-name>
chatbotx bot-fields update \x3Cid-or-name> --value \x3Cvalue>
chatbotx bot-fields delete \x3Cid-or-name>

Contacts

# CRUD
chatbotx contacts list
chatbotx contacts create --phoneNumber \x3Cphone> --email \x3Cemail>
chatbotx contacts show \x3CcontactId>
chatbotx contacts delete \x3CcontactId>
chatbotx contacts find-by-custom-field --customFieldId \x3Cid> --value \x3Cvalue>

# Tags on a contact
chatbotx contacts list-tags \x3CcontactId>
chatbotx contacts add-tag \x3CcontactId> \x3CtagId>
chatbotx contacts delete-tag \x3CcontactId> \x3CtagId>

# Custom fields on a contact
chatbotx contacts list-custom-fields \x3CcontactId>
chatbotx contacts update-custom-fields \x3CcontactId>
chatbotx contacts show-custom-field \x3CcontactId> \x3CcustomFieldId>
chatbotx contacts add-custom-field \x3CcontactId> \x3CcustomFieldId> --value \x3Cvalue>
chatbotx contacts delete-custom-field \x3CcontactId> \x3CcustomFieldId>

# Block / Unblock
chatbotx contacts add-block \x3CcontactId>
chatbotx contacts add-unblock \x3CcontactId>

# Messaging
chatbotx contacts add-message \x3CcontactId> --text \x3Cmessage>
chatbotx contacts add-message \x3CcontactId> --flowId \x3Cid> --nodeId \x3Cid>

Conversations & Broadcasts

chatbotx conversations create        # List conversations (with optional filters)
chatbotx broadcasts list

Flows & Sequences

chatbotx flows list
chatbotx sequences list
chatbotx sequences show \x3Cid>

Other

chatbotx saved-replies list
chatbotx whatsapp-message-templates list
chatbotx error-logs list

MCP Tools (for AI agents)

Tool names follow the pattern \x3Coperation>_workspace_token_api. Key tools:

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 show "vip" --json | jq -r '.id')
chatbotx contacts add-tag \x3CcontactId> $TAG_ID

Send a flow message to a contact:

FLOW_ID=$(chatbotx flows list --json | jq -r '.[] | select(.name=="Welcome") | .id')
chatbotx contacts add-message \x3CcontactId> --flowId $FLOW_ID --nodeId \x3CstartNodeId>

Set a custom field value on a contact:

FIELD_ID=$(chatbotx custom-fields show "plan" --json | jq -r '.id')
chatbotx contacts add-custom-field \x3CcontactId> $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 \x3Ccommand>
# or
rm ~/.chatbotX/openapi-cache.json

Getting Help

chatbotx --help
chatbotx contacts --help
chatbotx contacts add-message --help