Protocolo HTTP de Firebase Cloud Messaging

En este documento, se brinda una referencia para la sintaxis HTTP que se usa para pasar mensajes del servidor de apps a las apps cliente a través de Firebase Cloud Messaging.

Cuando uses el protocolo HTTP heredado, tu servidor de apps debe dirigir todas las solicitudes HTTP a este extremo:

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

Los parámetros y las opciones disponibles entran en las siguientes categorías generales:

Sintaxis de mensajes descendentes
Códigos de respuesta de errores de mensajes descendentes

Sintaxis de mensajes descendentes

En esta sección, se muestra la sintaxis para enviar mensajes downstream y, además, interpretar las respuestas HTTP de Firebase Cloud Messaging.

Mensajes HTTP descendentes (JSON)

En la siguiente tabla se enumeran los destinos, opciones y cargas para mensajes HTTP (JSON).

Tabla 1. Destinos, opciones y cargas para mensajes HTTP descendentes (JSON)

Parámetro	Uso	Descripción
Destinos
`to`	Opcional, string	Este parámetro especifica el destinatario de un mensaje. El valor puede ser el token de registro de un dispositivo, la clave de notificación de un grupo de dispositivos o un solo tema (con el prefijo `/topics/`). Para enviar varios temas, usa el parámetro `condition`.
`registration_ids`	Opcional, arreglo de strings	Este parámetro especifica el recipiente de un mensaje multidifusión, un mensaje enviado a más de un token de registro. El valor debería ser un arreglo de tokens de registro al cual se envía el mensaje multidifusión. El arreglo debe contener al menos 1 token de registro y un máximo de 1,000. Para enviar un mensaje a un solo dispositivo, usa el parámetro `to`. Los mensajes multidifusión se permiten solo con el formato HTTP JSON.
`condition`	Opcional, string	Este parámetro especifica una expresión lógica de las condiciones que determinan el destinatario del mensaje. Condición compatible: Topic, con el formato "tuTema" en topics. Este valor no distingue entre mayúsculas y minúsculas. Operadores admitidos: `&&`, `\|\|`. Se admite un máximo de dos operadores por mensaje a tema.
`notification_key` Obsoleto	Opcional, string	Este parámetro está obsoleto. En su lugar, usa `to` para especificar los destinatarios del mensaje. Para obtener más información acerca de cómo enviar mensajes a varios dispositivos, consulta la documentación de tu plataforma.
Opciones
`collapse_key`	Opcional, string	Este parámetro identifica un grupo de mensajes (p. ej., con `collapse_key: "Updates Available"`) que puede contraerse, de modo que solo se envíe el último mensaje cuando se pueda reanudar la entrega. El propósito es no enviar demasiados mensajes iguales cuando el dispositivo se activa o vuelve a conectarse. Toma en cuenta que no puede garantizarse el orden en que se envían los mensajes. Nota: Se permite un máximo de 4 claves de contracción diferentes en cualquier momento. Esto significa que FCM puede almacenar 4 mensajes diferentes por app cliente de manera simultánea. Si se excede esta cantidad, no habrá ninguna garantía de cuáles serán las 4 claves de contracción que conservará FCM.
`priority`	Opcional, string	Establece la prioridad del mensaje. Los valores válidos son “normal” y “high”. En las plataformas de Apple, estos corresponden a las prioridades 5 y 10 del APNS. De forma predeterminada, los mensajes de notificación se envían con prioridad alta y los mensajes de datos se envían con prioridad normal. La prioridad normal optimiza el consumo de la batería de la app cliente y debe usarse salvo que el mensaje deba entregarse inmediatamente. En el caso de los mensajes con prioridad normal, la app puede recibir los mensajes con una demora no específica. Los mensajes con prioridad alta se envían inmediatamente y la app muestra una notificación.
`content_available`	Opcional, booleano	En las plataformas de Apple, usa este campo para representar `content-available` en la carga útil del APNS. Cuando se envía una notificación o un mensaje y el valor del campo es `true`, se activa una app cliente inactiva y el mensaje se envía a través de APNs como una notificación silenciosa y no a través de FCM. Ten en cuenta que el envío de notificaciones silenciosas en APNS no está garantizado y puede depender de factores como la activación del Modo de bajo consumo por parte del usuario, el cierre forzoso de la app y otros. En Android, los mensajes de datos activan la app de forma predeterminada. En Chrome, no se admite actualmente.
`mutable_content`	Opcional, booleano JSON	En las plataformas de Apple, usa este campo para representar `mutable-content` en la carga útil del APNS. Cuando se envía una notificación y el valor de este parámetro es `true`, el contenido de la notificación se puede modificar antes de mostrarse mediante una extensión de app del servicio de notificaciones. Este parámetro se ignorará en Android y Web.
`time_to_live`	Opcional, número	Este parámetro especifica el tiempo (en segundos) que se debe conservar el mensaje en el almacenamiento de FCM si el dispositivo se encuentra sin conexión. El tiempo máximo admitido es de 4 semanas, al igual que el valor predeterminado. Para obtener más información, consulta Configura la duración de un mensaje.
`restricted_package_ name` (solo para Android)	Opcional, string	Este parámetro especifica el nombre del paquete de la aplicación donde los token de registro deben coincidir para recibir el mensaje.
`dry_run`	Opcional, booleano	Cuando el valor de este parámetro es `true`, los desarrolladores pueden probar una solicitud sin enviar realmente un mensaje. El valor predeterminado es `false`.
Carga útil
`data`	Opcional, objeto	Este parámetro especifica los pares clave-valor personalizados de la carga útil del mensaje. Por ejemplo, con `data:{"score":"3x1"}:`. En las plataformas de Apple, si el mensaje se envía a través del APNS, representa los campos de datos personalizados. Si se envía a través de FCM, se representará como un diccionario de pares clave-valor en `AppDelegate application:didReceiveRemoteNotification:`. En Android, el resultado podría ser un intent adicional denominado `score` con el valor de string `3x1`. La clave no debe ser una palabra reservada (“from”, “message_type”, ni ninguna palabra que empiece con “google“ o “gcm”). No uses ninguna de las palabras que se definen en esta tabla (por ejemplo, `collapse_key`). Se recomiendan los valores en tipos de string. Los valores de objetos u otros tipos de datos que no sean string (p. ej., enteros o booleanos) deben convertirse.
`notification`	Opcional, objeto	Este parámetro especifica los pares clave-valor predefinidos visibles para el usuario de la carga útil de notificación. Consulta Soporte de carga útil de notificación para obtener más información. Si quieres conocer más sobre las opciones de mensajes de notificación y mensajes de datos, consulta los tipos de mensajes. Si se proporciona la carga útil de una notificación o la opción `content_available` tiene el valor `true` para un mensaje a un dispositivo Apple, el mensaje se envía a través de APNs; de lo contrario, se envía a través de FCM.

