Protocolo HTTP do Firebase Cloud Messaging

Cuidado: o envio de mensagens (incluindo mensagens upstream) com as APIs legadas FCM XMPP e HTTP foi descontinuado em 20 de junho de 2023 e será removido em junho de 2024 . Se você estiver usando APIs de envio herdadas do FCM, recomendamos fortemente que você migre para a API HTTP v1 ou considere usar o Admin SDK para criar solicitações de envio.

Este documento fornece uma referência para a sintaxe HTTP usada para transmitir mensagens do servidor de aplicativos para aplicativos cliente por meio do Firebase Cloud Messaging.

Os aplicativos que usam a API HTTP legada do FCM devem considerar a migração para a API HTTP v1. Consulte o guia de migração para obter mais informações sobre as vantagens da API v1 e obter instruções de migração.

Ao usar o protocolo HTTP legado, o servidor do seu aplicativo deve direcionar todas as solicitações HTTP para este endpoint:

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

Os parâmetros e opções disponíveis se enquadram nas seguintes categorias amplas:

• Sintaxe de mensagem downstream
• Códigos de resposta de erro de mensagem downstream

Sintaxe de mensagem downstream

Esta seção fornece a sintaxe para enviar mensagens downstream e interpretar respostas HTTP do Firebase Cloud Messaging.

Mensagens HTTP downstream (JSON)

A tabela a seguir lista os destinos, as opções e a carga útil para mensagens HTTP JSON.

Tabela 1. Destinos, opções e carga útil para mensagens HTTP downstream (JSON).

