Criar solicitações de envio do servidor de apps

Ao usar os protocolos do servidor de apps Firebase Admin SDK ou FCM, é possível criar solicitações de mensagens e enviá-las a aos tipos de destino a seguir:

• Nome do tópico
• Condição
• Token de registro do dispositivo
• Nome do grupo de dispositivos (somente protocolo)

O payload de notificação das mensagens enviadas pode ser composto por campos predefinidos, por um payload de dados com seus próprios campos definidos por usuário ou por ambos. Consulte Tipos de mensagens para mais informações.

Importante: as solicitações de envio do protocolo HTTP v1 do Firebase Admin SDK precisam conter o ID do projeto do Firebase para seu app, disponível na guia Configurações gerais do projeto do Console do Firebase. Além disso, os dois métodos de envio de mensagens exigem que você autorize solicitações de envio.

Nos exemplos desta página, mostramos como enviar mensagens de notificação com o Firebase Admin SDK (que é compatível com Node, Java, Python, C# e Go) e o protocolo v1 HTTP. Você também verá orientações para enviar mensagens usando os protocolos HTTP e XMPP legados descontinuados.

Cuidado: o envio de mensagens (incluindo mensagens upstream) com as 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.

Como enviar mensagens para dispositivos específicos

Para enviar para um único dispositivo específico, transmita o token de registro do dispositivo, conforme mostrado. Consulte as informações de configuração do cliente da sua plataforma para saber mais sobre esses tokens.

Node.js

// This registration token comes from the client FCM SDKs.
const registrationToken = 'YOUR_REGISTRATION_TOKEN';

const message = {
  data: {
    score: '850',
    time: '2:45'
  },
  token: registrationToken
};

// Send a message to the device corresponding to the provided
// registration token.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// This registration token comes from the client FCM SDKs.
String registrationToken = "YOUR_REGISTRATION_TOKEN";

// See documentation on defining a message payload.
Message message = Message.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .setToken(registrationToken)
    .build();

// Send a message to the device corresponding to the provided
// registration token.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
FirebaseMessagingSnippets.java

Python

# This registration token comes from the client FCM SDKs.
registration_token = 'YOUR_REGISTRATION_TOKEN'

# See documentation on defining a message payload.
message = messaging.Message(
    data={
        'score': '850',
        'time': '2:45',
    },
    token=registration_token,
)

# Send a message to the device corresponding to the provided
# registration token.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
cloud_messaging.py

Go

// Obtain a messaging.Client from the App.
ctx := context.Background()
client, err := app.Messaging(ctx)
if err != nil {
	log.Fatalf("error getting Messaging client: %v\n", err)
}

// This registration token comes from the client FCM SDKs.
registrationToken := "YOUR_REGISTRATION_TOKEN"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Token: registrationToken,
}

// Send a message to the device corresponding to the provided
// registration token.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
messaging.go

C#

// This registration token comes from the client FCM SDKs.
var registrationToken = "YOUR_REGISTRATION_TOKEN";

// See documentation on defining a message payload.
var message = new Message()
{
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
    Token = registrationToken,
};

// Send a message to the device corresponding to the provided
// registration token.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
   "message":{
      "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
      "notification":{
        "body":"This is an FCM notification message!",
        "title":"FCM Message"
      }
   }
}

Comando cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "notification":{
     "title":"FCM Message",
     "body":"This is an FCM Message"
   },
   "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

Se for bem-sucedido, cada método de envio retorna um ID de mensagem. O Firebase Admin SDK retorna a string de ID no formato projects/{project_id}/messages/{message_id}. A resposta do protocolo HTTP é uma única chave JSON:

    {
      "name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
    }

Como enviar mensagens para vários dispositivos

Importante os métodos de envio em lote descritos nesta seção foram descontinuados em 21 de junho de 2023 e serão removidos em junho de 2024. Para protocolo, use o método padrão de envio da API HTTP v1, implementando seu próprio envio em lote, iterando a lista de destinatários e enviando para o token de cada destinatário. Para os métodos do SDK Admin, atualize para a próxima versão principal. Consulte as Perguntas frequentes sobre o Firebase para mais informações.

As APIs Admin FCM permitem fazer multicast de uma mensagem para uma lista de tokens de registro de dispositivo. É possível especificar até 500 tokens de registro de dispositivo por invocação.

Node.js

// Create a list containing up to 500 registration tokens.
// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
  'YOUR_REGISTRATION_TOKEN_1',
  // …
  'YOUR_REGISTRATION_TOKEN_N',
];

const message = {
  data: {score: '850', time: '2:45'},
  tokens: registrationTokens,
};

getMessaging().sendMulticast(message)
  .then((response) => {
    console.log(response.successCount + ' messages were sent successfully');
  });

Java

// Create a list containing up to 500 registration tokens.
// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n"
);

MulticastMessage message = MulticastMessage.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .addAllTokens(registrationTokens)
    .build();
BatchResponse response = FirebaseMessaging.getInstance().sendMulticast(message);
// See the BatchResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " messages were sent successfully");
FirebaseMessagingSnippets.java

Python

# Create a list containing up to 500 registration tokens.
# These registration tokens come from the client FCM SDKs.
registration_tokens = [
    'YOUR_REGISTRATION_TOKEN_1',
    # ...
    'YOUR_REGISTRATION_TOKEN_N',
]

message = messaging.MulticastMessage(
    data={'score': '850', 'time': '2:45'},
    tokens=registration_tokens,
)
response = messaging.send_multicast(message)
# See the BatchResponse reference documentation
# for the contents of response.
print('{0} messages were sent successfully'.format(response.success_count))
cloud_messaging.py

Go

// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens := []string{
	"YOUR_REGISTRATION_TOKEN_1",
	// ...
	"YOUR_REGISTRATION_TOKEN_n",
}
message := &messaging.MulticastMessage{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Tokens: registrationTokens,
}

br, err := client.SendMulticast(context.Background(), message)
if err != nil {
	log.Fatalln(err)
}

// See the BatchResponse reference documentation
// for the contents of response.
fmt.Printf("%d messages were sent successfully\n", br.SuccessCount)
messaging.go

C#

// Create a list containing up to 500 registration tokens.
// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n",
};
var message = new MulticastMessage()
{
    Tokens = registrationTokens,
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
};

var response = await FirebaseMessaging.DefaultInstance.SendEachForMulticastAsync(message);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");
FirebaseMessagingSnippets.cs

O valor de retorno é uma lista de tokens que corresponde à ordem dos tokens de entrada. Isso é útil quando se quer verificar quais tokens resultaram em erros.

Node.js

// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
  'YOUR_REGISTRATION_TOKEN_1',
  // …
  'YOUR_REGISTRATION_TOKEN_N',
];

