plain-support

Plain API 技能

通过 GraphQL API 访问 Plain 客户支持平台。此技能提供读取客户、支持会话、时间线条目、帮助中心内容、广播等内容的命令。可以在会话中添加备注。可以直接创建、更新和发布帮助中心文章。可以起草和编辑广播及广播受众，但绝不会安排或发送。

前置条件

• 设置 PLAIN_API_KEY 环境变量，并填入你的 API 密钥
• 已安装 curl 和 jq

快速参考

客户（只读）

# List customers
scripts/plain-api.sh customer list --first 10

# Get customer by ID
scripts/plain-api.sh customer get c_01ABC...

# Get customer by email
scripts/plain-api.sh customer get-by-email [email protected]

# Get customer by external ID
scripts/plain-api.sh customer get-by-external-id your-system-id

# Search customers
scripts/plain-api.sh customer search "john doe"

会话（读写）

# List threads (TODO status by default)
scripts/plain-api.sh thread list --first 20

# List all threads including done
scripts/plain-api.sh thread list --status all

# List done threads
scripts/plain-api.sh thread list --status DONE

# List threads by priority
scripts/plain-api.sh thread list --priority urgent
scripts/plain-api.sh thread list --priority high
scripts/plain-api.sh thread list --status TODO --priority low

# Get thread details
scripts/plain-api.sh thread get th_01ABC...

# Search threads
scripts/plain-api.sh thread search "billing issue"

# Get thread timeline (all messages, events, status changes)
scripts/plain-api.sh thread timeline th_01ABC... --first 50

# Paginate through timeline
scripts/plain-api.sh thread timeline th_01ABC... --first 20 --after "cursor_from_previous_page"

# Add a note to a thread (internal note, not visible to customer)
scripts/plain-api.sh thread note th_01ABC... --text "This is an internal note"

# Add a note with markdown formatting
scripts/plain-api.sh thread note th_01ABC... --text "Note text" --markdown "**Bold** and *italic*"

# Add a note from a file (for longer notes)
scripts/plain-api.sh thread note th_01ABC... --text-file /path/to/note.txt

会话备注选项：

选项	必填	说明
--text	是*	备注的纯文本内容
--text-file	是*	包含备注文本的文件路径
--markdown	否	备注的 Markdown 格式版本

*必须指定 --text 或 --text-file。

会话列表选项：

选项	说明
--status	按状态筛选：TODO、SNOOZED、DONE 或 all
--priority	按优先级筛选：urgent、high、normal、low
--customer	按客户 ID 筛选
--first	结果数量（默认值：10）

会话优先级： urgent > high > normal（默认值）> low

会话链接（读写）

将外部问题（GitHub 等）附加到会话。Plain 会在服务端从集成中获取标题、URL、描述和状态——只需提供 ref。

# Add a GitHub issue or PR — accepts URL, shorthand, or canonical sourceId
scripts/plain-api.sh thread link add th_01ABC... https://github.com/owner/repo/issues/45
scripts/plain-api.sh thread link add th_01ABC... https://github.com/owner/repo/pull/45
scripts/plain-api.sh thread link add th_01ABC... owner/repo#45
scripts/plain-api.sh thread link add th_01ABC... owner/repo/45

# List links on a thread
scripts/plain-api.sh thread link list th_01ABC...

添加会话链接选项：

选项	必填	说明
<thread_id>	是	要附加链接的会话
<ref>	是	GitHub URL、owner/repo#N 或 owner/repo/N
--source	否	来源类型（默认值：github_issue）。其他值：shortcut_issue、rootly_incident、incidentio_incident——对于这些类型，请将集成的原生 sourceId 作为 <ref> 传入

注意：

• 工作区必须配置相关集成（例如 GitHub），Plain 才能解析元数据。否则，add 调用会返回错误。
• 不支持通过 API 密钥移除链接——请在 Plain UI 中删除。
• Plain 不会向机器用户开放 searchThreadLinkCandidates，因此 Agent 必须直接提供 ref（例如，从客户粘贴的 URL 中解析）。

公司（只读）

# List companies
scripts/plain-api.sh company list --first 10

# Get company by ID
scripts/plain-api.sh company get co_01ABC...

租户（只读）

# List tenants
scripts/plain-api.sh tenant list --first 10

# Get tenant by ID
scripts/plain-api.sh tenant get ten_01ABC...

标签（只读）

# List available label types
scripts/plain-api.sh label list --first 20

帮助中心（读写）

# List help centers
scripts/plain-api.sh helpcenter list

# Get help center details
scripts/plain-api.sh helpcenter get hc_01ABC...

# List articles in help center
scripts/plain-api.sh helpcenter articles hc_01ABC... --first 20

# Get article by ID
scripts/plain-api.sh helpcenter article get hca_01ABC...

# Get article by slug
scripts/plain-api.sh helpcenter article get-by-slug hc_01ABC... my-article-slug

