slack-openapi-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Slack Web API Skill

Slack Web API 技能

Use this skill to run Slack Web API operations through

uxc

+ OpenAPI.

Reuse the

uxc

skill for shared execution, auth, and error-handling guidance.

使用此技能通过

uxc

+ OpenAPI来运行Slack Web API操作。

复用

uxc

技能以实现共享执行、认证和错误处理指导。

Prerequisites

前提条件

```
uxc
```
is installed and available in
```
PATH
```
.
Network access to
```
https://slack.com/api
```
.

Access to the curated OpenAPI schema URL:

https://raw.githubusercontent.com/holon-run/uxc/main/skills/slack-openapi-skill/references/slack-web.openapi.json

A Slack bot token and, for selected thread/history reads, an optional user token.

```
uxc
```
已安装且可在
```
PATH
```
中访问。
可访问
```
https://slack.com/api
```
的网络权限。

可访问精选OpenAPI Schema的URL：

https://raw.githubusercontent.com/holon-run/uxc/main/skills/slack-openapi-skill/references/slack-web.openapi.json

一个Slack机器人令牌；对于部分线程/历史记录读取操作，可选用户令牌。

Scope

适用范围

This skill covers a Messaging Core surface:

auth validation
channel lookup and inspection
conversation history reads
thread replies reads
posting messages, including replies via
```
thread_ts
```
adding reactions

This skill does not cover:

Slack OAuth app installation flow
file upload flows
```
users.*
```
,
```
admin.*
```
, or
```
usergroups.*
```
method families

此技能涵盖消息核心相关功能：

认证验证
频道查找与检查
对话历史记录读取
线程回复读取
发送消息，包括通过
```
thread_ts
```
回复消息
添加表情反应

此技能不涵盖：

Slack OAuth应用安装流程
文件上传流程
```
users.*
```
、
```
admin.*
```
或
```
usergroups.*
```
方法系列

Subscribe / Socket Mode Status

订阅/Socket Mode 状态

Slack inbound events can be delivered through Socket Mode.

uxc

now has a built-in Slack Socket Mode transport, but this skill still treats it as a limited event-ingest path rather than a fully packaged workflow surface.

Current

uxc subscribe

status:

Slack Web API request/response calls are supported by this skill
a live Socket Mode smoke test succeeded with the built-in transport:
- ```
uxc subscribe start https://slack.com/api --transport slack-socket-mode --auth slack-app --sink file:...
```
- the runtime opened a fresh temporary WebSocket URL automatically
- the initial Slack
```
hello
```
  frame was received
a real inbound message event was validated end-to-end:
- while the Socket Mode job was running, a live Slack message event was delivered as an
```
events_api
```
  envelope
- the sink recorded the message payload and
```
ack_sent=true
```

What the current built-in transport already handles:

app-level
```
xapp-...
```
auth via
```
--auth
```
automatic
```
apps.connections.open
```
before each connect attempt
raw Socket Mode frame capture
automatic ack for envelopes that carry
```
envelope_id
```

What is still not packaged:

event-shape guidance per subscribed Slack event family
higher-level workflow packaging for common Slack event intake flows

Slack Socket Mode is now a validated IM subscribe provider at the transport/runtime level.

Slack入站事件可通过Socket Mode传递。

uxc

现在内置了Slack Socket Mode传输功能，但此技能仍将其视为有限的事件摄入路径，而非完整封装的工作流界面。

当前

uxc subscribe

状态：

此技能支持Slack Web API请求/响应调用
使用内置传输功能完成了一次Socket Mode实时冒烟测试：
- ```
uxc subscribe start https://slack.com/api --transport slack-socket-mode --auth slack-app --sink file:...
```
- 运行时自动打开了一个全新的临时WebSocket URL
- 已接收到初始Slack
```
hello
```
  帧
端到端验证了真实的入站消息事件：
- 当Socket Mode任务运行时，实时Slack消息事件以
```
events_api
```
  信封形式传递
- 接收器记录了消息负载且
```
ack_sent=true
```

当前内置传输功能已处理的内容：

通过
```
--auth
```
实现应用级
```
xapp-...
```
认证
每次连接尝试前自动调用
```
apps.connections.open
```
原始Socket Mode帧捕获
自动确认带有
```
envelope_id
```
的信封

尚未封装的内容：

按订阅的Slack事件系列提供事件格式指导
为常见Slack事件摄入流提供更高层级的工作流封装

Slack Socket Mode现已在传输/运行时层面成为经验证的IM订阅提供者。

Authentication

认证

Slack Web API uses

Authorization: Bearer <token>

Token types used in practice:

```
xoxb-...
```
: Bot User OAuth Token. This is the recommended default for this skill.
```
xoxp-...
```
: User OAuth Token. Use this only when you explicitly want user-token semantics.
```
xapp-...
```
: App-level token. Use this for Socket Mode subscribe, not for normal Web API methods.

To create an app-level

xapp-...