Parâmetro	Uso	Descrição
Alvos
to	Opcional, sequência	Este parâmetro especifica o destinatário de uma mensagem. O valor pode ser um token de registro de dispositivo, uma chave de notificação de grupo de dispositivos ou um único tópico (prefixado com /topics/ ). Para enviar para vários tópicos, use o parâmetro condition .
registration_ids	Opcional, matriz de strings	Este parâmetro especifica o destinatário de uma mensagem multicast, uma mensagem enviada para mais de um token de registro. O valor deve ser uma matriz de tokens de registro para os quais a mensagem multicast será enviada. A matriz deve conter no mínimo 1 e no máximo 1.000 tokens de registro. Para enviar uma mensagem para um único dispositivo, use o parâmetro to . Mensagens multicast só são permitidas usando o formato HTTP JSON.
condition	Opcional, sequência	Este parâmetro especifica uma expressão lógica de condições que determinam o destino da mensagem. Condição suportada: Tópico, formatado como "'yourTopic' em tópicos". Este valor não diferencia maiúsculas de minúsculas. Operadores suportados: && , || . Máximo de dois operadores por mensagem de tópico suportados.
notification_key Descontinuada	Opcional, sequência	Este parâmetro está obsoleto. Em vez disso, use to para especificar os destinatários da mensagem. Para obter mais informações sobre como enviar mensagens para vários dispositivos, consulte a documentação da sua plataforma.
Opções
collapse_key	Opcional, sequência	Este parâmetro identifica um grupo de mensagens (por exemplo, collapse_key: "Updates Available" ) que podem ser recolhidas, de modo que apenas a última mensagem seja enviada quando a entrega puder ser retomada. O objetivo é evitar o envio de muitas mensagens iguais quando o dispositivo voltar a ficar on-line ou ficar ativo. Observe que não há garantia da ordem em que as mensagens são enviadas. Nota: São permitidas no máximo 4 chaves de recolhimento diferentes a qualquer momento. Isso significa que o FCM pode armazenar simultaneamente 4 mensagens diferentes por aplicativo cliente. Se você exceder esse número, não há garantia de quais 4 chaves de recolhimento o FCM manterá.
priority	Opcional, sequência	Define a prioridade da mensagem. Os valores válidos são “normal” e “alto”. Nas plataformas Apple, correspondem às prioridades 5 e 10 dos APNs. Por padrão, as mensagens de notificação são enviadas com prioridade alta e as mensagens de dados são enviadas com prioridade normal. A prioridade normal otimiza o consumo de bateria do aplicativo cliente e deve ser usada a menos que seja necessária entrega imediata. Para mensagens com prioridade normal, o aplicativo pode receber a mensagem com atraso indeterminado. Quando uma mensagem é enviada com alta prioridade, ela é enviada imediatamente e o aplicativo pode exibir uma notificação.
content_available	Opcional, booleano	Nas plataformas Apple, use este campo para representar content-available na carga útil dos APNs. Quando uma notificação ou mensagem é enviada e definida como true , um aplicativo cliente inativo é ativado e a mensagem é enviada por meio de APNs como uma notificação silenciosa e não por meio de FCM. Observe que as notificações silenciosas em APNs não têm garantia de entrega e podem depender de fatores como o usuário ativar o modo de baixo consumo, forçar o encerramento do aplicativo, etc. No Android, as mensagens de dados ativam o aplicativo por padrão. No Chrome, atualmente não é compatível.
mutable_content	Opcional, JSON booleano	Nas plataformas Apple, use este campo para representar mutable-content na carga útil dos APNs. Quando uma notificação é enviada e está definida como true , o conteúdo da notificação pode ser modificado antes de ser exibido, usando uma extensão de aplicativo do Notification Service . Este parâmetro será ignorado para Android e web.
time_to_live	Opcional, número	Este parâmetro especifica por quanto tempo (em segundos) a mensagem deve ser mantida no armazenamento FCM se o dispositivo estiver offline. O tempo máximo de vida suportado é de 4 semanas e o valor padrão é de 4 semanas. Para obter mais informações, consulte Configurando a vida útil de uma mensagem .
restricted_package_ name (somente Android)	Opcional, sequência	Este parâmetro especifica o nome do pacote do aplicativo ao qual os tokens de registro devem corresponder para receber a mensagem.
dry_run	Opcional, booleano	Este parâmetro, quando definido como true , permite que os desenvolvedores testem uma solicitação sem realmente enviar uma mensagem. O valor padrão é false .
Carga útil
data	Opcional, objeto	Este parâmetro especifica os pares de valores-chave personalizados da carga útil da mensagem. Por exemplo, com data:{"score":"3x1"}: Nas plataformas Apple, se a mensagem for enviada via APNs, ela representa os campos de dados personalizados. Se for enviado via FCM, será representado como dicionário de valor-chave em AppDelegate application:didReceiveRemoteNotification: . No Android, isso resultaria em uma score extra nomeada de intenção com o valor da string 3x1 . A chave não deve ser uma palavra reservada ("from", "message_type" ou qualquer palavra que comece com "google" ou "gcm"). Não use nenhuma das palavras definidas nesta tabela (como collapse_key ). Valores em tipos de string são recomendados. Você deve converter valores em objetos ou outros tipos de dados que não sejam string (por exemplo, inteiros ou booleanos) em string.
notification	Opcional, objeto	Este parâmetro especifica os pares de valores-chave predefinidos e visíveis ao usuário da carga de notificação. Consulte Suporte à carga útil de notificação para obter detalhes. Para obter mais informações sobre opções de mensagens de notificação e mensagens de dados, consulte Tipos de mensagens . Se uma carga de notificação for fornecida ou a opção content_available for definida como true para uma mensagem para um dispositivo Apple, a mensagem será enviada por meio de APNs , caso contrário, será enviada por meio de FCM.

Suporte a carga útil de notificação

As tabelas a seguir listam as chaves predefinidas disponíveis para criar mensagens de notificação para iOS e Android.

Tabela 2a. iOS — chaves para mensagens de notificação