const message = {
  data: {score: '850', time: '2:45'},
  tokens: registrationTokens,
};

getMessaging().sendMulticast(message)
  .then((response) => {
    if (response.failureCount > 0) {
      const failedTokens = [];
      response.responses.forEach((resp, idx) => {
        if (!resp.success) {
          failedTokens.push(registrationTokens[idx]);
        }
      });
      console.log('List of tokens that caused failures: ' + failedTokens);
    }
  });

Java

// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n"
);

MulticastMessage message = MulticastMessage.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .addAllTokens(registrationTokens)
    .build();
BatchResponse response = FirebaseMessaging.getInstance().sendMulticast(message);
if (response.getFailureCount() > 0) {
  List<SendResponse> responses = response.getResponses();
  List<String> failedTokens = new ArrayList<>();
  for (int i = 0; i < responses.size(); i++) {
    if (!responses.get(i).isSuccessful()) {
      // The order of responses corresponds to the order of the registration tokens.
      failedTokens.add(registrationTokens.get(i));
    }
  }

  System.out.println("List of tokens that caused failures: " + failedTokens);
}
FirebaseMessagingSnippets.java

Python

# These registration tokens come from the client FCM SDKs.
registration_tokens = [
    'YOUR_REGISTRATION_TOKEN_1',
    # ...
    'YOUR_REGISTRATION_TOKEN_N',
]

message = messaging.MulticastMessage(
    data={'score': '850', 'time': '2:45'},
    tokens=registration_tokens,
)
response = messaging.send_multicast(message)
if response.failure_count > 0:
    responses = response.responses
    failed_tokens = []
    for idx, resp in enumerate(responses):
        if not resp.success:
            # The order of responses corresponds to the order of the registration tokens.
            failed_tokens.append(registration_tokens[idx])
    print('List of tokens that caused failures: {0}'.format(failed_tokens))
cloud_messaging.py

Go

// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens := []string{
	"YOUR_REGISTRATION_TOKEN_1",
	// ...
	"YOUR_REGISTRATION_TOKEN_n",
}
message := &messaging.MulticastMessage{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Tokens: registrationTokens,
}

br, err := client.SendMulticast(context.Background(), message)
if err != nil {
	log.Fatalln(err)
}

if br.FailureCount > 0 {
	var failedTokens []string
	for idx, resp := range br.Responses {
		if !resp.Success {
			// The order of responses corresponds to the order of the registration tokens.
			failedTokens = append(failedTokens, registrationTokens[idx])
		}
	}

	fmt.Printf("List of tokens that caused failures: %v\n", failedTokens)
}
messaging.go

C#

// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n",
};
var message = new MulticastMessage()
{
    Tokens = registrationTokens,
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
};

var response = await FirebaseMessaging.DefaultInstance.SendEachForMulticastAsync(message);
if (response.FailureCount > 0)
{
    var failedTokens = new List<string>();
    for (var i = 0; i < response.Responses.Count; i++)
    {
        if (!response.Responses[i].IsSuccess)
        {
            // The order of responses corresponds to the order of the registration tokens.
            failedTokens.Add(registrationTokens[i]);
        }
    }

    Console.WriteLine($"List of tokens that caused failures: {failedTokens}");
}
FirebaseMessagingSnippets.cs

Como enviar mensagens para tópicos

Depois de criar um tópico, seja inscrevendo instâncias do app cliente no tópico do lado do cliente ou usando a API do servidor, será possível enviar mensagens ao tópico. Se esta for a primeira vez que você cria solicitações de envio para o FCM, consulte o guia do ambiente do servidor e o FCM para informações gerais importantes e sobre configuração.

Na sua lógica de envio no back-end, especifique o nome do tópico desejado conforme mostrado abaixo:

Node.js

// The topic name can be optionally prefixed with "/topics/".
const topic = 'highScores';

const message = {
  data: {
    score: '850',
    time: '2:45'
  },
  topic: topic
};

// Send a message to devices subscribed to the provided topic.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// The topic name can be optionally prefixed with "/topics/".
String topic = "highScores";

// See documentation on defining a message payload.
Message message = Message.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .setTopic(topic)
    .build();

// Send a message to the devices subscribed to the provided topic.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
FirebaseMessagingSnippets.java

Python

# The topic name can be optionally prefixed with "/topics/".
topic = 'highScores'

# See documentation on defining a message payload.
message = messaging.Message(
    data={
        'score': '850',
        'time': '2:45',
    },
    topic=topic,
)

# Send a message to the devices subscribed to the provided topic.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
cloud_messaging.py

Go

// The topic name can be optionally prefixed with "/topics/".
topic := "highScores"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Topic: topic,
}

// Send a message to the devices subscribed to the provided topic.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
messaging.go

C#

// The topic name can be optionally prefixed with "/topics/".
var topic = "highScores";

// See documentation on defining a message payload.
var message = new Message()
{
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
    Topic = topic,
};

// Send a message to the devices subscribed to the provided topic.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
    "topic" : "foo-bar",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message"
      }
   }
}

Comando cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "message": {
    "topic" : "foo-bar",
    "notification": {
      "body": "This is a Firebase Cloud Messaging Topic Message!",
      "title": "FCM Message"
    }
  }
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Para enviar uma mensagem para uma combinação de tópicos, especifique uma condição, que é uma expressão booleana que especifica os tópicos de destino. Por exemplo, a seguinte condição vai enviar mensagens para dispositivos que estão inscritos em TopicA e TopicB ou TopicC:

"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"

No FCM, todas as condições entre parênteses são avaliadas primeiro e depois expressão é analisada da esquerda para a direita. Na expressão acima, um usuário que se inscreveu em um só tópico não receberá a mensagem. Do mesmo modo, um usuário que não se inscreveu em TopicA também não receberá a mensagem. Somente estas combinações são válidas:

• TopicA e TopicB
• TopicA e TopicC

Você pode incluir até cinco tópicos na sua expressão condicional.

Para enviar para uma condição:

Node.js

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
const condition = '\'stock-GOOG\' in topics || \'industry-tech\' in topics';

// See documentation on defining a message payload.
const message = {
  notification: {
    title: '$FooCorp up 1.43% on the day',
    body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
  },
  condition: condition
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
String condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
Message message = Message.builder()
    .setNotification(Notification.builder()
        .setTitle("$GOOG up 1.43% on the day")
        .setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
        .build())
    .setCondition(condition)
    .build();

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
FirebaseMessagingSnippets.java

Python

# Define a condition which will send to devices which are subscribed
# to either the Google stock or the tech industry topics.
condition = "'stock-GOOG' in topics || 'industry-tech' in topics"

# See documentation on defining a message payload.
message = messaging.Message(
    notification=messaging.Notification(
        title='$GOOG up 1.43% on the day',
        body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
    ),
    condition=condition,
)

# Send a message to devices subscribed to the combination of topics
# specified by the provided condition.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
cloud_messaging.py

Go

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
condition := "'stock-GOOG' in topics || 'industry-tech' in topics"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Condition: condition,
}

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
messaging.go

