Channel Talk Bot (Beta)

Beta: Channel Talk Bot support is in beta. Some features may change.

Tip: agent-channeltalkbot is a shortcut for agent-messenger channeltalkbot.

Quick Start

# 1. Set your API credentials
agent-channeltalkbot auth set your-access-key your-access-secret

# 2. Verify authentication
agent-channeltalkbot auth status

# 3. Get a workspace overview
agent-channeltalkbot snapshot --pretty

# 4. Send a message
agent-channeltalkbot message send @support "Hello from the bot!"

Key Concepts

Channel Talk has different terminology from Slack or Discord:

Channel Talk Term	Equivalent In	Description
Channel	Workspace (Slack)	Your entire workspace
UserChat	DM with a customer	1:1 conversations with end users
Group	Channel (Slack)	Team inbox channels (use `@name`)
Manager	Member/Agent	Human agents on your team
Bot	Bot	Automated agents that send messages

Authentication

API Credential Setup

agent-channeltalkbot uses Access Key + Access Secret pairs from Channel Talk's developer settings:

# Set credentials (validates against Channel Talk API before saving)
agent-channeltalkbot auth set your-access-key your-access-secret

# Check auth status
agent-channeltalkbot auth status

# Clear stored credentials
agent-channeltalkbot auth clear

How to Get API Credentials

Log in to Channel Talk
Go to Settings > Developers > Open API
Create or copy your Access Key and Access Secret
Run agent-channeltalkbot auth set <access-key> <access-secret>

Multi-Workspace Support

# List stored workspaces
agent-channeltalkbot auth list

# Switch active workspace
agent-channeltalkbot auth use <workspace-id>

# Remove a stored workspace
agent-channeltalkbot auth remove <workspace-id>

Default Bot

Set a default bot name for sending messages and closing chats:

# Set default bot name
agent-channeltalkbot auth bot "Support Bot"

Authentication Commands

# Set workspace credentials (validates against API)
agent-channeltalkbot auth set <access-key> <access-secret>

# Check auth status
agent-channeltalkbot auth status

# Clear all credentials
agent-channeltalkbot auth clear

# List stored workspaces
agent-channeltalkbot auth list

# Switch active workspace
agent-channeltalkbot auth use <workspace-id>

# Remove a stored workspace
agent-channeltalkbot auth remove <workspace-id>

# Set default bot name for sending messages
agent-channeltalkbot auth bot <name>

Commands

Message Commands

# Send a message to a UserChat or Group
agent-channeltalkbot message send <target> <text>
agent-channeltalkbot message send abc123-chat-id "Hello!"
agent-channeltalkbot message send @support "Team update"

# List messages from a UserChat or Group
agent-channeltalkbot message list <target>
agent-channeltalkbot message list abc123-chat-id --limit 50

# Get a specific message by ID
agent-channeltalkbot message get <target> <message-id>

Target auto-detection: if the target starts with @, it's treated as a group. Otherwise, it's treated as a UserChat. You can override with --type userchat or --type group.

Chat Commands (UserChats)

# List UserChats (default: opened)
agent-channeltalkbot chat list
agent-channeltalkbot chat list --state opened
agent-channeltalkbot chat list --state snoozed
agent-channeltalkbot chat list --state closed

# Get a specific UserChat
agent-channeltalkbot chat get <chat-id>

# Close a UserChat (requires --bot or default bot)
agent-channeltalkbot chat close <chat-id>
agent-channeltalkbot chat close <chat-id> --bot "Support Bot"

# Delete a UserChat (requires --force)
agent-channeltalkbot chat delete <chat-id> --force

Group Commands

# List groups
agent-channeltalkbot group list

# Get a group by ID or @name
agent-channeltalkbot group get <group>
agent-channeltalkbot group get @support

# Get messages from a group
agent-channeltalkbot group messages <group>
agent-channeltalkbot group messages @support --limit 50

Manager Commands

# List all managers
agent-channeltalkbot manager list

# Get a specific manager
agent-channeltalkbot manager get <manager-id>

Bot Commands

# List all bots
agent-channeltalkbot bot list

# Create a new bot
agent-channeltalkbot bot create <name>
agent-channeltalkbot bot create "Deploy Bot" --color "#FF5733" --avatar-url "https://example.com/avatar.png"

# Delete a bot (requires --force)
agent-channeltalkbot bot delete <bot-id> --force

Snapshot Command

Get comprehensive workspace state for AI agents:

# Full snapshot of current workspace
agent-channeltalkbot snapshot

# Filtered snapshots
agent-channeltalkbot snapshot --groups-only
agent-channeltalkbot snapshot --chats-only

# Limit messages per group/chat
agent-channeltalkbot snapshot --limit 10

Returns JSON with:

Workspace metadata (id, name, homepage_url, description)
Groups with recent messages (id, name, messages)
UserChat summary (opened/snoozed/closed counts, recent opened with last message)
Managers (id, name, description)
Bots (id, name)

Global Options

All commands support these options:

--pretty              # Pretty-print JSON output (default is compact JSON)
--workspace <id>      # Use a specific workspace for this command
--bot <name>          # Use a specific bot name for this command

Troubleshooting

`agent-channeltalkbot: command not found`

agent-channeltalkbot is NOT the npm package name. The npm package is agent-messenger.

# If installed globally
agent-channeltalkbot message send abc123-chat-id "Hello"

# If not installed, use npx
npx -y agent-messenger channeltalkbot message send abc123-chat-id "Hello"

Some operations (closing chats, sending messages) require a bot name. Set a default with auth bot <name> or pass --bot <name> per command. The bot must exist in your workspace. Use bot list to see available bots.

Rate limiting

Channel Talk enforces rate limits on API calls. The CLI automatically retries on rate limit (429) responses using the Retry-After header. For bulk operations, add delays between requests.

Limitations

No real-time events / WebSocket connection
No file upload support
No message editing or deletion (Channel Talk API limitation)
No webhook support
No message search
No reactions support
No thread support
Plain text messages only (no rich blocks)
Bot name must exist in the workspace for sending messages

AI Agent Integration

See skills/agent-channeltalkbot/ for:

Complete skill documentation
Common patterns for AI agent workflows