Global Options
| Option | When to Use It |
|---|---|
--apiKey | Override the Workspace API key for a single command |
--apiUrl | Override the base API URL for a single command |
--allowSelfSignedCert | Allow secure TLS connection to a self-hosted server with a self-signed certificate |
--refresh-spec | Force re-fetch the OpenAPI specification (clears cached CLI command definitions) |
--json | Return raw JSON output instead of formatted text (ideal for shell scripts and jq) |
Contact Identifiers
For any command in thecontacts group, the <identifier> parameter supports three lookup formats. Always specify the prefix so the CLI resolves the exact Contact record:
| Format | Example | Lookup By |
|---|---|---|
id:<value> | id:123456789 | Internal Contact ID |
email:<value> | email:user@example.com | Email address |
phone:<value> | phone:+84708123123 | International phone number |
Examples
# Get contact by email
chatbotx contacts get email:user@example.com
# Get contact by phone
chatbotx contacts get phone:+84708123123
# Get contact by internal ID
chatbotx contacts get id:123456789
Command Groups Overview
| Group | Common Commands | Use It For |
|---|---|---|
| Workspace & Team | workspaces get, members list, inboxes list, teams list | Manage workspace settings, collaborators, connected inboxes, and teams |
| Tags | tags list, tags create, tags update, tags delete | Manage contact audience labels |
| Custom Fields | custom-fields list, custom-fields create, custom-fields delete | Manage contact attribute schemas |
| Bot Fields | bot-fields list, bot-fields create, bot-fields update, bot-fields delete | Manage global workspace variables |
| Contacts | contacts list, contacts get, contacts upsert, contacts import | Find, create, update, import, and block contacts |
| Contact Actions | contacts tag add, contacts message send, contacts flow add | Execute direct operations on a specific contact |
| Conversations | conversations list, conversations get, conversations assign | Manage live chat inbox threads and agent assignments |
| Broadcasts | broadcasts list, broadcasts create, broadcasts stop, broadcasts duplicate | Create and monitor mass outbound messaging campaigns |
| Flows | flows list, flows get, flows create, flows update-draft, flows publish | Build, validate, and publish automation flow drafts |
| Sequences | sequences list, sequences get, sequences create, sequences update | Manage drip campaigns and delayed messaging steps |
| AI Agents & MCP | ai-agents list, ai-files list, ai-functions list, ai-mcp-servers list | Configure autonomous AI agents, knowledge files, tools, and external MCP servers |
| Automation Triggers | keywords list, triggers list, webhooks list | Manage incoming keyword triggers, event triggers, and webhooks |
| Analytics & Logs | analytics contact-counts-per-day, analytics flow-stats, error-logs list | Monitor performance metrics and runtime execution error logs |
Workspace, Members, Inboxes, and Teams
# Workspace info
chatbotx workspaces get
# Workspace members
chatbotx members list # [--page --perPage --sort --keyword]
chatbotx members get <memberId>
# Connected inboxes (returns internal id and platform sourceId)
chatbotx inboxes list # [--page --perPage]
# Inbox teams
chatbotx teams list
Tags
chatbotx tags list
chatbotx tags create --name <name>
chatbotx tags get <idOrName>
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>
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 get <idOrName>
chatbotx bot-fields update <idOrName> --value <value>
chatbotx bot-fields delete <idOrName>
Contacts
# List contacts with advanced filters
chatbotx contacts list # [--page --perPage --sort --keyword --includes]
chatbotx contacts create --phoneNumber <phoneNumber> --email <email> --gender <gender>
chatbotx contacts get <identifier>
chatbotx contacts upsert <identifier> # [--firstName --lastName --email --phoneNumber --avatar --gender]
chatbotx contacts update <identifier>
chatbotx contacts delete <identifier>
chatbotx contacts import --fileId <fileId> --channel <channel> --inboxId <inboxId>
Contact Tags
chatbotx contacts tags list <identifier>
chatbotx contacts tag add <identifier> --tagIds <tagIds>
chatbotx contacts tag delete <identifier> --tagIds <tagIds>
Contact Custom Fields
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>
Contact Actions
chatbotx contacts block <identifier>
chatbotx contacts unblock <identifier>
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 <flowId> # [--inboxId]
Conversations
chatbotx conversations list # [--botCategory --assignedId --channel --status --keyword ...]
chatbotx conversations get <conversationId>
chatbotx conversations assign <conversationId> --userId <userId> --teamId <teamId>
Broadcasts
chatbotx broadcasts list # [--page --perPage --status]
chatbotx broadcasts get <id>
chatbotx broadcasts create --name <name> --flowId <flowId> --channel <channel>
chatbotx broadcasts stop <id>
chatbotx broadcasts duplicate <id>
chatbotx broadcasts delete <id>
chatbotx broadcasts audience get <id> # [--page --perPage]
Flows
chatbotx flows list # [--page --perPage --keyword]
chatbotx flows get <flowId>
chatbotx flows create --name <name> # [--spec <specJson> --publish <boolean>]
chatbotx flows update-draft <flowId> # [--spec <specJson> --nodes <nodesJson>]
chatbotx flows publish <flowId>
chatbotx flows validate --spec <specJson>
chatbotx flows delete <flowId>
Sequences
chatbotx sequences list # [--page --perPage --sort]
chatbotx sequences get <sequenceId>
chatbotx sequences create --name <name>
chatbotx sequences update <sequenceId> # [--name --active]
chatbotx sequences delete <sequenceId>
AI Agents, Files, Functions, and MCP Servers
# AI Agents
chatbotx ai-agents list
chatbotx ai-agents get <agentId>
chatbotx ai-agents create --name <name> --model <model> --prompt <prompt>
chatbotx ai-agents update <agentId>
chatbotx ai-agents delete <agentId>
# Knowledge Files
chatbotx ai-files list
chatbotx ai-files create --name <name> --url <fileUrl>
chatbotx ai-files delete <fileId>
# Custom AI Functions
chatbotx ai-functions list
chatbotx ai-functions create --name <name> --description <desc> --parameters <schema>
chatbotx ai-functions delete <functionId>
# External AI MCP Servers
chatbotx ai-mcp-servers list
chatbotx ai-mcp-servers create --name <name> --url <serverUrl> --transport <transport>
chatbotx ai-mcp-servers delete <serverId>
Automation Triggers & Integrations
# Keywords
chatbotx keywords list
chatbotx keywords create --keyword <keyword> --flowId <flowId>
chatbotx keywords delete <keywordId>
# Triggers
chatbotx triggers list
chatbotx triggers create --type <triggerType> --flowId <flowId>
chatbotx triggers delete <triggerId>
# Webhooks
chatbotx webhooks list
chatbotx webhooks create --url <targetUrl> --events <events>
chatbotx webhooks delete <webhookId>
# WhatsApp Templates
chatbotx whatsapp templates # [--inboxId --integrationWhatsappId --status]
# Saved Replies
chatbotx saved-replies list
chatbotx saved-replies create --shortcut <shortcut> --text <text>
Analytics & Error Logs
# Analytics reports (supports --from --to --timezone)
chatbotx analytics contact-counts-per-day
chatbotx analytics blocked-contacts-per-day
chatbotx analytics flow-stats --flowId <flowId>
chatbotx analytics broadcast-stats --broadcastId <broadcastId>
chatbotx analytics sequence-step-stats --sequenceId <sequenceId>
# System error logs
chatbotx error-logs list # [--page --perPage --sort --keyword]