plain-support

Plain API スキル

GraphQL API を通じて Plain カスタマーサポートプラットフォームにアクセスします。このスキルでは、顧客、サポートスレッド、タイムラインエントリー、ヘルプセンターのコンテンツ、ブロードキャストなどを読み取るコマンドを利用できます。スレッドにメモを追加できます。ヘルプセンターの記事は直接作成、更新、公開できます。ブロードキャストとブロードキャストのオーディエンスは下書きの作成と編集ができますが、スケジュール設定や送信はできません。

前提条件

• API キーを設定した PLAIN_API_KEY 環境変数
• 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> として渡します

注意：

• Plain がメタデータを解決するには、ワークスペースで関連する連携（例：GitHub）が設定されている必要があります。設定されていない場合、add 呼び出しはエラーを返します。
• API キー経由でのリンク削除はサポートされていません。Plain の UI から削除してください。
• Plain はマシンユーザーに searchThreadLinkCandidates を公開していないため、エージェントが 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...

記事の upsert オプション：

オプション	必須	説明
--title	はい	記事のタイトル
--description	はい	短い説明（記事一覧に表示されます）
--content	はい*	HTML コンテンツ（インライン）
--content-file	はい*	HTML コンテンツを含むファイルのパス
--id	いいえ	記事 ID（更新用）
--group	いいえ	記事グループ ID
--status	いいえ	DRAFT（デフォルト）または PUBLISHED

*--content または --content-file のいずれかが必須です。コンテンツが大きい場合は --content-file を使用してください。

注： レスポンスには、Plain UI で記事を編集するための URL を含む link フィールドがあります。

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

ブロードキャスト（読み取り＋書き込み）

ブロードキャストとは、1つのメッセージを複数の 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 を実行すると、保存済みフィルターがすべて置き換えられます。マージは行われません。行を1つ追加するだけの場合は、先に 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. 必要に応じてページネーションします：pageInfo.endCursor のカーソルを --after に指定します

スレッドに内部メモを追加する

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 の定義
• ヘルプセンター、記事、記事グループのスキーマ
• ティアと 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'