Parâmetro	Uso	Descrição
title	Opcional, sequência	O título da notificação. Este campo não está visível em telefones e tablets.
body	Opcional, sequência	O texto do corpo da notificação.
sound	Opcional, sequência	O som a ser reproduzido quando o dispositivo recebe a notificação. String especificando arquivos de som no pacote principal do aplicativo cliente ou na pasta Library/Sounds do contêiner de dados do aplicativo. Consulte a Biblioteca de Desenvolvedores iOS para obter mais informações.
badge	Opcional, sequência	O valor do selo no ícone do aplicativo na tela inicial. Se não for especificado, o emblema não será alterado. Se definido como 0 , o emblema será removido.
click_action	Opcional, sequência	A ação associada a um clique do usuário na notificação. Corresponde à category na carga útil dos APNs.
subtitle	Opcional, sequência	O subtítulo da notificação.
body_loc_key	Opcional, sequência	A chave para a string do corpo nos recursos de string do aplicativo a serem usados ​​para localizar o texto do corpo para a localização atual do usuário. Corresponde à loc-key na carga útil dos APNs. Consulte Referência de chave de carga útil e localização do conteúdo de suas notificações remotas para obter mais informações.
body_loc_args	Opcional, matriz JSON como string	Valores de string variáveis ​​a serem usados ​​no lugar dos especificadores de formato em body_loc_key a serem usados ​​para localizar o texto do corpo para a localização atual do usuário. Corresponde a loc-args na carga útil dos APNs. Consulte Referência de chave de carga útil e localização do conteúdo de suas notificações remotas para obter mais informações.
title_loc_key	Opcional, sequência	A chave para a string de título nos recursos de string do aplicativo a serem usados ​​para localizar o texto do título para a localização atual do usuário. Corresponde à title-loc-key na carga útil dos APNs. Consulte Referência de chave de carga útil e localização do conteúdo de suas notificações remotas para obter mais informações.
title_loc_args	Opcional, matriz JSON como string	Valores de string variáveis ​​a serem usados ​​no lugar dos especificadores de formato em title_loc_key a serem usados ​​para localizar o texto do título para a localização atual do usuário. Corresponde a title-loc-args na carga útil dos APNs. Consulte Referência de chave de carga útil e localização do conteúdo de suas notificações remotas para obter mais informações.

Tabela 2b. Android — chaves para mensagens de notificação

Parâmetro	Uso	Descrição
title	Opcional, sequência	O título da notificação.
body	Opcional, sequência	O texto do corpo da notificação.
android_channel_id	Opcional, sequência	O ID do canal da notificação (novo no Android O). O aplicativo deve criar um canal com esse ID de canal antes que qualquer notificação com esse ID de canal seja recebida. Se você não enviar esse ID de canal na solicitação ou se o ID de canal fornecido ainda não tiver sido criado pelo aplicativo, o FCM usará o ID de canal especificado no manifesto do aplicativo.
icon	Opcional, sequência	O ícone da notificação. Define o ícone de notificação como myicon para o recurso drawable myicon . Se você não enviar essa chave na solicitação, o FCM exibirá o ícone do iniciador especificado no manifesto do seu aplicativo.
sound	Opcional, sequência	O som a ser reproduzido quando o dispositivo recebe a notificação. Suporta "default" ou o nome do arquivo de um recurso de som incluído no aplicativo. Os arquivos de som devem residir em /res/raw/ .
tag	Opcional, sequência	Identificador usado para substituir notificações existentes na gaveta de notificações. Se não for especificado, cada solicitação criará uma nova notificação. Se especificado e uma notificação com a mesma tag já estiver sendo mostrada, a nova notificação substituirá a existente na gaveta de notificações.
color	Opcional, sequência	A cor do ícone da notificação, expressa no formato #rrggbb .
click_action	Opcional, sequência	A ação associada a um clique do usuário na notificação. Se especificado, uma atividade com um filtro de intenção correspondente será iniciada quando um usuário clicar na notificação.
body_loc_key	Opcional, sequência	A chave para a string do corpo nos recursos de string do aplicativo a serem usados ​​para localizar o texto do corpo para a localização atual do usuário. Consulte Recursos de String para obter mais informações.
body_loc_args	Opcional, matriz JSON como string	Valores de string variáveis ​​a serem usados ​​no lugar dos especificadores de formato em body_loc_key a serem usados ​​para localizar o texto do corpo para a localização atual do usuário. Consulte Formatação e estilo para obter mais informações.
title_loc_key	Opcional, sequência	A chave para a string de título nos recursos de string do aplicativo a serem usados ​​para localizar o texto do título para a localização atual do usuário. Consulte Recursos de String para obter mais informações.
title_loc_args	Opcional, matriz JSON como string	Valores de string variáveis ​​a serem usados ​​no lugar dos especificadores de formato em title_loc_key a serem usados ​​para localizar o texto do título para a localização atual do usuário. Consulte Formatação e estilo para obter mais informações.

