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...

SKILL.md

---
name: chatbotx
description: 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...
version: 0.1.0
emoji: 🤖
homepage: https://github.com/ChatbotXIO/ChatbotX
metadata:
  openclaw:
    primaryEnv: CHATBOTX_API_KEY
    requires:
      env:
        - CHATBOTX_API_KEY
        - CHATBOTX_API_URL
    envVars:
      - name: CHATBOTX_API_KEY
        description: Workspace API token (Settings → Developer → API Keys)
        required: true
      - name: CHATBOTX_API_URL
        description: Base URL of your ChatbotX instance, e.g. https://app.chatbotx.io/api
        required: true
      - name: CHATBOTX_ALLOW_SELF_SIGNED_CERT
        description: Set to true to disable TLS verification for self-hosted instances
        required: false
    os:
      - macos
      - linux
      - windows
---

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

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

Or via environment variables (no config file needed):

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

For local instances with self-signed certificates:

```bash
export CHATBOTX_ALLOW_SELF_SIGNED_CERT=true
```

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

### MCP Server (stdio — recommended for local use)

```bash
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)

```bash
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

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

### Workspace & Members

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

### Tags

```bash
chatbotx tags list
chatbotx tags create --name <name>
chatbotx tags show <id-or-name>
chatbotx tags update <id> --name <name>
chatbotx tags delete <id>
```

### Custom Fields

```bash
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

```bash
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

```bash
# 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

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

### Flows & Sequences

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

### Other

```bash
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):**
```bash
TAG_ID=$(chatbotx tags show "vip" --json | jq -r '.id')
chatbotx contacts add-tag <contactId> $TAG_ID
```

**Send a flow message to a contact:**
```bash
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:**
```bash
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:

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

---

## Getting Help

```bash
chatbotx --help
chatbotx contacts --help
chatbotx contacts add-message --help
```