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, Este parâmetro especifica o destinatário de uma mensagem.

string
O valor pode ser o token de registro de um dispositivo, a chave de
de dispositivos ou um único tópico (prefixado com /topics/). P
tópicos, use o parâmetro condition.

registration_ids Opcional, Este parâmetro especifica o destinatário de uma mensagem mult

matriz de enviada a mais de um token de registro.
strings
O valor deve ser uma matriz de tokens de registro para onde envi
A matriz precisa conter pelo menos 1 e no máximo 1.000 tokens d
uma mensagem a um único dispositivo, use o parâmetro to.

As mensagens multicast só são permitidas usando o formato HT

condition Opcional, Este parâmetro especifica uma expressão lógica de condições qu

string da mensagem.

Condição aceita: tópico, formatado como "'seuTópico' em tópicos

diferencia minúsculas de maiúsculas.

Operadores compatíveis: &&, ||. No máximo dois operadores são

mensagem de tópico.

notification_key Opcional, Este parâmetro está obsoleto. Use to para especificar destinatár
Obsoleto string mais informações sobre como enviar mensagens a vários dispos
documentação da sua plataforma.

Opções

collapse_key Opcional, Este parâmetro identifica um grupo de mensagens (por exemplo,

string "Updates Available") que podem ser recolhidas, para que ap
enviada quando a entrega puder ser feita. O objetivo disso é evita
excessivo de mensagens iguais quando o dispositivo voltar a fica
 Não há garantia da ordem em que as mensagens são enviadas.

Observação: no máximo quatro chaves de recolhimento diferente

qualquer momento. Isso significa que um servidor de conexão do
mesmo tempo, quatro mensagens diferentes por app cliente. Se v
não há garantia de qual das quatro chaves recolhidas serão mant
conexão do FCM.

priority Opcional, Define a prioridade da mensagem. Os valores válidos são "norma

string eles correspondem às prioridades 5 e 10 de APNs.

Por padrão, as mensagens de notificação são enviadas com prior

mensagens de dados com prioridade normal. A prioridade norma
bateria do app cliente e deve ser sempre usada, exceto quando a
necessária. Mensagens com prioridade normal podem ser recebi
não especificado.

Uma mensagem com prioridade alta é enviada imediatamente, e

notificação.

content_available Opcional, No iOS, use este campo para representar content-available n

booleano Quando uma notificação ou mensagem é enviada e este campo e
um app cliente inativo é ativado, e a mensagem é enviada por me
notificação silenciosa e não por meio do servidor de conexão do F
garantido que essas notificações silenciosas em APNs sejam ent
depender de fatores como o usuário ativar o modo de baixo cons
app etc. No Android, as mensagens de dados ativam o app por pa
compatibilidade com o Chrome.

mutable_content Opcional, Atualmente, apenas para dispositivos iOS 10 ou posterior. No iOS

JSON representar mutable-content no payload de APNs. Quando um
booleano este campo está definido como true, o conteúdo dela pode ser m
exibição por meio de uma extensão de app do serviço de notificaç
esse parâmetro é ignorado.

time_to_live Opcional, Este parâmetro especifica por quanto tempo (em segundos) a me
número mantida no armazenamento do FCM se o dispositivo ficar off-line
permitida é quatro semanas. Esse também é o valor padrão. Para
consulte Definir a vida útil de uma mensagem.

restricted_package_ Opcional, Este parâmetro especifica o nome do pacote do app no qual os to

name (somente no string precisam corresponder para receber a mensagem.
Android)

dry_run Opcional, Quando definido como true, este parâmetro permite que os dese
booleano solicitação sem realmente enviar uma mensagem.

O valor padrão é false.

 Payload

data Opcional, Este parâmetro especifica os pares de chave-valor personalizado

objeto mensagem.

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

No iOS, se a mensagem é enviada por meio de APNs, ela represen

personalizados. Se for enviada pelo servidor de conexão do FCM,
como um dicionário de chave-valor em AppDelegate
application:didReceiveRemoteNotification:.

No Android, isso resulta em um intent adicional chamado score

string 3x1.

A chave não pode ser uma palavra reservada, por exemplo, "from
qualquer palavra que comece com "google" ou "gcm". Não use pa
tabela como, por exemplo, collapse_key.

É recomendável usar valores do tipo string. É preciso converter os

