Protocolo HTTP do Firebase Cloud Messaging

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

Este documento oferece uma referência para a sintaxe HTTP usada para encaminhar mensagens do servidor de aplicativos para apps cliente via Firebase Cloud Messaging.

Os apps que usam a API HTTP legada do FCM precisam migrar para a API HTTP v1. Veja o guia de migração para mais informações sobre as vantagens da API v1 e para instruções de migração.

Ao usar o protocolo HTTP legado, seu servidor do app precisa direcionar todas as solicitações HTTP para este ponto de extremidade:

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

Os parâmetros e as opções se enquadram nestas categorias amplas:

• sintaxe de mensagens downstream
• códigos de resposta de erro de mensagens downstream

sintaxe de mensagens 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 o payload para mensagens JSON HTTP.

Tabela 1. Destinos, opções e payload para mensagens HTTP (JSON).

Parâmetro	Uso	Descrição
Metas
to	Opcional, string	Este parâmetro especifica o destinatário de uma mensagem. O valor pode ser o token de registro de um dispositivo, a chave de notificação de um grupo de dispositivos ou um único tópico (prefixado com /topics/). Para enviar a 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 a mais de um token de registro. O valor deve ser uma matriz de tokens de registro para onde enviar a mensagem multicast. A matriz precisa conter pelo menos 1 e no máximo 1.000 tokens de registro. Para enviar uma mensagem a um único dispositivo, use o parâmetro to. As mensagens multicast só são permitidas usando o formato HTTP JSON.
condition	Opcional, string	Este parâmetro especifica uma expressão lógica de condições que determinam o destino da mensagem. Condição aceita: tópico, formatado como "'seuTópico' em tópicos". Esse valor não diferencia minúsculas de maiúsculas. Operadores compatíveis: &&, ||. No máximo dois operadores são permitidos por mensagem de tópico.
notification_key Obsoleto	Opcional, string	Este parâmetro foi descontinuado. Use to para especificar destinatários da mensagem. Para mais informações sobre como enviar mensagens a vários dispositivos, consulte a documentação da sua plataforma.
Opções
collapse_key	Opcional, string	Este parâmetro identifica um grupo de mensagens (por exemplo, com collapse_key: "Updates Available") que podem ser recolhidas, para que apenas a última seja enviada quando a entrega puder ser feita. O objetivo disso é evitar o envio de um número excessivo de mensagens iguais quando o dispositivo voltar a ficar on-line ou ativo. Não há garantia da ordem em que as mensagens são enviadas. No máximo quatro chaves de recolhimento diferentes são permitidas a qualquer momento. Isso significa que o FCM pode armazenar simultaneamente quatro mensagens diferentes por app cliente. Se você exceder esse limite, não há garantia de qual das quatro chaves recolhidas será mantida pelo FCM.
priority	Opcional, string	Define a prioridade da mensagem. Os valores válidos são "normal" e "high" (alta). Nas plataformas Apple, eles correspondem às prioridades 5 e 10 de APNs. Por padrão, as mensagens de notificação são enviadas com prioridade alta e as mensagens de dados com prioridade normal. A prioridade normal otimiza o consumo de bateria do app cliente e deve ser sempre usada, exceto quando a entrega imediata é necessária. Mensagens com prioridade normal podem ser recebidas pelo app com atraso não especificado. Uma mensagem com prioridade alta é enviada imediatamente, e o app pode exibir uma notificação.
content_available	Opcional, booleano	Nas plataformas Apple, use este campo para representar content-available no payload de APNs. Quando uma notificação ou mensagem é enviada e o campo está definido como true, um app cliente inativo é ativado e a mensagem é enviada por APNs como uma notificação silenciosa e não pelo servidor de conexão do FCM. Não é garantido que essas notificações silenciosas em APNs sejam entregues e isso depende de fatores como o usuário ativar o modo de baixo consumo, saída forçada do app etc. No Android, as mensagens de dados ativam o app por padrão. Ainda não há compatibilidade com o Chrome.
mutable_content	Opcional, JSON booleano	Nas plataformas Apple, use este campo para representar mutable-content no payload de APNs. Quando uma notificação é enviada e este campo está definido como true, o conteúdo dela pode ser modificado antes da exibição por uma extensão de app do serviço de notificação. No Android e na Web, esse parâmetro é ignorado.
time_to_live	Opcional, número	Este parâmetro especifica o tempo, em segundos, de manutenção da mensagem no armazenamento do FCM se o dispositivo ficar off-line. A vida útil máxima permitida é 4 semanas, que também é o valor padrão. Para mais informações, consulte Definir a vida útil de uma mensagem.
restricted_package_ name (somente no Android)	Opcional, string	Este parâmetro especifica o nome do pacote do app no qual os tokens de registro precisam corresponder para receber a mensagem.
dry_run	Opcional, booleano	Quando definido como true, este parâmetro permite que os desenvolvedores testem uma solicitação sem realmente enviar uma mensagem. O valor padrão é false.
Payload
data	Opcional, objeto	Este parâmetro especifica os pares de chave-valor personalizados do payload da mensagem. Por exemplo, com data:{"score":"3x1"}: Nas plataformas Apple, se a mensagem é enviada por APNs, ela é representada por campos de dados personalizados. Se for enviada pelo FCM, ela será representada como um dicionário de chave-valor no AppDelegate application:didReceiveRemoteNotification:. No Android, isso resulta em uma intent adicional chamada score com o valor de string 3x1. A chave não pode ser uma palavra reservada, por exemplo, "from", "message_type" ou qualquer palavra que comece com "google" ou "gcm". Não use palavras definidas nesta tabela como, por exemplo, collapse_key. É recomendável usar valores do tipo string. É preciso converter os valores nos objetos ou outros tipos de dados sem string (por exemplo, números inteiros ou booleanos) para string.
notification	Opcional, objeto	Este parâmetro especifica os pares chave-valor predefinidos do payload da notificação, visíveis ao usuário. Consulte o suporte do payload para mais detalhes. Para ver mais informações sobre a mensagem de notificação e opções de mensagens de dados, consulte Tipos de mensagem. Se houver um payload de notificação ou a opção content_available estiver definida como true em uma mensagem para um dispositivo da Apple, a mensagem será enviada por APNs. Caso contrário, ela será enviada pelo FCM.

