Firebase で AI 搭載アプリを構築して実行する方法のデモを、2024 年の Demo Day でご覧ください。ぜひご覧ください。

Firebase Cloud Messaging の HTTP プロトコル

このドキュメントでは、Firebase Cloud Messaging 経由でアプリサーバーからクライアントアプリにメッセージを渡すために使用される HTTP 構文のリファレンスを示します。

以前の HTTP プロトコルを使用する場合、アプリサーバーはすべての HTTP リクエストを次のエンドポイントに送信する必要があります。

https://fcm.googleapis.com/fcm/send

使用できるパラメータとオプションは、次の大きなカテゴリに分類されます。

ダウンストリームメッセージの構文
ダウンストリームメッセージのエラーレスポンスコード

ダウンストリームメッセージの構文

このセクションでは、Firebase Cloud Messaging からダウンストリームメッセージを送信し、HTTP レスポンスを解釈するための構文を示します。

ダウンストリーム HTTP メッセージ（JSON）

次の表は、HTTP JSON メッセージのターゲット、オプション、ペイロードを示しています。

表 1.ダウンストリーム HTTP メッセージ（JSON）のターゲット、オプション、ペイロード

パラメータ	指定方法	説明
ターゲット
`to`	省略可、文字列	このパラメータでは、メッセージの受信者を指定します。指定できる値は、デバイスの登録トークン、デバイスグループの通知キー、または（`/topics/` の接頭辞が付いた）単一のトピックです。複数のトピックに送信するには、`condition` パラメータを使用します。
`registration_ids`	省略可、文字列の配列	このパラメータは、複数の登録トークンに送信されるマルチキャストメッセージの受信者を指定します。値には、マルチキャストメッセージの送信先となる登録トークンの配列を指定します。配列には少なくとも 1 つの登録トークンが含まれている必要があります。指定可能な最大登録トークン数は 1,000 個です。単一のデバイスにメッセージを送信するには、`to` パラメータを使用します。マルチキャストメッセージには HTTP JSON 形式のみを使用できます。
`condition`	省略可、文字列	このパラメータでは、メッセージのターゲットを決定する条件の論理式を指定します。サポートされる条件: 「'yourTopic' in topics」の形式で表したトピック。この値は大文字と小文字が区別されません。サポートされる演算子: `&&`、`\|\|`。トピックメッセージ 1 つあたり演算子は 2 つまで使用できます。
`notification_key` 非推奨	省略可、文字列	このパラメータは廃止されました。代わりに、`to` を使用してメッセージの受信者を指定してください。複数のデバイスにメッセージを送信する方法の詳細については、お使いのプラットフォームのドキュメントをご覧ください。
オプション
`collapse_key`	省略可、文字列	このパラメータは、配信が再開されるときに最後のメッセージだけが送信されるように、折りたたみ可能なメッセージのグループを（たとえば `collapse_key: "Updates Available"` により）識別します。これは、デバイスがオンラインに戻るか、アクティブになったときに、同じメッセージが過剰に送信されないようにするためのものです。メッセージが送信される順序は保証されません。注: 任意の時点で最大 4 つの異なる折りたたみキーを使用できます。つまり、FCM はクライアントアプリごとに 4 つの異なるメッセージを同時に保存できます。この数を超えた場合、FCM が保存する 4 つの折りたたみキーがどれになるかは保証されません。
`priority`	省略可、文字列	メッセージの優先度を設定します。有効な値は「normal」と「high」です。Apple プラットフォームでは、これらは APNs 優先度の 5 と 10 に相当します。デフォルトでは、通知メッセージは high（高）の優先度で送信され、データメッセージは normal（標準）の優先度で送信されます。優先度が normal の場合、クライアントアプリのバッテリー消費量が最適化されるため、すぐに配信する必要がない限り、これを使用してください。この優先度を指定されたメッセージは、アプリで受信されるまでに不特定の遅延が発生する可能性があります。優先度が high のメッセージはすぐに送信され、アプリに通知が表示されます。
`content_available`	省略可、ブール値	Apple プラットフォームでは、このフィールドを使用して APNs ペイロード内の `content-available` を表します。通知やメッセージの送信時にこのフィールドが `true` に設定されている場合、非アクティブなクライアントアプリのスリープ状態が解除されます。また、メッセージは FCM ではなく APNs を介して、サイレント通知として送信されます。APNs のサイレント通知の配信は保証されておらず、ユーザーが [低電力モード] をオンにする、アプリを強制終了するなどの要因によって結果が異なる場合があるので注意してください。Android では、デフォルトでデータメッセージによってアプリが復帰します。Chrome では現在サポートされていません。
`mutable_content`	省略可、JSON ブール値	Apple プラットフォームでは、このフィールドを使用して APNs ペイロード内の `mutable-content` を表します。通知の送信時にこのフィールドが `true` に設定されている場合、その通知が表示される前に通知サービスアプリ拡張機能を使って通知の内容を変更できます。このパラメータは Android とウェブでは無視されます。
`time_to_live`	省略可、数値	このパラメータでは、デバイスがオフラインの場合にメッセージを FCM のストレージに保持する期間（秒単位）を指定します。サポートされている最大有効期間は 4 週間で、デフォルト値は 4 週間です。詳細については、メッセージの有効期間の設定をご覧ください。
`restricted_package_ name`（Android のみ）	省略可、文字列	このパラメータは、アプリケーションのパッケージ名を指定します。メッセージを受信するには登録トークンがこの値と一致している必要があります。
`dry_run`	省略可、ブール値	このパラメータが `true` に設定されている場合、デベロッパーは実際にメッセージを送信せずにリクエストをテストできます。デフォルト値は `false` です。
ペイロード
`data`	省略可、オブジェクト	このパラメータは、メッセージのペイロードのカスタム Key-Value ペアを指定します。たとえば、`data:{"score":"3x1"}:` と指定した場合は次のようになります。 Apple プラットフォームでは、メッセージが APNs 経由で送信された場合、カスタムデータフィールドを表します。FCM 経由で送信された場合は、`AppDelegate application:didReceiveRemoteNotification:` で Key-Value の辞書として表されます。 Android では、`score` というインテントの extra に文字列値 `3x1` が設定されます。キーを予約語（「from」や「message_type」、または「google」や「gcm」で始まる語）にすることはできません。この表に定義されたどの単語も使用しないでください（`collapse_key` など）。値は文字列型にすることをおすすめします。オブジェクトに含まれる値や文字列型以外のデータ型（整数またはブール値）は、文字列型に変換する必要があります。
`notification`	省略可、オブジェクト	このパラメータは、通知ペイロードの事前定義されたユーザー表示用の Key-Value ペアを指定します。詳細については、通知ペイロードのサポートをご覧ください。通知メッセージとデータメッセージのオプションの詳細については、メッセージタイプをご覧ください。通知ペイロードが提供されている場合、または Apple デバイスへのメッセージについて `content_available` オプションが `true` に設定されている場合は、メッセージは APNs を介して送信されます。それ以外の場合は、FCM を介して送信されます。

