Protocolo HTTP do Firebase Cloud Messaging

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

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

Nesta seção, é apresentada a sintaxe para envio de mensagens downstream e interpretação das 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 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 este 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 pode depender 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 por quanto tempo (em segundos) a mensagem deverá ser mantida no armazenamento do FCM se o dispositivo ficar off-line. A vida útil máxima permitida é quatro semanas. Esse 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 mensagens. 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 vai ser enviada por APNs. Caso contrário, vai 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 envia 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 4000 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 app. 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 é vinculado a 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.
Parameters 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 ou 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.
Vida útil 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 espera 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.