token for Socket Mode:

Open the target Slack app at
```
https://api.slack.com/apps
```
Go to
```
Basic Information
```
Find
```
App-Level Tokens
```
Generate a token with the
```
connections:write
```
scope
Enable
```
Socket Mode
```
in the app configuration before relying on subscribe-based event intake

Slack Web API使用

Authorization: Bearer <token>

。

实际使用的令牌类型：

```
xoxb-...
```
：机器人用户OAuth令牌。这是此技能推荐的默认令牌。
```
xoxp-...
```
：用户OAuth令牌。仅当明确需要用户令牌语义时使用。
```
xapp-...
```
：应用级令牌。用于Socket Mode订阅，而非常规Web API方法。

为Socket Mode创建应用级

xapp-...

令牌：

在
```
https://api.slack.com/apps
```
打开目标Slack应用
进入
```
Basic Information
```
（基本信息）页面
找到
```
App-Level Tokens
```
（应用级令牌）
生成带有
```
connections:write
```
权限范围的令牌
在依赖基于订阅的事件摄入前，在应用配置中启用
```
Socket Mode
```

Option 1: Bot Token (Recommended Default)

选项1：机器人令牌（推荐默认）

Use the Slack

Bot User OAuth Token

(

xoxb-...

) for the default binding and for most messaging operations:

bash

uxc auth credential set slack-bot \
  --auth-type bearer \
  --secret-env SLACK_BOT_TOKEN

uxc auth binding add \
  --id slack-bot \
  --host slack.com \
  --path-prefix /api \
  --scheme https \
  --credential slack-bot \
  --priority 100

使用Slack

Bot User OAuth Token

（

xoxb-...

）进行默认绑定及大多数消息操作：

bash

uxc auth credential set slack-bot \
  --auth-type bearer \
  --secret-env SLACK_BOT_TOKEN

uxc auth binding add \
  --id slack-bot \
  --host slack.com \
  --path-prefix /api \
  --scheme https \
  --credential slack-bot \
  --priority 100

Option 2: User Token (Explicit Override For Selected Reads)

选项2：用户令牌（针对特定读取操作的显式覆盖）

Use a separate Slack

User OAuth Token

(

xoxp-...

) when the method requires user-token semantics, especially thread/history access outside bot-accessible conversations:

bash

uxc auth credential set slack-user \
  --auth-type bearer \
  --secret-env SLACK_USER_TOKEN

Do not bind

slack-user

by default to the same host/path. Invoke it explicitly when needed:

bash

uxc auth binding match https://slack.com/api
slack-openapi-cli --auth slack-user get:/conversations.replies channel=C1234567890 ts=1717171717.000100

If you intentionally want writes to appear as the installing user rather than the bot, you can also invoke write methods with

--auth slack-user

, but treat that as an explicit override rather than the default path.

当方法需要用户令牌语义时，尤其是在机器人无法访问的对话中读取线程/历史记录时，使用单独的Slack

User OAuth Token

（

xoxp-...

）：

bash

uxc auth credential set slack-user \
  --auth-type bearer \
  --secret-env SLACK_USER_TOKEN

不要将

slack-user

默认绑定到同一主机/路径。仅在需要时显式调用：

bash

uxc auth binding match https://slack.com/api
slack-openapi-cli --auth slack-user get:/conversations.replies channel=C1234567890 ts=1717171717.000100

如果有意让写入操作显示为安装用户而非机器人，也可以使用

--auth slack-user

调用写入方法，但请将其视为显式覆盖而非默认方式。

Core Workflow

核心工作流

Use the fixed link command by default:

```
command -v slack-openapi-cli
```

If missing, create it:

uxc link slack-openapi-cli https://slack.com/api --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/slack-openapi-skill/references/slack-web.openapi.json

```
slack-openapi-cli -h
```

Inspect operation schema first:

```
slack-openapi-cli get:/auth.test -h
```

slack-openapi-cli get:/conversations.history -h

slack-openapi-cli post:/chat.postMessage -h

Prefer read validation before writes:

```
slack-openapi-cli get:/auth.test
```

slack-openapi-cli get:/conversations.list limit=20 types=public_channel,private_channel

slack-openapi-cli get:/conversations.info channel=C1234567890

Execute with key/value or positional JSON:

key/value:

slack-openapi-cli get:/conversations.history channel=C1234567890 limit=20

positional JSON:

slack-openapi-cli post:/chat.postMessage '{"channel":"C1234567890","text":"Hello from UXC"}'

默认使用固定链接命令：

```
command -v slack-openapi-cli
```

如果缺失，创建链接：

uxc link slack-openapi-cli https://slack.com/api --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/slack-openapi-skill/references/slack-web.openapi.json

```
slack-openapi-cli -h
```

先检查操作Schema：

```
slack-openapi-cli get:/auth.test -h
```

slack-openapi-cli get:/conversations.history -h

slack-openapi-cli post:/chat.postMessage -h

写入操作前优先进行读取验证：