通知ペイロードのサポート

次の表は、iOS および Android 用の通知メッセージの構築に使用できる事前定義されたキーの一覧を示しています。

表 2a. iOS - 通知メッセージのキー

パラメータ	指定方法	説明
`title`	省略可、文字列	通知のタイトル。このフィールドはスマートフォンやタブレットには表示されません。
`body`	省略可、文字列	通知の本文。
`sound`	省略可、文字列	デバイスが通知を受信したときに再生される通知音。クライアントアプリのメインバンドル内またはアプリのデータコンテナの `Library/Sounds` フォルダ内にある通知音ファイルを指定する文字列。詳細については、iOS デベロッパーライブラリをご覧ください。
`badge`	省略可、文字列	ホーム画面のアプリアイコンのバッジの値。これを指定しなかった場合、バッジは変更されません。 `0` に設定するとバッジは削除されます。
`click_action`	省略可、文字列	ユーザーが通知をクリックしたときに実行されるアクション。 APNs ペイロード内の `category` に対応します。
`subtitle`	省略可、文字列	通知のサブタイトル。
`body_loc_key`	省略可、文字列	ユーザーの現在のローカライズに合わせて本文テキストをローカライズするために使用する、アプリの文字列リソース内の本文文字列のキー。 APNs ペイロード内の `loc-key` に対応します。詳細については、ペイロードキーのリファレンスとリモート通知内容のローカライズをご覧ください。
`body_loc_args`	省略可、文字列による JSON 配列	ユーザーの現在のローカライズに合わせて本文テキストをローカライズするために使用する、`body_loc_key` で指定された書式指定子を置き換える可変文字列値。 APNs ペイロード内の `loc-args` に対応します。詳細については、ペイロードキーのリファレンスとリモート通知内容のローカライズをご覧ください。
`title_loc_key`	省略可、文字列	ユーザーの現在のローカライズに合わせてタイトルテキストをローカライズするために使用する、アプリの文字列リソース内のタイトル文字列のキー。 APNs ペイロード内の `title-loc-key` に対応します。詳細については、ペイロードキーのリファレンスとリモート通知内容のローカライズをご覧ください。
`title_loc_args`	省略可、文字列による JSON 配列	ユーザーの現在のローカライズに合わせてタイトルテキストをローカライズするために使用する、`title_loc_key` で指定された書式指定子を置き換える可変文字列値。 APNs ペイロード内の `title-loc-args` に対応します。詳細については、ペイロードキーのリファレンスとリモート通知内容のローカライズをご覧ください。

