Protocolo HTTP de mensajería en la nube de Firebase

Este documento proporciona una referencia para la sintaxis HTTP utilizada para pasar mensajes desde el servidor de su aplicación a las aplicaciones cliente a través de Firebase Cloud Messaging.

Cuando utilice el protocolo HTTP heredado, su servidor de aplicaciones debe dirigir todas las solicitudes HTTP a este punto final:

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

Los parámetros y opciones disponibles se dividen en las siguientes categorías amplias:

Sintaxis de mensajes posteriores

Esta sección brinda la sintaxis para enviar mensajes posteriores e interpretar respuestas HTTP de Firebase Cloud Messaging.

Mensajes HTTP descendentes (JSON)

La siguiente tabla enumera los destinos, las opciones y la carga útil de los mensajes HTTP JSON.

Tabla 1. Destinos, opciones y carga útil para mensajes HTTP descendentes (JSON).

Parámetro Uso Descripción
Objetivos
to Opcional, cadena

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 a varios temas, utilice el parámetro condition .

registration_ids
Opcional, conjunto de cadenas.

Este parámetro especifica el destinatario de un mensaje de multidifusión, un mensaje enviado a más de un token de registro.

El valor debe ser una matriz de tokens de registro a los que enviar el mensaje de multidifusión. La matriz debe contener al menos 1 y como máximo 1000 tokens de registro. Para enviar un mensaje a un solo dispositivo, utilice el parámetro to .

Los mensajes de multidifusión solo se permiten utilizando el formato HTTP JSON.

condition Opcional, cadena

Este parámetro especifica una expresión lógica de condiciones que determinan el destino del mensaje.

Condición admitida: Tema, formateado como "'tuTema' en temas". Este valor no distingue entre mayúsculas y minúsculas.

Operadores admitidos: && , || . Se admiten un máximo de dos operadores por mensaje de tema.

notification_key
Obsoleto
Opcional, cadena

Este parámetro está en desuso. En su lugar, utilice to para especificar los destinatarios del mensaje. Para obtener más información sobre cómo enviar mensajes a múltiples dispositivos, consulte la documentación de su plataforma.

Opciones
collapse_key Opcional, cadena

Este parámetro identifica un grupo de mensajes (por ejemplo, con collapse_key: "Updates Available" ) que se pueden contraer, de modo que solo se envíe el último mensaje cuando se pueda reanudar la entrega. Esto tiene como objetivo evitar enviar demasiados mensajes iguales cuando el dispositivo vuelve a estar en línea o se activa.

Tenga en cuenta que no hay garantía del orden en que se envían los mensajes.

Nota: Se permite un máximo de 4 claves de colapso diferentes en un momento dado. Esto significa que FCM puede almacenar simultáneamente 4 mensajes diferentes por aplicación cliente. Si excede este número, no hay garantía de qué 4 claves de colapso conservará FCM.

priority Opcional, cadena

Establece la prioridad del mensaje. Los valores válidos son "normal" y "alto". En las plataformas Apple, corresponden a las prioridades 5 y 10 de APN.

De forma predeterminada, los mensajes de notificación se envían con prioridad alta y los mensajes de datos con prioridad normal. La prioridad normal optimiza el consumo de batería de la aplicación cliente y debe usarse a menos que se requiera una entrega inmediata. Para mensajes con prioridad normal, la aplicación puede recibir el mensaje con un retraso no especificado.

Cuando se envía un mensaje con alta prioridad, se envía inmediatamente y la aplicación puede mostrar una notificación.

content_available Opcional, booleano

En las plataformas Apple, utilice este campo para representar content-available en la carga útil de APN. Cuando se envía una notificación o un mensaje y esto se establece en true , se activa una aplicación cliente inactiva y el mensaje se envía a través de APN como una notificación silenciosa y no a través de FCM. Tenga en cuenta que no se garantiza que las notificaciones silenciosas en APN se entreguen y pueden depender de factores como que el usuario active el modo de bajo consumo, fuerce el cierre de la aplicación, etc. En Android, los mensajes de datos activan la aplicación de forma predeterminada. En Chrome, actualmente no es compatible.