Suporte ao payload 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, string	O título da notificação. Este campo não está visível em smartphones e tablets.
body	Opcional, string	O texto do corpo da notificação.
sound	Opcional, string	O som a ser reproduzido quando o dispositivo recebe a notificação. String que especifica arquivos de som no pacote principal do app cliente ou na pasta Library/Sounds do contêiner de dados do app. Consulte mais informações na Biblioteca dos desenvolvedores do iOS.
badge	Opcional, string	O valor do indicador no ícone do app da tela inicial. Se não é especificado, o indicador não é alterado. Se é definido como 0, o indicador é removido.
click_action	Opcional, string	A ação associada a um clique de usuário na notificação. Corresponde a category no payload de APNs.
subtitle	Opcional, string	A legenda da notificação.
body_loc_key	Opcional, string	A chave da string de corpo nos recursos de string do app, a ser usada para identificar o texto do corpo na localização atual do usuário. Corresponde a loc-key no payload de APNs. Para mais informações, consulte Referência da chave de payload e Como localizar o conteúdo de notificações remotas.
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 para identificar o texto do corpo na localização atual do usuário. Corresponde a loc-args no payload de APNs. Para mais informações, consulte Referência da chave de payload e Como localizar o conteúdo de notificações remotas.
title_loc_key	Opcional, string	A chave da string de título nos recursos de string do app a ser usada para identificar o texto do título na localização atual do usuário. Corresponde a title-loc-key no payload de APNs. Para mais informações, consulte Referência da chave de payload e Como localizar o conteúdo de notificações remotas.
title_loc_args	Opcional, matriz JSON como string	Valores de string variáveis a serem usados no lugar de especificadores de formato em title_loc_key para identificar o texto do título na localização atual do usuário. Corresponde a title-loc-args no payload de APNs. Para mais informações, consulte Referência da chave de payload e Como localizar o conteúdo de notificações remotas.

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