表 2b.Android - 通知メッセージのキー

パラメータ	指定方法	説明
`title`	省略可、文字列	通知のタイトル。
`body`	省略可、文字列	通知の本文。
`android_channel_id`	省略可、文字列	通知のチャネル ID（Android O の新機能）。このチャネル ID を含む通知を受け取るには、アプリが事前にこのチャネル ID を持つチャネルを作成する必要があります。リクエストでこのチャネル ID を送信しなかった場合、または提供されたチャネル ID がアプリによってまだ作成されていない場合は、FCMでは、アプリマニフェストで指定されたチャネル ID が使用されます。
`icon`	省略可、文字列	通知アイコン。通知アイコンをドローアブルリソース `myicon` の `myicon` に設定します。リクエストでこのキーを送信しなかった場合は、FCM　にアプリマニフェストで指定されたランチャーアイコンが表示されます。
`sound`	省略可、文字列	デバイスが通知を受信したときに再生される通知音。 `"default"`、またはアプリにバンドルされた通知音リソースのファイル名を指定できます。通知音ファイルは `/res/raw/` に置く必要があります。
`tag`	省略可、文字列	通知ドロワーにある既存の通知を置き換えるために使用される識別子。指定されていない場合、リクエストごとに新しい通知が作成されます。このタグが指定されていて、同じタグを持つ通知がすでに表示されている場合は、新しい通知によって通知ドロワー内の既存の通知が置き換えられます。
`color`	省略可、文字列	通知のアイコンの色。`#rrggbb` 形式で表します。
`click_action`	省略可、文字列	ユーザーが通知をクリックしたときに実行されるアクション。これが指定されている場合、ユーザーが通知をクリックすると、一致するインテントフィルタを持つアクティビティが起動します。
`body_loc_key`	省略可、文字列	ユーザーの現在のローカライズに合わせて本文テキストをローカライズするために使用する、アプリの文字列リソース内の本文文字列のキー。詳細については、文字列リソースをご覧ください。
`body_loc_args`	省略可、文字列による JSON 配列	ユーザーの現在のローカライズに合わせて本文テキストをローカライズするために使用する、`body_loc_key` で指定された書式指定子を置き換える可変文字列値。詳細については、書式設定とスタイル設定をご覧ください。
`title_loc_key`	省略可、文字列	ユーザーの現在のローカライズに合わせてタイトルテキストをローカライズするために使用する、アプリの文字列リソース内のタイトル文字列のキー。詳細については、文字列リソースをご覧ください。
`title_loc_args`	省略可、文字列による JSON 配列	ユーザーの現在のローカライズに合わせてタイトルテキストをローカライズするために使用する、`title_loc_key` で指定された書式指定子を置き換える可変文字列値。詳細については、書式設定とスタイル設定をご覧ください。

