# プッシュ通知を作成 (POST)

デバイスにプッシュ通知を送信します。

## エンドポイント

```
POST https://api.pocketalert.app/v1/messages
```

## 認証

> **Info: 必須**
>
> リクエストに次のいずれかのヘッダーを含めてください:
> - `Token: <your-api-key>` — [API キー](https://pocketalert.app/account/apikeys)から取得できます
> - `Authorization: Bearer <jwt-token>` — [ログイン](https://info.pocketalert.app/api/user/login.md)から取得できます

## リクエスト

### ヘッダー

| ヘッダー | 必須 | 説明 |
|--------|:--------:|-------------|
| `Content-Type` | ✅ | `application/json` |
| `Token` | ✅ | API キー |
| `Authorization` | ✅ | `Bearer <jwt-token>` |

<small>* `Token` または `Authorization` のいずれかが必須です</small>

### ボディパラメーター

| パラメーター | 型 | 必須 | 説明 |
|-----------|------|:--------:|-------------|
| `title` | string | ✅ | 通知のタイトル |
| `message` | string | ✅ | 通知の本文 |
| `application_id` | string | ❌ | メッセージを分類するためのアプリケーション TID |
| `device_id` | string | ❌ | 特定のデバイス TID。省略すると全デバイスに送信されます |
| `level` | string \| int | ❌ | プッシュ通知の配信方法を制御する優先度レベル。名前または整数（`-2`..`2`）を指定できます。`priority` も同義語として使えます。省略時はアプリケーションの既定レベル、その後 `default` が使われます。 |
| `actions` | array | ❌ | 通知に表示するアクションボタン（最大 3 つ）。[アクションボタン](#action-buttons)を参照してください。 |
| `send_at` | string \| int | ❌ | 即時ではなく指定した時刻に配信します。RFC3339、Unix タイムスタンプ、または `YYYY-MM-DD HH:MM` を指定できます。[予約送信](#scheduled-delivery)を参照してください。 |
| `delay` | string | ❌ | 相対的な遅延後に配信します（`30m`、`2h`、または秒数のみ）。`send_at` とは同時に指定できません。 |

#### アクションボタン

各通知には、アクションボタンを最大 **3** 個含められます。アプリが開いている場合、バックグラウンドの場合、終了している場合のいずれでも動作します。`actions` はオブジェクトの配列で、JSON エンコード後のサイズは最大 2048 バイトです（プッシュ通知全体の上限は 4 KB のため、この中に含まれます。長い `message` は、収まるように短縮されます）:

| フィールド | 型 | 必須 | 説明 |
|-------|------|:--------:|-------------|
| `type` | string | ✅ | `view`（URL を開く）、`http`（HTTP リクエストを送信）、または `copy`（テキストをクリップボードにコピー） |
| `label` | string | ✅ | ボタンのテキスト。Android と iOS でそのまま表示されます |
| `value` | string | ✅ | `type` によって異なります。下記を参照してください |

型ごとの `value`:

- **`view`** — 開く URL。例: `"https://pocketalert.app"`
- **`http`** — リクエストを記述した JSON 文字列: `{"url":"https://…","method":"POST","headers":{…},"body":"…"}`。`url` のみ必須で、`method` の既定値は `GET` です。アプリを開かずにデバイスからバックグラウンドで送信されるため、スマホのローカルネットワーク内のホストにも届きます。リクエストが失敗した場合（2xx/3xx 以外のステータスまたはネットワークエラー）、**再試行**ボタン付きの通知が表示されます。サーバーに届いた可能性がある場合は、自動的に再試行されることはありません。
- **`copy`** — クリップボードに置くリテラルのテキスト。

> **Tip: 人の確認を挟む**
>
> `http` アクションを 2 つ（例: **承認** / **却下**）設定すると、ワンタップの操作パネルになります。LLM エージェントの操作を、通知から直接承認するのに最適です。

> **Warning: 有料機能**
>
> 無料プランではアクションボタンは削除されます。メッセージはボタンなしで配信され、`actions` の検証も行われません。

上限、検証、Webhook テンプレートについては [アクションボタン](https://info.pocketalert.app/features/action-buttons.md)を参照してください。

#### 優先度レベル

| レベル | 別名 | 動作 |
|-------|---------|----------|
| `silent` | `min`, `-2` | トレイにのみ配信され、音もバイブレーションもありません |
| `low` | `-1` | 静かに届き、割り込みません |
| `default` | `normal`, `0`（または省略時） | 標準のバナーと通知音 |
| `high` | `1` | 時間に敏感な通知です。集中モードや予約サマリーを突破して届きます |
| `critical` | `max`, `urgent`, `2` | サイレントスイッチやおやすみモードを無視してデバイスを起動します。[優先度レベル](https://info.pocketalert.app/features/priority-levels.md)を参照してください |

> **Warning**
>
> `critical` は有料プランの機能です。無料プランでは自動的に `high` に格下げされます。無効な値（不明な名前や範囲外の整数）の場合は `400` が返されます。

各レベルが iOS と Android でどのように動作するかについては、[優先度レベル](https://info.pocketalert.app/features/priority-levels.md)を参照してください。

#### 予約送信

`send_at` または `delay` のどちらか一方を指定すると（両方の指定は不可）、メッセージは即時送信されず、暗号化されて配信時刻まで保存されます。

| パラメーター | 指定できる形式 | 例 |
|-----------|---------|----------|
| `send_at` | RFC3339、Unix タイムスタンプ、または `YYYY-MM-DD HH:MM` | `2026-08-15T09:00:00Z`, `1786867200` |
| `delay` | Go 形式の期間、または秒数のみ | `30m`, `2h`, `3600` |

タイムゾーンのオフセットを含まない時刻は、アカウントのタイムゾーンとして解釈されます。予約可能な期間は 30 日までです。過去の `send_at` は `400` を返します（時計のずれを考慮し、60 秒の許容があります）。

予約送信のリクエストは、配信済みのメッセージではなく、`201` と `"scheduled": true`、`status`、`deliver_at`、`deliver_at_utc` を返します。一覧は `GET /v1/messages/scheduled` で取得し、キャンセルは `DELETE /v1/messages/scheduled/{tid}` で行います。詳しくは[予約送信](https://info.pocketalert.app/features/scheduled-delivery.md)を参照してください。

> **Warning**
>
> 予約送信は有料プランの機能です。無料プランで `send_at` または `delay` を使用したリクエストは `403` を返します。

### リクエスト例

**cURL**

```bash
curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Server Alert",
    "message": "CPU usage exceeded 90%",
    "application_id": "qm47b9pzxzxg",
    "level": "critical",
    "actions": [
      { "type": "view", "label": "Dashboard", "value": "https://status.example.com" },
      { "type": "http", "label": "Restart", "value": "{\"url\":\"https://ops.example.com/restart\",\"method\":\"POST\"}" },
      { "type": "copy", "label": "Copy ID", "value": "incident-4821" }
    ]
  }'
```

**JavaScript**

```javascript
const response = await fetch('https://api.pocketalert.app/v1/messages', {
  method: 'POST',
  headers: {
    'Token': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Server Alert',
    message: 'CPU usage exceeded 90%',
    application_id: 'qm47b9pzxzxg'
  })
});

const data = await response.json();
console.log(data);
```

**Python**

```python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/messages',
    headers={
        'Token': 'your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Server Alert',
        'message': 'CPU usage exceeded 90%',
        'application_id': 'qm47b9pzxzxg'
    }
)

print(response.json())
```

**PHP**

```php
$response = Http::withHeaders([
    'Token' => 'your-api-key',
])->post('https://api.pocketalert.app/v1/messages', [
    'title' => 'Server Alert',
    'message' => 'CPU usage exceeded 90%',
    'application_id' => 'qm47b9pzxzxg',
]);

return $response->json();
```

## レスポンス

### 成功時のレスポンス

> **Tip: 201 Created**
>
> メッセージの作成に成功しました

| フィールド | 型 | 説明 |
|-------|------|-------------|
| `tid` | string | メッセージの一意な識別子 |
| `title` | string | メッセージのタイトル |
| `message` | string | メッセージの本文 |
| `application` | string | アプリケーション名（指定した場合） |
| `device` | string | 送信先デバイス名 |
| `actions` | array | 送信されたアクションボタン（指定した場合のみ返されます） |
| `created_at` | string | 作成日時 |

```json
{
  "tid": "jb4xw9elz28g",
  "title": "Server Alert",
  "message": "CPU usage exceeded 90%",
  "application": "Monitoring",
  "device": "iPhone",
  "actions": [
    { "type": "view", "label": "Dashboard", "value": "https://status.example.com" }
  ],
  "created_at": "18.01.2026 15:35:35"
}
```

### クォータのヘッダー

レスポンスには、本日の [1 日の上限](https://info.pocketalert.app/features/daily-limits.md)の使用状況が含まれます（無制限プランでは省略されます）:

| ヘッダー | 説明 |
|--------|-------------|
| `X-PA-Daily-Limit` | お使いのプランで 1 日に送信できるメッセージ数 |
| `X-PA-Daily-Remaining` | 今回のメッセージを含めた後、本日残りの送信可能数 |
| `X-PA-Daily-Reset` | 次回リセット（00:00 UTC）の Unix タイムスタンプ（秒） |

### エラーレスポンス

| ステータス | 説明 |
|:------:|-------------|
| `400` | 不正なリクエスト — `title` または `message` の欠落、無効な `level`、または有料プランでの無効な `actions` |
| `401` | 認証エラー — トークンが無効または未指定です |
| `403` | 禁止 — 無料プランで `send_at` または `delay` を使用しています |
| `404` | 見つかりません — `application_id` または `device_id` が存在しません |
| `429` | 1 日の上限に到達 — メッセージは保存も送信もされていません。`Retry-After` の秒数だけ待つか、プランをアップグレードしてください。[1 日のメッセージ上限](https://info.pocketalert.app/features/daily-limits.md)を参照してください。 |

```json
{
  "error": "Validation failed",
  "details": {
    "title": ["The title field is required"]
  }
}
```

#### 1 日の上限に到達

本日の上限を使い切ると、メッセージはキューに入れられず拒否されます。00:00 UTC までこの状態が続きます。`Retry-After` には、リセットまでの残り秒数が入ります。

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 30142
X-PA-Daily-Limit: 50
X-PA-Daily-Remaining: 0
X-PA-Daily-Reset: 1790035200
```

```json
{
  "error": "Daily message limit reached (50/50). New messages are rejected until 00:00 UTC. Upgrade your plan to raise the limit.",
  "limit": 50,
  "used": 50,
  "resets_at": "2026-09-22T00:00:00Z",
  "upgrade_url": "https://pocketalert.app/pricing"
}
```

メッセージを削除しても、上限は回復しません。本日の使用状況は [`GET /v1/messages/usage`](https://info.pocketalert.app/api/messages/usage.md) で確認できます。