Tabela 2c. Web (JavaScript) — chaves para mensagens de notificação

Parâmetro	Uso	Descrição
title	Opcional, sequência	O título da notificação.
body	Opcional, sequência	O texto do corpo da notificação.
icon	Opcional, sequência	A URL a ser usada para o ícone da notificação.
click_action	Opcional, sequência	A ação associada a um clique do usuário na notificação. Para todos os valores de URL, HTTPS é obrigatório.

Mensagens HTTP downstream (texto simples)

A tabela a seguir lista a sintaxe para destinos, opções e carga útil em mensagens HTTP downstream de texto simples.

Tabela 3. Destinos, opções e carga útil para mensagens HTTP de texto simples downstream.

Parâmetro	Uso	Descrição
Alvos
registration_id	Obrigatório, sequência	Este parâmetro especifica os aplicativos cliente (tokens de registro) que recebem a mensagem. Mensagens multicast (envio para mais de um token de registro) são permitidas somente no formato HTTP JSON.
Opções
collapse_key	Opcional, sequência	Consulte a tabela 1 para obter detalhes.
time_to_live	Opcional, número	Consulte a tabela 1 para obter detalhes.
restricted_package_name	Opcional, sequência	Consulte a tabela 1 para obter detalhes.
dry_run	Opcional, booleano	Consulte a tabela 1 para obter detalhes.
Carga útil
data.<key>	Opcional, sequência	Este parâmetro especifica os pares de valores-chave da carga útil da mensagem. Não há limite para o número de parâmetros de valor-chave, mas há um limite total de tamanho de mensagem de 4.000 bytes. Por exemplo, no Android, "data.score"."3x1" resultaria em uma score extra nomeada de intenção com o valor da string 3x1 . A chave não deve ser uma palavra reservada ("from", "message_type" ou qualquer palavra que comece com "google" ou "gcm"). Não use nenhuma das palavras definidas nesta tabela (como collapse_key ).

Interpretando uma resposta de mensagem downstream

O servidor do aplicativo deve avaliar o cabeçalho e o corpo da resposta da mensagem para interpretar a resposta da mensagem enviada pelo FCM. A tabela a seguir descreve as respostas possíveis.

Tabela 4. Cabeçalho de resposta de mensagem HTTP downstream.

Resposta	Descrição
200	A mensagem foi processada com sucesso. O corpo da resposta conterá mais detalhes sobre o status da mensagem, mas seu formato dependerá se a solicitação foi JSON ou texto simples. Consulte a tabela 5 para obter mais detalhes.
400	Aplica-se apenas a solicitações JSON. Indica que a solicitação não pôde ser analisada como JSON ou continha campos inválidos (por exemplo, passar uma string onde era esperado um número). O motivo exato da falha está descrito na resposta e o problema deve ser resolvido antes que a solicitação possa ser repetida.
401	Ocorreu um erro ao autenticar a conta do remetente.
5xx	Erros no intervalo 500-599 (como 500 ou 503) indicam que houve um erro interno no back-end do FCM ao tentar processar a solicitação ou que o servidor está temporariamente indisponível (por exemplo, devido a tempos limite). O remetente deve tentar novamente mais tarde, respeitando qualquer cabeçalho Retry-After incluído na resposta. Os servidores de aplicativos devem implementar a retirada exponencial.

A tabela a seguir lista os campos em um corpo de resposta de mensagem downstream (JSON).

Tabela 5. Corpo de resposta de mensagem HTTP downstream (JSON).

Parâmetro	Uso	Descrição
multicast_id	Obrigatório, número	ID exclusivo (número) que identifica a mensagem multicast.
success	Obrigatório, número	Número de mensagens que foram processadas sem erros.
failure	Obrigatório, número	Número de mensagens que não puderam ser processadas.
results	Obrigatório, matriz de objetos	Matriz de objetos que representam o status das mensagens processadas. Os objetos são listados na mesma ordem da solicitação (ou seja, para cada ID de registro na solicitação, seu resultado é listado no mesmo índice da resposta). message_id : String especificando um ID exclusivo para cada mensagem processada com sucesso. error : String especificando o erro ocorrido ao processar a mensagem para o destinatário. Os valores possíveis podem ser encontrados na tabela 9 .

