agent-channeltalkbot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent ChannelTalkBot

A TypeScript CLI tool that enables AI agents and humans to interact with Channel Talk workspaces using API credentials (Access Key + Access Secret). Designed for customer support automation, team inbox management, and CI/CD integrations.

一款TypeScript CLI工具，支持AI Agent和人类使用API凭证（Access Key + Access Secret）与Channel Talk工作区交互。适用于客户支持自动化、团队收件箱管理以及CI/CD集成场景。

Key Concepts

核心概念

Before diving in, a few things about Channel Talk's terminology:

Channel = workspace (not a chat channel like Slack). The API calls it a "channel," but it means your entire workspace.
UserChats = 1:1 conversations with end users (customers).
Groups = team inbox channels (similar to Slack channels). Referenced by ID or
```
@name
```
.
Managers = human agents on your team.
Bots = automated agents that can send messages and close chats.
Messages use a
```
blocks
```
format:
```
[{ type: "text", value: "..." }]
```
. The CLI handles this automatically when you pass plain text.

在开始之前，先了解Channel Talk的几个术语：

Channel = 工作区（并非Slack那样的聊天频道）。API中称为“channel”，但实际指整个工作区。
UserChats = 与终端用户（客户）的一对一对话。
Groups = 团队收件箱频道（类似Slack频道）。通过ID或
```
@name
```
引用。
Managers = 团队中的人工客服。
Bots = 可发送消息和关闭对话的自动化Agent。
Messages 使用
```
blocks
```
格式：
```
[{ type: "text", value: "..." }]
```
。当你传入纯文本时，CLI会自动处理该格式。

Quick Start

快速开始

bash

undefined

bash

undefined

Set your API credentials

设置API凭证

agent-channeltalkbot auth set your-access-key your-access-secret

Verify authentication

验证身份

agent-channeltalkbot auth status

Get a workspace overview

获取工作区概览

agent-channeltalkbot snapshot --pretty

Send a message to a UserChat

向UserChat发送消息

agent-channeltalkbot message send abc123-chat-id "Hello from the CLI!"

Send a message to a Group

向群组发送消息

agent-channeltalkbot message send @support "Team update: deployment complete"

undefined

agent-channeltalkbot message send @support "Team update: deployment complete"

undefined

Authentication

身份验证

API Credential Setup

API凭证设置

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

bash

undefined

agent-channeltalkbot 使用Channel Talk开发者设置中的Access Key + Access Secret密钥对：

bash

undefined

Set credentials (validates against Channel Talk API before saving)

设置凭证（保存前会验证Channel Talk API）

agent-channeltalkbot auth set your-access-key your-access-secret

Check auth status

检查身份验证状态

agent-channeltalkbot auth status

Clear stored credentials

清除存储的凭证

agent-channeltalkbot auth clear


For credential setup, multi-workspace management, and security details, see [references/authentication.md](references/authentication.md).

agent-channeltalkbot auth clear


关于凭证设置、多工作区管理和安全细节，请查看[references/authentication.md](references/authentication.md)。

Memory

记忆功能

The agent maintains a

~/.config/agent-messenger/MEMORY.md

file as persistent memory across sessions. This is agent-managed, the CLI does not read or write this file. Use the

Read

and

Write

tools to manage your memory file.

该Agent会维护一个

~/.config/agent-messenger/MEMORY.md

文件，作为跨会话的持久化存储。此文件由Agent管理，CLI不会读取或写入它。使用

Read

和

Write

工具管理你的记忆文件。

Reading Memory

读取记忆

At the start of every task, read

~/.config/agent-messenger/MEMORY.md

using the

Read

tool to load any previously discovered workspace IDs, group IDs, chat IDs, manager IDs, bot names, and preferences.

If the file doesn't exist yet, that's fine. Proceed without it and create it when you first have useful information to store.
If the file can't be read (permissions, missing directory), proceed without memory. Don't error out.

在每个任务开始时，使用

Read

工具读取

~/.config/agent-messenger/MEMORY.md

，加载之前保存的工作区ID、群组ID、对话ID、客服ID、机器人名称和偏好设置。

如果文件尚未存在，无需担心。继续执行任务，当有有用信息时再创建它。
如果无法读取文件（权限问题、目录缺失），无需报错，继续无记忆执行任务。

