プッシュ通知を作成 POST
デバイスにプッシュ通知を送信します。
エンドポイント
POST https://api.pocketalert.app/v1/messages認証
必須
リクエストに次のいずれかのヘッダーを含めてください:
リクエスト
ヘッダー
| ヘッダー | 必須 | 説明 |
|---|---|---|
Content-Type | ✅ | application/json |
Token | ✅ | API キー |
Authorization | ✅ | Bearer <jwt-token> |
* Token または Authorization のいずれかが必須です
ボディパラメーター
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
title | string | ✅ | 通知のタイトル |
message | string | ✅ | 通知の本文 |
application_id | string | ❌ | メッセージを分類するためのアプリケーション TID |
device_id | string | ❌ | 特定のデバイス TID。省略すると全デバイスに送信されます |
level | string | int | ❌ | プッシュ通知の配信方法を制御する優先度レベル。名前または整数(-2..2)を指定できます。priority も同義語として使えます。省略時はアプリケーションの既定レベル、その後 default が使われます。 |
actions | array | ❌ | 通知に表示するアクションボタン(最大 3 つ)。アクションボタンを参照してください。 |
send_at | string | int | ❌ | 即時ではなく指定した時刻に配信します。RFC3339、Unix タイムスタンプ、または YYYY-MM-DD HH:MM を指定できます。予約送信を参照してください。 |
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— クリップボードに置くリテラルのテキスト。
人の確認を挟む
http アクションを 2 つ(例: 承認 / 却下)設定すると、ワンタップの操作パネルになります。LLM エージェントの操作を、通知から直接承認するのに最適です。
有料機能
無料プランではアクションボタンは削除されます。メッセージはボタンなしで配信され、actions の検証も行われません。
上限、検証、Webhook テンプレートについては アクションボタンを参照してください。
優先度レベル
| レベル | 別名 | 動作 |
|---|---|---|
silent | min, -2 | トレイにのみ配信され、音もバイブレーションもありません |
low | -1 | 静かに届き、割り込みません |
default | normal, 0(または省略時) | 標準のバナーと通知音 |
high | 1 | 時間に敏感な通知です。集中モードや予約サマリーを突破して届きます |
critical | max, urgent, 2 | サイレントスイッチやおやすみモードを無視してデバイスを起動します。優先度レベルを参照してください |
WARNING
critical は有料プランの機能です。無料プランでは自動的に high に格下げされます。無効な値(不明な名前や範囲外の整数)の場合は 400 が返されます。
各レベルが iOS と Android でどのように動作するかについては、優先度レベルを参照してください。
予約送信
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} で行います。詳しくは予約送信を参照してください。
WARNING
予約送信は有料プランの機能です。無料プランで send_at または delay を使用したリクエストは 403 を返します。
リクエスト例
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" }
]
}'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);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())$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();レスポンス
成功時のレスポンス
201 Created
メッセージの作成に成功しました
| フィールド | 型 | 説明 |
|---|---|---|
tid | string | メッセージの一意な識別子 |
title | string | メッセージのタイトル |
message | string | メッセージの本文 |
application | string | アプリケーション名(指定した場合) |
device | string | 送信先デバイス名 |
actions | array | 送信されたアクションボタン(指定した場合のみ返されます) |
created_at | string | 作成日時 |
{
"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 日の上限の使用状況が含まれます(無制限プランでは省略されます):
| ヘッダー | 説明 |
|---|---|
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 日のメッセージ上限を参照してください。 |
{
"error": "Validation failed",
"details": {
"title": ["The title field is required"]
}
}1 日の上限に到達
本日の上限を使い切ると、メッセージはキューに入れられず拒否されます。00:00 UTC までこの状態が続きます。Retry-After には、リセットまでの残り秒数が入ります。
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{
"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 で確認できます。