Parâmetro	Uso	Descrição
title	Opcional, string	O título da notificação.
body	Opcional, string	O texto do corpo da notificação.
android_channel_id	Opcional, string	O código do canal da notificação (novo no Android O). O app precisa criar um canal com este ID do canal antes que qualquer notificação com esse ID seja recebida. Se você não enviar esse ID do canal na solicitação ou, se o ID do canal fornecido ainda não foi criado pelo app, o FCM usará o ID do canal especificado no manifesto do app.
icon	Opcional, string	O ícone da notificação. Define o ícone da notificação como myicon para o recurso drawable myicon. Se você não enviar essa chave na solicitação, o FCM exibe o ícone do inicializador especificado no manifesto do app.
sound	Opcional, string	O som a ser reproduzido quando o dispositivo recebe a notificação. Aceita "default" ou o nome do arquivo de um recurso de som no pacote do app. Arquivos de som precisam residir em /res/raw/.
tag	Opcional, string	Identificador usado para substituir notificações existentes na gaveta de notificações. Se não está especificado, cada solicitação cria uma nova notificação. Se está especificado e uma notificação com a mesma tag já está sendo mostrada, a nova notificação substitui a existente na gaveta das notificações.
color	Opcional, string	A cor do ícone da notificação, expressa no formato #rrggbb.
click_action	Opcional, string	A ação associada a um clique de usuário na notificação. Se especificado, uma atividade com um filtro de intent correspondente é iniciada quando um usuário clica na notificação.
body_loc_key	Opcional, string	A chave da string de corpo nos recursos de string do app, a ser usada para identificar o texto do corpo na localização atual do usuário. Consulte Recursos de string para 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 para identificar o texto do corpo na localização atual do usuário. Consulte Como formatar e definir estilo para mais informações.
title_loc_key	Opcional, string	A chave da string de título nos recursos de string do app a ser usada para identificar o texto do título na localização atual do usuário. Consulte Recursos de string para mais informações.
title_loc_args	Opcional, matriz JSON como string	Valores de string variáveis a serem usados no lugar de especificadores de formato em title_loc_key para identificar o texto do título na localização atual do usuário. Consulte Como formatar e definir estilo para mais informações.

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

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

Mensagens HTTP downstream (texto simples)

A tabela a seguir lista a sintaxe para os destinos, as opções e o payload em mensagens HTTP downstream de texto simples.

Tabela 3. Destinos, opções e payload para mensagens HTTP downstream em texto simples.

Parâmetro	Uso	Descrição
Metas
registration_id	Obrigatório, string	Este parâmetro especifica os apps cliente (tokens de registro) que recebem a mensagem. O envio e o recebimento de mensagens multicast (envio para mais de um token de registro) só são permitidos no formato HTTP JSON.
Opções
collapse_key	Opcional, string	Consulte detalhes na tabela 1.
time_to_live	Opcional, número	Consulte detalhes na tabela 1.
restricted_package_name	Opcional, string	Consulte detalhes na tabela 1.
dry_run	Opcional, booleano	Consulte detalhes na tabela 1.
Payload
data.<key>	Opcional, string	Os pares de chave-valor de payload da mensagem são especificados nesse parâmetro. Não há limite para o número de parâmetros de chave-valor, mas há um limite de tamanho de mensagem total de 4096 bytes. Por exemplo, no Android, "data.score"."3x1" resultaria em uma intent adicional chamada score com o valor de string 3x1. A chave não pode ser uma palavra reservada, por exemplo, "from", "message_type" ou qualquer palavra que comece com "google" ou "gcm". Não use palavras definidas nesta tabela como, por exemplo, collapse_key.

Interpretar uma resposta a uma mensagem downstream

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

Tabela 4. Cabeçalho da resposta HTTP downstream.

