Ir para o console

Protocolo HTTP do Firebase Cloud Messaging

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

Ao usar o protocolo HTTP legado, seu servidor de aplicativos deve 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
Destinos
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 da notificação de um 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 a mais de um token de registro.

O valor deve ser uma matriz de tokens de registro para o qual 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 "'seu tópico' em tópicos". Esse valor não diferencia minúsculas de maiúsculas.

Operadores aceitos: &&, ||. No máximo dois operadores são permitidos por mensagem de tópico.

notification_key
Obsoleto
Opcional, string

Este parâmetro está obsoleto. 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 mensagem seja enviada quando for possível retomar a entrega. O objetivo disso é evitar o envio de um número excessivo de mensagens iguais quando o dispositivo volta a ficar on-line ou ativo.

Não há garantia da ordem em que as mensagens são enviadas.

Observação: no máximo quatro chaves de recolhimento diferentes são permitidas a qualquer momento. Isso significa que um servidor de conexão do FCM pode armazenar simultaneamente quatro mensagens diferentes por aplicativo cliente. Se você exceder esse limite, não há garantia de qual das quatro chaves recolhidas serão mantidas pelo servidor de conexão do FCM.

priority Opcional, string

Define a prioridade da mensagem. Os valores válidos são "normal" e "high" (alta). No iOS, 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

No iOS, 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 aplicativo cliente inativo é ativado, e a mensagem é enviada por meio de APNs como uma notificação silenciosa e não por meio do servidor de conexão FCM. Observe que 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 aplicativo etc. No Android, as mensagens de dados ativam o aplicativo por padrão. Ainda não há compatibilidade com o Chrome.

mutable_content Opcional, JSON booleano

Atualmente, apenas para dispositivos iOS 10 ou posterior. No iOS, 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 meio de 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
(apenas 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 chave-valor personalizados do payload da mensagem.

Por exemplo, com data:{"score":"3x1"}:

No iOS, se a mensagem é enviada por meio de APNs, ela representa campos de dados personalizados. Se for enviada pelo servidor de conexão do FCM, ela será representada como um dicionário de chave-valor em AppDelegate application:didReceiveRemoteNotification:.

No Android, isso resultaria em um intent adicional chamado score com o valor de string de 3x1.

A chave não deve ser uma palavra reservada ("from" ou qualquer palavra começando com "google" ou "gcm"). Não use as palavras definidas nesta tabela, como collapse_key.

Valores em tipos de string são recomendados. É 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 detalhes no suporte ao payload de notificação. Para mais informações sobre as opções de mensagens de dados e de notificação, consulte Tipos de mensagens. Se um payload de notificação for fornecido ou a opção content_available estiver definida como true em uma mensagem para um dispositivo iOS, a mensagem será enviada por meio de APNs. Caso contrário, ela será enviada por meio do servidor de conexão do FCM.

Compatibilidade com o 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 é visível em smartphones e tablets iOS.

body Opcional, string

O texto do corpo da notificação.

sound Opcional, string ou dicionário

O som a ser reproduzido quando o dispositivo recebe a notificação.

String que especifica arquivos de som no pacote principal do aplicativo cliente ou na pasta Library/Sounds do contêiner de dados do aplicativo. Consulte mais informações na Biblioteca dos desenvolvedores do iOS (em inglês).

Para notificações críticas, use um dicionário que contenha informações de som para alertas críticos. Consulte a biblioteca de desenvolvedores do iOS para acessar as chaves necessárias. Para notificações regulares, use a string de som.

badge Opcional, string

O valor do indicador no ícone do aplicativo 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 (ambos em inglês).

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 (ambos em inglês).

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 (ambos em inglês).

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 (ambos em inglês).

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 aplicativo precisa criar um canal com este código do canal antes que qualquer notificação com esse código seja recebida.

Se você não enviar esse código do canal na solicitação ou se o código do canal fornecido ainda não foi criado pelo app, o FCM usará o código 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. Os arquivos de som precisam estar 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 da 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 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 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
Destinos
registration_id Obrigatório, string

Este parâmetro especifica os apps cliente (IDs de registro) que recebem a mensagem.

O envio e o recebimento de mensagens multicast (envio para mais de um código 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

Este parâmetro especifica os pares de chave-valor do payload da mensagem. Não há limite para o número de parâmetros de chave-valor, mas há um limite de tamanho de mensagem total de 4 KB.

Por exemplo, no Android, "data.score"."3x1" resultaria em um intent adicional chamado score com o valor de string de 3x1.

A chave não deve ser uma palavra reservada ("from" ou qualquer palavra começando com "google" ou "gcm"). Não use as palavras definidas nesta tabela, como collapse_key.

Interpretar uma resposta a uma mensagem downstream

O servidor de apps 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 servidor de conexão 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 código exclusivo para cada mensagem processada.
  • registration_id: string opcional que especifica o token de registro para o app cliente em que a mensagem foi processada e enviada.
  • 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 código exclusivo da mensagem que o servidor de conexão do 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. Certifique-se de 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 atual pode deixar de ser válido em diversas situações, como:
  • Se o app cliente cancelou 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 de 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 as chaves de servidor legadas: a solicitação originada de um servidor que não consta na lista de permissões de IPs de chave de servidor.
Verifique se o token que você está enviando no cabeçalho de autenticação é a chave de servidor correta associada a seu projeto. Consulte 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.
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 códigos de remetente ao enviar mensagens ao app cliente. Se você mudar para outro remetente, os tokens de registro atuais não funcionarão.
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 em time_to_live é um número inteiro que representa uma duração em segundos entre 0 e 2.419.200 (quatro semanas).
Tempo limite 5xx ou 200 + error:Unavailable

O servidor não conseguiu processar a solicitação a tempo. Tente realizar a mesma solicitação novamente. Para isso, é necessário:

  • respeitar o cabeçalho Retry-After se estiver incluído na resposta do servidor de conexão do FCM;
  • implementar o recuo 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 Ocorreu um erro no servidor ao tentar 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 iOS envia mensagens a uma taxa que exceda os limites de APN, pode receber esta mensagem de erro.

Reduza o número de mensagens enviadas a esse dispositivo e use recuo 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 iOS 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. Para 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, string A operação que 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 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.