Writing Memory

写入记忆

After discovering useful information, update

~/.config/agent-messenger/MEMORY.md

using the

Write

tool. Write triggers include:

After discovering workspace IDs and names (from
```
auth list
```
,
```
snapshot
```
, etc.)
After discovering group IDs and names (from
```
group list
```
,
```
snapshot
```
, etc.)
After discovering chat IDs (from
```
chat list
```
, etc.)
After discovering manager IDs and names (from
```
manager list
```
, etc.)
After discovering bot names (from
```
bot list
```
, etc.)
After the user gives you an alias or preference ("call this the support workspace", "my main group is X")
After setting a default bot name (from
```
auth bot
```
)

When writing, include the complete file content. The

Write

tool overwrites the entire file.

在发现有用信息后，使用

Write

工具更新

~/.config/agent-messenger/MEMORY.md

。触发写入的场景包括：

发现工作区ID和名称后（来自
```
auth list
```
、
```
snapshot
```
等命令）
发现群组ID和名称后（来自
```
group list
```
、
```
snapshot
```
等命令）
发现对话ID后（来自
```
chat list
```
等命令）
发现客服ID和名称后（来自
```
manager list
```
等命令）
发现机器人名称后（来自
```
bot list
```
等命令）
用户提供别名或偏好设置后（如“将此称为支持工作区”、“我的主要群组是X”）
设置默认机器人名称后（来自
```
auth bot
```
命令）

写入时需包含完整文件内容。

Write

工具会覆盖整个文件。

What to Store

存储内容

Workspace IDs with names
Group IDs with names (and
```
@name
```
aliases)
UserChat IDs with context
Manager IDs with names
Bot names and their purposes
Default bot name per workspace
User-given aliases ("support workspace", "billing group")
Any user preference expressed during interaction

带名称的工作区ID
带名称的群组ID（以及
```
@name
```
别名）
带上下文的UserChat ID
带名称的客服ID
机器人名称及其用途
每个工作区的默认机器人名称
用户指定的别名（如“支持工作区”、“账单群组”）
交互过程中用户表达的任何偏好

What NOT to Store

禁止存储内容

Never store access keys, access secrets, or any credentials. Never store full message content (just IDs and context). Never store personal user data.

切勿存储Access Key、Access Secret或任何凭证。切勿存储完整消息内容（仅存储ID和上下文）。切勿存储用户个人数据。

Handling Stale Data

处理过期数据

If a memorized ID returns an error (chat not found, group not found), remove it from

MEMORY.md

. Don't blindly trust memorized data. Verify when something seems off. Prefer re-listing over using a memorized ID that might be stale.

如果记忆中的ID返回错误（对话未找到、群组未找到），请从

MEMORY.md

中删除该ID。不要盲目信任记忆中的数据。当出现异常时进行验证。优先重新列出数据，而非使用可能过期的记忆ID。

Format / Example

格式示例

markdown

undefined

markdown

undefined

Agent Messenger Memory

Channel Talk Workspaces

```
abc123
```
- Acme Support

```
abc123
```
- Acme Support

Default Bot (Acme Support)

Support Bot

Support Bot

Groups (Acme Support)

```
grp_111
```
- @support (Support Inbox)
```
grp_222
```
- @billing (Billing Inbox)
```
grp_333
```
- @engineering (Engineering)

```
grp_111
```
- @support (Support Inbox)
```
grp_222
```
- @billing (Billing Inbox)
```
grp_333
```
- @engineering (Engineering)

Recent UserChats (Acme Support)

```
uc_aaa
```
- John Doe inquiry (opened)
```
uc_bbb
```
- Refund request (closed)

```
uc_aaa
```
- John Doe inquiry (opened)
```
uc_bbb
```
- Refund request (closed)

Managers (Acme Support)

```
mgr_001
```
- Alice (Team Lead)
```
mgr_002
```
- Bob (Support Agent)

```
mgr_001
```
- Alice (Team Lead)
```
mgr_002
```
- Bob (Support Agent)

Bots (Acme Support)

Support Bot (default, used for auto-replies)
Notification Bot (used for alerts)

Support Bot (default, used for auto-replies)
Notification Bot (used for alerts)

Aliases