mutable_content Opcional, JSON booleano

En las plataformas Apple, utilice este campo para representar mutable-content en la carga útil de APN. Cuando se envía una notificación y esto se establece en true , el contenido de la notificación se puede modificar antes de que se muestre, usando una extensión de la aplicación del Servicio de notificaciones . Este parámetro se ignorará para Android y web.

time_to_live Opcional, número

Este parámetro especifica cuánto tiempo (en segundos) debe mantenerse el mensaje en el almacenamiento FCM si el dispositivo está fuera de línea. El tiempo de vida máximo admitido es de 4 semanas y el valor predeterminado es de 4 semanas. Para obtener más información, consulte Configuración de la vida útil de un mensaje .

restricted_package_
name
(solo Android)
Opcional, cadena Este parámetro especifica el nombre del paquete de la aplicación donde los tokens de registro deben coincidir para recibir el mensaje.
dry_run Opcional, booleano

Este parámetro, cuando se establece en true , permite a los desarrolladores probar una solicitud sin enviar 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 Apple, si el mensaje se envía a través de APN, representa los campos de datos personalizados. Si se envía a través de FCM, se representará como un diccionario de valores clave en AppDelegate application:didReceiveRemoteNotification:

En Android, esto daría como resultado una score con nombre adicional de intención con el valor de cadena 3x1 .

La clave no debe ser una palabra reservada ("de", "tipo_mensaje" ni ninguna palabra que comience con "google" o "gcm"). No utilice ninguna de las palabras definidas en esta tabla (como collapse_key ).

Se recomiendan valores en tipos de cadena. Debe convertir valores en objetos u otros tipos de datos que no sean cadenas (por ejemplo, enteros o booleanos) a cadenas.

notification Opcional, objeto Este parámetro especifica los pares clave-valor predefinidos y visibles para el usuario de la carga útil de notificación. Consulte Compatibilidad con la carga útil de notificaciones para obtener más detalles. Para obtener más información sobre las opciones de mensajes de notificación y mensajes de datos, consulte Tipos de mensajes . Si se proporciona una carga útil de notificación, o la opción content_available está configurada en true para un mensaje a un dispositivo Apple, el mensaje se envía a través de APN ; de lo contrario, se envía a través de FCM.

Soporte de carga útil de notificación

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

Tabla 2a. iOS: claves para mensajes de notificación

Parámetro Uso Descripción
title Opcional, cadena

El título de la notificación.

Este campo no es visible en teléfonos y tabletas.

body Opcional, cadena

El texto del cuerpo de la notificación.

sound Opcional, cadena

El sonido que se reproducirá cuando el dispositivo reciba la notificación.

Cadena que especifica archivos de sonido en el paquete principal de la aplicación cliente o en la carpeta Library/Sounds del contenedor de datos de la aplicación. Consulte la biblioteca para desarrolladores de iOS para obtener más información.

badge Opcional, cadena

El valor de la insignia en el ícono de la aplicación de la pantalla de inicio.

Si no se especifica, la insignia no se cambia.

Si se establece en 0 , se elimina la insignia.

click_action Opcional, cadena

La acción asociada con un usuario hace clic en la notificación.

Corresponde a la category en la carga útil de APN.

subtitle Opcional, cadena

El subtítulo de la notificación.

body_loc_key Opcional, cadena

La clave de la cadena del cuerpo en los recursos de cadena de la aplicación que se usará para localizar el texto del cuerpo a la localización actual del usuario.

Corresponde a loc-key en la carga útil de APN.

Consulte Referencia clave de carga útil y Localización del contenido de sus notificaciones remotas para obtener más información.

body_loc_args Opcional, matriz JSON como cadena