表 2c.ウェブ（JavaScript） — 通知メッセージのキー

パラメータ	指定方法	説明
`title`	省略可、文字列	通知のタイトル。
`body`	省略可、文字列	通知の本文。
`icon`	省略可、文字列	通知のアイコンに使用する URL。
`click_action`	省略可、文字列	ユーザーが通知をクリックしたときに実行されるアクション。すべての URL 値で HTTPS が必須です。

ダウンストリーム HTTP メッセージ（書式なしテキスト）

次の表は、書式なしテキストのダウンストリーム HTTP メッセージに含まれるターゲット、オプション、ペイロードの構文を示しています。

表 3.書式なしテキストのダウンストリーム HTTP メッセージのターゲット、オプション、ペイロード

パラメータ	指定方法	説明
ターゲット
`registration_id`	必須、文字列	このパラメータでは、メッセージを受信するクライアントアプリ（登録トークン）を指定します。マルチキャストメッセージング（複数の登録トークンに送信）には HTTP JSON 形式のみを使用できます。
オプション
`collapse_key`	省略可、文字列	詳細については表 1 を参照してください。
`time_to_live`	省略可、数値	詳細については表 1 を参照してください。
`restricted_package_name`	省略可、文字列	詳細については表 1 を参照してください。
`dry_run`	省略可、ブール値	詳細については表 1 を参照してください。
ペイロード
`data.<key>`	省略可、文字列	このパラメータでは、メッセージのペイロードの Key-Value ペアを指定します。Key-Value パラメータの数に上限はありませんが、合計メッセージサイズは 4,096 バイトまでに制限されています。たとえば、Android で `"data.score"."3x1"` とすると、`score` というインテントの extra に文字列値 `3x1` が設定されます。キーを予約語（「from」や「message_type」、または「google」や「gcm」で始まる語）にすることはできません。この表に定義されたどの単語も使用しないでください（`collapse_key` など）。

ダウンストリームメッセージレスポンスの解釈

FCM から送信されたメッセージレスポンスを解釈するには、アプリサーバーでメッセージレスポンスのヘッダーと本文の両方を評価する必要があります。次の表に想定されるレスポンスを示します。

表 4.ダウンストリーム HTTP メッセージレスポンスヘッダー

レスポンス	説明
200	メッセージは正常に処理されました。レスポンスの本文にはメッセージのステータスに関する詳細が含まれますが、その形式はリクエストが JSON と書式なしテキストのどちらであったかによって異なります。詳細については表 5 を参照してください。
400	JSON リクエストに対してのみ適用されます。リクエストが JSON として解析できなかったか、リクエストに無効なフィールド（数値が期待されている場合に文字列が渡されているなど）が含まれていたことを示します。レスポンスには障害の理由が明記されており、リクエストを再試行する前に、問題に対処する必要があります。
401	送信者アカウントの認証エラーが発生しました。
5xx	500～599 の範囲に含まれるエラー（500 や 503 など）は、リクエストの処理中に FCM 接続サーバーで内部エラーが発生したか、サーバーが（タイムアウトなどの理由で）一時的に利用できないことを示します。送信者はレスポンスに含まれている `Retry-After` ヘッダーを適用し、後で再試行する必要があります。アプリケーションサーバーでは指数バックオフを実装する必要があります。

次の表は、ダウンストリームメッセージレスポンスの本文（JSON）に含まれるフィールドを示しています。

表 5.ダウンストリーム HTTP メッセージレスポンス本文（JSON）

パラメータ	指定方法	説明
`multicast_id`	必須、数値	マルチキャストメッセージを識別する一意の ID（番号）。
`success`	必須、数値	エラーなしで処理されたメッセージの数。
`failure`	必須、数値	処理できなかったメッセージの数。
`results`	必須、オブジェクトの配列	処理されたメッセージのステータスを表すオブジェクトの配列。オブジェクトはリクエストと同じ順序でリストされます（リクエストに含まれる各登録 ID の結果は、レスポンス内にリクエストと同じインデックスで記載されます）。 `message_id`: 正常に処理されたメッセージごとに一意の ID を指定する文字列。 `error`: 受信者のためにメッセージを処理する際に発生したエラーを指定する文字列。想定される値は表 9 に記載されています。