"support" ->
```
grp_111
```
(@support in Acme Support)

"support" ->
```
grp_111
```
(@support in Acme Support)

Notes

Support Bot is used for closing chats and auto-replies
Notification Bot is used for CI/CD alerts to @engineering


> Memory lets you skip repeated `group list` and `chat list` calls. When you already know an ID from a previous session, use it directly.

Support Bot is used for closing chats and auto-replies
Notification Bot is used for CI/CD alerts to @engineering


> 记忆功能可让你跳过重复的`group list`和`chat list`调用。当你从之前的会话中已知道某个ID时，可直接使用它。

Commands

命令

Auth Commands

身份验证命令

bash

undefined

bash

undefined

Set workspace credentials (validates against API)

设置工作区凭证（会验证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>

undefined

agent-channeltalkbot auth bot <name>

undefined

Whoami Command

Whoami命令

bash

undefined

bash

undefined

Show current authenticated bot

显示当前已验证的机器人

agent-channeltalkbot whoami agent-channeltalkbot whoami --pretty agent-channeltalkbot whoami --workspace <workspace-id>

undefined

agent-channeltalkbot whoami agent-channeltalkbot whoami --pretty agent-channeltalkbot whoami --workspace <workspace-id>

undefined

Message Commands

消息命令

bash

undefined

bash

undefined

Send a message to a UserChat or Group

向UserChat或群组发送消息

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

列出UserChat或群组中的消息

agent-channeltalkbot message list <target> agent-channeltalkbot message list abc123-chat-id --limit 50

Get a specific message by ID

通过ID获取特定消息

Note: Searches the latest 100 messages. Older messages may not be found.

注意：仅搜索最新的100条消息。可能无法找到更早的消息。

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

agent-channeltalkbot message get <target> <message-id>


目标自动检测：如果目标以`@`开头，则视为群组；否则视为UserChat。你可以使用`--type userchat`或`--type group`覆盖默认检测。

Chat Commands (UserChats)

对话命令（UserChats）

bash

undefined

bash

undefined

List UserChats (default: opened)

列出UserChat（默认：已打开）

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

获取特定UserChat

agent-channeltalkbot chat get <chat-id>

Close a UserChat (requires --bot or default bot)

关闭UserChat（需要--bot参数或默认机器人）

agent-channeltalkbot chat close <chat-id> agent-channeltalkbot chat close <chat-id> --bot "Support Bot"

Delete a UserChat (requires --force)

删除UserChat（需要--force参数）

agent-channeltalkbot chat delete <chat-id> --force

undefined

agent-channeltalkbot chat delete <chat-id> --force

undefined

Group Commands

群组命令

bash

undefined

bash

undefined

List groups

列出群组

agent-channeltalkbot group list

Get a group by ID or @name

通过ID或@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

undefined

agent-channeltalkbot group messages <group> agent-channeltalkbot group messages @support --limit 50

undefined

Manager Commands

客服命令

bash

undefined

bash

undefined

List all managers

列出所有客服

agent-channeltalkbot manager list

Get a specific manager

获取特定客服

agent-channeltalkbot manager get <manager-id>

undefined

agent-channeltalkbot manager get <manager-id>

undefined

Bot Commands

机器人命令

bash

undefined

bash

undefined

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)

删除机器人（需要--force参数）

agent-channeltalkbot bot delete <bot-id> --force

undefined

agent-channeltalkbot bot delete <bot-id> --force

undefined

Snapshot Command

快照命令

Get workspace overview for AI agents (brief by default):

bash

undefined

为AI Agent获取工作区概览（默认简要版）：

bash

undefined

Brief snapshot (default) — fast, minimal API calls

简要快照（默认）——快速，API调用最少

agent-channeltalkbot snapshot

Full snapshot — includes messages, managers, bots (slow, large output)

完整快照——包含消息、客服、机器人（较慢，输出内容大）

agent-channeltalkbot snapshot --full

Filtered full snapshots

筛选后的完整快照

agent-channeltalkbot snapshot --full --groups-only agent-channeltalkbot snapshot --full --chats-only

Limit messages per group/chat (only with --full)

限制每个群组/对话的消息数量（仅适用于--full参数）

agent-channeltalkbot snapshot --full --limit 10