C#

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
var condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
var message = new Message()
{
    Notification = new Notification()
    {
        Title = "$GOOG up 1.43% on the day",
        Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
    },
    Condition = condition,
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
   "message":{
    "condition": "'dogs' in topics || 'cats' in topics",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message",
    }
  }
}

Comando cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "notification": {
    "title": "FCM Message",
    "body": "This is a Firebase Cloud Messaging Topic Message!",
  },
  "condition": "'dogs' in topics || 'cats' in topics"
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Como enviar mensagens para grupos de dispositivos

Para enviar mensagens a grupos de dispositivos, use a API HTTP v1. Se você estiver enviando para grupos de dispositivos usando as APIs de envio legadas descontinuadas para HTTP ou XMPP, ou qualquer uma das versões mais antigas do Firebase Admin SDK para Node.js com base nos protocolos legados, recomendamos migrar para a API HTTP v1 assim que possível. As APIs de envio legadas serão desativadas e removidas em junho de 2024.

O envio de mensagens para um grupo de dispositivos é muito semelhante ao envio para um dispositivo individual, usando o mesmo método para autorizar solicitações de envio. Defina o campo token como a chave de notificação do grupo:

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
   "message":{
      "token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
      "data":{
        "hello": "This is a Firebase Cloud Messaging device group message!"
      }
   }
}

Comando cURL

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "data":{
     "hello": "This is a Firebase Cloud Messaging device group message!"
   },
   "token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

Observação: diferentemente dos métodos de envio do grupo de dispositivos em APIs legadas obsoletas, a resposta HTTP v1 não contém contagens de sucesso e falha. Um envio bem-sucedido retorna uma resposta vazia.

Enviar um lote de mensagens

Importante: os métodos de envio em lote descritos nesta seção foram descontinuados em 21 de junho de 2023 e vão ser removidos em junho de 2024. Para protocolo, use o método padrão de envio da API HTTP v1, implementando seu próprio envio em lote, iterando a lista de destinatários e enviando para o token de cada destinatário. Para os métodos do SDK Admin, atualize para a próxima versão principal. Consulte as Perguntas frequentes sobre o Firebase para mais informações.

Os SDKs Admin são compatíveis com o envio de mensagens em lotes. É possível agrupar até 500 mensagens em um único lote e enviá-las em uma única chamada de API, com uma melhoria de desempenho significativa em relação ao envio de solicitações HTTP separadas para cada mensagem.

Esse recurso pode ser usado para criar um conjunto personalizado de mensagens e enviá-las para diferentes destinatários, incluindo tópicos ou tokens de registro de dispositivos específicos. Use esse recurso quando, por exemplo, for necessário enviar simultaneamente mensagens para diferentes públicos com detalhes ligeiramente diferentes no corpo da mensagem.

Node.js

// Create a list containing up to 500 messages.
const messages = [];
messages.push({
  notification: { title: 'Price drop', body: '5% off all electronics' },
  token: registrationToken,
});
messages.push({
  notification: { title: 'Price drop', body: '2% off all books' },
  topic: 'readers-club',
});

getMessaging().sendAll(messages)
  .then((response) => {
    console.log(response.successCount + ' messages were sent successfully');
  });

Java

// Create a list containing up to 500 messages.
List<Message> messages = Arrays.asList(
    Message.builder()
        .setNotification(Notification.builder()
            .setTitle("Price drop")
            .setBody("5% off all electronics")
            .build())
        .setToken(registrationToken)
        .build(),
    // ...
    Message.builder()
        .setNotification(Notification.builder()
            .setTitle("Price drop")
            .setBody("2% off all books")
            .build())
        .setTopic("readers-club")
        .build()
);

BatchResponse response = FirebaseMessaging.getInstance().sendAll(messages);
// See the BatchResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " messages were sent successfully");
FirebaseMessagingSnippets.java

Python

# Create a list containing up to 500 messages.
messages = [
    messaging.Message(
        notification=messaging.Notification('Price drop', '5% off all electronics'),
        token=registration_token,
    ),
    # ...
    messaging.Message(
        notification=messaging.Notification('Price drop', '2% off all books'),
        topic='readers-club',
    ),
]

response = messaging.send_all(messages)
# See the BatchResponse reference documentation
# for the contents of response.
print('{0} messages were sent successfully'.format(response.success_count))
cloud_messaging.py

Go

// Create a list containing up to 500 messages.
messages := []*messaging.Message{
	{
		Notification: &messaging.Notification{
			Title: "Price drop",
			Body:  "5% off all electronics",
		},
		Token: registrationToken,
	},
	{
		Notification: &messaging.Notification{
			Title: "Price drop",
			Body:  "2% off all books",
		},
		Topic: "readers-club",
	},
}

br, err := client.SendAll(context.Background(), messages)
if err != nil {
	log.Fatalln(err)
}

// See the BatchResponse reference documentation
// for the contents of response.
fmt.Printf("%d messages were sent successfully\n", br.SuccessCount)
messaging.go

C#

// Create a list containing up to 500 messages.
var messages = new List<Message>()
{
    new Message()
    {
        Notification = new Notification()
        {
            Title = "Price drop",
            Body = "5% off all electronics",
        },
        Token = registrationToken,
    },
    new Message()
    {
        Notification = new Notification()
        {
            Title = "Price drop",
            Body = "2% off all books",
        },
        Topic = "readers-club",
    },
};

var response = await FirebaseMessaging.DefaultInstance.SendEachAsync(messages);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");
FirebaseMessagingSnippets.cs

Como enviar mensagens ativadas para inicialização direta (somente Android)

É possível enviar mensagens para dispositivos no modo de inicialização direta usando as APIs HTTP v1 ou HTTP legadas. Antes do envio para dispositivos no modo de inicialização direta, conclua as etapas para permitir que os dispositivos clientes recebam mensagens do FCM no modo de inicialização direta.

Cuidado: é importante considerar a visibilidade das mensagens ativadas para inicialização direta. Qualquer usuário com acesso ao dispositivo pode ver essas mensagens sem digitar as credenciais do usuário.

Enviar usando a API HTTP v1 do FCM

A solicitação de mensagem precisa incluir a chave "direct_boot_ok" : true nas opções AndroidConfig do corpo da solicitação. Por exemplo:

https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
  "message":{
    "token" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
    "data": {
      "score": "5x1",
      "time": "15:10"
    },
    "android": {
      "direct_boot_ok": true,
    },
}