表 6.トピックメッセージの HTTP レスポンス本文（JSON）

パラメータ	指定方法	説明
`message_id`	省略可、数値	FCM が正常にリクエストを受信し、特定のトピックを登録した全デバイスに配信を試みる際のトピックメッセージ ID。
`error`	省略可、文字列	メッセージを処理する際に発生したエラー。想定される値は表 9 に記載されています。

表 7.ダウンストリーム HTTP メッセージレスポンス本文（書式なしテキスト）の正常なレスポンス

パラメータ	指定方法	説明
`id`	必須、文字列	このパラメータでは、FCM によって正常に処理された一意のメッセージ ID を指定します。
`registration_id`	省略可、文字列	このパラメータでは、メッセージが処理され送信されたクライアントアプリの登録トークンを指定します。

表 8.ダウンストリーム HTTP メッセージレスポンス本文（書式なしテキスト）のエラーレスポンス

パラメータ	指定方法	説明
`Error`	必須、文字列	このパラメータでは、受信者のためにメッセージを処理する際のエラー値を指定します。詳細については、表 9 をご覧ください。

ダウンストリームメッセージのエラーレスポンスコード

次の表は、ダウンストリームメッセージのエラーレスポンスコードを示しています。

表 9.ダウンストリームメッセージのエラーレスポンスコード