Default returns brief JSON with:

- Workspace metadata (id, name, homepage_url, description)
- Groups (id, name)
- UserChat summary (opened/snoozed/closed counts)
- Hint for next commands

With `--full`, returns comprehensive 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)

agent-channeltalkbot snapshot --full --limit 10


默认返回包含以下内容的简要JSON：

- 工作区元数据（id、名称、homepage_url、描述）
- 群组（id、名称）
- UserChat摘要（已打开/已 snooze/已关闭的数量）
- 后续命令提示

使用`--full`参数时，返回包含以下内容的完整JSON：

- 工作区元数据（id、名称、homepage_url、描述）
- 带最近消息的群组（id、名称、消息）
- UserChat摘要（已打开/已 snooze/已关闭的数量，最近已打开对话及最后一条消息）
- 客服（id、名称、描述）
- 机器人（id、名称）

Output Format

输出格式

JSON (Default)

JSON（默认）

All commands output JSON by default for AI consumption:

json

{
  "id": "msg_abc123",
  "chat_id": "uc_def456",
  "person_type": "bot",
  "plain_text": "Hello world",
  "created_at": 1705312200000
}

所有命令默认输出JSON格式，供AI使用：

json

{
  "id": "msg_abc123",
  "chat_id": "uc_def456",
  "person_type": "bot",
  "plain_text": "Hello world",
  "created_at": 1705312200000
}

Pretty (Human-Readable)

美观格式（人类可读）

Use

--pretty

flag for formatted output:

bash

agent-channeltalkbot group list --pretty

使用

--pretty

参数获取格式化输出：

bash

agent-channeltalkbot group list --pretty

Global Options

全局选项

Option	Description
`--pretty`	Human-readable output instead of JSON
`--workspace <id>`	Use a specific workspace for this command
`--bot <name>`	Use a specific bot name for this command

选项	描述
`--pretty`	输出人类可读格式而非JSON
`--workspace <id>`	为此命令使用特定工作区
`--bot <name>`	为此命令使用特定机器人名称

Common Patterns

常见模式

See

references/common-patterns.md

for typical AI agent workflows.

典型AI Agent工作流请查看

references/common-patterns.md

。

Templates

模板

See

templates/

directory for runnable examples:

```
post-message.sh
```
- Send messages with error handling
```
monitor-chat.sh
```
- Poll for new UserChats
```
workspace-summary.sh
```
- Generate workspace summary

可运行示例请查看

templates/

```
post-message.sh
```
- 带错误处理的消息发送脚本
```
monitor-chat.sh
```
- 轮询新UserChat的脚本
```
workspace-summary.sh
```
- 生成工作区摘要的脚本

Error Handling

错误处理

All commands return consistent error format:

json

{
  "error": "No credentials. Run \"auth set <access-key> <access-secret>\" first."
}

Common errors:

No credentials

Workspace not found

Bot name is required

Use --force to confirm deletion

所有命令返回一致的错误格式：

json

{
  "error": "No credentials. Run \"auth set <access-key> <access-secret>\" first."
}

常见错误：

No credentials

、

Workspace not found

、

Bot name is required

、

Use --force to confirm deletion

。

Configuration

配置

Credentials stored in

~/.config/agent-messenger/channeltalkbot-credentials.json

(0600 permissions). See references/authentication.md for format and security details.

Config format:

json

{
  "current": { "workspace_id": "abc123" },
  "workspaces": {
    "abc123": {
      "workspace_id": "abc123",
      "workspace_name": "My Workspace",
      "access_key": "...",
      "access_secret": "..."
    }
  },
  "default_bot": "Support Bot"
}

凭证存储在

~/.config/agent-messenger/channeltalkbot-credentials.json

（权限为0600）。格式和安全细节请查看references/authentication.md。

配置格式：

json

{
  "current": { "workspace_id": "abc123" },
  "workspaces": {
    "abc123": {
      "workspace_id": "abc123",
      "workspace_name": "My Workspace",
      "access_key": "...",
      "access_secret": "..."
    }
  },
  "default_bot": "Support Bot"
}

Key Differences from agent-channeltalk

与agent-channeltalk的主要区别