Enviar usando a API HTTP legada do FCM

Cuidado: o envio de mensagens (incluindo mensagens upstream) com as 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.

A solicitação de mensagem precisa incluir a chave "direct_boot_ok" : true no nível superior do corpo da solicitação. Por exemplo:

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{ "data": {
    "score": "5x1",
    "time": "15:10"
  },
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  "direct_boot_ok" : true
}

As mensagens enviadas com essa chave no corpo da solicitação podem ser processadas por apps em dispositivos que estão atualmente no modo de inicialização direta (e também quando não estão nesse modo).

Personalizar mensagens entre plataformas

O Firebase Admin SDK e o protocolo HTTP v1 do FCM permitem que as solicitações de mensagens configurem todos os campos disponíveis no objeto message. Incluindo:

• Um conjunto comum de campos a serem interpretados por todas as instâncias do app que recebem a mensagem.
• Conjuntos de campos específicos da plataforma, como AndroidConfig e WebpushConfig, interpretados apenas pelas instâncias do app em execução na plataforma especificada.

Os blocos específicos da plataforma oferecem flexibilidade para personalizar mensagens em plataformas diferentes, garantindo, assim, que elas sejam gerenciadas corretamente quando recebidas. O back-end do FCM considerará todos os parâmetros especificados e personalizará a mensagem para cada plataforma.

Quando usar campos comuns

Use campos comuns ao:

• segmentar instâncias de aplicativos em todas as plataformas: Apple, Android e Web;
• enviar mensagens para tópicos.

Todas as instâncias do app, independentemente da plataforma, podem interpretar os seguintes campos comuns:

• message.notification.title
• message.notification.body
• message.data

Quando usar campos específicos da plataforma

Use campos específicos da plataforma quando quiser:

• enviar campos apenas para plataformas específicas;
• enviar campos específicos da plataforma, além dos campos comuns.

Sempre que você quiser enviar valores apenas para plataformas específicas, não use campos comuns. Em vez disso, use campos específicos da plataforma. Por exemplo, para enviar uma notificação apenas para as plataformas Apple e Web, mas não para o Android, use dois conjuntos de campos separados, um para a Apple e outro para a Web.

Ao enviar mensagens com opções de entrega específicas, use os campos específicos da plataforma para configurá-las. É possível especificar valores diferentes por plataforma, se você quiser. No entanto, mesmo quando você quiser definir essencialmente o mesmo valor em todas as plataformas, é necessário usar campos específicos da plataforma. Isso ocorre porque o valor pode ser interpretado de maneira ligeiramente diferente dependendo da plataforma. Por exemplo, no Android, a vida útil é definida como um prazo de validade em segundos. Já na Apple, é definida como uma data de validade.

Exemplo: mensagem de notificação com opções de cor e ícone

A solicitação de exemplo a seguir envia o título e o conteúdo de uma notificação comum para todas as plataformas, mas também inclui algumas substituições específicas da plataforma para dispositivos Android.

Para Android, a solicitação define uma cor e um ícone especiais para exibir nos dispositivos. Conforme observado na AndroidNotification, a cor é especificada no formato #rrggbb, e a imagem precisa ser um recurso de ícone drawable local para o app Android.

Esta é uma aproximação do efeito visual no dispositivo de um usuário:

Node.js

const topicName = 'industry-tech';

const message = {
  notification: {
    title: '`$FooCorp` up 1.43% on the day',
    body: 'FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
  },
  android: {
    notification: {
      icon: 'stock_ticker_update',
      color: '#7e55c3'
    }
  },
  topic: topicName,
};

getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

Message message = Message.builder()
    .setNotification(Notification.builder()
        .setTitle("$GOOG up 1.43% on the day")
        .setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
        .build())
    .setAndroidConfig(AndroidConfig.builder()
        .setTtl(3600 * 1000)
        .setNotification(AndroidNotification.builder()
            .setIcon("stock_ticker_update")
            .setColor("#f45342")
            .build())
        .build())
    .setApnsConfig(ApnsConfig.builder()
        .setAps(Aps.builder()
            .setBadge(42)
            .build())
        .build())
    .setTopic("industry-tech")
    .build();
FirebaseMessagingSnippets.java

Python

message = messaging.Message(
    notification=messaging.Notification(
        title='$GOOG up 1.43% on the day',
        body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
    ),
    android=messaging.AndroidConfig(
        ttl=datetime.timedelta(seconds=3600),
        priority='normal',
        notification=messaging.AndroidNotification(
            icon='stock_ticker_update',
            color='#f45342'
        ),
    ),
    apns=messaging.APNSConfig(
        payload=messaging.APNSPayload(
            aps=messaging.Aps(badge=42),
        ),
    ),
    topic='industry-tech',
)
cloud_messaging.py

Go

oneHour := time.Duration(1) * time.Hour
badge := 42
message := &messaging.Message{
	Notification: &messaging.Notification{
		Title: "$GOOG up 1.43% on the day",
		Body:  "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
	},
	Android: &messaging.AndroidConfig{
		TTL: &oneHour,
		Notification: &messaging.AndroidNotification{
			Icon:  "stock_ticker_update",
			Color: "#f45342",
		},
	},
	APNS: &messaging.APNSConfig{
		Payload: &messaging.APNSPayload{
			Aps: &messaging.Aps{
				Badge: &badge,
			},
		},
	},
	Topic: "industry-tech",
}
messaging.go

C#

var message = new Message
{
    Notification = new Notification()
    {
        Title = "$GOOG up 1.43% on the day",
        Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
    },
    Android = new AndroidConfig()
    {
        TimeToLive = TimeSpan.FromHours(1),
        Notification = new AndroidNotification()
        {
            Icon = "stock_ticker_update",
            Color = "#f45342",
        },
    },
    Apns = new ApnsConfig()
    {
        Aps = new Aps()
        {
            Badge = 42,
        },
    },
    Topic = "industry-tech",
};
FirebaseMessagingSnippets.cs

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
     "topic":"industry-tech",
     "notification":{
       "title":"`$FooCorp` up 1.43% on the day",
       "body":"FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day."
     },
     "android":{
       "notification":{
         "icon":"stock_ticker_update",
         "color":"#7e55c3"
       }
     }
   }
 }

Consulte a documentação de referência HTTP v1 para mais detalhes sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem.

Exemplo: mensagem de notificação com uma imagem personalizada

O exemplo de solicitação de envio a seguir envia um título de notificação comum para todas as plataformas, mas também envia uma imagem. Esta é uma aproximação do efeito visual no dispositivo de um usuário:

Node.js

const topicName = 'industry-tech';