# Create new article (defaults to DRAFT status)
scripts/plain-api.sh helpcenter article upsert hc_01ABC... \
  --title "How to reset password" \
  --description "Step-by-step guide for resetting your password" \
  --content "<h1>Reset Password</h1><p>Follow these steps...</p>"

# Create and publish article directly
scripts/plain-api.sh helpcenter article upsert hc_01ABC... \
  --title "Getting Started" \
  --description "Quick start guide for new users" \
  --content "<p>Welcome!</p>" \
  --status PUBLISHED

# Update existing article
scripts/plain-api.sh helpcenter article upsert hc_01ABC... \
  --id hca_01ABC... \
  --title "Updated Title" \
  --description "Updated description" \
  --content "<p>New content</p>"

# Use --content-file for large HTML content (recommended)
scripts/plain-api.sh helpcenter article upsert hc_01ABC... \
  --title "Detailed Guide" \
  --description "Comprehensive documentation" \
  --content-file /path/to/article.html \
  --status PUBLISHED

# Get article group
scripts/plain-api.sh helpcenter group get hcag_01ABC...

# Create article group
scripts/plain-api.sh helpcenter group create hc_01ABC... --name "Getting Started"

# Create nested article group
scripts/plain-api.sh helpcenter group create hc_01ABC... --name "Advanced Topics" --parent hcag_01PARENT...

# Update article group
scripts/plain-api.sh helpcenter group update hcag_01ABC... --name "New Group Name"

# Delete article group
scripts/plain-api.sh helpcenter group delete hcag_01ABC...

文章新增或更新选项：

选项	必填	说明
--title	是	文章标题
--description	是	简短描述（显示在文章列表中）
--content	是*	HTML 内容（内联）
--content-file	是*	包含 HTML 内容的文件路径
--id	否	文章 ID（用于更新）
--group	否	文章分组 ID
--status	否	DRAFT（默认值）或 PUBLISHED

*必须指定 --content 或 --content-file。内容较长时，请使用 --content-file。

注意： 响应包含一个 link 字段，其中是用于在 Plain UI 中编辑文章的 URL：

{
  "data": { ... },
  "link": "https://app.plain.com/workspace/w_01.../help-center/hc_01.../articles/hca_01.../"
}

广播（读取 + 写入）

广播是一条同时发布到多个 Slack 频道的消息。此技能可起草和查看广播。它绝不会安排或发送广播——包括会发布真实消息到真实频道的测试发送。发送由人工在 Plain 应用中完成。

# List broadcasts (newest first)
scripts/plain-api.sh broadcast list --first 10
scripts/plain-api.sh broadcast list --status DRAFT
scripts/plain-api.sh broadcast list --status SENT --status PARTIALLY_SENT

# Get one broadcast, including content, sender and send target
scripts/plain-api.sh broadcast get bc_01ABC...

# Search by name (2+ characters)
scripts/plain-api.sh broadcast search "launch"

# Send history. Unfiltered this includes test sends — check isTest
scripts/plain-api.sh broadcast sends bc_01ABC... --real-only

# Per-recipient results for the latest real send
scripts/plain-api.sh broadcast deliveries bc_01ABC... --status FAILED
scripts/plain-api.sh broadcast deliveries bc_01ABC... --send bcs_01ABC...

# Preview who a target reaches right now, before drafting anything
scripts/plain-api.sh broadcast recipients --tier tier_01ABC...
scripts/plain-api.sh broadcast recipients --audience ba_01ABC... --search eng
scripts/plain-api.sh broadcast recipients --all-recipients

# Draft a broadcast (stays in DRAFT — nothing is sent)
scripts/plain-api.sh broadcast create \
  --name "March launch" \
  --notification-title "We shipped bulk actions" \
  --text "Bulk actions are live today." \
  --tier tier_01ABC...

# Edit a draft. Omitted flags are left alone, not cleared
scripts/plain-api.sh broadcast update bc_01ABC... --name "March launch (EU)"
scripts/plain-api.sh broadcast update bc_01ABC... --content-file /tmp/broadcast.json

# Soft-delete
scripts/plain-api.sh broadcast delete bc_01ABC...

广播创建／更新选项：

选项	必填	描述
--name	是（创建时）	内部名称。收件人永远看不到
--text	是*	纯文本正文，会自动包装为 Tiptap 文档（可在 Plain 应用中编辑）
--content-file	是*	Tiptap 文档（{"type":"doc"}）或 Slack Block Kit JSON 数组的路径
--notification-title	否	收件人在通知中看到的内容。人工发送前必须填写
--sender-type	否	PLAIN_WORKSPACE 或 PLAIN_USER（由 --sender-user 推断）
--sender-user	否	发布所用的用户 ID
--link-unfurling	否	true 或 false
--all-recipients	否	以所有已连接的客户频道为目标（ALL_RECIPIENTS）。接受 --all-tenants 作为别名
--tier / --tenant / --audience / --channel-name-contains	否	目标维度。可重复指定，且会组合使用
--filters-file	否	使用 and／or／not 的筛选器树，用于表达命令行选项无法表达的条件