Feature	agent-channeltalk	agent-channeltalkbot
Auth type	Cookie extraction (browser)	API credentials (access key/secret)
Token source	Auto-extracted from session	Channel Talk admin Open API
Acts as	Manager (you)	Bot (named identity)
Send group messages	Yes	Yes (requires bot name)
Send user-chat reply	Yes	Yes
Manage bots	No	Yes (create / delete)
Workspace snapshot	Yes	Yes
Search messages	Yes (UI search)	No (API limitation)
CI/CD friendly	Requires browser session	Yes (just set access key/secret)

功能	agent-channeltalk	agent-channeltalkbot
身份验证类型	Cookie提取（浏览器）	API凭证（Access Key/Secret）
Token来源	从会话自动提取	Channel Talk管理员Open API
身份角色	客服（你）	机器人（命名身份）
发送群组消息	是	是（需要机器人名称）
回复UserChat	是	是
管理机器人	否	是（创建/删除）
工作区快照	是	是
搜索消息	是（UI搜索）	否（API限制）
CI/CD友好性	需要浏览器会话	是（只需设置Access Key/Secret）

Limitations

限制

No real-time events / WebSocket connection
No file upload support
No message editing or deletion (Channel Talk API limitation)
No user management (users are end-customers, managed by Channel Talk)
No webhook support
No message search (Channel Talk Open API does not provide a search endpoint)
Plain text messages only (no rich blocks in v1)
Bot name must exist in the workspace for sending messages
Channel Talk has rate limits on API calls

无实时事件/WebSocket连接
无文件上传支持
无消息编辑或删除功能（Channel Talk API限制）
无用户管理（用户为终端客户，由Channel Talk管理）
无Webhook支持
无消息搜索功能（Channel Talk Open API未提供搜索端点）
仅支持纯文本消息（v1版本无富文本块）
发送消息时必须使用工作区中已存在的机器人名称
Channel Talk对API调用有速率限制

Troubleshooting

故障排除

agent-channeltalkbot: command not found

agent-channeltalkbot: command not found

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

agent-messenger

If the package is installed globally, use

agent-channeltalkbot

directly:

bash

agent-channeltalkbot message send abc123-chat-id "Hello"

If the package is NOT installed, run it directly with

npx -y

bash

npx -y agent-messenger channeltalkbot message send abc123-chat-id "Hello"

Note: If the user prefers a different package runner (e.g.,
bunx
,
pnpx
,
pnpm dlx
), use that instead.

NEVER run
npx agent-channeltalkbot
,
bunx agent-channeltalkbot
, or
pnpm dlx agent-channeltalkbot
. It will fail or install a wrong package since

agent-channeltalkbot

is not the npm package name.

agent-channeltalkbot
并非npm包名称。npm包名称为

agent-messenger

。

如果已全局安装该包，可直接使用

agent-channeltalkbot

：

bash

agent-channeltalkbot message send abc123-chat-id "Hello"

如果未安装该包，可使用

npx -y

直接运行：

bash

npx -y agent-messenger channeltalkbot message send abc123-chat-id "Hello"

注意：如果用户偏好其他包运行器（如
bunx
、
pnpx
、
pnpm dlx
），可使用对应工具。

切勿运行
npx agent-channeltalkbot
、
bunx agent-channeltalkbot
或
pnpm dlx agent-channeltalkbot
。这会失败或安装错误的包，因为

agent-channeltalkbot

并非npm包名称。

How to get API credentials

如何获取API凭证

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>

登录Channel Talk
进入设置 > 开发者 > Open API
创建或复制你的Access Key和Access Secret

运行

agent-channeltalkbot auth set <access-key> <access-secret>

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 to avoid hitting limits.

Channel Talk对API调用实施速率限制。CLI会根据

Retry-After

头自动重试速率限制（429）响应。对于批量操作，请在请求之间添加延迟以避免触发限制。

Bot name errors

机器人名称错误

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.

For other troubleshooting, see references/authentication.md.

某些操作（关闭对话、发送消息）需要机器人名称。使用

auth bot <name>

设置默认机器人，或为每个命令传入

--bot <name>

参数。该机器人必须存在于你的工作区中。使用

bot list

查看可用机器人。

其他故障排除内容请查看references/authentication.md。

References

参考资料

Authentication Guide
Common Patterns

身份验证指南
常见模式