const message = {
  notification: {
    title: 'Sparky says hello!'
  },
  android: {
    notification: {
      imageUrl: 'https://foo.bar.pizza-monster.png'
    }
  },
  apns: {
    payload: {
      aps: {
        'mutable-content': 1
      }
    },
    fcm_options: {
      image: 'https://foo.bar.pizza-monster.png'
    }
  },
  webpush: {
    headers: {
      image: 'https://foo.bar.pizza-monster.png'
    }
  },
  topic: topicName,
};

getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
     "topic":"industry-tech",
     "notification":{
       "title":"Sparky says hello!",
     },
     "android":{
       "notification":{
         "image":"https://foo.bar/pizza-monster.png"
       }
     },
     "apns":{
       "payload":{
         "aps":{
           "mutable-content":1
         }
       },
       "fcm_options": {
           "image":"https://foo.bar/pizza-monster.png"
       }
     },
     "webpush":{
       "headers":{
         "image":"https://foo.bar/pizza-monster.png"
       }
     }
   }
 }

Consulte a documentação de referência HTTP v1 para mais detalhes sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem.

Exemplo: mensagem de notificação com uma ação de clique associada

O exemplo de solicitação de envio a seguir envia um título de notificação comum para todas as plataformas, mas também envia uma ação para o aplicativo realizar em resposta ao usuário que interage com a notificação. Esta é uma aproximação do efeito visual no dispositivo de um usuário:

Node.js

const topicName = 'industry-tech';

const message = {
  notification: {
    title: 'Breaking News....'
  },
  android: {
    notification: {
      clickAction: 'news_intent'
    }
  },
  apns: {
    payload: {
      aps: {
        'category': 'INVITE_CATEGORY'
      }
    }
  },
  webpush: {
    fcmOptions: {
      link: 'breakingnews.html'
    }
  },
  topic: topicName,
};

getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
     "topic":"industry-tech",
     "notification":{
       "title":"Breaking News...",
     },
     "android":{
       "notification":{
         "click_action":"news_intent"
       }
     },
     "apns":{
       "payload":{
         "aps":{
           "category" : "INVITE_CATEGORY"
         }
       },
     },
     "webpush":{
       "fcm_options":{
         "link":"breakingnews.html"
       }
     }
   }
 }

Consulte a documentação de referência HTTP v1 para mais detalhes sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem.

Exemplo: mensagem de notificação com opções de localização

O exemplo de solicitação de envio a seguir envia opções de localização para o cliente exibir mensagens localizadas. Esta é uma aproximação do efeito visual no dispositivo de um usuário:

Node.js

var topicName = 'industry-tech';

var message = {
  android: {
    ttl: 3600000,
    notification: {
      bodyLocKey: 'STOCK_NOTIFICATION_BODY',
      bodyLocArgs: ['FooCorp', '11.80', '835.67', '1.43']
    }
  },
  apns: {
    payload: {
      aps: {
        alert: {
          locKey: 'STOCK_NOTIFICATION_BODY',
          locArgs: ['FooCorp', '11.80', '835.67', '1.43']
        }
      }
    }
  },
  topic: topicName,
};

getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
             "topic":"Tech",
             "android":{
               "ttl":"3600s",
               "notification":{
                 "body_loc_key": "STOCK_NOTIFICATION_BODY",
                 "body_loc_args":  ["FooCorp", "11.80", "835.67", "1.43"],
               },
             },
             "apns":{
               "payload":{
                 "aps":{
                   "alert" : {
                     "loc-key": "STOCK_NOTIFICATION_BODY",
                     "loc-args":  ["FooCorp", "11.80", "835.67", "1.43"],
                    },
                 },
               },
             },
  },
}'

Consulte a documentação de referência HTTP v1 para mais detalhes sobre as chaves disponíveis em blocos específicos da plataforma no corpo da mensagem.

Códigos de erro REST para a API HTTP v1

As respostas de erro HTTP para a API HTTP v1 contêm um código do erro, uma mensagem de erro e o status do erro. Eles também podem conter uma matriz details com mais detalhes sobre o erro.

Veja dois exemplos de respostas de erro:

Exemplo 1: resposta de erro de uma solicitação de API HTTP v1 com um valor inválido em uma mensagem de dados

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "message.data[0].value",
            "description": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12"
          }
        ]
      }
    ]
  }
}

Exemplo 2: resposta de erro de uma solicitação de API HTTP v1 com um token de registro inválido

{
  "error": {
    "code": 400,
    "message": "The registration token is not a valid FCM registration token",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError",
        "errorCode": "INVALID_ARGUMENT"
      }
    ]
   }
}

Observe que ambas as mensagens têm o mesmo código e status, mas a matriz de detalhes contém tipos de valores diferentes. O primeiro exemplo tem o tipo type.googleapis.com/google.rpc.BadRequest, indicando um erro nos valores da solicitação. O segundo exemplo com o tipo type.googleapis.com/google.firebase.fcm.v1.FcmError tem um erro específico do FCM. Para muitos erros, a matriz de detalhes contém as informações necessárias para depurar e encontrar uma resolução.

A tabela a seguir lista os códigos de erro da API REST do FCM v1 e as respectivas descrições.

