通知の送信

必要なもの

notify または full スコープの API キー
通知を送るアプリの App ID

全購読者への送信

アプリの全アクティブ購読者に通知を送ります。

curl -X POST https://api.todoke.dev/api/v1/notify \
  -H "Authorization: Bearer pk_notify_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "新着情報",
    "body": "アップデートがあります",
    "url": "https://yourapp.com/news",
    "icon": "https://yourapp.com/icon.png"
  }'

import { PushCF } from "@elchika-inc/todoke";

const client = new PushCF({
  apiKey: "pk_notify_key",
});

await client.notify({
  title: "新着情報",
  body: "アップデートがあります",
  url: "https://yourapp.com/news",
  icon: "https://yourapp.com/icon.png",
});

await fetch("https://api.todoke.dev/api/v1/notify", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pk_notify_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "新着情報",
    body: "アップデートがあります",
    url: "https://yourapp.com/news",
  }),
});

特定ユーザーへの送信

endpoint フィールドを指定すると、その購読者のみに送信できます。

curl -X POST https://api.todoke.dev/api/v1/notify \
  -H "Authorization: Bearer pk_notify_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "あなた宛のメッセージ",
    "body": "個別通知です",
    "endpoint": "https://fcm.googleapis.com/fcm/send/..."
  }'

バッチ送信（複数エンドポイントへの一括送信）

POST /api/v1/notify/batch を使うと、同じ内容の通知を複数の endpoint へ一度にまとめて送信できます。

curl -X POST https://api.todoke.dev/api/v1/notify/batch \
  -H "Authorization: Bearer pk_notify_key" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoints": ["https://fcm.googleapis.com/fcm/send/aaa", "https://fcm.googleapis.com/fcm/send/bbb"],
    "payload": { "title": "新着情報", "body": "アップデートがあります", "url": "https://yourapp.com/news" }
  }'
# → 202 { "queued": 2 }

フィールド	型	必須	説明
`endpoints`	string[]	✅	送信先 endpoint の一覧。最大 100 件（超過時は 400 `TOO_MANY_ENDPOINTS`）
`payload.title`	string	✅	通知タイトル
`payload.body`	string	✅	通知本文
`payload.url`	string	—	クリック時の遷移先 URL（https:// のみ）
`dry_run`	boolean	—	`true` の場合は検証と送信見込み件数の取得だけを行う

dry run で送信前に件数を確認する

dry_run: true を指定すると、実送信と同じ入力・URL・ペイロードサイズ・プラン上限・レート制限の検証を行い、Queue へ投入せずに送信見込み件数を返します。notification_logs と monthly_usage も更新しません。

curl -X POST https://api.todoke.dev/api/v1/notify \
  -H "Authorization: Bearer pk_notify_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "新着情報",
    "body": "アップデートがあります",
    "dry_run": true
  }'
# → 200 { "ok": true, "dry_run": true, "queued": 0, "would_send": 42 }

POST /api/v1/notify では、endpoint を省略するとアプリの有効購読者数、指定するとその endpoint が同じアプリの有効購読なら 1、そうでなければ 0 を返します。POST /api/v1/notify/batch でも body のトップレベルに dry_run: true を指定でき、endpoints に一致する有効購読者を重複なしで数えます。dry run の成功応答には send_id は含まれません。

リクエストパラメータ

フィールド	型	必須	説明
`title`	string	✅	通知タイトル
`body`	string	✅	通知本文
`url`	string	—	クリック時の遷移先 URL
`icon`	string	—	通知アイコン URL
`badge`	string	—	バッジアイコン URL
`endpoint`	string	—	指定時はこの購読者のみに送信
`dry_run`	boolean	—	`true` の場合は検証と送信見込み件数の取得だけを行う

title と body は必須です。url / icon / badge は https:// の URL のみ許可され、http:// を指定すると 400 INVALID_URL が返ります。

制限とエラー

ペイロードサイズ: title / body / url / icon / badge の合計が 3,072 バイトまで（超過時は 413 PAYLOAD_TOO_LARGE）
月間送信数: Free プランは 30,000 通まで（超過時は 429 MONTHLY_LIMIT_EXCEEDED、upgrade_url 付き）
URL 形式: url / icon / badge は https:// のみ（400 INVALID_URL）

エラーコードの全一覧はエラーコード・制限値を参照してください。

送信の仕組み

REST API → Cloudflare Queues → Queue Consumer Worker → ブラウザへ Push

通知はリクエスト受信後すぐに Queue に enqueue されます。Consumer Worker が自動起動して非同期に送信するため、大量の購読者がいてもタイムアウトしません。