Esta página se ha traducido con Cloud Translation API.

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
Códigos de respuesta de error de mensajes posteriores

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.