Código do erro	Etapas de descrição e resolução
UNSPECIFIED_ERROR Não há mais informações disponíveis sobre esse erro.	Nenhuma.
INVALID_ARGUMENT (código do erro HTTP = 400) Os parâmetros da solicitação eram inválidos. Uma extensão do tipo google.rpc.BadRequest é retornada para especificar qual campo era inválido.	As possíveis causas incluem registro inválido, nome de pacote inválido, mensagem muito grande, chave de dados inválida, TTL inválido ou outros parâmetros inválidos. Registro inválido: verifique o formato do token de registro que você transmite ao servidor. Verifique se ele corresponde ao token de registro que o app cliente recebe ao se registrar no FCM. Não faça truncamento nem adicione caracteres. Nome de pacote inválido: verifique se a mensagem foi endereçada a um token de registro cujo nome do pacote corresponde ao valor transmitido na solicitação. Mensagem muito grande: 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. Inclui as chaves e os valores. Chave de dados inválida: verifique se os dados de payload não contêm uma chave (como "from", "gcm" ou qualquer valor com prefixo "google") usada 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. TTL inválido: verifique se o valor usado em ttl é um número inteiro que representa uma duração em segundos entre 0 e 2.419.200 (4 semanas). Parâmetros inválidos: verifique se os parâmetros fornecidos têm o nome e o tipo corretos.
UNREGISTERED (código do erro HTTP = 404) A instância do app teve a inscrição cancelada do FCM. Isso geralmente significa que o token usado não é mais válido e deve ser usado um novo.	Esse erro pode ser causado por tokens de registro ausentes ou tokens com inscrição cancelada. Registro ausente: se o destino da mensagem for um valor token, verifique se a solicitação contém um token de registro. Não registrado: um token de registro atual pode deixar de ser válido em diversos cenários, incluindo: - se o app cliente cancelar a inscrição com o FCM. - se o app cliente tiver a inscrição cancelada 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 de APNs 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. - Quando o app cliente está atualizado, mas a nova versão não está configurada para receber mensagens. Para todos esses casos, remova o token de registro do servidor do app e pare de usá-lo para enviar mensagens.
SENDER_ID_MISMATCH (código do erro HTTP = 403) O ID do remetente autenticado é diferente do ID do remetente do token de registro.	Um token de registro está vinculado a um determinado grupo de remetentes. Quando um app cliente se registra no FCM, os remetentes autorizados a enviar mensagens precisam ser especificados. 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.
QUOTA_EXCEEDED (código do erro HTTP = 429) O limite de envio foi excedido para o destino da mensagem. Uma extensão do tipo google.rpc.QuotaFailure é retornada para especificar qual cota foi excedida.	Esse erro pode ser causado por ter excedido a cota de taxa de mensagens, a cota de taxa de mensagens do dispositivo ou a cota de taxa de mensagens de tópico. Taxa de mensagens excedida: a taxa de envio de mensagens está muito alta. Reduza a taxa geral de envio de mensagens. Use a espera exponencial com um delay inicial mínimo de um minuto para tentar enviar novamente as mensagens rejeitadas. Taxa de mensagens do dispositivo excedida: a taxa de mensagens para um determinado dispositivo está muito alta. Consulte Limite de taxa de mensagens para um único dispositivo. 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: 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 a espera exponencial com um delay inicial mínimo de 1 minuto para tentar novamente o envio.
UNAVAILABLE (código do erro HTTP = 503) O servidor está sobrecarregado.	A solicitação não foi processada a tempo no servidor. 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 você estiver enviando várias mensagens, considere aplicar a instabilidade. Para mais informações, consulte Como lidar com novas tentativas Os remetentes que causam problemas podem ser incluídos em listas de proibições.
INTERNAL (código do erro HTTP = 500) Ocorreu um erro interno desconhecido.	O servidor encontrou um erro enquanto tentava processar a solicitação. Repita a mesma solicitação seguindo as sugestões em Como lidar com novas tentativas. Se o erro persistir, entre em contato com o suporte do Firebase.
THIRD_PARTY_AUTH_ERROR (código do erro HTTP = 401) O certificado de APNs ou a chave de autenticação por push na Web era inválido ou estava ausente.	Não foi possível enviar uma mensagem direcionada a um dispositivo iOS ou um registro de push da Web. Verifique a validade das credenciais de desenvolvimento e produção.

Códigos de erro do administrador

Confira na tabela a seguir os códigos de erro da API Firebase Admin FCM e a descrição de cada erro, incluindo as etapas de resolução recomendadas.

Código do erro	Etapas de descrição e resolução
messaging/invalid-argument	Um argumento inválido foi fornecido a um método do FCM. A mensagem de erro deve conter informações adicionais.
messaging/invalid-recipient	O destinatário da mensagem pretendida é inválido. A mensagem de erro deve conter informações adicionais.
messaging/invalid-payload	Um objeto de payload de mensagem inválido foi fornecido. A mensagem de erro deve conter informações adicionais.
messaging/invalid-data-payload-key	O payload da mensagem de dados contém uma chave inválida. Consulte a documentação de referência de DataMessagePayload para mais detalhes sobre chaves restritas.
messaging/payload-size-limit-exceeded	O payload da mensagem fornecido excede os limites de tamanho do FCM. O limite é de 4.096 bytes para a maioria das mensagens. Para mensagens enviadas para tópicos, o limite é de 2.048 bytes. O tamanho do payload total inclui chaves e valores.
messaging/invalid-options	Um objeto de opções de mensagem inválido foi fornecido. A mensagem de erro deve conter informações adicionais.
messaging/invalid-registration-token	Um token de registro inválido foi fornecido. Verifique se ele corresponde ao token de registro que o app cliente recebe ao se registrar no FCM. Não faça truncagem nem acrescente caracteres adicionais.
messaging/registration-token-not-registered	O token de registro fornecido não está registrado. Um token de registro anteriormente válido pode ter a inscrição cancelada por várias razões, incluindo: O app cliente cancelou a inscrição do FCM. O app cliente foi automaticamente cancelado. Isso pode acontecer se o usuário desinstala o app ou, em plataformas Apple, se o Serviço de feedback APNS informou o token APNS como inválido. O token de registro expirou. Por exemplo, o Google pode decidir atualizar tokens de registro, ou o token APNS pode ter expirado para dispositivos Apple. O app cliente foi atualizado, mas a nova versão não está configurada para receber mensagens. Para todos esses casos, remova o token de registro e pare de usá-lo no envio de mensagens.
messaging/invalid-package-name	A mensagem foi encaminhada a um token de registro e o nome do pacote dele não corresponde à opção restrictedPackageName fornecida.
messaging/message-rate-exceeded	A taxa de mensagens para um determinado destino é muito alta. Reduza o número de mensagens enviadas a esse dispositivo e não tente reenviar mensagens ao mesmo dispositivo imediatamente.
messaging/device-message-rate-exceeded	A taxa de mensagens para um determinado dispositivo é muito alta. Reduza o número de mensagens enviadas a esse dispositivo e não tente reenviar mensagens a esse dispositivo imediatamente.
messaging/topics-message-rate-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 não tente reenviar mensagens a esse tópico imediatamente.
messaging/too-many-topics	Um token de registro foi inscrito no número máximo de tópicos e não pode ser inscrito em mais.
messaging/invalid-apns-credentials	Uma mensagem direcionada a um dispositivo Apple não conseguiu ser enviada porque o certificado obrigatório de SSL de APNs não foi enviado ou expirou. Verifique a validade de seus certificados de desenvolvimento e produção.
messaging/mismatched-credential	A credencial utilizada para autenticar esse SDK não tem permissão para enviar mensagens ao dispositivo correspondente ao token de registro fornecido. Verifique se o token de registro e a credencial pertencem ao mesmo projeto do Firebase. Consulte Adicionar o Firebase ao seu app para conferir a documentação sobre como autenticar os Firebase Admin SDKs.
messaging/authentication-error	O SDK não conseguiu se autenticar com os servidores do FCM. Certifique-se de autenticar o Firebase Admin SDK com uma credencial que tenha as adequadas permissões para enviar mensagens FCM. Consulte Adicionar o Firebase ao seu app para conferir a documentação sobre como autenticar os Firebase Admin SDKs.
messaging/server-unavailable	O servidor do FCM não conseguiu processar a solicitação a tempo. Repita o mesmo pedido, mas é 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 você 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 a todas as mensagens ao mesmo tempo. Os remetentes que causam problemas podem ser incluídos em listas de proibições.
messaging/internal-error	O servidor do FCM encontrou um erro enquanto tentava processar a solicitação. Repita a mesma solicitação seguindo os requisitos listados na linha messaging/server-unavailable acima. Se o erro persistir, informe o problema para nosso canal de suporte Relatório de bugs.
messaging/unknown-error	Um erro de servidor desconhecido foi retornado. Veja a resposta do servidor bruto na mensagem de erro para saber mais. Se você receber esse erro, informe a mensagem completa no nosso canal de suporte Relatório de bugs.

