How is an FCM HTTP v1 send request addressed and authorized, and where do Android options like priority, TTL and collapse key go?
answer
- one project-scoped endpoint
- a short-lived bearer token
- the firebase.messaging scope
- exactly one target per message
- android block: priority, ttl, collapse_key
basics
~10 sPOST a {"message": ...} body to https://fcm.googleapis.com/v1/projects/PROJECT_ID/messages:send with a short-lived OAuth2 bearer token for a service account. Android options sit in the message's android block: priority, ttl, collapse_key and notification fields.
solid answer
~40 sAn HTTP v1 send is a `POST` to `https://fcm.googleapis.com/v1/projects/{project_id}/messages:send`, authorized with `Authorization: Bearer` and a short-lived **OAuth2 access token** minted from a service account for the `https://www.googleapis.com/auth/firebase.messaging` scope; the Admin SDK mints and refreshes it for me. The body is `{"message": {...}}` with exactly one target, `fid`, the deprecated `token`, `topic` or `condition`, plus `notification`, string-only `data`, and platform blocks. Android options live in `android`: `priority` (`normal`, the default, or `high`), `ttl` as a duration string such as `"3600s"` (up to 28 days, four weeks if unset), `collapse_key`, and `android.notification` with `channel_id` or `click_action`. One trap: the Node.js Admin SDK takes `ttl` in **milliseconds** and `collapseKey` in camelCase, then converts them.
code
http · 15 linesPOST https://fcm.googleapis.com/v1/projects/parcel-tracker-prod/messages:send
Authorization: Bearer <short-lived OAuth2 access token>
Content-Type: application/json
{
"message": {
"fid": "<registered Firebase Installation ID>",
"data": { "type": "inbox-sync", "since": "1728480000" },
"android": {
"priority": "normal",
"ttl": "3600s",
"collapse_key": "inbox-sync"
}
}
}go deeper
Recall the endpoint shape, that a server credential (not the app's config file) authorizes it, and that one message names exactly one target.
Explain the android block field by field, the ttl range and default, why collapse_key does nothing for notification messages, and the Admin SDK's millisecond ttl.
Show operational sense: cross-project service accounts, reading a message ID as accepted rather than delivered, and mapping BatchResponse failures back to targets.
Decide where send credentials live, whether sends go through the Admin SDK or raw HTTP, and how per-message Android options are standardised across the team.
## The endpoint and its credential The **FCM HTTP v1 API** has one send method per Firebase project: ```http POST https://fcm.googleapis.com/v1/projects/{project_id}/messages:send ``` It is authorized with an **OAuth2 access token**, not with anything shipped in the app. A backend holds a **service account** credential, exchanges it for a short-lived access token covering the `https://www.googleapis.com/auth/firebase.messaging` scope, and sends `Authorization: Bearer <access token>`. The Firebase Admin SDK does all of this: `initializeApp({ credential: applicationDefault() })` reads the key named by `GOOGLE_APPLICATION_CREDENTIALS` and refreshes tokens as they expire. Two setup points come up in practice: - The **Cloud Messaging API** must be enabled for the project (Firebase console, Settings, Cloud Messaging tab). - To send for a project whose service account lives in another project, grant that account the **Firebase Cloud Messaging API Admin** role in the target project's IAM and initialise the Admin SDK with the target project's `projectId`. ## The message body The body wraps one `message` object: - **Target**: exactly one of `fid` (a Firebase Installation ID), `token` (a legacy registration token, deprecated), `topic` (a topic name) or `condition` (a boolean expression over topic names). The Admin SDK rejects a message with zero or several targets. - **`notification`**: `title`, `body` and an image, shared by all platforms. - **`data`**: a flat map of string keys to string values. - **Platform blocks**: `android`, `apns` and `webpush` override or extend the shared fields per platform. Inside `android`, a `data` map replaces the top-level one for Android devices. ## Android options | Field in `android` | Meaning | |---|---| | `priority` | `normal` (the default for data and notification messages) or `high`, which lets FCM try to deliver at once and wake a sleeping device | | `ttl` | How long FCM stores an undeliverable message: a duration string from `"0s"` to `"2419200s"` (28 days); four weeks when omitted | | `collapse_key` | Lets a newer message replace an undelivered older one with the same key; FCM keeps at most four collapse keys per device at once | | `restricted_package_name` | The package name the registration must match | | `notification.channel_id` | The Android notification channel; FCM falls back to the manifest default if the app has not created it | | `notification.click_action` | The intent action the tap opens instead of the launcher | | `direct_boot_ok` | Allows delivery while the device is in direct boot mode | Two rules surprise people. **Notification messages are always collapsible and ignore `collapse_key`**; the key only changes behaviour for other messages. And a `ttl` of `"0s"` means a message that cannot be delivered immediately is discarded instead of stored. Which priority, TTL or collapse key fits which product event is a design question for push on mobile; the API's job is only to carry them. ## The Admin SDK versus raw HTTP The Admin SDK for Node.js builds the same request but uses **TypeScript-style names and units**: 1. Field names are camelCase (`collapseKey`, `restrictedPackageName`, `channelId`, `clickAction`) and the SDK renames them to the wire's snake_case. 2. `android.ttl` is a **number of milliseconds**, which the SDK turns into a seconds string. Passing `"3600s"` fails validation with "TTL must be a non-negative duration in milliseconds", and passing `3600` thinking in seconds sends a TTL of 3.6 seconds. 3. `send()` takes one message; `sendEach()` takes up to 500 different messages; `sendEachForMulticast()` takes one message and up to 500 FIDs or tokens and returns a `BatchResponse` whose `responses` follow the input order. ## What the response means A successful send returns the message name, `projects/{project_id}/messages/{message_id}`. It means FCM **accepted** the message, not that a device received it: the device may be offline, dozing, or gone. Failures come back as HTTP errors with an FCM error code, such as `UNREGISTERED` (404) for a target that is no longer valid, `INVALID_ARGUMENT` (400) for a malformed request, and `QUOTA_EXCEEDED` (429) for a rate limit. Which of these justify deleting a stored registration is its own question. ## Topics as a target Sending to `topic` fans out to every app instance subscribed to it. App instances subscribe themselves with `FirebaseMessaging.subscribeToTopic(name)`, which the Android SDK persists and retries until it succeeds; names must match `[a-zA-Z0-9-_.~%]{1,900}`. One app instance can hold at most 2000 topics. Topic sends are tuned for throughput rather than latency, so the docs steer them to public information such as weather alerts and point latency-sensitive sends at individual registrations.
- How do you send one message to many specific devices with the Admin SDK?Use `sendEachForMulticast` with up to 500 targets in `fids` (or the deprecated `tokens`; with both, tokens go first). It returns a `BatchResponse` whose `responses` follow the input order, so each failure maps back to its FID. `sendEach` instead sends up to 500 different messages with mixed targets.
- How does a backend send for a Firebase project whose service account lives in another project?Enable the Cloud Messaging API in the sender project, create the service account there, grant it the Firebase Cloud Messaging API Admin role in the target project's IAM, and initialise the Admin SDK with that credential and the target project's `projectId`.
- What limits apply to topic subscriptions?One app instance can be subscribed to at most 2000 topics, a batch subscription request covers at most 1000 app instances, and adding or removing subscriptions is limited to 3,000 QPS per project; beyond that FCM answers `429 RESOURCE_EXHAUSTED`, so retry with exponential backoff.
- The Admin SDK's ttl is in seconds, like the REST API's duration string
- A returned message ID means the device has received the message
- An API key from google-services.json can authorize server-side sends
- Setting collapse_key is what makes notification messages collapsible
- One v1 send can target a topic and a list of FIDs at once