Tabela 6. Corpo de resposta HTTP (JSON) da mensagem do tópico.

Parâmetro	Uso	Descrição
message_id	Opcional, número	O ID da mensagem do tópico quando o FCM recebeu a solicitação com êxito e tentará entregar a todos os dispositivos inscritos.
error	Opcional, sequência	Erro que ocorreu ao processar a mensagem. Os valores possíveis podem ser encontrados na tabela 9 .

Tabela 7. Resposta de sucesso para corpo de resposta de mensagem HTTP downstream (texto simples).

Parâmetro	Uso	Descrição
id	Obrigatório, sequência	Este parâmetro especifica o ID de mensagem exclusivo que o FCM processou com êxito.
registration_id	Opcional, sequência	Este parâmetro especifica o token de registro do aplicativo cliente para o qual a mensagem foi processada e enviada.

Tabela 8. Resposta de erro para corpo de resposta de mensagem HTTP downstream (texto simples).

Parâmetro	Uso	Descrição
Error	Obrigatório, sequência	Este parâmetro especifica o valor do erro ao processar a mensagem para o destinatário. Consulte a tabela 9 para obter detalhes.

Códigos de resposta de erro de mensagem downstream

A tabela a seguir lista os códigos de resposta de erro para mensagens downstream.

Tabela 9. Códigos de resposta de erro de mensagem downstream.