エラー	HTTP コード	推奨される対処方法
登録トークンが見つからない	200 + error:MissingRegistration	登録トークンがリクエストに含まれているか調べます。書式なしテキストメッセージでは `registration_id` 内、JSON では `to` フィールドまたは `registration_ids` フィールド内を確認してください。
無効な登録トークン	200 + error:InvalidRegistration	サーバーに渡す登録トークンの形式を確認します。Firebase Notifications に登録した際にクライアントアプリが受信する登録トークンと一致している必要があります。文字の追加や削除は行わないでください。
デバイスが登録されていない	200 + error:NotRegistered	次のようないくつかの状況では、既存の登録トークンが有効でなくなることがあります。クライアントアプリが FCM から登録解除した場合。クライアントアプリが自動的に登録解除された場合。これはユーザーがアプリケーションをアンインストールしたときに発生する可能性があります。たとえば iOS で、APNs フィードバックサービスによって APNs トークンが無効であると報告された場合です。登録トークンが期限切れになった場合（たとえば、Google が登録トークンを更新する場合、iOS デバイスの APNs トークンが期限切れになった場合）。クライアントアプリが更新されたが、新しいバージョンはメッセージを受信するように構成されていない場合。上記のすべての状況で、アプリサーバーから既存の登録トークンを削除し、これを使用したメッセージの送信を停止してください。
無効なパッケージ名	200 + error:InvalidPackageName	メッセージの宛先は、リクエストで渡された値に一致するパッケージ名を持つ登録トークンにしてください。
認証エラー	401	メッセージの送信に使用された送信者のアカウントを認証できませんでした。考えられる原因は次のとおりです。認証ヘッダーが見つからないか、HTTP リクエストに含まれた構文が無効です。指定されたサーバーキーの Firebase プロジェクトが正しくありません。以前のサーバーキーのみ - リクエストが、サーバーキーの IP でホワイトリストに登録されていないサーバーから送信されています。認証ヘッダー内で送信しているトークンが、プロジェクトに関連付けられている正しいサーバーキーであることを確認してください。詳細については、サーバーキーの有効性の確認をご覧ください。以前のサーバーキーを使用している場合は、IP 制限のない新しいキーにアップグレードすることをおすすめします。以前のサーバーキーを移行するをご覧ください。
送信者が一致しない	200 + error:MismatchSenderId	登録トークンは、特定の送信者グループに結び付けられています。クライアントアプリを FCM に登録するときに、メッセージの送信が許可される送信者を指定する必要があります。メッセージをクライアントアプリに送信する場合は、これらの送信者 ID のいずれかを使用してください。別の送信者に切り替えると、既存の登録トークンは機能しなくなります。
無効な JSON	400	JSON メッセージの形式が適切であり、有効なフィールドが含まれていることを確認します（たとえば、正しいデータ型が渡されているか確認します）。
無効なパラメータ	400 + error:InvalidParameters	提供されたパラメータの名前と型が正しいことを確認します。
メッセージが大きすぎる	200 + error:MessageTooBig	メッセージに含まれているペイロードデータの合計サイズが、FCM の上限を超えていないことを確認します。FCM の上限サイズは、ほとんどのメッセージでは 4,096 バイト、トピックメッセージでは 2,048 バイトです。これには、キーと値の両方が含まれます。
無効なデータキー	200 + error: InvalidDataKey	ペイロードデータに、FCM 内部で使用されるキー（`from`、`gcm`、先頭に `google` が付けられたすべての値など）が含まれていないことを確認します。一部の語（`collapse_key` など）は FCM でも使用されますが、ペイロードでも使用できます。この場合、ペイロードの値は FCM の値によってオーバーライドされます。
無効な有効期間	200 + error:InvalidTtl	`time_to_live` で使用される値が、0～2,419,200（4 週間）の期間（秒単位）を示す整数であることを確認します。
タイムアウト	5xx または 200 + error:Unavailable	サーバーで時間内にリクエストを処理できませんでした。同じリクエストを再試行してください。ただし、次の条件を満たす必要があります。 FCM 接続サーバーからのレスポンスに `Retry-After` ヘッダーが含まれている場合は、それに従います。再試行メカニズムに指数バックオフを実装します。（例: 最初に再試行する前に 1 秒間待機した場合は、次の再試行までに少なくとも 2 秒間待機し、さらに次は 4 秒間待機します。）複数のメッセージを再送信する場合は、すべてのメッセージに対して新規リクエストが同時に発行されないように、各メッセージにランダムな秒数を加えて送信を個別に遅らせます。問題を引き起こす送信者はブラックリストに登録されるおそれがあります。
内部サーバーエラー	500 または 200 + error:InternalServerError	リクエストを処理しようとしてサーバーでエラーが発生しました。「タイムアウト」（上の行を参照）に記載されている要件に従って同じリクエストを再試行できます。エラーが解消されない場合は、Firebase サポートまでお問い合わせください。
デバイスメッセージレートの超過	200 + error: DeviceMessageRate Exceeded	特定のデバイスへのメッセージレートが高すぎます。Apple アプリが APNs の制限を超えるレートでメッセージを送信した場合、このエラーメッセージが発生することがありますこのデバイスに送信されるメッセージの数を減らし、指数バックオフを使用して送信を再試行します。
トピックメッセージレートの超過	200 + error: TopicsMessageRate Exceeded	特定のトピックのサブスクライバーへのメッセージレートが高すぎます。このトピックに送信されるメッセージの数を減らし、指数バックオフを使用して送信を再試行します。
無効な APNs 認証情報	200 + error: InvalidApnsCredential	必要な APNs 認証キーがアップロードされていないか、期限切れになっているため、Apple デバイスを対象とするメッセージを送信できませんでした。開発用認証情報と本番用認証情報の有効性を確認します。

デバイスグループ管理

次の表は、デバイスグループを作成し、メンバーを追加および削除するためのキーを示しています。詳細については、各プラットフォームのガイド（iOS+ または Android）をご覧ください。

表 10.デバイスグループ管理キー

パラメータ	指定方法	説明
`operation`	必須、文字列	実行するオペレーション。有効な値は、`create`、`add`、`remove` です。
`notification_key_name`	必須、文字列	作成または変更するデバイスグループのユーザー定義の名前。
`notification_key`	必須（`create` オペレーション、文字列を除く）	デバイスグループの一意の識別子。この値は、正常な `create` オペレーションのレスポンスで返され、デバイスグループに対する後続のすべてのオペレーションに必要です。
`registration_ids`	必須、文字列の配列	追加または削除するデバイストークン。デバイスグループから既存のすべての登録トークンを削除すると、デバイスグループ自体も削除されます。