Valores de cadena variables que se utilizarán en lugar de los especificadores de formato en body_loc_key para localizar el texto del cuerpo a la localización actual del usuario.

Corresponde a loc-args en la carga útil de APN.

Consulte Referencia clave de carga útil y Localización del contenido de sus notificaciones remotas para obtener más información.

title_loc_key Opcional, cadena

La clave de la cadena de título en los recursos de cadena de la aplicación que se usará para localizar el texto del título a la localización actual del usuario.

Corresponde a title-loc-key en la carga útil de APN.

Consulte Referencia clave de carga útil y Localización del contenido de sus notificaciones remotas para obtener más información.

title_loc_args Opcional, matriz JSON como cadena

Valores de cadena variables que se utilizarán en lugar de los especificadores de formato en title_loc_key para localizar el texto del título a la localización actual del usuario.

Corresponde a title-loc-args en la carga útil de APN.

Consulte Referencia clave de carga útil y Localización del contenido de sus notificaciones remotas para obtener más información.

Tabla 2b. Android: claves para mensajes de notificación

Parámetro Uso Descripción
title Opcional, cadena

El título de la notificación.

body Opcional, cadena

El texto del cuerpo de la notificación.

android_channel_id Opcional, cadena

La identificación del canal de notificación (nuevo en Android O).

La aplicación debe crear un canal con este ID de canal antes de recibir cualquier notificación con este ID de canal.

Si no envía este ID de canal en la solicitud, o si la aplicación aún no ha creado el ID de canal proporcionado, FCM usa el ID de canal especificado en el manifiesto de la aplicación.

icon Opcional, cadena

El icono de notificación.

Establece el ícono de notificación en myicon para el recurso dibujable myicon . Si no envía esta clave en la solicitud, FCM muestra el icono del iniciador especificado en el manifiesto de su aplicación.

sound Opcional, cadena

El sonido que se reproducirá cuando el dispositivo reciba la notificación.

Admite "default" o el nombre de archivo de un recurso de sonido incluido en la aplicación. Los archivos de sonido deben residir en /res/raw/ .

tag Opcional, cadena

Identificador utilizado para reemplazar notificaciones existentes en el cajón de notificaciones.

Si no se especifica, cada solicitud crea una nueva notificación.

Si se especifica y ya se muestra una notificación con la misma etiqueta, la nueva notificación reemplaza la existente en el cajón de notificaciones.

color Opcional, cadena

El color del icono de la notificación, expresado en formato #rrggbb .

click_action Opcional, cadena

La acción asociada con un usuario hace clic en la notificación.

Si se especifica, se inicia una actividad con un filtro de intención coincidente cuando un usuario hace clic en la notificación.

body_loc_key Opcional, cadena

La clave de la cadena del cuerpo en los recursos de cadena de la aplicación que se usará para localizar el texto del cuerpo a la localización actual del usuario.

Consulte Recursos de cadenas para obtener más información.

body_loc_args Opcional, matriz JSON como cadena

Valores de cadena variables que se utilizarán en lugar de los especificadores de formato en body_loc_key para localizar el texto del cuerpo a la localización actual del usuario.

Consulte Formato y estilo para obtener más información.

title_loc_key Opcional, cadena

La clave de la cadena de título en los recursos de cadena de la aplicación que se usará para localizar el texto del título a la localización actual del usuario.

Consulte Recursos de cadenas para obtener más información.

title_loc_args Opcional, matriz JSON como cadena

Valores de cadena variables que se utilizarán en lugar de los especificadores de formato en title_loc_key para localizar el texto del título a la localización actual del usuario.

Consulte Formato y estilo para obtener más información.

Tabla 2c. Web (JavaScript): claves para mensajes de notificación

Parámetro Uso Descripción
title Opcional, cadena

El título de la notificación.

body Opcional, cadena

El texto del cuerpo de la notificación.

icon Opcional, cadena

La URL que se utilizará para el icono de notificación.

click_action Opcional, cadena