Soporte de carga de notificación

En las siguientes tablas se enumeran las claves predefinidas disponibles para crear mensajes de notificación de iOS y Android.

Tabla 2a. Claves para mensajes de notificación en iOS

Parámetro	Uso	Descripción
`title`	Opcional, string	El título de la notificación. Este campo no es visible en tablets ni teléfonos.
`body`	Opcional, string	El texto del cuerpo de la notificación.
`sound`	Opcional, string	El sonido que se reproduce cuando el dispositivo recibe la notificación. Las strings que especifican los archivos de sonido pueden estar dentro del conjunto principal de la app cliente o en la carpeta `Library/Sounds` del contenedor de datos de la app. Consulta la biblioteca para desarrolladores de iOS para obtener más información.
`badge`	Opcional, string	El valor de la insignia en el ícono de la app de la pantalla principal. Si no se especifica, la insignia no se cambia. Si se le asigna el valor `0`, la insignia se quita.
`click_action`	Opcional, string	La acción asociada con el clic de un usuario en la notificación. Corresponde a `category` en la carga útil de APNS.
`subtitle`	Opcional, string	El subtítulo de la notificación.
`body_loc_key`	Opcional, string	La clave de la string del cuerpo en los recursos de string de la app que se usa para localizar el texto del cuerpo en la localización actual del usuario. Corresponde a `loc-key` en la carga útil de APNS. Para obtener más información, consulta la referencia de la clave de carga útil y cómo localizar el contenido de las notificaciones remotas.
`body_loc_args`	Opcional, matriz de JSON como string	Valores de string variables que se usarán en lugar de los especificadores de formato en `body_loc_key` para localizar el cuerpo del texto en la localización actual del usuario. Corresponde a `loc-args` en la carga útil de APNS. Para obtener más información, consulta la referencia de la clave de carga útil y cómo localizar el contenido de las notificaciones remotas.
`title_loc_key`	Opcional, string	La clave de la string del título en los recursos de string de la app que se usa para localizar el texto del título en la localización actual del usuario. Corresponde a `title-loc-key` en la carga útil de APNS. Para obtener más información, consulta la referencia de la clave de carga útil y cómo localizar el contenido de las notificaciones remotas.
`title_loc_args`	Opcional, matriz de JSON como string	Valores de string variables que se usarán en lugar de los especificadores de formato en `title_loc_key` para localizar el título del texto en la localización actual del usuario. Corresponde a `title-loc-args` en la carga útil de APNS. Para obtener más información, consulta la referencia de la clave de carga útil y cómo localizar el contenido de las notificaciones remotas.

