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 がアプリによってまだ作成されていない場合は、アプリ マニフェストで指定されたチャネル ID が使用されます。

icon 省略可、文字列

通知アイコン。

通知アイコンをドローアブル リソース myicon の myicon に設定します。リクエストでこのキーを送信しなかった場合は、アプリ マニフェストで指定されたランチャー アイコンが表示されます。
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,000 バイトまでに制限されています。

たとえば、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 の上限を超えていないことを確認します。上限サイズは、ほとんどのメッセージでは 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 必須、文字列の配列 追加または削除するデバイス トークン。デバイス グループから既存のすべての登録トークンを削除すると、デバイス グループ自体も削除されます。