Plain API Skill

Access to the Plain customer support platform via GraphQL API. This skill provides commands to read customers, support threads, timeline entries, help center content, and more. Notes can be added to threads. Help center articles can be created, updated, and published directly.

通过GraphQL API访问Plain客户支持平台。该Skill提供读取客户、支持工单、时间线条目、帮助中心内容等的命令，还可为工单添加备注，直接创建、更新和发布帮助中心文章。

Prerequisites

前置条件

```
PLAIN_API_KEY
```
environment variable set with your API key
```
curl
```
and
```
jq
```
installed

```
PLAIN_API_KEY
```
环境变量设置为你的API密钥
已安装
```
curl
```
和
```
jq
```

Quick Reference

快速参考

Customers (Read Only)

客户（只读）

bash

undefined

bash

undefined

List customers

列出客户

scripts/plain-api.sh customer list --first 10

Get customer by ID

通过ID获取客户

scripts/plain-api.sh customer get c_01ABC...

Get customer by email

通过邮箱获取客户

scripts/plain-api.sh customer get-by-email user@example.com

Get customer by external ID

通过外部ID获取客户

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

Search customers

搜索客户

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

undefined

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

undefined

Threads (Read + Write)

工单（可读可写）

bash

undefined

bash

undefined

List threads (TODO status by default)

列出工单（默认显示TODO状态）

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

添加带Markdown格式的备注

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


**Thread note options:**
| Option | Required | Description |
|--------|----------|-------------|
| `--text` | Yes* | Plain text content of the note |
| `--text-file` | Yes* | Path to file containing note text |
| `--markdown` | No | Markdown formatted version of the note |

*Either `--text` or `--text-file` is required.

**Thread list options:**
| Option | Description |
|--------|-------------|
| `--status` | Filter by status: `TODO`, `SNOOZED`, `DONE`, or `all` |
| `--priority` | Filter by priority: `urgent`, `high`, `normal`, `low` |
| `--customer` | Filter by customer ID |
| `--first` | Number of results (default: 10) |

**Thread priorities:** `urgent` > `high` > `normal` (default) > `low`

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`

Companies (Read Only)

公司（只读）

bash

undefined

bash

undefined

List companies

列出公司

scripts/plain-api.sh company list --first 10

Get company by ID

通过ID获取公司

scripts/plain-api.sh company get co_01ABC...

undefined

scripts/plain-api.sh company get co_01ABC...

undefined

Tenants (Read Only)

租户（只读）

bash

undefined

bash

undefined

List tenants

列出租户

scripts/plain-api.sh tenant list --first 10

Get tenant by ID

通过ID获取租户

scripts/plain-api.sh tenant get ten_01ABC...

undefined

scripts/plain-api.sh tenant get ten_01ABC...

undefined

Labels (Read Only)

标签（只读）

bash

undefined

bash

undefined

List available label types

列出可用标签类型

scripts/plain-api.sh label list --first 20

undefined

scripts/plain-api.sh label list --first 20

undefined

Help Center (Read + Write)

帮助中心（可读可写）

bash

undefined

bash

undefined

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

通过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)

创建新文章（默认状态为DRAFT）

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>Follow these steps..."

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 "Welcome!"
--status PUBLISHED

Update existing article

更新现有文章

scripts/plain-api.sh helpcenter article upsert hc_01ABC...
--id hca_01ABC...
--title "Updated Title"
--description "Updated description"
--content "New content"

Use --content-file for large HTML content (recommended)

对于大篇幅HTML内容，推荐使用--content-file

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


**Article upsert options:**
| Option | Required | Description |
|--------|----------|-------------|
| `--title` | Yes | Article title |
| `--description` | Yes | Short description (shown in article lists) |
| `--content` | Yes* | HTML content (inline) |
| `--content-file` | Yes* | Path to file containing HTML content |
| `--id` | No | Article ID (for updates) |
| `--group` | No | Article group ID |
| `--status` | No | DRAFT (default) or PUBLISHED |

*Either `--content` or `--content-file` is required. Use `--content-file` for large content.

**Note:** The response includes a `link` field with the URL to edit the article in the Plain UI:

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

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：

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

Tiers & SLAs (Read Only)

服务等级与SLA（只读）

bash

undefined

bash

undefined

List tiers with SLA configurations

列出包含SLA配置的服务等级

scripts/plain-api.sh tier list

Get tier details

获取服务等级详情

scripts/plain-api.sh tier get tier_01ABC...

undefined

scripts/plain-api.sh tier get tier_01ABC...

undefined

Workspace

工作区

bash

undefined

bash

undefined

Get current workspace info

获取当前工作区信息

scripts/plain-api.sh workspace

undefined

scripts/plain-api.sh workspace

undefined

Common Workflows

常见工作流

Research customer history

查询客户历史

Get customer:

customer get c_...

or

customer get-by-email user@example.com

List their threads:

thread list --customer c_... --status all

Get thread details:
```
thread get th_...
```
Read full conversation:
```
thread timeline th_... --first 100
```

获取客户信息：

customer get c_...

或

customer get-by-email user@example.com

列出客户的工单：

thread list --customer c_... --status all

获取工单详情：
```
thread get th_...
```
查看完整对话：
```
thread timeline th_... --first 100
```

Read thread conversation

查看工单对话

Get thread:
```
thread get th_...
```
Fetch timeline entries:
```
thread timeline th_... --first 50
```
Extract messages: Look for
```
EmailEntry
```
,
```
ChatEntry
```
,
```
SlackMessageEntry
```
, etc. in the response
Paginate if needed: Use
```
--after
```
with cursor from
```
pageInfo.endCursor
```

获取工单：
```
thread get th_...
```
获取时间线条目：
```
thread timeline th_... --first 50
```
提取消息：在响应结果中查找
```
EmailEntry
```
、
```
ChatEntry
```
、
```
SlackMessageEntry
```
等类型
如需分页：使用
```
--after
```
参数并传入
```
pageInfo.endCursor
```
中的游标

Add internal note to thread

为工单添加内部备注

Get thread ID from URL or search:
```
thread search "issue keyword"
```

Add note:

thread note th_... --text "Investigation notes here"

Verify in timeline:
```
thread timeline th_... --first 5
```

通过URL或搜索获取工单ID：
```
thread search "issue keyword"
```

添加备注：

thread note th_... --text "Investigation notes here"

在时间线中验证：
```
thread timeline th_... --first 5
```

Create or update help article

创建或更新帮助中心文章

List help centers:
```
helpcenter list
```
Write HTML content to a file (for large articles):
```
/tmp/article.html
```

Create/update article:

bash

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

Use the returned link to view/edit in Plain UI

列出帮助中心：
```
helpcenter list
```
将HTML内容写入文件（适用于大篇幅文章）：
```
/tmp/article.html
```

创建/更新文章：

bash

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

使用返回的link在Plain UI中查看/编辑

Entity Reference

实体参考

See references/ENTITIES.md for detailed documentation on all entities including:

Customer fields and statuses
Thread status, priority, and channels
Timeline entry types (24 types: emails, chats, notes, events, status changes, etc.)
Company and Tenant structures
Label and LabelType definitions
Help Center, Article, and ArticleGroup schemas
Tier and SLA configurations

查看references/ENTITIES.md获取所有实体的详细文档，包括：

客户字段与状态
工单状态、优先级与渠道
时间线条目类型（24种：邮件、聊天、备注、事件、状态变更等）
公司与租户结构
标签与标签类型定义
帮助中心、文章与文章分组架构
服务等级与SLA配置

Environment Variables

环境变量

Variable	Required	Description
`PLAIN_API_KEY`	Yes	Your Plain API key
`PLAIN_API_URL`	No	API endpoint (default: `https://core-api.uk.plain.com/graphql/v1` )

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