Tabla 2b. Claves para mensajes de notificación en Android

Parámetro	Uso	Descripción
`title`	Opcional, string	El título de la notificación.
`body`	Opcional, string	El texto del cuerpo de la notificación.
`android_channel_id`	Opcional, string	El ID de canal de la notificación (nuevo en Android O). La app debe crear un canal con este ID antes de que se reciba cualquier notificación con él. Si no envías este ID del canal en la solicitud o si la app aún no crea el ID del canal proporcionado, FCM usa el ID del canal que especifica el manifiesto de la app.
`icon`	Opcional, string	El ícono de la notificación. Configura el ícono de la notificación como `myicon` para el elemento de diseño `myicon`. Si no envías esta clave en la solicitud, FCM muestra el ícono de selector que se especifica en el manifiesto de la app.
`sound`	Opcional, string	El sonido que se reproduce cuando el dispositivo recibe la notificación. Admite `"default"` o el nombre de archivo de un recurso de sonido incluido en la app. Los archivos de sonido deben alojarse en `/res/raw/`.
`tag`	Opcional, string	Identificador que se usa para reemplazar las notificaciones existentes en el panel lateral de notificaciones. Si no se configura, cada solicitud crea una nueva notificación. Si se especifica y ya se muestra una notificación con la misma etiqueta, la notificación nueva reemplaza la existente en el panel lateral de notificaciones.
`color`	Opcional, string	El color del ícono de la notificación, expresado en formato `#rrggbb`.
`click_action`	Opcional, string	La acción asociada con el clic de un usuario en la notificación. Si se especifica, se lanza una actividad con un filtro de intents que coinciden cuando un usuario hace clic en la notificación.
`body_loc_key`	Opcional, string	La clave de la string del cuerpo en los recursos de string de la app que se usa para localizar el texto del cuerpo en la localización actual del usuario. Consulta los recursos de string para obtener más información.
`body_loc_args`	Opcional, matriz de JSON como string	Valores de string variables que se usarán en lugar de los especificadores de formato en `body_loc_key` para localizar el cuerpo del texto en la localización actual del usuario. Consulta el formato y estilo para obtener más información.
`title_loc_key`	Opcional, string	La clave de la string del título en los recursos de string de la app que se usa para localizar el texto del título en la localización actual del usuario. Consulta los recursos de string para obtener más información.
`title_loc_args`	Opcional, matriz de JSON como string	Valores de string variables que se usarán en lugar de los especificadores de formato en `title_loc_key` para localizar el título del texto en la localización actual del usuario. Consulta el formato y estilo para obtener más información.

Tabla 2c. Claves para mensajes de notificación en la Web (JavaScript)

Parámetro	Uso	Descripción
`title`	Opcional, string	El título de la notificación.
`body`	Opcional, string	El texto del cuerpo de la notificación.
`icon`	Opcional, string	La URL que se usará para el ícono de la notificación.
`click_action`	Opcional, string	La acción asociada con el clic de un usuario en la notificación. Para todos los valores de URL, se debe usar el protocolo HTTPS.