Erro	Código HTTP	Ação recomendada
Token de registro ausente	200 + erro: Registro ausente	Verifique se a solicitação contém um token de registro (no registration_id em uma mensagem de texto simples ou no campo to ou registration_ids em JSON).
Token de registro inválido	200 + erro:Registro inválido	Verifique o formato do token de registro que você passa ao servidor. Verifique se ele corresponde ao token de registro que o aplicativo cliente recebe ao se registrar no Firebase Notifications. Não trunque ou adicione caracteres adicionais.
Dispositivo não registrado	200 + erro:Não registrado	Um token de registro existente pode deixar de ser válido em vários cenários, incluindo: Se o aplicativo cliente cancelar o registro no FCM. Se o registro do aplicativo cliente for automaticamente cancelado, o que pode acontecer se o usuário desinstalar o aplicativo. Por exemplo, no iOS, se o Serviço de Feedback de APNs reportar o token de APNs como inválido. Se o token de registro expirar (por exemplo, o Google pode decidir atualizar os tokens de registro ou o token APNs expirou para dispositivos iOS). Se o aplicativo cliente estiver atualizado, mas a nova versão não estiver configurada para receber mensagens. Para todos esses casos, remova esse token de registro do servidor do aplicativo e pare de usá-lo para enviar mensagens.
Nome de pacote inválido	200 + erro:InvalidPackageName	Certifique-se de que a mensagem foi endereçada a um token de registro cujo nome do pacote corresponda ao valor passado na solicitação.
Erro de autenticação	401	A conta do remetente usada para enviar uma mensagem não pôde ser autenticada. As possíveis causas são: Cabeçalho de autorização ausente ou com sintaxe inválida na solicitação HTTP. O projeto do Firebase ao qual pertence a chave do servidor especificada está incorreto. Somente chaves de servidor herdadas: a solicitação originada de um servidor que não está na lista de permissões nos IPs de chave do servidor. Verifique se o token que você está enviando dentro do cabeçalho Authentication é a chave de servidor correta associada ao seu projeto. Consulte Verificando a validade de uma chave de servidor para obter detalhes. Se você estiver usando uma chave de servidor herdada, é recomendável atualizar para uma nova chave que não tenha restrições de IP. Consulte Migrar chaves de servidor legado .
Remetente incompatível	200 + erro:IncompatibilidadeSenderId	Um token de registro está vinculado a um determinado grupo de remetentes. Quando um aplicativo cliente se registra no FCM, ele precisa especificar quais remetentes têm permissão para enviar mensagens. Você deve usar um desses IDs de remetente ao enviar mensagens para o aplicativo cliente. Se você mudar para um remetente diferente, os tokens de registro existentes não funcionarão.
JSON inválido	400	Verifique se a mensagem JSON está formatada corretamente e contém campos válidos (por exemplo, certificando-se de que o tipo de dados correto foi transmitido).
Parâmetros inválidos	400 + erro: Parâmetros inválidos	Verifique se os parâmetros fornecidos têm o nome e o tipo corretos.
Mensagem muito grande	200 + erro: Mensagem Muito Grande	Verifique se o tamanho total dos dados de carga incluídos em uma mensagem não excede os limites do FCM: 4.096 bytes para a maioria das mensagens ou 2.048 bytes no caso de mensagens para tópicos. Isso inclui as chaves e os valores.
Chave de dados inválida	200 + erro: DataKey inválida	Verifique se os dados da carga útil não contêm uma chave (como from ou gcm ou qualquer valor prefixado por google ) que seja usada internamente pelo FCM. Observe que algumas palavras (como collapse_key ) também são usadas pelo FCM, mas são permitidas na carga útil; nesse caso, o valor da carga útil será substituído pelo valor do FCM.
Tempo de vida inválido	200 + erro:Ttl inválido	Verifique se o valor usado em time_to_live é um número inteiro que representa uma duração em segundos entre 0 e 2.419.200 (4 semanas).
Tempo esgotado	Erro 5xx ou 200 +: Indisponível	O servidor não conseguiu processar a solicitação a tempo. Tente novamente a mesma solicitação, mas você deve: Respeite o cabeçalho Retry-After se ele estiver incluído na resposta do FCM Connection Server. Implemente a retirada exponencial em seu mecanismo de nova tentativa. (por exemplo, se você esperou um segundo antes da primeira tentativa, espere pelo menos dois segundos antes da próxima, depois 4 segundos e assim por diante). Se você estiver enviando várias mensagens, atrase cada uma delas de forma independente por um valor aleatório adicional para evitar a emissão de uma nova solicitação para todas as mensagens ao mesmo tempo. Remetentes que causam problemas correm o risco de serem colocados na lista negra.
Erro do Servidor Interno	500 ou 200 + erro:InternalServerError	O servidor encontrou um erro ao tentar processar a solicitação. Você pode tentar novamente a mesma solicitação seguindo os requisitos listados em "Tempo limite" (veja a linha acima). Se o erro persistir, entre em contato com o suporte do Firebase .
Taxa de mensagens do dispositivo excedida	200 + erro: Taxa de mensagem do dispositivo Excedido	A taxa de mensagens para um determinado dispositivo é muito alta. Se um aplicativo da Apple enviar mensagens a uma taxa que excede os limites de APNs, ele poderá receber esta mensagem de erro Reduza o número de mensagens enviadas para este dispositivo e use a espera exponencial para tentar enviar novamente.
Taxa de mensagens de tópicos excedida	200 + erro: TópicosMensagemTaxa Excedido	A taxa de mensagens para assinantes de um determinado tópico é muito alta. Reduza o número de mensagens enviadas para este tópico e use a espera exponencial para tentar enviar novamente.
Credenciais de APNs inválidas	200 + erro: Credencial Apns inválida	Não foi possível enviar uma mensagem direcionada a um dispositivo Apple porque a chave de autenticação de APNs necessária não foi carregada ou expirou. Verifique a validade de suas credenciais de desenvolvimento e produção.

Gerenciamento de grupo de dispositivos

A tabela a seguir lista as chaves para criar grupos de dispositivos e adicionar e remover membros. Para obter mais informações, consulte o guia da sua plataforma, iOS+ ou Android .

Tabela 10. Chaves de gerenciamento de grupo de dispositivos.

Parâmetro	Uso	Descrição
operation	Obrigatório, sequência	A operação a ser executada. Os valores válidos são create , add e remove .
notification_key_name	Obrigatório, sequência	O nome definido pelo usuário do grupo de dispositivos a ser criado ou modificado.
notification_key	Obrigatório (exceto para operação create , string	Identificador exclusivo do grupo de dispositivos. Esse valor é retornado na resposta para uma operação create bem-sucedida e é necessário para todas as operações subsequentes no grupo de dispositivos.
registration_ids	Obrigatório, matriz de strings	Os tokens de dispositivo a serem adicionados ou removidos. Se você remover todos os tokens de registro existentes de um grupo de dispositivos, o FCM excluirá o grupo de dispositivos.