Enviar mensagens usando os protocolos do servidor de apps legados

Cuidado: o envio de mensagens (incluindo mensagens upstream) com as 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.

Se você estiver usando os protocolos legados, crie solicitações de mensagens conforme mostrado nesta seção. Tenha em mente que, se você estiver enviando para várias plataformas via HTTP, o protocolo v1 pode simplificar bastante as solicitações de mensagens.

Como enviar mensagens para dispositivos específicos

Para enviar mensagens a dispositivos específicos, defina a chave to como o token de registro da instância de app. Consulte as informações de configuração do cliente da sua plataforma para saber mais sobre esses tokens.

Solicitação HTTP POST

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{ "data": {
    "score": "5x1",
    "time": "15:10"
  },
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}

Resposta HTTP

{ "multicast_id": 108,
  "success": 1,
  "failure": 0,
  "results": [
    { "message_id": "1:08" }
  ]
}

Mensagem XMPP

<message id="">
  <gcm xmlns="google:mobile:data">
    { "data": {
      "score": "5x1",
      "time": "15:10"
    },
    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }
  </gcm>
</message>

Resposta XMPP

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "from":"REGID",
      "message_id":"m-1366082849205"
      "message_type":"ack"
  }
  </gcm>
</message>

No servidor de conexão XMPP, há outras opções de resposta. Consulte Formato de resposta do servidor.

Para ver a lista completa de opções de mensagens disponíveis ao enviar mensagens downstream a apps clientes, consulte as informações de referência do protocolo do servidor de conexão selecionado, HTTP ou XMPP.

Como enviar mensagens para tópicos

O envio de mensagens para um tópico Firebase Cloud Messaging é muito semelhante ao envio de mensagens para um dispositivo individual ou um grupo de usuários. O servidor do app define a chave to com um valor como /topics/yourTopic. Os desenvolvedores podem escolher um nome de tópico que corresponda à seguinte expressão regular: "/topics/[a-zA-Z0-9-_.~%]+".

Para enviar a combinações de vários tópicos, o servidor de apps precisa definir a chave condition (em vez da chave to) como uma condição booleana que especifica os tópicos de destino. Por exemplo, para enviar mensagens para dispositivos que estão inscritos em TopicA e TopicB ou TopicC:

'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)

No FCM, todas as condições entre parênteses são avaliadas primeiro e depois a expressão é analisada da esquerda para a direita. Na expressão acima, um usuário que se inscreveu em um só tópico não receberá a mensagem. Do mesmo modo, um usuário que não se inscreveu no TopicA também não receberá a mensagem. As seguintes combinações receberão a mensagem:

• TopicA e TopicB
• TopicA e TopicC

Inclua até cinco tópicos em sua expressão condicional, e parênteses são aceitos. Operadores compatíveis: &&, ||.

Solicitação HTTP POST de tópico

Enviar para um único tópico:

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Enviar para dispositivos inscritos nos tópicos "dogs" ou "cats":

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Resposta HTTP de tópico

// Success example:
{
  "message_id": "1023456"
}

// failure example:
{
  "error": "TopicsMessageRateExceeded"
}

Mensagem XMPP de tópico

Enviar para um único tópico:

<message id="">
  <gcm xmlns="google:mobile:data">


  </gcm>
</message>

Enviar para dispositivos inscritos nos tópicos "dogs" ou "cats":

<message id="">
  <gcm xmlns="google:mobile:data">


  </gcm>
</message>

Resposta XMPP de tópico

// Success example:
{
  "message_id": "1023456"
}

// failure example:
{
  "error": "TopicsMessageRateExceeded"
}

Aguarde até 30 segundos para que o servidor de conexão do FCM retorne uma resposta de êxito ou falha para as solicitações de envio de tópico. Defina corretamente o valor de tempo limite do servidor do app na solicitação.

Observação: também é possível segmentar mensagens para vários tópicos configurando a chave condition. Para mais informações, consulte o guia sobre mensagens de tópico da sua plataforma.

Como enviar mensagens para grupos de dispositivos

Cuidado: o envio de mensagens (incluindo mensagens upstream) com as 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.

O envio de mensagens para um grupo de dispositivos usando as APIs legadas e descontinuadas é muito semelhante ao envio de mensagens para um dispositivo individual. Defina o parâmetro to como a chave de notificação exclusiva do grupo. Os exemplos nesta seção mostram como enviar mensagens de dados para esses grupos de dispositivos nos protocolos HTTP e XMPP legados.

Solicitação HTTP POST para grupo de dispositivos

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to": "aUniqueKey",
  "data": {
    "hello": "This is a Firebase Cloud Messaging Device Group Message!",
   }
}

Resposta HTTP do grupo de dispositivos

Este é um exemplo de êxito na operação: a notification_key tem dois tokens de registro associados a ela e a mensagem foi enviada a ambos:

{
  "success": 2,
  "failure": 0
}

Este é um exemplo de "êxito parcial" na operação: a notification_key tem três tokens de registro associados a ela. A mensagem foi enviada apenas para um dos tokens de registro. A mensagem da resposta lista os tokens (registration_ids) onde houve falha ao receber a mensagem:

{
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

Quando uma mensagem não é entregue a um ou mais tokens de registro associados a uma notification_key, o servidor do app faz uma nova tentativa com um intervalo de espera entre elas.

Se o servidor tenta enviar uma mensagem para um grupo de dispositivos que não tem membros, a resposta é parecida com esta, com 0 sucesso e 0 falha:

{
  "success": 0,
  "failure": 0
}

Mensagem XMPP para grupo de dispositivos

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to": "aUniqueKey",
      "message_id": "m-1366082849205" ,
      "data": {
          "hello":"This is a Firebase Cloud Messaging Device Group Message!"
      }
  }
  </gcm>
</message>

Resposta XMPP do grupo de dispositivos

Quando a mensagem é enviada com sucesso para qualquer um dos dispositivos do grupo, o servidor de conexões XMPP responde com um ACK. Quando ocorre falha no envio de todas as mensagens a todos os dispositivos do grupo, o servidor responde com um NACK.