Mensajes HTTP descendentes (texto sin formato)

En la siguiente tabla se indica la sintaxis para objetivos, opciones y carga útil en mensajes HTTP descendentes de texto sin formato.

Tabla 3. Objetivos, opciones y carga útil para mensajes HTTP descendentes de texto sin formato

Parámetro	Uso	Descripción
Destinos
`registration_id`	Obligatorio, string	Este parámetro especifica las apps cliente (tokens de registro) que reciben el mensaje. Se permiten los mensajes multidifusión (que se envían a más de un token de registro) solo si se usa el formato JSON HTTP.
Opciones
`collapse_key`	Opcional, string	Consulta la tabla 1 para ver los detalles.
`time_to_live`	Opcional, número	Consulta la tabla 1 para ver los detalles.
`restricted_package_name`	Opcional, string	Consulta la tabla 1 para ver los detalles.
`dry_run`	Opcional, booleano	Consulta la tabla 1 para ver los detalles.
Carga útil
`data.<key>`	Opcional, string	Este parámetro especifica los pares clave-valor de la carga útil del mensaje. No hay límite para la cantidad de parámetros de par clave-valor, pero el tamaño máximo del mensaje es 4,096 bytes. Por ejemplo, en Android, `"data.score"."3x1"` da como resultado un intent adicional denominado `score` con el valor de string `3x1`. La clave no debe ser una palabra reservada (“from”, “message_type”, ni ninguna palabra que empiece con “google“ o “gcm”). No uses ninguna de las palabras que se definen en esta tabla (por ejemplo, `collapse_key`).

Interpretar una respuesta de mensajes descendentes

El servidor de apps debe evaluar tanto el encabezado como el cuerpo de la respuesta del mensaje para interpretar la respuesta que envía FCM. En la siguiente tabla, se describen las respuestas posibles.

Tabla 4. Encabezado de respuesta de mensaje HTTP descendente

Respuesta	Descripción
200	El mensaje se procesó correctamente. El cuerpo de la respuesta contiene más detalles sobre el estado del mensaje, pero su formato dependerá del formato de la solicitud, JSON o texto sin formato. Consulta la tabla 5 para obtener más detalles.
400	Solo se aplica para solicitudes JSON. Indica que la solicitud no se pudo analizar como JSON o que contenía campos no válidos (por ejemplo, pasaba una string cuando se esperaba un número). El motivo exacto de la falla se describe en la respuesta y el problema se debe abordar antes de que se vuelva a intentar la solicitud.
401	Se generó un error al autenticar la cuenta del emisor.
5xx	Los errores del rango 500 a 599 (como el 500 o el 503) indican que se produjo un error interno en el backend de FCM mientras se intentaba procesar la solicitud, o que el servidor no está disponible temporalmente (por ejemplo, debido a que se agotó el tiempo de espera). El remitente debe volver a intentar más tarde, tras esperar el tiempo que se indica en el encabezado `Retry-After` incluido en la respuesta. Los servidores de aplicaciones deben implementar retiradas exponenciales.

En la siguiente tabla, se muestran los campos que se incluyen en el cuerpo de una respuesta de mensajes descendentes (JSON).

Tabla 5. Cuerpo de respuesta de mensaje HTTP descendente

Parámetro	Uso	Descripción
`multicast_id`	Obligatorio, número	ID único (número) que identifica el mensaje multidifusión.
`success`	Obligatorio, número	Número de mensajes que se procesaron sin un error.
`failure`	Obligatorio, número	Número de mensajes que no se procesaron.
`results`	Obligatorio, matriz de objetos	Matriz de objetos que representan el estado de los mensajes procesados. Los objetos se indican en el mismo orden que la solicitud (es decir, por cada ID de registro en la solicitud, el resultado aparece en el mismo índice en la respuesta). `message_id`: Es una string que especifica un ID único para cada mensaje procesado correctamente. `error`: Es una string que especifica el error que se produjo cuando se procesaba el mensaje para el destinatario. Los valores posibles se indican en la tabla 9.

Tabla 6. Cuerpo de respuesta HTTP de mensaje a tema (JSON)