La acción asociada con un usuario hace clic en la notificación.

Para todos los valores de URL, se requiere HTTPS.

Mensajes HTTP descendentes (texto sin formato)

La siguiente tabla enumera la sintaxis de destinos, opciones y carga útil en mensajes HTTP posteriores de texto sin formato.

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

Parámetro Uso Descripción
Objetivos
registration_id Requerido, cadena

Este parámetro especifica las aplicaciones cliente (tokens de registro) que reciben el mensaje.

La mensajería de multidifusión (envío a más de un token de registro) se permite utilizando únicamente el formato HTTP JSON.

Opciones
collapse_key Opcional, cadena Consulte la tabla 1 para obtener más detalles.
time_to_live Opcional, número Consulte la tabla 1 para obtener más detalles.
restricted_package_name Opcional, cadena Consulte la tabla 1 para obtener más detalles.
dry_run Opcional, booleano Consulte la tabla 1 para obtener más detalles.
Carga útil
data.<key> Opcional, cadena

Este parámetro especifica los pares clave-valor de la carga útil del mensaje. No hay límite en la cantidad de parámetros clave-valor, pero existe un límite de tamaño total de mensaje de 4000 bytes.

Por ejemplo, en Android, "data.score"."3x1" daría como resultado una score con nombre adicional de intención con el valor de cadena 3x1 .

La clave no debe ser una palabra reservada ("de", "tipo_mensaje" ni ninguna palabra que comience con "google" o "gcm"). No utilice ninguna de las palabras definidas en esta tabla (como collapse_key ).

Interpretación de una respuesta de mensaje posterior

El servidor de aplicaciones debe evaluar tanto el encabezado de respuesta del mensaje como el cuerpo para interpretar la respuesta del mensaje enviada desde FCM. La siguiente tabla describe las posibles respuestas.

Tabla 4. Encabezado de respuesta de mensaje HTTP descendente.

Respuesta Descripción
200 El mensaje fue procesado exitosamente. El cuerpo de la respuesta contendrá más detalles sobre el estado del mensaje, pero su formato dependerá de si la solicitud fue JSON o texto sin formato. Consulte la tabla 5 para obtener más detalles.
400 Solo aplica para solicitudes JSON. Indica que la solicitud no se pudo analizar como JSON o contenía campos no válidos (por ejemplo, pasar una cadena donde se esperaba un número). El motivo exacto del error se describe en la respuesta y el problema debe solucionarse antes de poder volver a intentar la solicitud.
401 Se produjo un error al autenticar la cuenta del remitente.
5xx Los errores en el rango 500-599 (como 500 o 503) indican que hubo un error interno en el backend de FCM al intentar procesar la solicitud o que el servidor no está disponible temporalmente (por ejemplo, debido a tiempos de espera). El remitente debe volver a intentarlo más tarde, respetando cualquier encabezado Retry-After incluido en la respuesta. Los servidores de aplicaciones deben implementar un retroceso exponencial.

La siguiente tabla enumera los campos en un cuerpo de respuesta de mensaje posterior (JSON).

Tabla 5. Cuerpo de respuesta del mensaje HTTP descendente (JSON).

Parámetro Uso Descripción
multicast_id Numero requerido ID único (número) que identifica el mensaje de multidifusión.
success Numero requerido Número de mensajes que se procesaron sin error.
failure Numero requerido Número de mensajes que no se pudieron procesar.
results Requerido, conjunto de objetos. Matriz de objetos que representan el estado de los mensajes procesados. Los objetos se enumeran en el mismo orden que la solicitud (es decir, para cada ID de registro en la solicitud, su resultado se enumera en el mismo índice en la respuesta).
  • message_id : Cadena que especifica una identificación única para cada mensaje procesado exitosamente.
  • error : Cadena que especifica el error que ocurrió al procesar el mensaje para el destinatario. Los valores posibles se pueden encontrar en la tabla 9 .

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