Output Format

输出格式

All commands return JSON. Use

jq

for parsing:

bash

undefined

所有命令均返回JSON格式结果，可使用

jq

进行解析：

bash

undefined

Get just customer name

仅获取客户姓名

scripts/plain-api.sh customer get c_01ABC... | jq '.data.customer.fullName'

Get thread IDs

获取工单ID列表

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 "Test" | jq -r '.link'

undefined

scripts/plain-api.sh helpcenter article upsert hc_... --title "Test" --content "Test" | jq -r '.link'

undefined

plain-support

Original

Translation

Plain API Skill

Plain API Skill

Prerequisites

前置条件

Quick Reference

快速参考

Customers (Read Only)

客户（只读）

List customers

列出客户

Get customer by ID

通过ID获取客户

Get customer by email

通过邮箱获取客户

Get customer by external ID

通过外部ID获取客户

Search customers

搜索客户

Threads (Read + Write)

工单（可读可写）

List threads (TODO status by default)

列出工单（默认显示TODO状态）

List all threads including done

列出所有工单（包括已完成）

List done threads

列出已完成工单

List threads by priority

按优先级列出工单

Get thread details

获取工单详情

Search threads

搜索工单

Get thread timeline (all messages, events, status changes)

获取工单时间线（所有消息、事件、状态变更）

Paginate through timeline

分页查看时间线

Add a note to a thread (internal note, not visible to customer)

为工单添加备注（内部备注，客户不可见）

Add a note with markdown formatting

添加带Markdown格式的备注

Add a note from a file (for longer notes)

从文件导入备注内容（适用于长备注）

Companies (Read Only)

公司（只读）

List companies

列出公司

Get company by ID

通过ID获取公司

Tenants (Read Only)

租户（只读）

List tenants

列出租户

Get tenant by ID

通过ID获取租户

Labels (Read Only)

标签（只读）

List available label types

列出可用标签类型

Help Center (Read + Write)

帮助中心（可读可写）

List help centers

列出帮助中心

Get help center details

获取帮助中心详情

List articles in help center

列出帮助中心内的文章

Get article by ID

通过ID获取文章

Get article by slug

通过别名获取文章

Create new article (defaults to DRAFT status)

创建新文章（默认状态为DRAFT）

Create and publish article directly

创建并直接发布文章

Update existing article

更新现有文章

Use --content-file for large HTML content (recommended)