Parámetro	Uso	Descripción
`message_id`	Opcional, número	El ID del mensaje por tema cuando FCM recibe correctamente la solicitud y hará el intento de entregar a todos los dispositivos suscritos.
`error`	Opcional, string	Error que se produjo al procesar el mensaje. Los valores posibles se indican en la tabla 9.

Tabla 7. Respuesta de procesamiento correcto para el cuerpo de respuesta de mensaje HTTP descendente (texto sin formato)

Parámetro	Uso	Descripción
`id`	Obligatorio, string	Este parámetro especifica el ID del mensaje único que FCM procesó correctamente.
`registration_id`	Opcional, string	Este parámetro especifica el token de registro de la app cliente a la que se envió el mensaje después de procesarlo.

Tabla 8. Respuesta de error para el cuerpo de respuesta de mensaje HTTP descendente (texto sin formato)

Parámetro	Uso	Descripción
`Error`	Obligatorio, string	Este parámetro especifica el valor de error mientras se procesa el mensaje para el destinatario. Consulta la tabla 9 para ver los detalles.

Códigos de respuesta de errores de mensajes descendentes

En la siguiente tabla se indican los códigos de respuesta de errores para mensajes descendentes.

Tabla 9. Códigos de respuesta de error de mensajes descendentes

Error	Código HTTP	Acción recomendada
Falta el token de registro	200 + error:MissingRegistration	Verifica que la solicitud contenga un token de registro (en el `registration_id`, si es un mensaje de texto sin formato, o en los campos `to` o `registration_ids` en JSON).
Token de registro no válido	200 + error:InvalidRegistration	Revisa el formato del token de registro que pasaste al servidor. Asegúrate de que coincida con el token de registro que la app cliente recibe cuando se registra en Firebase Notifications. No lo trunques ni agregues caracteres adicionales.
Dispositivo no registrado	200 + error:NotRegistered	Un token de registro existente puede dejar de ser válido en diversas situaciones, como las siguientes: Si la app cliente deja de estar registrada en FCM. Si se cancela el registro de la app cliente de forma automática, lo cual puede ocurrir si el usuario desinstala la aplicación. Por ejemplo, en iOS esto sucede si el servicio de comentarios de APNS informó que los tokens de APNS no son válidos Si caduca el token de registro (por ejemplo, porque Google decidió actualizar estos tokens o porque caducó el token de APNS para los dispositivos iOS) Si se actualiza la app cliente, pero la versión nueva no está configurada para recibir mensajes En todos estos casos, debes quitar este token de registro del servidor de apps y dejar de utilizarlo para enviar mensajes.
Nombre de paquete no válido	200 + error:InvalidPackageName	Asegúrate de que el mensaje se haya dirigido a un token de registro cuyo nombre de paquete coincida con el valor que se pasa en la solicitud.
Error de autenticación	401	No se pudo autenticar la cuenta emisora que se usó para enviar un mensaje. Las posibles causas son: Falta el encabezado de la autorización o su sintaxis no es válida en la solicitud HTTP. El proyecto de Firebase al que pertenece la clave de servidor especificada es incorrecto. Solo claves de servidor heredadas: La solicitud se originó de un servidor no incluido en la lista blanca de IP de clave de servidor. Verifica que el token que envías dentro del encabezado de autenticación sea la clave de servidor correcta asociada con tu proyecto. Consulta Cómo verificar la validez de una clave de servidor para obtener detalles. Si utilizas una clave de servidor heredada, es conveniente que realices una actualización a una nueva clave que no tenga restricciones de IP. Consulta Migra claves de servidor heredadas.
El emisor no coincide	200 + error:MismatchSenderId	Un token de registro está asociado con un determinado grupo de emisores. Cuando una app cliente se registra para FCM, debe especificar qué remitentes tienen autorización para enviar mensajes. Debes utilizar el ID de uno de esos remitentes cuando envíes mensajes a la app cliente. Si cambias a otro diferente, los tokens de registro existentes no funcionarán.
JSON no válido	400	Verifica que el mensaje JSON tenga un formato adecuado y contenga campos válidos (por ejemplo, que se pase el tipo de datos correcto).
Parámetros no válidos	400 + error:InvalidParameters	Comprueba que los parámetros proporcionados tienen el nombre y el tipo correctos.
Mensaje demasiado grande	200 + error:MessageTooBig	Comprueba que el tamaño total de los datos de la carga útil incluidos en un mensaje no supere los límites de FCM: 4,096 bytes para la mayor parte de los mensajes y 2,048 bytes para los mensajes a temas. Esto incluye las claves y los valores.
Clave de datos no válida	200 + error: InvalidDataKey	Comprueba que los datos de la carga útil no contengan una clave (como `from`, o `gcm`, o cualquier valor con el prefijo `google`) que FCM usa internamente. Ten en cuenta que hay algunas palabras (como `collapse_key`) que se usan en FCM, pero se permiten en la carga útil. En este caso, el valor de FCM anulará el valor de la carga útil.
Tiempo de vida no válido	200 + error:InvalidTtl	Comprueba que el valor que se usa en `time_to_live` sea un número entero que represente una duración en segundos entre 0 y 2,419,200 (4 semanas).
Tiempo de espera	5xx or 200 + error:Unavailable	El servidor no pudo procesar la solicitud a tiempo. Vuelve a intentarlo con la misma solicitud, pero haz lo siguiente: Si se incluye el encabezado `Retry-After` en la respuesta del servidor de conexiones de FCM, debes respetar el tiempo de espera que se especifica. Implementa la retirada exponencial en el mecanismo de reintento. (p. ej., si esperaste un segundo antes del primer intento, espera al menos dos segundos antes del próximo, luego, 4 segundos y así sucesivamente). Si envías varios mensajes, agrega una demora independiente a cada uno con un valor aleatorio adicional, a fin de evitar emitir una nueva solicitud para todos los mensajes en forma simultánea. Los emisores que causan problemas corren riesgo de pasar a la lista negra.
Error de servidor interno	500 or 200 + error:InternalServerError	Se produjo un error en el servidor mientras se intentaba procesar la solicitud. Puedes volver a intentar con la misma solicitud siguiendo los requisitos que se enumeran en “Tiempo de espera” (ver fila anterior de esta tabla). Si el error persiste, comunícate con el equipo de asistencia de Firebase.
Tasa de mensajes de dispositivos excedida	200 + error: DeviceMessageRate Exceeded	La tasa de mensajes a un dispositivo específico es demasiado alta. Si una app para Apple envía mensajes a una tasa superior a los límites de APNS, puede recibir este mensaje de error. Reduce la cantidad de mensajes enviados a este dispositivo y usa la retirada exponencial para volver a intentar el envío.
Tasa de mensajes a temas excedida	200 + error: TopicsMessageRate Exceeded	La tasa de mensajes a suscriptores de un tema particular es demasiado alta. Reduce la cantidad de mensajes enviados a este tema y usa la retirada exponencial para volver a intentar el envío.
Credenciales de APNS no válidas	200 + error: InvalidApnsCredential	No se pudo enviar un mensaje destinado a un dispositivo Apple, ya que la clave de autenticación de APNS obligatoria venció o no se subió. Verifica la validez de tus credenciales de desarrollo y producción.

Administración de grupos de dispositivos

En la siguiente tabla, se indican las claves para crear grupos de dispositivos y agregar y quitar miembros. Si quieres obtener más información, consulta la guía para tu plataforma ( iOS+ o Android).

Tabla 10. Claves de administración de grupos de dispositivos

Parámetro	Uso	Descripción
`operation`	Obligatorio, string	La operación que se ejecutará. Los valores válidos son `create`, `add` y `remove`.
`notification_key_name`	Obligatorio, string	El nombre que definió el usuario para el grupo de dispositivos que se creará o se modificará.
`notification_key`	Obligatorio (excepto para la operación `create`, string)	El identificador único del grupo de dispositivos. Este valor se muestra en respuesta a una operación de tipo `create` realizada correctamente y es obligatorio para todas las operaciones posteriores que afecten al grupo de dispositivos.
`registration_ids`	Obligatorio, arreglo de strings	Los tokens de dispositivo que se agregarán o quitarán. Si quitas todos los tokens de registro existentes de un grupo de dispositivos, FCM lo borrará.