*创建时必须指定 --text 或 --content-file。--text 会转换为 Tiptap 格式，方便人工在 Plain 应用中完成草稿。Block Kit 格式的 --content-file 无法在应用中编辑——请参阅 references/ENTITIES.md。

广播受众（读取 + 写入）

已保存且可重复使用的收件人集合。发送时会解析为频道，因此随着租户和频道的变化，受众也会保持最新。

# List audiences
scripts/plain-api.sh audience list --first 20
scripts/plain-api.sh audience list --search enterprise

# Get one
scripts/plain-api.sh audience get ba_01ABC...

# Create
scripts/plain-api.sh audience create --name "Enterprise" --tier tier_01ABC...
scripts/plain-api.sh audience create --name "Support channels" --channel-name-contains "-support"
scripts/plain-api.sh audience create --name "Everyone" --all-recipients

# Rename, or replace the filters
scripts/plain-api.sh audience update ba_01ABC... --name "Enterprise (EU)"
scripts/plain-api.sh audience update ba_01ABC... --filters-file /tmp/filters.json

# Soft-delete (rejected while a broadcast targeting it is scheduled or sending)
scripts/plain-api.sh audience delete ba_01ABC...

警告： 使用任何筛选器选项执行 audience update，都会完全替换已保存的筛选器——不会合并。如果只想添加一行，请先运行 audience get，并传回完整的筛选器树。编辑受众也会改变使用该受众的每条广播在下次发送时所覆盖的对象。

等级和 SLA（只读）

# List tiers with SLA configurations
scripts/plain-api.sh tier list

# Get tier details
scripts/plain-api.sh tier get tier_01ABC...

工作区

# Get current workspace info
scripts/plain-api.sh workspace

常见工作流

调查客户历史记录

1. 获取客户：customer get c_... 或 customer get-by-email [email protected]
2. 列出客户的工单：thread list --customer c_... --status all
3. 获取工单详情：thread get th_...
4. 阅读完整对话：thread timeline th_... --first 100

阅读工单对话

1. 获取工单：thread get th_...
2. 获取时间线条目：thread timeline th_... --first 50
3. 提取消息：在响应中查找 EmailEntry、ChatEntry、SlackMessageEntry 等
4. 如有需要，进行分页：使用 --after 和 pageInfo.endCursor 中的游标

向工单添加内部备注

1. 从 URL 获取工单 ID，或通过搜索查找：thread search "issue keyword"
2. 添加备注：thread note th_... --text "Investigation notes here"
3. 在时间线中验证：thread timeline th_... --first 5

创建或更新帮助文章

1. 列出帮助中心：helpcenter list
2. 将 HTML 内容写入文件（适用于较长的文章）：/tmp/article.html
3. 创建／更新文章：

   helpcenter article upsert hc_... \
     --title "Article Title" \
     --description "Short description" \
     --content-file /tmp/article.html \
     --status PUBLISHED
   

4. 使用返回的链接在 Plain UI 中查看／编辑

为某个等级起草广播

1. 查找等级：tier list
2. 保存受众（可选，但可重复使用）：audience create --name "Enterprise" --tier tier_...
3. 开始撰写前，先检查广播覆盖对象：broadcast recipients --audience ba_...——查看 count，若为 0 则查看 emptyReason
4. 起草广播：broadcast create --name "..." --notification-title "..." --text "..." --audience ba_...
5. 确认草稿：broadcast get bc_...（状态保持为 DRAFT）
6. 将广播 ID 交给人工——安排和发送操作都在 Plain 应用中完成

实体参考

请参阅 references/ENTITIES.md，了解所有实体的详细文档，包括：

• 客户字段和状态
• 会话状态、优先级和渠道
• 时间线条目类型（24 种类型：电子邮件、聊天、备注、事件、状态变更等）
• 公司和租户结构
• 标签和 LabelType 定义
• 帮助中心、文章和 ArticleGroup 架构
• 层级和 SLA 配置
• 广播字段、状态和 Tiptap 内容格式
• BroadcastSend 和投递状态，包括失败原因
• BroadcastAudience 筛选树和发送目标

环境变量

变量	必填	描述
PLAIN_API_KEY	是	你的 Plain API 密钥
PLAIN_API_URL	否	API 端点（默认值：https://core-api.uk.plain.com/graphql/v1）

输出格式

所有命令均返回 JSON。使用 jq 进行解析：

# Get just customer name
scripts/plain-api.sh customer get c_01ABC... | jq '.data.customer.fullName'

# Get thread IDs
scripts/plain-api.sh thread list | jq '.data.threads.edges[].node.id'

# Get timeline message content
scripts/plain-api.sh thread timeline th_01ABC... | jq '.data.thread.timelineEntries.edges[].node.entry'

# Get link from article creation
scripts/plain-api.sh helpcenter article upsert hc_... --title "Test" --content "<p>Test</p>" | jq -r '.link'