Parámetro Uso Descripción
message_id Opcional, número El ID del mensaje del tema cuando FCM haya recibido correctamente la solicitud e intentará entregarla a todos los dispositivos suscritos.
error Opcional, cadena Error que ocurrió al procesar el mensaje. Los valores posibles se pueden encontrar en la tabla 9 .

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

Parámetro Uso Descripción
id Requerido, cadena Este parámetro especifica el ID de mensaje único que FCM procesó correctamente.
registration_id Opcional, cadena Este parámetro especifica el token de registro para la aplicación cliente a la que se procesó y envió el mensaje.

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

Parámetro Uso Descripción
Error Requerido, cadena Este parámetro especifica el valor de error al procesar el mensaje para el destinatario. Consulte la tabla 9 para obtener más detalles.

Códigos de respuesta de error de mensajes posteriores

La siguiente tabla enumera los códigos de respuesta de error para mensajes posteriores.

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

Error Código HTTP Acción sugerida
Token de registro faltante 200 + error:FaltaRegistro Compruebe que la solicitud contenga un token de registro (en el registration_id en un mensaje de texto sin formato, o en el campo to o registration_ids en JSON).
Token de registro no válido 200 + error: Registro no válido Verifique el formato del token de registro que pasa al servidor. Asegúrese de que coincida con el token de registro que recibe la aplicación cliente al registrarse en Firebase Notifications. No trunque ni agregue caracteres adicionales.
Dispositivo no registrado 200 + error: No registrado Un token de registro existente puede dejar de ser válido en varios escenarios, entre ellos:
  • Si la aplicación cliente se da de baja de FCM.
  • Si la aplicación cliente se cancela automáticamente, lo que puede suceder si el usuario desinstala la aplicación. Por ejemplo, en iOS, si el servicio de comentarios de APN informa que el token de APN no es válido.
  • Si el token de registro caduca (por ejemplo, Google podría decidir actualizar los tokens de registro o el token APN ha caducado para dispositivos iOS).
  • Si la aplicación cliente se actualiza pero la nueva versión no está configurada para recibir mensajes.
Para todos estos casos, elimine este token de registro del servidor de aplicaciones y deje de usarlo para enviar mensajes.
Nombre de paquete no válido 200 + error: nombre de paquete no válido Asegúrese de que el mensaje esté dirigido a un token de registro cuyo nombre de paquete coincida con el valor pasado en la solicitud.
Error de autenticación 401 No se pudo autenticar la cuenta del remitente utilizada para enviar un mensaje. Las posibles causas son:
  • Falta el encabezado de autorización o la sintaxis no es válida en la solicitud HTTP.
  • El proyecto de Firebase al que pertenece la clave del servidor especificada es incorrecto.
  • Solo claves de servidor heredadas: la solicitud se originó en un servidor que no está incluido en la lista blanca de IP de clave de servidor.
Verifique que el token que está enviando dentro del encabezado de Autenticación sea la clave de servidor correcta asociada con su proyecto. Consulte Comprobación de la validez de una clave de servidor para obtener más detalles. Si está utilizando una clave de servidor heredada, se recomienda actualizar a una nueva clave que no tenga restricciones de IP. Consulte Migrar claves de servidor heredadas .
Remitente no coincidente 200 + error: MismatchSenderId Un token de registro está vinculado a un determinado grupo de remitentes. Cuando una aplicación cliente se registra en FCM, debe especificar qué remitentes pueden enviar mensajes. Debe utilizar una de esas ID de remitente al enviar mensajes a la aplicación cliente. Si cambia a un remitente diferente, los tokens de registro existentes no funcionarán.
JSON no válido 400 Verifique que el mensaje JSON tenga el formato correcto y contenga campos válidos (por ejemplo, asegurándose de que se pase el tipo de datos correcto).
Parámetros inválidos 400 + error: parámetros no válidos Compruebe que los parámetros proporcionados tengan el nombre y tipo correctos.
Mensaje demasiado grande 200 + error: Mensaje demasiado grande Verifique que el tamaño total de los datos de carga útil incluidos en un mensaje no exceda los límites de FCM: 4096 bytes para la mayoría de los mensajes o 2048 bytes en el caso de mensajes a temas. Esto incluye tanto las claves como los valores.
Clave de datos no válida 200+ error:
Clave de datos no válida
Compruebe que los datos de la carga útil no contengan una clave (como from , gcm o cualquier valor con el prefijo google ) que FCM utilice internamente. Tenga en cuenta que FCM también utiliza algunas palabras (como collapse_key ) pero están permitidas en la carga útil, en cuyo caso el valor de FCM anulará el valor de la carga útil.
Tiempo de vida no válido 200 + error: Ttl no válido Compruebe que el valor utilizado en time_to_live sea un número entero que represente una duración en segundos entre 0 y 2.419.200 (4 semanas).
Se acabó el tiempo Error 5xx o 200 +: No disponible

