# アクションボタン

通知には最大 3 つのボタンを付けられます。アラートを読んでからパソコンを開いて対応する代わりに、ロック画面から直接操作できます。実行の確認、再起動の実行、コードのコピーなどがその場でできます。

## 3 つのタイプ

| タイプ | ボタンの動作 | `value` に入れる内容 |
|------|----------------------|---------------|
| `view` | URL を開く | URL（例: `https://status.example.com`） |
| `http` | バックグラウンドで HTTP リクエストを送信する | JSON 文字列: `{"url":"…","method":"POST","headers":{…},"body":"…"}` |
| `copy` | テキストをクリップボードにコピーする | コピーする文字列そのもの |

`http` の場合、必須なのは `url` だけです。`method` を省略すると `GET` になります。`body` があり、Content-Type が未指定の場合は `Content-Type: application/json` が自動で追加されます。

`http` と `copy` は、アプリが閉じていてもアプリを開かずに実行されます。`view` は、アプリまたはブラウザを前面に表示します。

## ボタンが表示される場所

ボタンは iOS と Android のどちらでも、システムの通知に表示されます。アプリが開いていても、バックグラウンドでも、閉じていても同じです。メッセージ自体の中にも表示されます。バナーをスワイプして消しても、後からメッセージを開けばボタンは残っています。

- **ラベル**は、送信したとおりに両方のプラットフォームで表示されます。iOS でカスタムボタンの準備が間に合わない場合は、タイプごとの汎用ラベル（**Open**、**Run**、**Copy**）に切り替わります。ボタン自体は引き続き動作します。
- **ロック画面。** `http` と `copy` は、ロックを解除しなくてもロック画面から実行できます。`view` はアプリまたはブラウザを開くため、先にロック解除が求められます。Android では、ロック画面に通知内容を表示する設定になっている場合のみ、ロック画面にボタンが表示されます。
- **リクエストの失敗。** `http` リクエストが失敗した場合（2xx/3xx 以外のステータス、またはネットワークエラー）、**Retry** ボタン付きの通知が表示されます。サーバーに届いた可能性があるリクエストは、自動では再送されません。
- **アプリのバージョン。** システム通知のボタンには Pocket Alert アプリ 2.0.1 以降が必要です。古いバージョンでは、ボタンはメッセージの中にだけ表示されます。

## 承認ワークフロー

**Approve** と **Decline** の 2 つの `http` ボタンを使うと、通知をワンタップで操作できるコントロールパネルにできます。人の判断を待って止まっているあらゆる処理に使えます。

- 手動承認を待って止まっているデプロイパイプライン
- お金を使ったり本番環境に触れたりする前に承認が必要な LLM エージェント
- しきい値を超える返金
- ドア、ゲート、照明、ガレージ

リクエストはスマホからお使いのエンドポイントへ直接送られます。Pocket Alert が中継することはなく、レスポンスの本文も見ることはありません。

> **Warning: 冪等性はご自身で確保してください**
>
> 同じ `http` ボタンを 2 回タップすると、リクエストも 2 回送信されます。繰り返しの送信は Pocket Alert ではブロックしません。二重実行のコストが高い場合は、エンドポイントを冪等にしてください。

## Webhook からのボタン

Webhook には `%path%` プレースホルダーを含むアクションテンプレートを設定でき、受信したペイロードの値で埋められます。Sentry のアラートでは、その特定の issue を指す **Open issue** ボタンが動作する状態で届きます。Stripe のイベントでは、その決済に対する **View payment** ボタンが付きます。

置換される値は、テンプレートを解析する前に JSON エスケープされます。そのため、引用符を含むペイロードのフィールドが URL を壊して書き換えることはありません。ボタンが無効な値になった場合（例: アラートに Runbook URL がないのに **Runbook** ボタンを付けようとした場合）は、そのボタンだけが除外されます。残りのボタンとメッセージは引き続き配信されます。不正なボタンが原因でアラートが届かなくなることはありません。

テンプレートは、Webhook を作成または編集するときにコンソールで設定できます。または、[Webhook API](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template) から設定することもできます。

## 上限とバリデーション

- 1 つのメッセージにつき最大 **3** 個のボタンを付けられます。送信した順に表示されます。
- `actions` 配列は JSON エンコード後に最大 **2048 バイト**です。プッシュ通知全体の上限は 4 KB のため、その中に収まるよう長い `message` は短縮されます。
- `view` と `http` には有効な `http(s)` URL が必要です。それ以外は API で `400` を返します。Webhook テンプレートでは、無効なボタンは除外されます。
- 未知の `type` の値は `400` を返します。

> **Warning: 有料機能**
>
> アクションボタンは、無料プランのメッセージからサーバー側で取り除かれます。メッセージ自体は通常どおり配信されます。

## 関連

- [メッセージ作成](https://info.pocketalert.app/api/messages/create.md) — `actions` 配列と完全なリクエストリファレンス
- [優先度レベル](https://info.pocketalert.app/features/priority-levels.md) — アラートがどの程度目立つか
- [Webhook 設定](https://info.pocketalert.app/api/webhooks/settings.md) — 受信 Webhook のアクションテンプレート
