Best Practices & Troubleshooting

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:

List resources to retrieve IDs

Find target IDs by running lookup commands, for example:

chatbotx tags list

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

Perform the action

Execute the command using the retrieved IDs:

chatbotx contacts tag add email:user@example.com --tagIds <tagId>

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

Issue	Common Cause	Fix
`401` or `403`	Token is incorrect, expired, or missing permissions.	Create a new Workspace token and update configuration. See Authentication
CLI does not show a new command	OpenAPI spec cache is stale.	Run the command with `--refresh-spec` option.
TLS certificate error	Self-hosted server uses a self-signed certificate.	Enable `--allowSelfSignedCert` or `CHATBOTX_ALLOW_SELF_SIGNED_CERT=true`. See Authentication
Contact not found	Identifier format is incorrect.	Use explicit prefix: `id:<value>`, `email:<value>`, or `phone:<value>`.

References

ChatbotX CLI on npm: Official npm package details.

Getting Started

Usage & Reference

Safe Operating Workflows

Testing Actions Safely

Common Automation Examples

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

2. Send a specific Flow to a contact

3. Set a Custom Field value on a contact

4. Send a message and verify history

CLI Help and Cache Management

Common Issues

References

​Safe Operating Workflows

​Testing Actions Safely

​Common Automation Examples

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

​2. Send a specific Flow to a contact

​3. Set a Custom Field value on a contact

​4. Send a message and verify history

​CLI Help and Cache Management

​Common Issues

​References

Safe Operating Workflows

Testing Actions Safely

Common Automation Examples

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

2. Send a specific Flow to a contact

3. Set a Custom Field value on a contact

4. Send a message and verify history

CLI Help and Cache Management

Common Issues

References