ChatbotX is an open-source chat marketing platform for managing contacts, conversations, flows, broadcasts, and sequences across WhatsApp, Messenger, Instagram, TikTok, Telegram, Zalo OA, Email, and Webchat. An alternative to ManyChat, Chatfuel, Wati, Respond, etc...

Other

Install

openclaw skills install chatbotx

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:

Authenticate before executing any commands — every API call requires a workspace token
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 <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:

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

CLI Commands

Config

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

Workspace & Members

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

Custom Fields

chatbotx custom-fields list
chatbotx custom-fields create --name <name>
chatbotx custom-fields show <id-or-name>
chatbotx custom-fields update <id> --name <name>
chatbotx custom-fields delete <id>

Bot Fields

chatbotx bot-fields list
chatbotx bot-fields create
chatbotx bot-fields show <id-or-name>
chatbotx bot-fields update <id-or-name> --value <value>
chatbotx bot-fields delete <id-or-name>

Contacts

# CRUD
chatbotx contacts list
chatbotx contacts create --phoneNumber <phone> --email <email>
chatbotx contacts show <contactId>
chatbotx contacts delete <contactId>
chatbotx contacts find-by-custom-field --customFieldId <id> --value <value>

# Tags on a contact
chatbotx contacts list-tags <contactId>
chatbotx contacts add-tag <contactId> <tagId>
chatbotx contacts delete-tag <contactId> <tagId>

# Custom fields on a contact
chatbotx contacts list-custom-fields <contactId>
chatbotx contacts update-custom-fields <contactId>
chatbotx contacts show-custom-field <contactId> <customFieldId>
chatbotx contacts add-custom-field <contactId> <customFieldId> --value <value>
chatbotx contacts delete-custom-field <contactId> <customFieldId>

# Block / Unblock
chatbotx contacts add-block <contactId>
chatbotx contacts add-unblock <contactId>

# Messaging
chatbotx contacts add-message <contactId> --text <message>
chatbotx contacts add-message <contactId> --flowId <id> --nodeId <id>

Conversations & Broadcasts

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

Flows & Sequences

chatbotx flows list
chatbotx sequences list
chatbotx sequences show <id>

Other

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

MCP Tools (for AI agents)

Tool names follow the pattern <operation>_workspace_token_api. Key tools:

Category	Tool
Workspace	`get_workspace_workspace_token_api`
Channels	`list_inboxes_workspace_token_api`
Tags	`list_tags_workspace_token_api`, `create_tag_workspace_token_api`, `find_tag_workspace_token_api`, `update_tag_workspace_token_api`, `delete_tags_workspace_token_api`
Contacts	`list_contacts_workspace_token_api`, `create_contact_workspace_token_api`, `find_contact_workspace_token_api`, `send_message_workspace_token_api`, `block_contact_workspace_token_api`
Conversations	`list_conversations_workspace_token_api`
Broadcasts	`list_broadcasts_workspace_token_api`
Flows	`list_flows_workspace_token_api`
Sequences	`list_sequences_workspace_token_api`, `get_sequence_workspace_token_api`

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 <contactId> $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 <contactId> --flowId $FLOW_ID --nodeId <startNodeId>

Set a custom field value on a contact:

FIELD_ID=$(chatbotx custom-fields show "plan" --json | jq -r '.id')
chatbotx contacts add-custom-field <contactId> $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 add-message --help