```
slack-openapi-cli get:/auth.test
```

slack-openapi-cli get:/conversations.list limit=20 types=public_channel,private_channel

slack-openapi-cli get:/conversations.info channel=C1234567890

使用键值对或位置JSON执行操作：

键值对：

slack-openapi-cli get:/conversations.history channel=C1234567890 limit=20

位置JSON：

slack-openapi-cli post:/chat.postMessage '{"channel":"C1234567890","text":"Hello from UXC"}'

Operation Groups

操作组

Read / Lookup

读取/查找

```
get:/auth.test
```
```
get:/conversations.list
```
```
get:/conversations.info
```
```
get:/conversations.history
```
```
get:/conversations.replies
```

```
get:/auth.test
```
```
get:/conversations.list
```
```
get:/conversations.info
```
```
get:/conversations.history
```
```
get:/conversations.replies
```

Messaging / Reactions

消息/反应

```
post:/chat.postMessage
```
```
post:/reactions.add
```

```
post:/chat.postMessage
```
```
post:/reactions.add
```

Guardrails

防护规则

Keep automation on the JSON output envelope; do not use
```
--text
```
.
Parse stable fields first:
```
ok
```
,
```
kind
```
,
```
protocol
```
,
```
data
```
,
```
error
```
.
Bot token is the recommended default for send and basic read flows.
Bot token means Slack
```
Bot User OAuth Token
```
(
```
xoxb-...
```
); do not confuse it with
```
xapp-...
```
app-level tokens.
User token means Slack
```
User OAuth Token
```
(
```
xoxp-...
```
); use
```
--auth slack-user
```
when you intentionally need user identity or user-token-only reads.
```
get:/conversations.replies
```
has token-type restrictions:
- bot token works for IM and MPIM threads the bot can access
- public/private channel thread reads should use
```
--auth slack-user
```
```
get:/conversations.history
```
only returns conversations visible to the supplied token; a bot token is limited to joined conversations.
Slack rate limits for
```
conversations.history
```
and
```
conversations.replies
```
vary by app distribution. Slack documents a tighter limit for newly created commercially distributed non-Marketplace apps starting on May 29, 2025; do not assume generic Tier 3 behavior.
Treat
```
post:/chat.postMessage
```
and
```
post:/reactions.add
```
as write/high-risk operations; require explicit user confirmation before execution.

slack-openapi-cli <operation> ...

is equivalent to

uxc https://slack.com/api --schema-url <slack_openapi_schema> <operation> ...

保持自动化基于JSON输出信封；不要使用
```
--text
```
。
优先解析稳定字段：
```
ok
```
、
```
kind
```
、
```
protocol
```
、
```
data
```
、
```
error
```
。
机器人令牌是发送和基础读取流的推荐默认选项。
机器人令牌指Slack
```
Bot User OAuth Token
```
（
```
xoxb-...
```
）；不要与
```
xapp-...
```
应用级令牌混淆。
用户令牌指Slack
```
User OAuth Token
```
（
```
xoxp-...
```
）；当有意需要用户身份或仅用户令牌可读取的内容时，使用
```
--auth slack-user
```
。
```
get:/conversations.replies
```
有令牌类型限制：
- 机器人令牌适用于机器人可访问的IM和多用户IM线程
- 公共/私有频道线程读取应使用
```
--auth slack-user
```
```
get:/conversations.history
```
仅返回提供的令牌可见的对话；机器人令牌仅限于已加入的对话。
```
conversations.history
```
和
```
conversations.replies
```
的Slack速率限制因应用分发方式而异。Slack文档指出，从2025年5月29日起，新创建的商业分发非市场应用将有更严格的限制；不要假设通用的Tier 3行为。
将
```
post:/chat.postMessage
```
和
```
post:/reactions.add
```
视为写入/高风险操作；执行前需要用户明确确认。

slack-openapi-cli <operation> ...

等同于

uxc https://slack.com/api --schema-url <slack_openapi_schema> <operation> ...

。

References

参考资料

Usage patterns:
```
references/usage-patterns.md
```
Curated OpenAPI schema:
```
references/slack-web.openapi.json
```
Slack Web API docs: https://docs.slack.dev/apis/web-api
```
chat.postMessage
```
: https://docs.slack.dev/reference/methods/chat.postMessage
```
conversations.history
```
: https://docs.slack.dev/reference/methods/conversations.history
```
conversations.replies
```
: https://docs.slack.dev/reference/methods/conversations.replies/

使用模式：
```
references/usage-patterns.md
```
精选OpenAPI Schema：
```
references/slack-web.openapi.json
```
Slack Web API文档：https://docs.slack.dev/apis/web-api
```
chat.postMessage
```
：https://docs.slack.dev/reference/methods/chat.postMessage
```
conversations.history
```
：https://docs.slack.dev/reference/methods/conversations.history
```
conversations.replies
```
：https://docs.slack.dev/reference/methods/conversations.replies/