Telegram Send

通过 Telegram 机器人发送语音、图片和文档文件 — 采用 Bot API 优先的投递策略，支持自动聊天 ID 解析，并提供本地端点回退机制用于文本通知和重试。

默认启用 通信

快速参考

投递策略（Bot 优先）

该技能遵循严格的两级投递策略。始终优先尝试 Telegram Bot API。本地 CLI-JAW 端点作为文本消息的便捷通道，以及 Bot API 失败时的回退方案。

必需输入

分步工作流

步骤 1：读取令牌和聊天 ID

代理从 CLI-JAW 设置文件中读取凭据。令牌仅保存在 shell 变量中 — 不会打印到标准输出或日志。

TOKEN=$(jq -r '.telegram.token' ~/.cli-jaw/settings.json)
CHAT_ID=$(jq -r '.telegram.allowedChatIds[-1]' ~/.cli-jaw/settings.json)

如果 CHAT_ID 解析为 null（没有之前的 Telegram 消息记录），代理会通过 ping 本地端点来恢复：

CHAT_ID=$(curl -sS -X POST http://localhost:3457/api/telegram/send \
  -H "Content-Type: application/json" \
  -d '{"type":"text","text":"chat_id check"}' | jq -r '.chat_id')

步骤 2：通过 Bot API 发送（主要方式）

代理根据消息类型构造一个 curl multipart 表单 POST 请求，发送到对应的 Telegram Bot API 端点。

发送图片

curl -sS -X POST "https://api.telegram.org/bot${TOKEN}/sendPhoto" \
  -F "chat_id=${CHAT_ID}" \
  -F "photo=@/tmp/chart.png" \
  -F "caption=Analysis chart"

发送语音消息

curl -sS -X POST "https://api.telegram.org/bot${TOKEN}/sendVoice" \
  -F "chat_id=${CHAT_ID}" \
  -F "voice=@/tmp/reply.ogg" \
  -F "caption=Voice response"

发送文档

curl -sS -X POST "https://api.telegram.org/bot${TOKEN}/sendDocument" \
  -F "chat_id=${CHAT_ID}" \
  -F "document=@/tmp/report.pdf" \
  -F "caption=Weekly report"

步骤 3：本地端点（备用/回退）

本地 CLI-JAW 服务器在以下地址暴露了 Telegram 发送端点：

文本消息（本地端点的主要用途）

curl -sS -X POST http://localhost:3457/api/telegram/send \
  -H "Content-Type: application/json" \
  -d '{"type":"text","text":"Deployment complete!"}'

通过本地端点回退发送媒体

curl -sS -X POST http://localhost:3457/api/telegram/send \
  -H "Content-Type: application/json" \
  -d '{"type":"photo","file_path":"/tmp/chart.png","caption":"Analysis chart"}'

步骤 4：验证投递

发送成功会返回包含 "ok": true 的 JSON 响应：

{"ok":true,"chat_id":8231528245,"type":"text"}

代理在向用户报告成功之前会检查此响应。如果响应表示失败，且主要方式为 Bot API，则会通过本地端点进行一次重试。

支持的消息类型

配置

该技能从 ~/.cli-jaw/settings.json 读取所有配置，无需单独的配置文件。

// ~/.cli-jaw/settings.json (相关键)
{
  "telegram": {
    "token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
    "allowedChatIds": [8231528245]
  }
}

依赖

该技能仅需要标准 Unix 工具，这些工具在 macOS 和大多数 Linux 发行版上已预装。

验证依赖

# 检查 curl
curl --version

# 检查 jq
jq --version

# 如果缺少 jq 则安装（macOS）
brew install jq

# 如果缺少 jq 则安装（Ubuntu/Debian）
sudo apt-get install -y jq

安全规则

该技能围绕令牌处理强制执行严格的安全实践：

快速验证

要测试 Telegram 集成是否正常工作，运行以下 ping 命令：

curl -sS -X POST http://localhost:3457/api/telegram/send \
  -H "Content-Type: application/json" \
  -d '{"type":"text","text":"ping"}'

预期响应：

{"ok":true,"chat_id":8231528245,"type":"text"}

如果收到错误，请检查：

1. CLI-JAW 服务器是否正在运行（jaw server status）
2. Bot 令牌是否已在 ~/.cli-jaw/settings.json 中配置
3. 你是否已在 Telegram 上向机器人发送过至少一条消息（以建立聊天）

"~해줘" 用法示例

展示如何使用自然语言触发 telegram-send 技能的实际示例。韩语和英语均可使用。

与其他技能的集成

telegram-send 技能通常是多技能工作流中的最后一步。它可以与任何生成输出文件或状态更新的技能自然配合。

API 参考

使用的 Bot API 端点

本地端点

响应格式

// 成功
{"ok": true, "chat_id": 8231528245, "type": "text"}

// 失败（示例）
{"ok": false, "error": "Bot token not configured"}

故障排除

聊天 ID 为 null

如果 jq -r '.telegram.allowedChatIds[-1]' 返回 null，说明机器人尚未收到你的任何消息。请先在 Telegram 上向机器人发送任意消息，然后聊天 ID 将被记录到设置中。或者，代理将通过探测本地端点自动恢复。

Bot API 返回 401 Unauthorized

Bot 令牌无效或已过期。请从 @BotFather 生成新令牌并更新 ~/.cli-jaw/settings.json。

Bot API 返回 400 Bad Request

常见原因：

• 无效的 chat_id： 聊天 ID 不对应与机器人的活跃对话。
• 文件过大： Telegram Bot API 限制上传文件最大为 50 MB。对于更大的文件，请使用可能支持分块上传的本地端点。
• 语音文件格式错误： 语音消息必须为 OGG 格式（OPUS 编码）。其他音频格式应作为 document 发送。

本地端点连接被拒绝

CLI-JAW 服务器未运行。请使用以下命令启动：

jaw server start

# 或检查状态
jaw server status

找不到 jq

安装 jq 以解析设置文件：

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install -y jq

# 验证
jq --version

与 Telegram 指南的对比

CLI-JAW 文档在两个地方涵盖了 Telegram 相关内容。它们用途不同：