outros tipos de dados sem string (por exemplo, números inteiros
string.

notification Opcional, Este parâmetro especifica os pares de chave-valor do payload da

objeto e visíveis ao usuário. Consulte detalhes no suporte ao payload de
informações sobre as opções de mensagens de dados e de notifi
mensagens. Se um payload de notificação for fornecido ou a
opção content_available estiver definida como true para um
dispositivo iOS, a mensagem será enviada por meio de APNs. Cas
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 fica visível em smartphones e tablets iOS.

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
ou dicionário
String que especifica arquivos de som no pacote principal do app
pasta Library/Sounds do contêiner de dados do app. Consulte
na Biblioteca de desenvolvedores do iOS (em inglês).

Para notificações críticas, use um dicionário que contenha inform

críticos. Consulte a Biblioteca de desenvolvedores do iOS para ace
necessárias. Para notificações regulares, use a string de som.

badge Opcional, string O valor do indicador no ícone do app da tela inicial.

Se não for especificado, o indicador não é alterado.

Se for 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 para a string de corpo nos recursos de string do app, a se
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

conteúdo de notificações remotas (ambos em inglês).

body_loc_args Opcional, matriz Valores de string variáveis a serem usados no lugar dos especifica
JSON como em body_loc_key para identificar o texto do corpo na localizaçã
string
Corresponde a loc-args no payload de APNs.

Para mais informações, consulte Referência da chave de payload

conteúdo de notificações remotas (ambos em inglês).

title_loc_key Opcional, string A chave para a string de título nos recursos de string do app a ser
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

conteúdo de notificações remotas (ambos em inglês).

title_loc_args Opcional, matriz Valores de string variáveis a serem usados no lugar de especificad
JSON como em title_loc_key para identificar o texto do título na localizaçã
string
 Corresponde a title-loc-args no payload de APNs.

Para mais informações, consulte Referência da chave de payload

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 app precisa criar um canal com este ID do canal antes que

com esse ID seja recebida.

Se você não enviar esse ID do canal na solicitação ou se o ID

não foi criado pelo app, o FCM usará o ID do canal especific

icon Opcional, string O ícone da notificação.

Define o ícone da notificação como myicon para o recurso d

não envia essa chave na solicitação, o FCM exibe o ícone do
no manifesto do app.

sound Opcional, string O som a ser reproduzido quando o dispositivo recebe a notif

Aceita "default" ou o nome do arquivo de um recurso de

Arquivos de som precisam residir em /res/raw/.

tag Opcional, string Identificador usado para substituir notificações existentes n

Se não está especificado, cada solicitação cria uma nova no

Se está especificado e uma notificação com a mesma tag já

nova notificação substitui a existente na gaveta de notificaç

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 corre

quando um usuário clica na notificação.
 body_loc_key Opcional, string A chave para a string de corpo nos recursos de string do ap
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 Valores de string variáveis a serem usados no lugar dos esp
JSON como string em body_loc_key para identificar o texto do corpo na loca

Consulte Formatar e definir estilo para mais informações.

title_loc_key Opcional, string A chave para a string de título nos recursos de string do app
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 Valores de string variáveis a serem usados no lugar de espe
JSON como string em title_loc_key para identificar o texto do título na loc

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, Este parâmetro especifica os apps cliente (IDs de registro)

string mensagem.

O envio e o recebimento de mensagens multicast (envio p

registro) só são permitidos no formato HTTP JSON.

Opções

collapse_key Opcional, Consulte detalhes na tabela 1.

string

time_to_live Opcional, Consulte detalhes na tabela 1.

número

restricted_package_name Opcional, Consulte detalhes na tabela 1.

string

dry_run Opcional, Consulte detalhes na tabela 1.

booleano

Payload

data.<key> Opcional, Este parâmetro especifica os pares de chave-valor do pay

string há limite para o número de parâmetros de chave-valor, ma
tamanho de mensagem total de 4 KB.

Por exemplo, no Android, "data.score"."3x1" resultar

chamado score com o valor de string 3x1.

A chave não pode ser uma palavra reservada, por exemplo

ou qualquer palavra que comece com "google" ou "gcm". N
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
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 JSO
campos inválidos, por exemplo, ao encaminhar uma string quando um número era esperado. A r
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 servid
tentar processar a solicitação ou que o servidor está temporariamente indisponível (por exempl
O remetente precisa tentar novamente mais tarde, seguindo cabeçalhos Retry-After incluído
servidores de app precisam implementar a espera 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, Código exclusivo (número) que identifica a mensagem multicast.

número

success Obrigatório, Número de mensagens processadas sem erro.

número

failure Obrigatório, Número de mensagens não processadas.

número

results Obrigatório, A matriz de objetos que representa o status das mensagens process
matriz de objetos listados na mesma ordem da solicitação, ou seja, para cada código d
o resultado é listado no mesmo índice na resposta.

• message_id: string que especifica um ID único para cada mensage

corretamente.

• registration_id: string opcional que especifica o token de regist

que a mensagem foi processada e enviada.

• error: string que especifica o erro que ocorreu ao processar a mens

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, O código da mensagem de tópico quando o FCM recebe a solicitação e te

número dispositivos inscritos.

error Opcional, string Erro que ocorreu ao processar a mensagem. Os valores possíveis estão d

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, Este parâmetro especifica o código exclusivo da mensagem que o

string FCM processou.

registration_id Opcional, string Este parâmetro especifica o token de registro do app cliente para
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, Este parâmetro especifica o valor do erro ao processar a mensagem para o
string 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 200 + Verifique se a solicitação contém um token de registro
não encontrado error:MissingRegistration (no registration_id em uma mensagem de texto
campo to ou registration_ids no JSON).

Token de registro 200 + error:InvalidRegistration Verifique o formato do token de registro que você tran
inválido Garanta que ele corresponde ao token de registro que
realizar o registro com o Firebase Notificações. Não fa
acrescente caracteres adicionais.

Dispositivo não 200 + error:NotRegistered Um token de registro existente pode deixar de ser válid
registrado incluindo:

• Se o app cliente cancelar o registro com o FCM.

• Se o app cliente tiver o registro cancelado automatica

ocorrer se o usuário desinstalar o app. Por exemplo, n
feedback de APNs informou o token delas como inváli

• Se o token de registro expirar, por exemplo, se o Goog

registro, ou o token de APNs expirou para dispositivos

• Se o app cliente estiver atualizado, mas a nova versão

para receber mensagens.
Para todos esses casos, remova o token de registro d
de utilizá-lo para enviar mensagens.

Nome de pacote 200 + Garanta que a mensagem foi endereçada a um token d

inválido error:InvalidPackageName de pacote corresponde ao valor transmitido na solicita

Erro de 401 Não foi possível autenticar a conta do remetente usad

autenticação mensagem. As possíveis causas são:

• Cabeçalho de autorização não encontrado ou com sin

solicitação HTTP.

• O projeto do Firebase ao qual a chave do servidor esp

incorreto.

• Somente chaves de servidor legadas: a solicitação ori

que não consta na lista de permissões dos IPs de cha

Verifique se o token que você está enviando no cabeç

chave de servidor correta associada ao seu projeto. C
em Como verificar a validade de uma chave de servido
uma chave de servidor legada, recomendamos atualiz
que não tenha restrições de IP.
Remetente 200 + error:MismatchSenderId Um token de registro é vinculado a determinado grupo
incompatível um app cliente se registra no FCM, ele precisa especif
autorizados para enviar mensagens. Use um desses I
mensagens ao app cliente. Quando você muda para o
de registro existentes não funcionam.

JSON inválido 400 Verifique se a mensagem JSON está formatada corret

válidos. Por exemplo, verifique se o tipo de dados corr

Parâmetros 400 + error:InvalidParameters Verifique se os parâmetros fornecidos têm o nome e o

inválidos

Mensagem 200 + error:MessageTooBig Verifique se o tamanho total dos dados de payload inc
grande demais mensagem não excede os limites do FCM: 4.096 bytes
mensagens ou 2.048 bytes no caso de mensagens pa
chaves e os valores.

Chave de dados 200 + error: Verifique se os dados do payload não contêm uma ch
inválida InvalidDataKey ou valores prefixados por google), usados intername
palavras (como collapse_key) também são usadas
permitidas no payload. Nesse caso, o valor do payload
valor do FCM.

Vida útil inválida 200 + error:InvalidTtl Verifique se o valor usado no time_to_live é um nú

representa uma duração em segundos entre 0 e 2.419

Tempo limite 5xx ou 200 + error:Unavailable O servidor não conseguiu processar a solicitação a te
mesma solicitação novamente. Para isso, é necessári

• respeitar o cabeçalho Retry-After se ele estiver inc

servidor de conexão do FCM;

• implementar uma espera exponencial no mecanismo

exemplo, se você esperou um segundo antes da prime
aguarde pelo menos dois segundos antes da próxima
e assim por diante. Se estiver enviando várias mensag
maneira independente por um período aleatório adicio
nova solicitação para todas as mensagens ao mesmo

Os remetentes que causam problemas podem ser incl

Erro interno do 500 ou 200 + O servidor encontrou um erro enquanto tentava proce
servidor error:InternalServerError realizar a mesma solicitação novamente seguindo os
"Tempo limite" (consulte a linha acima). Se o erro pers
com o suporte do Firebase.
 Taxa de 200 + error: A taxa de mensagens para um determinado dispositiv
mensagens do DeviceMessageRateExceeded iOS enviar mensagens a uma taxa que exceda os limit
dispositivo receber esta mensagem de erro
excedida
Reduza o número de mensagens enviadas a esse disp
espera exponencial para tentar novamente o envio.

Taxa de 200 + error: A taxa de mensagens enviadas a inscritos em determi

mensagens de TopicsMessageRateExceeded Reduza o número de mensagens enviadas a esse tópi
tópico excedida espera exponencial para tentar novamente o envio.

Credenciais de 200 + error: Uma mensagem direcionada a um dispositivo iOS não

APNs inválidas InvalidApnsCredential chave de autenticação de APNs necessária não foi ca
Verifique a validade das credenciais de desenvolvimen

Gerenciamento de grupo 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 a ser executada. Valores válidos sã

notification_key_name Obrigatório, string O nome definido pelo usuário do grupo de dispo

modificado.

notification_key Obrigatório (exceto para a Identificador exclusivo do grupo de dispositivos

operação create, string) na resposta para uma operação create bem-s
para todas as operações subsequentes no grup

registration_ids Obrigatório, matriz de Tokens do dispositivo que serão adicionados o

strings remover todos os tokens de registro existentes
dispositivos, o FCM excluirá esse grupo.