Resposta	Descrição
200	A mensagem foi processada corretamente. O corpo da mensagem conterá mais detalhes sobre o status, mas o formato dependerá se a solicitação foi em JSON ou texto simples. Consulte mais detalhes na tabela 5.
400	Aplicável apenas a solicitações JSON. Indica que não é possível analisar a solicitação como JSON ou ela continha campos inválidos, por exemplo, ao encaminhar uma string quando um número era esperado. A razão exata da falha é descrita na resposta, e é preciso resolver o problema antes de tentar a solicitação novamente.
401	Houve um erro ao autenticar a conta do remetente.
5xx	Erros no intervalo de 500 a 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 tempo limite). O remetente precisa tentar novamente mais tarde, seguindo cabeçalhos Retry-After incluídos na resposta. Os servidores de app precisam implementar o recuo exponencial.

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

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

Parâmetro	Uso	Descrição
multicast_id	Obrigatório, número	Código exclusivo (número) que identifica a mensagem multicast.
success	Obrigatório, número	Número de mensagens processadas sem erro.
failure	Obrigatório, número	Número de mensagens não processadas.
results	Obrigatório, matriz de objetos	A matriz de objetos que representa o status das mensagens processadas. Os objetos são listados na mesma ordem da solicitação, ou seja, para cada código de registro na solicitação, o resultado é listado no mesmo índice na resposta. message_id: string que especifica um ID único para cada mensagem processada corretamente. error: string que especifica o erro que ocorreu ao processar a mensagem para o destinatário. Os valores possíveis estão disponíveis na tabela 9.

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

Parâmetro	Uso	Descrição
message_id	Opcional, número	O código da mensagem de tópico quando o FCM recebe a solicitação e tenta entregar a todos os dispositivos inscritos.
error	Opcional, string	Erro que ocorreu ao processar a mensagem. Os valores possíveis estão disponíveis na tabela 9.

Tabela 7. Resposta de operação bem-sucedida para corpo de resposta de mensagem HTTP downstream (texto simples).

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

Tabela 8. Resposta de operação com erro para corpo de resposta de mensagem HTTP downstream (texto simples).

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

Códigos de resposta de erro de mensagens 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 mensagens downstream

