Skip to main content
Optimize your command line operations by following safety best practices and resolving common CLI errors.

​
Safe Operating Workflows

Some CLI commands require internal IDs (e.g., contactId, tagId, flowId, customFieldId, or inboxId). Find and verify these IDs before executing commands that modify data:
1

List resources to retrieve IDs

Find target IDs by running lookup commands, for example:
chatbotx tags list
2

Verify target Contact

Inspect the contact details by email or phone number to confirm you have the correct record:
chatbotx contacts get email:user@example.com
3

Perform the action

Execute the command using the retrieved IDs:
chatbotx contacts tag add email:user@example.com --tagIds <tagId>
4

Confirm results

Verify the changes were applied successfully:
chatbotx contacts tags list email:user@example.com

​
Testing Actions Safely

For commands that send messages, trigger Flows, or update bulk records, always run the command on a test Contact first: 
# 1. Retrieve the test contact
chatbotx contacts get email:test@example.com

# 2. Send a test message
chatbotx contacts message send email:test@example.com --text "Test message"

# 3. Check message history to confirm
chatbotx contacts messages list email:test@example.com

​
Common Automation Examples

Combine the CLI’s --json option and jq to automate common workflows in shell scripts:

​
1. Tag a contact by tag name (resolving ID dynamically)

Find the ID of a tag by its name, then apply it to a contact: 
# Fetch the ID of the tag named "VIP"
TAG_ID=$(chatbotx tags get "VIP" --json | jq -r '.id')

# Add the tag to the contact by email
chatbotx contacts tag add email:user@example.com --tagIds $TAG_ID

​
2. Send a specific Flow to a contact

Find the ID of a flow by its name, then trigger it for a contact: 
# Find the ID of the flow named "Welcome Flow"
FLOW_ID=$(chatbotx flows list --json | jq -r '.[] | select(.name=="Welcome Flow") | .id')

# Trigger the flow for the contact by phone number
chatbotx contacts flow add phone:+84708123123 --flowId $FLOW_ID

​
3. Set a Custom Field value on a contact

Find the ID of a custom field, then update its value for a contact: 
# Find the ID of the custom field named "plan"
FIELD_ID=$(chatbotx custom-fields get "plan" --json | jq -r '.id')

# Set the custom field value to "premium"
chatbotx contacts custom-field add email:user@example.com $FIELD_ID --value "premium"

​
4. Send a message and verify history

Send a direct message and inspect history to confirm delivery: 
# Send a text message to a contact
chatbotx contacts message send email:user@example.com --text "Hello from ChatbotX CLI!"

# List recent messages for this contact to verify
chatbotx contacts messages list email:user@example.com --perPage 5

​
CLI Help and Cache Management

The CLI caches the OpenAPI spec at ~/.chatbotX/openapi-cache.json for 1 hour. If your self-hosted system recently added new APIs, force the CLI to refresh the spec: 
chatbotx --refresh-spec <command>
# or delete the cache manually
rm ~/.chatbotX/openapi-cache.json
Use --help at any group or sub-command level to inspect syntax: 
chatbotx --help
chatbotx contacts --help
chatbotx contacts message --help
chatbotx contacts message send --help

​
Common Issues

IssueCommon CauseFix
401 or 403Token is incorrect, expired, or missing permissions.Create a new Workspace token and update configuration. See Authentication
CLI does not show a new commandOpenAPI spec cache is stale.Run the command with --refresh-spec option.
TLS certificate errorSelf-hosted server uses a self-signed certificate.Enable --allowSelfSignedCert or CHATBOTX_ALLOW_SELF_SIGNED_CERT=true. See Authentication
Contact not foundIdentifier format is incorrect.Use explicit prefix: id:<value>, email:<value>, or phone:<value>.

​
References