Este é um exemplo de "êxito" na operação: a notification_key tem três tokens de registro associados a ela e a mensagem foi enviada a todos:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success": 3,
  "failure": 0,
  "message_id": "m-1366082849205"
}

Este é um exemplo de "êxito parcial" na operação: a notification_key tem três tokens de registro associados a ela. A mensagem foi enviada apenas para um dos tokens de registro. A mensagem de resposta lista os tokens de registro que não receberam a mensagem:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

quando um servidor de conexão do FCM não entrega para todos os dispositivos no grupo. o servidor do app receberá uma resposta NACK.

Para ver a lista completa de opções de mensagens, consulte as informações de referência do protocolo do servidor de conexão selecionado, HTTP ou XMPP.

Métodos de envio legados do Firebase Admin SDK

Cuidado: as APIs do SDK Admin para Node.js descritas nesta seção foram descontinuadas em 21 de fevereiro de 2023, e a funcionalidade será removida em fevereiro de 2024. Em vez de sendToDevice() e sendToDeviceGroup(), use send().

O SDK Admin para Node.js do Firebase oferece suporte a métodos de envio de mensagens (FCM) baseados na API legada do servidor do FCM. Esses métodos aceitam argumentos diferentes em comparação com o método send(). Use o método send() sempre que possível e utilize os métodos descritos nesta página apenas ao enviar mensagens para dispositivos individuais ou grupos de dispositivos.

Observação: essas APIs estão disponíveis apenas no SDK Admin para Node.js.

Enviar para dispositivos individuais

É possível transmitir um token de registro ao método sendToDevice() para enviar uma mensagem a esse dispositivo:

Node.js

// This registration token comes from the client FCM SDKs.
const registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';

// See the "Defining the message payload" section below for details
// on how to define a message payload.
const payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

// Send a message to the device corresponding to the provided
// registration token.
getMessaging().sendToDevice(registrationToken, payload)
  .then((response) => {
    // See the MessagingDevicesResponse reference documentation for
    // the contents of response.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

O método sendToDevice() também pode enviar uma mensagem multicast (ou seja, para vários dispositivos) ao transmitir uma matriz de tokens de registro, em vez de apenas um único token de registro:

Node.js

// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
  'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...',
  // ...
  'ecupwIfBy1w:APA91bFtuMY7MktgxA3Au_Qx7cKqnf...'
];

// See the "Defining the message payload" section below for details
// on how to define a message payload.
const payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

// Send a message to the devices corresponding to the provided
// registration tokens.
getMessaging().sendToDevice(registrationTokens, payload)
  .then((response) => {
    // See the MessagingDevicesResponse reference documentation for
    // the contents of response.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Observação: você pode enviar mensagens para até mil dispositivos em uma única solicitação. Se você fornecer uma matriz com mais de 1.000 tokens de registro, a solicitação falhará com um erro messaging/invalid-recipient.

O método sendToDevice() retorna uma promessa que é resolvida com um objeto MessagingDevicesResponse contendo a resposta do FCM. O tipo de retorno tem o mesmo formato, seja para transmitir um único token de registro ou uma matriz de tokens.

Alguns casos, como um erro de autenticação ou limitação de taxa, fazem com que a totalidade da mensagem não seja processada. Nesses casos, a promessa retornada por sendToDevice() é rejeitada com erro. Para ver uma lista completa de códigos de erro, incluindo descrições e etapas de solução de problemas, consulte Erros da API Admin do FCM.

Como enviar para um grupo de dispositivos

Com o método sendToDeviceGroup(), é possível enviar uma mensagem para um grupo de dispositivos ao especificar a chave de notificação para ele:

Node.js

// See the "Managing device groups" link above on how to generate a
// notification key.
const notificationKey = 'some-notification-key';

// See the "Defining the message payload" section below for details
// on how to define a message payload.
const payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

// Send a message to the device group corresponding to the provided
// notification key.
getMessaging().sendToDeviceGroup(notificationKey, payload)
  .then((response) => {
    // See the MessagingDeviceGroupResponse reference documentation for
    // the contents of response.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

O método sendToDeviceGroup() retorna uma promessa que é resolvida com um objeto MessagingDevicesResponse contendo a resposta do FCM.

Alguns casos, como um erro de autenticação ou limitação de taxa, fazem com que a mensagem inteira não seja processada. Nesses casos, a promessa retornada por sendToDeviceGroup() é rejeitada com erro. Para ver uma lista completa de códigos de erro, incluindo descrições e etapas de solução de problemas, consulte Erros da API Admin do FCM.

Como definir o payload da mensagem

Os métodos acima baseados nos protocolos legados do FCM aceitam um payload da mensagem como segundo argumento e oferecem suporte a mensagens de notificação e de dados. Especifique um ou ambos os tipos de mensagens criando um objeto com as chaves de data e/ou notification. Por exemplo, veja como definir diferentes tipos de payloads de mensagens:

Mensagem de notificação

const payload = {
  notification: {
    title: '$FooCorp up 1.43% on the day',
    body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
  }
};

Mensagem de dados

const payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

Mensagem combinada

const payload = {
  notification: {
    title: '$FooCorp up 1.43% on the day',
    body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
  },
  data: {
    stock: 'GOOG',
    open: '829.62',
    close: '635.67'
  }
};

Os payloads das mensagens de notificação têm um subconjunto predefinido de propriedades válidas e diferem ligeiramente, dependendo de qual sistema operacional móvel é o objeto das suas atividades. Consulte a documentação de referência de NotificationMessagePayload para ver uma lista completa.

Os payloads das mensagens de dados são compostos por pares de chave-valor personalizados com algumas restrições, incluindo o fato de que todos os valores precisam ser strings. Para ver uma lista completa de restrições, consulte a documentação de referência de DataMessagePayload.

Como definir as opções de mensagem

Os métodos acima baseados nos protocolos legados do FCM aceitam um terceiro argumento opcional que especifica algumas opções para a mensagem. Veja no exemplo a seguir o envio de uma mensagem de alta prioridade a um dispositivo, que expira após 24 horas:

Node.js

// This registration token comes from the client FCM SDKs.
const registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';

// See the "Defining the message payload" section above for details
// on how to define a message payload.
const payload = {
  notification: {
    title: 'Urgent action needed!',
    body: 'Urgent action is needed to prevent your account from being disabled!'
  }
};

// Set the message as high priority and have it expire after 24 hours.
const options = {
  priority: 'high',
  timeToLive: 60 * 60 * 24
};

// Send a message to the device corresponding to the provided
// registration token with the provided options.
getMessaging().sendToDevice(registrationToken, payload, options)
  .then((response) => {
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Para ver uma lista completa das opções disponíveis, consulte a documentação de referência de MessagingOptions.