El servidor no pudo procesar la solicitud a tiempo. Vuelva a intentar la misma solicitud, pero debe:

  • Respete el encabezado Retry-After si está incluido en la respuesta del servidor de conexión FCM.
  • Implemente un retroceso exponencial en su mecanismo de reintento. (por ejemplo, si esperó un segundo antes del primer reintento, espere al menos dos segundos antes del siguiente, luego 4 segundos y así sucesivamente). Si envía varios mensajes, retrase cada uno de ellos de forma independiente una cantidad aleatoria adicional para evitar emitir una nueva solicitud para todos los mensajes al mismo tiempo.

Los remitentes que causan problemas corren el riesgo de ser incluidos en la lista negra.

Error Interno del Servidor Error 500 o 200 +: InternalServerError El servidor encontró un error al intentar procesar la solicitud. Puede volver a intentar la misma solicitud siguiendo los requisitos enumerados en "Tiempo de espera" (consulte la fila anterior). Si el error persiste, comuníquese con el soporte de Firebase .
Se superó la tasa de mensajes del dispositivo 200+ error:
Tasa de mensajes del dispositivo
Excedido

La tasa de mensajes a un dispositivo en particular es demasiado alta. Si una aplicación de Apple envía mensajes a una velocidad que excede los límites de APN, puede recibir este mensaje de error

Reduzca la cantidad de mensajes enviados a este dispositivo y utilice un retroceso exponencial para volver a intentar enviarlos.

Tasa de mensajes de temas superada 200+ error:
TemasMensajeRate
Excedido
La tasa de mensajes a suscriptores de un tema en particular es demasiado alta. Reduzca la cantidad de mensajes enviados para este tema y utilice un retroceso exponencial para volver a intentar enviarlos.
Credenciales de APN no válidas 200+ error:
CredencialApns no válida
No se pudo enviar un mensaje dirigido a un dispositivo Apple porque la clave de autenticación de APN requerida no se cargó o expiró. Verifique la validez de sus credenciales de desarrollo y producción.

Gestión de grupos de dispositivos

La siguiente tabla enumera las claves para crear grupos de dispositivos y agregar y eliminar miembros. Para obtener más información, consulta la guía de tu plataforma, iOS+ o Android .

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

Parámetro Uso Descripción
operation Requerido, cadena La operación a ejecutar. Los valores válidos son create , add y remove .
notification_key_name Requerido, cadena El nombre definido por el usuario del grupo de dispositivos que se creará o modificará.
notification_key Requerido (excepto para la operación create , cadena Identificador único del grupo de dispositivos. Este valor se devuelve en la respuesta para una operación create exitosa y es necesario para todas las operaciones posteriores en el grupo de dispositivos.
registration_ids Requerido, conjunto de cadenas Los tokens del dispositivo para agregar o eliminar. Si elimina todos los tokens de registro existentes de un grupo de dispositivos, FCM elimina el grupo de dispositivos.