Erro	Código HTTP	Ação recomendada
Token de registro não encontrado	200 + error:MissingRegistration	Verifique se a solicitação contém um token de registro (no registration_id em uma mensagem de texto sem formatação ou no campo to ou registration_ids no JSON).
Token de registro inválido	200 + error:InvalidRegistration	Verifique o formato do token de registro que você transmite ao servidor. Garanta que ele corresponde ao token de registro que o app cliente recebe ao realizar o registro com o Firebase Notificações. Não faça truncagem nem adicione caracteres adicionais.
Dispositivo não registrado	200 + error:NotRegistered	Um token de registro existente pode deixar de ser válido em diversas situações, incluindo: Se o app cliente cancelar o registro com o FCM. Se o app cliente tiver o registro cancelado automaticamente, algo que pode ocorrer se o usuário desinstalar o aplicativo. Por exemplo, no iOS, se o serviço de feedback de APNs informou o token delas como inválido. Se o token de registro expirar, por exemplo, se o Google atualizar os tokens de registro, ou o token de APNs expirou para dispositivos iOS. Se o app cliente estiver atualizado, mas a nova versão não estiver configurada para receber mensagens. Para todos esses casos, remova o token de registro do servidor do app e pare de utilizá-lo para enviar mensagens.
Nome de pacote inválido	200 + error:InvalidPackageName	Certifique-se de que a mensagem tenha sido endereçada a um token de registro cujo nome de pacote corresponda ao valor transmitido na solicitação.
Erro de autenticação	401	Não foi possível autenticar a conta do remetente usada para enviar uma mensagem. As possíveis causas são: Cabeçalho de autorização não encontrado ou com sintaxe inválida na solicitação HTTP. O projeto do Firebase ao qual a chave do servidor especificada pertence está incorreto. Somente chaves de servidor legadas: a solicitação originada de um servidor que não consta na lista de permissões dos IPs de chave do servidor. Verifique se o token que você está enviando no cabeçalho de autenticação é a chave de servidor correta associada ao seu projeto. Consulte os detalhes em Como verificar a validade de uma chave de servidor. Se você estiver usando uma chave de servidor legada, recomendamos atualizar para uma nova chave que não tenha restrições de IP. Consulte Migrar chaves de servidor legadas.
Remetente incompatível	200 + error:MismatchSenderId	Um token de registro está vinculado a um determinado grupo de remetentes. Quando um app cliente se registra no FCM, ele precisa especificar os remetentes autorizados para enviar mensagens. Use um desses IDs de remetente ao enviar mensagens ao app cliente. Quando você muda para outro remetente, os tokens de registro existentes não funcionam.
JSON inválido	400	Verifique se a mensagem JSON está formatada corretamente e contém campos válidos. Por exemplo, verifique se o tipo de dados correto é transmitido.
Parâmetros inválidos	400 + error:InvalidParameters	Verifique se os parâmetros fornecidos têm o nome e o tipo certos.
Message grande demais	200 + error:MessageTooBig	Verifique se o tamanho total dos dados de payload 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 + error: InvalidDataKey	Verifique se os dados do payload não contêm uma chave (como from gcm, ou valores prefixados por google), usados internamente pelo FCM. Algumas palavras (como collapse_key) também são usadas pelo FCM, mas são permitidas no payload. Nesse caso, o valor do payload será substituído pelo valor do FCM.
Time to Live inválida	200 + error:InvalidTtl	Verifique se o valor usado no time_to_live é um número inteiro que representa uma duração em segundos entre 0 e 2.419.200 (4 semanas).
Tempo limite	5xx ou 200 + error:Unavailable	O servidor não conseguiu processar a solicitação a tempo. Tente enviar a mesma solicitação novamente. Para isso, é necessário: respeitar o cabeçalho Retry-After se ele estiver incluído na resposta do servidor de conexão do FCM. implementar uma retirada exponencial no mecanismo de nova tentativa. Por exemplo, se você esperou um segundo antes da primeira nova tentativa, aguarde pelo menos dois segundos antes da próxima, depois quatro segundos e assim por diante. Se estiver enviando várias mensagens, atrase cada uma de maneira independente por um período aleatório adicional para evitar emitir uma nova solicitação para todas as mensagens ao mesmo tempo. Os remetentes que causam problemas podem ser incluídos nas listas negras.
Erro interno do servidor	500 ou 200 + error:InternalServerError	O servidor encontrou um erro enquanto tentava processar a solicitação. Tente realizar a mesma solicitação novamente seguindo os requisitos listados em "Tempo limite" (consulte a linha acima). Se o erro persistir, entre em contato com o suporte do Firebase.
Taxa de mensagens do dispositivo excedida	200 + error: DeviceMessageRate Exceeded	A taxa de mensagens para um determinado dispositivo é muito alta. Se um aplicativo da Apple enviar mensagens a uma velocidade que exceda os limites dos APNs, talvez receba esta mensagem de erro. Reduza o número de mensagens enviadas a esse dispositivo e use espera exponencial para tentar novamente o envio.
Taxa de mensagens de tópico excedida	200 + error: TopicsMessageRate Exceeded	A taxa de mensagens para assinantes de um determinado tópico está muito alta. Reduza o número de mensagens enviadas a esse tópico e use recuo exponencial para tentar novamente o envio.
Credenciais de APNs inválidas	200 + error: InvalidApnsCredential	Uma mensagem direcionada a um dispositivo da Apple não foi enviada porque a chave de autenticação de APNs necessária não foi carregada ou expirou. Verifique a validade das credenciais de desenvolvimento e produção.

Gerenciamento de grupos de dispositivos

A tabela a seguir lista as chaves para criação de grupos de dispositivo e adição e remoção de participantes. Veja mais informações no guia da sua plataforma iOS+ ou Android.

Tabela 10. Chaves de gerenciamento de grupo de dispositivos.

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