สร้างคำขอส่งคำขอจากเซิร์ฟเวอร์แอป

เมื่อใช้โปรโตคอลเซิร์ฟเวอร์แอป Firebase Admin SDK หรือ FCM คุณจะสร้างคำขอข้อความและส่งไปยังเป้าหมายประเภทต่อไปนี้ได้

• ชื่อหัวข้อ
• เงื่อนไข
• โทเค็นการลงทะเบียนอุปกรณ์
• ชื่อกลุ่มอุปกรณ์ (โปรโตคอลเท่านั้น)

คุณสามารถส่งข้อความที่มีเพย์โหลดการแจ้งเตือนซึ่งประกอบด้วยช่องที่กําหนดไว้ล่วงหน้า เพย์โหลดข้อมูลของช่องที่ผู้ใช้กําหนดเอง หรือข้อความที่มีเพย์โหลดทั้ง 2 ประเภท ดูข้อมูลเพิ่มเติมที่หัวข้อ ประเภทข้อความ

สำคัญ: ส่งคำขอสำหรับทั้งโปรโตคอล HTTP Firebase Admin SDK และ v1 ต้องระบุรหัสโปรเจ็กต์ Firebase ของแอป ซึ่งดูได้ในแท็บการตั้งค่าโปรเจ็กต์ทั่วไปของคอนโซล Firebase นอกจากนี้ คุณจะต้องให้สิทธิ์ส่งคำขอ

ด้วยหากต้องการส่งข้อความด้วยทั้ง 2 วิธี

ตัวอย่างในหน้านี้แสดงวิธีส่งข้อความแจ้งเตือนโดยใช้ Firebase Admin SDK (ซึ่งรองรับ Node, Java, Python, C# และ Go) และโปรโตคอล HTTP v1 นอกจากนี้ยังมีคำแนะนำสำหรับการส่งข้อความผ่านโปรโตคอล HTTP และ XMPP เดิมที่เลิกใช้งานแล้ว

ข้อควรระวัง: เราได้เลิกใช้งานการส่งข้อความ (รวมถึงข้อความขาเข้า) ด้วย FCM API เดิมของ XMPP และ HTTP ไปเมื่อวันที่ 20 มิถุนายน 2023 และจะนำออกตั้งแต่เดือนมิถุนายน 2024 หากคุณใช้ FCM Send API รุ่นเดิม เราขอแนะนําอย่างยิ่งให้คุณย้ายข้อมูลไปยัง HTTP v1 API หรือพิจารณาใช้ Admin SDK เพื่อสร้างคําขอส่ง

ส่งข้อความไปยังอุปกรณ์ที่ต้องการ

หากต้องการส่งไปยังอุปกรณ์เครื่องเดียว ให้ส่งโทเค็นการลงทะเบียนของอุปกรณ์ตามที่แสดง ดูข้อมูลเพิ่มเติมเกี่ยวกับโทเค็นการลงทะเบียนได้จากข้อมูลการตั้งค่าไคลเอ็นต์สําหรับแพลตฟอร์มของคุณ

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"
      }
   }
}

คำสั่ง 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

เมื่อดำเนินการสำเร็จ วิธีการส่งแต่ละวิธีจะแสดงรหัสข้อความ Firebase Admin SDK จะแสดงผลสตริงรหัสในรูปแบบ projects/{project_id}/messages/{message_id} การตอบกลับโปรโตคอล HTTP คือคีย์ JSON รายการเดียว ดังนี้

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

ส่งข้อความไปยังอุปกรณ์หลายเครื่อง

สำคัญ: เราได้เลิกใช้งานวิธีการส่งที่อธิบายในส่วนนี้ไปเมื่อวันที่ 21 มิถุนายน 2023 และจะนําออกในเดือนมิถุนายน 2024 สำหรับโปรโตคอล ให้ใช้วิธีการส่ง HTTP v1 API มาตรฐานแทน โดยใช้การส่งแบบเป็นกลุ่มของคุณเองโดยเรียกใช้รายการผู้รับซ้ำๆ และส่งไปยังโทเค็นของผู้รับแต่ละราย สำหรับเมธอด Admin SDK โปรดตรวจสอบว่าได้อัปเดตเป็นเวอร์ชันหลักถัดไป ดูข้อมูลเพิ่มเติมได้ที่คำถามที่พบบ่อยของ Firebase

FCM API สำหรับผู้ดูแลระบบช่วยให้คุณส่งข้อความแบบมัลติแคสต์ไปยังรายการโทเค็นการลงทะเบียนอุปกรณ์ได้ คุณระบุโทเค็นการลงทะเบียนอุปกรณ์ได้สูงสุด 500 รายการต่อการเรียกใช้

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

ค่าที่แสดงผลคือรายการโทเค็นที่สอดคล้องกับลําดับของโทเค็นอินพุต ซึ่งจะมีประโยชน์เมื่อคุณต้องการตรวจสอบว่าโทเค็นใดทำให้เกิดข้อผิดพลาด

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

ส่งข้อความไปยังหัวข้อ

หลังจากสร้างหัวข้อแล้ว คุณสามารถส่งข้อความไปยังหัวข้อได้ด้วยการสมัครใช้บริการอินสแตนซ์แอปไคลเอ็นต์เพื่อรับหัวข้อที่ฝั่งไคลเอ็นต์ หรือผ่าน server API หากนี่เป็นการสร้างคำขอส่งสำหรับ FCM เป็นครั้งแรก ให้ดูคำแนะนำเกี่ยวกับสภาพแวดล้อมเซิร์ฟเวอร์และ FCM เพื่อดูข้อมูลเบื้องต้นและข้อมูลการตั้งค่าที่สำคัญ

ในตรรกะการส่งในแบ็กเอนด์ ให้ระบุชื่อหัวข้อที่ต้องการดังที่แสดง

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"
      }
   }
}

คำสั่ง 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

หากต้องการส่งข้อความไปยังชุดค่าผสมของหัวข้อ ให้ระบุเงื่อนไข ซึ่งเป็นนิพจน์บูลีนที่กำหนดหัวข้อเป้าหมาย ตัวอย่างเช่น เงื่อนไขต่อไปนี้จะส่งข้อความไปยังอุปกรณ์ที่สมัครใช้บริการ TopicA และ TopicB หรือ TopicC

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

FCM จะประเมินเงื่อนไขในวงเล็บก่อน แล้วจึงประเมินนิพจน์จากซ้ายไปขวา ในนิพจน์ข้างต้น ผู้ใช้ที่สมัครรับข้อมูลหัวข้อเดียวใดๆ จะไม่ได้รับการแจ้งเตือน ในทำนองเดียวกัน ผู้ใช้ที่ไม่ได้ติดตาม TopicA จะไม่ได้รับการแจ้งเตือน รายการต่อไปนี้จะได้รับเครดิต

• TopicA และ TopicB
• TopicA และ TopicC

คุณใส่หัวข้อในนิพจน์เงื่อนไขได้สูงสุด 5 หัวข้อ

หากต้องการส่งไปยังเงื่อนไข

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",
    }
  }
}

คำสั่ง 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

ส่งข้อความไปยังกลุ่มอุปกรณ์

หากต้องการส่งข้อความไปยังกลุ่มอุปกรณ์ ให้ใช้ HTTP v1 API หากคุณกําลังส่งไปยังกลุ่มอุปกรณ์โดยใช้ API ส่งเดิมที่เลิกใช้งานแล้วสําหรับ HTTP หรือ XMPP หรือ Firebase Admin SDK เวอร์ชันเก่าๆ สําหรับ Node.js ซึ่งอิงตามโปรโตคอลเดิม เราขอแนะนําอย่างยิ่งให้คุณย้ายข้อมูลไปยัง HTTP v1 API ทันทีที่มีโอกาส เราจะปิดใช้และนํา API การส่งเดิมออกในเดือนมิถุนายน 2024

การส่งข้อความไปยังกลุ่มอุปกรณ์คล้ายกับการส่งข้อความไปยังอุปกรณ์แต่ละเครื่องมาก โดยใช้วิธีการเดียวกันในการให้สิทธิ์ส่งคำขอ ตั้งค่าช่อง token เป็นคีย์การแจ้งเตือนกลุ่ม ดังนี้

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!"
      }
   }
}

คำสั่ง 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

หมายเหตุ: การตอบกลับ HTTP v1 จะไม่มีจํานวนความสําเร็จและการไม่สําเร็จ ซึ่งแตกต่างจากเมธอดการส่งกลุ่มอุปกรณ์ใน API เดิมที่เลิกใช้งานแล้ว หากส่งสำเร็จ ระบบจะแสดงผลการตอบกลับที่ว่างเปล่า

ส่งข้อความหลายรายการพร้อมกัน

สำคัญ: เราได้เลิกใช้งานวิธีการส่งแบบเป็นกลุ่มที่อธิบายในส่วนนี้ไปเมื่อวันที่ 21 มิถุนายน 2023 และจะนําออกในเดือนมิถุนายน 2024 สำหรับโปรโตคอล ให้ใช้วิธีการส่ง HTTP v1 API มาตรฐานแทน โดยใช้การส่งแบบเป็นกลุ่มของคุณเองโดยเรียกใช้รายการผู้รับซ้ำๆ และส่งไปยังโทเค็นของผู้รับแต่ละราย สำหรับเมธอด Admin SDK โปรดตรวจสอบว่าได้อัปเดตเป็นเวอร์ชันหลักถัดไป ดูข้อมูลเพิ่มเติมได้ที่คำถามที่พบบ่อยของ Firebase

Admin SDK รองรับการส่งข้อความทีละหลายรายการ คุณสามารถจัดกลุ่มข้อความได้สูงสุด 500 รายการเป็นกลุ่มเดียวและส่งทั้งหมดในการเรียก API ครั้งเดียว ซึ่งจะมีประสิทธิภาพที่ดีขึ้นอย่างมากเมื่อเทียบกับการส่งคําขอ HTTP แยกต่างหากสําหรับข้อความแต่ละรายการ

ฟีเจอร์นี้สามารถใช้สร้างชุดข้อความที่กำหนดเองและส่งไปยังผู้รับรายต่างๆ รวมถึงหัวข้อหรือโทเค็นการลงทะเบียนอุปกรณ์ที่เฉพาะเจาะจง ใช้ฟีเจอร์นี้เมื่อคุณต้องการส่งข้อความไปยังกลุ่มเป้าหมายที่แตกต่างกันพร้อมกันโดยมีรายละเอียดที่แตกต่างกันเล็กน้อยในเนื้อหาข้อความ

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

ส่งข้อความที่เปิดใช้การบูตโดยตรง (Android เท่านั้น)

คุณสามารถส่งข้อความไปยังอุปกรณ์ในโหมดการบูตโดยตรงได้โดยใช้ HTTP v1 หรือ HTTP API รุ่นเดิม ก่อนส่งไปยังอุปกรณ์ในโหมดการบูตโดยตรง โปรดตรวจสอบว่าคุณได้ทำตามขั้นตอนเพื่อเปิดใช้อุปกรณ์ไคลเอ็นต์ให้รับข้อความ FCM ในโหมดการบูตโดยตรงเรียบร้อยแล้ว

ข้อควรระวัง: คุณต้องพิจารณาระดับการเข้าถึงของข้อความที่เปิดใช้การบูตโดยตรง เนื่องจากผู้ใช้ทุกคนที่มีสิทธิ์เข้าถึงอุปกรณ์จะดูข้อความเหล่านี้ได้โดยไม่ต้องป้อนข้อมูลเข้าสู่ระบบของผู้ใช้

ส่งโดยใช้ FCM v1 HTTP API

คำขอข้อความต้องมีคีย์ "direct_boot_ok" : true ในตัวเลือก AndroidConfig ของเนื้อหาคำขอ เช่น

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,
    },
}

ส่งโดยใช้ FCM HTTP API เดิม

ข้อควรระวัง: เราได้เลิกใช้งานการส่งข้อความ (รวมถึงข้อความขาเข้า) ด้วย FCM API เดิมของ XMPP และ HTTP ไปเมื่อวันที่ 20 มิถุนายน 2023 และจะนำออกตั้งแต่เดือนมิถุนายน 2024 หากคุณใช้ FCM Send API รุ่นเดิม เราขอแนะนําอย่างยิ่งให้คุณย้ายข้อมูลไปยัง HTTP v1 API หรือพิจารณาใช้ Admin SDK เพื่อสร้างคําขอส่ง

คำขอข้อความต้องมีคีย์ "direct_boot_ok" : true ที่ระดับบนสุดของเนื้อหาคำขอ เช่น

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
}

แอปในอุปกรณ์ที่อยู่ในโหมดการบูตโดยตรง (และไม่ได้อยู่ในโหมดนั้น) สามารถจัดการข้อความที่ส่งด้วยคีย์นี้ในเนื้อหาคำขอได้

ปรับแต่งข้อความในแพลตฟอร์มต่างๆ

ทั้งโปรโตคอล HTTP ของ Firebase Admin SDK และ FCM v1 อนุญาตให้คำขอข้อความของคุณตั้งค่าช่องทั้งหมดที่มีอยู่ในออบเจ็กต์ message ได้ ซึ่งรวมถึงเนื้อหาต่อไปนี้

• ชุดช่องทั่วไปที่จะตีความโดยอินสแตนซ์แอปทั้งหมดที่ได้รับข้อความ
• ชุดช่องเฉพาะแพลตฟอร์ม เช่น AndroidConfig และ WebpushConfig จะตีความโดยอินสแตนซ์แอปที่ทํางานบนแพลตฟอร์มที่ระบุเท่านั้น

บล็อกเฉพาะแพลตฟอร์มช่วยให้คุณปรับแต่งข้อความสำหรับแพลตฟอร์มต่างๆ ได้อย่างยืดหยุ่นเพื่อให้แน่ใจว่าระบบจะจัดการข้อความอย่างถูกต้องเมื่อได้รับ แบ็กเอนด์ FCM จะพิจารณาพารามิเตอร์ที่ระบุทั้งหมดและปรับแต่งข้อความสำหรับแต่ละแพลตฟอร์ม

กรณีที่ควรใช้ช่องทั่วไป

ใช้ช่องทั่วไปในกรณีต่อไปนี้

• การกำหนดเป้าหมายอินสแตนซ์แอปในแพลตฟอร์มทั้งหมด ได้แก่ Apple, Android และเว็บ
• การส่งข้อความไปยังหัวข้อ

อินสแตนซ์แอปทั้งหมดไม่ว่าจะใช้แพลตฟอร์มใดก็สามารถตีความช่องทั่วไปต่อไปนี้ได้

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

กรณีที่ควรใช้ช่องเฉพาะแพลตฟอร์ม

ใช้ช่องเฉพาะแพลตฟอร์มเมื่อคุณต้องการทำสิ่งต่อไปนี้

• ส่งช่องไปยังบางแพลตฟอร์มเท่านั้น
• ส่งช่องเฉพาะแพลตฟอร์มนอกเหนือจากช่องทั่วไป

เมื่อใดก็ตามที่คุณต้องการส่งค่าไปยังแพลตฟอร์มที่เฉพาะเจาะจงเท่านั้น อย่าใช้ฟิลด์ทั่วไป แต่ให้ใช้ฟิลด์เฉพาะแพลตฟอร์ม เช่น หากต้องการส่งการแจ้งเตือนไปยังแพลตฟอร์มและเว็บของ Apple เท่านั้น แต่ไม่ส่งไปยัง Android คุณต้องใช้ช่อง 2 ชุดแยกกัน ได้แก่ ช่องสำหรับ Apple และช่องสำหรับเว็บ

เมื่อส่งข้อความที่มีตัวเลือกการนำส่งที่เฉพาะเจาะจง ให้ใช้ช่องเฉพาะแพลตฟอร์มเพื่อตั้งค่า คุณสามารถระบุค่าที่แตกต่างกันในแต่ละแพลตฟอร์มได้หากต้องการ อย่างไรก็ตาม แม้ว่าคุณต้องการตั้งค่าที่เหมือนกันในแพลตฟอร์มต่างๆ แต่ก็ต้องใช้ฟิลด์เฉพาะแพลตฟอร์ม เนื่องจากแต่ละแพลตฟอร์มอาจตีความค่านี้แตกต่างกันเล็กน้อย เช่น Android จะตั้งค่าการคงอยู่เป็นเวลาหมดอายุเป็นวินาที ส่วน Apple จะตั้งค่าเป็นวันที่หมดอายุ

ตัวอย่าง: ข้อความการแจ้งเตือนที่มีตัวเลือกสีและไอคอน

ตัวอย่างคำขอส่งนี้จะส่งชื่อและเนื้อหาการแจ้งเตือนทั่วไปไปยังแพลตฟอร์มทั้งหมด แต่ก็จะส่งการลบล้างเฉพาะแพลตฟอร์มบางอย่างไปยังอุปกรณ์ Android ด้วย

สําหรับ Android คําขอจะตั้งค่าไอคอนและสีพิเศษเพื่อแสดงในอุปกรณ์ Android ตามที่ระบุไว้ในข้อมูลอ้างอิงสำหรับ AndroidNotification ระบบจะระบุสีในรูปแบบ #rrggbb และรูปภาพต้องเป็นทรัพยากรไอคอนที่วาดได้ภายในแอป Android

ต่อไปนี้คือค่าโดยประมาณของเอฟเฟกต์ภาพในอุปกรณ์ของผู้ใช้

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"
       }
     }
   }
 }

ดูรายละเอียดทั้งหมดเกี่ยวกับคีย์ที่มีอยู่ในบล็อกเฉพาะแพลตฟอร์มในเนื้อหาข้อความได้ที่เอกสารอ้างอิง HTTP v1

ตัวอย่าง: ข้อความการแจ้งเตือนที่มีรูปภาพที่กำหนดเอง

ตัวอย่างคำขอส่งต่อไปนี้จะส่งชื่อการแจ้งเตือนทั่วไปไปยังทุกแพลตฟอร์ม แต่ก็จะส่งรูปภาพด้วย ต่อไปนี้คือภาพโดยประมาณของผลลัพธ์ภาพในอุปกรณ์ของผู้ใช้

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"
       }
     }
   }
 }

ดูรายละเอียดทั้งหมดเกี่ยวกับคีย์ที่มีอยู่ในบล็อกเฉพาะแพลตฟอร์มในเนื้อหาข้อความได้ที่เอกสารอ้างอิง HTTP v1

ตัวอย่าง: ข้อความการแจ้งเตือนที่มีการดำเนินการคลิกที่เชื่อมโยง

ตัวอย่างคำขอส่งต่อไปนี้จะส่งชื่อการแจ้งเตือนทั่วไปไปยังแพลตฟอร์มทั้งหมด แต่ก็จะส่งการดำเนินการให้แอปดำเนินการเพื่อตอบสนองต่อการโต้ตอบของผู้ใช้กับการแจ้งเตือนด้วย ต่อไปนี้คือค่าโดยประมาณของเอฟเฟกต์ภาพในอุปกรณ์ของผู้ใช้

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"
       }
     }
   }
 }

ดูรายละเอียดทั้งหมดเกี่ยวกับคีย์ที่มีอยู่ในบล็อกเฉพาะแพลตฟอร์มในเนื้อหาข้อความได้ที่เอกสารอ้างอิง HTTP v1

ตัวอย่าง: ข้อความการแจ้งเตือนที่มีตัวเลือกการแปล

ตัวอย่างคําขอส่งต่อไปนี้จะส่งตัวเลือกการแปลเพื่อให้ไคลเอ็นต์แสดงข้อความที่แปลแล้ว ต่อไปนี้คือค่าโดยประมาณของเอฟเฟกต์ภาพในอุปกรณ์ของผู้ใช้

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"],
                    },
                 },
               },
             },
  },
}'

ดูรายละเอียดทั้งหมดเกี่ยวกับคีย์ที่มีอยู่ในบล็อกเฉพาะแพลตฟอร์มในเนื้อหาข้อความได้ที่เอกสารอ้างอิง HTTP v1

รหัสข้อผิดพลาด REST สําหรับ HTTP v1 API

การตอบกลับข้อผิดพลาด HTTP สําหรับ HTTP v1 API จะมีรหัสข้อผิดพลาด ข้อความแสดงข้อผิดพลาด และสถานะข้อผิดพลาด และอาจมีอาร์เรย์ details ที่มีรายละเอียดเพิ่มเติมเกี่ยวกับข้อผิดพลาดด้วย

ตัวอย่างคำตอบแสดงข้อผิดพลาด 2 รายการมีดังนี้

ตัวอย่างที่ 1: การตอบกลับข้อผิดพลาดจากคําขอ HTTP v1 API ที่มีค่าไม่ถูกต้องในข้อความข้อมูล

{
  "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"
          }
        ]
      }
    ]
  }
}

ตัวอย่างที่ 2: การตอบกลับข้อผิดพลาดจากคําขอ HTTP v1 API ที่มีโทเค็นการลงทะเบียนไม่ถูกต้อง

{
  "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"
      }
    ]
   }
}

โปรดทราบว่าทั้ง 2 ข้อความมีรหัสและสถานะเดียวกัน แต่อาร์เรย์รายละเอียดมีค่าในประเภทที่แตกต่างกัน ตัวอย่างแรกมีประเภท type.googleapis.com/google.rpc.BadRequest ซึ่งบ่งบอกถึงข้อผิดพลาดในค่าคำขอ ตัวอย่างที่ 2 ที่มีประเภท type.googleapis.com/google.firebase.fcm.v1.FcmError มีข้อผิดพลาดเฉพาะของ FCM สำหรับข้อผิดพลาดจำนวนมาก อาร์เรย์รายละเอียดจะมีข้อมูลที่คุณต้องการเพื่อแก้ไขข้อบกพร่องและค้นหาวิธีแก้ไข

ตารางต่อไปนี้แสดงรหัสข้อผิดพลาดของ FCM v1 REST API และคำอธิบาย

รหัสข้อผิดพลาด	คําอธิบายและขั้นตอนการแก้ปัญหา
UNSPECIFIED_ERROR ไม่มีข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดนี้	ไม่มี
INVALID_ARGUMENT (รหัสข้อผิดพลาด HTTP = 400) พารามิเตอร์คำขอไม่ถูกต้อง ระบบจะแสดงผลส่วนขยายประเภท google.rpc.BadRequest เพื่อระบุช่องที่ไม่ถูกต้อง	สาเหตุที่เป็นไปได้ ได้แก่ การลงทะเบียนไม่ถูกต้อง ชื่อแพ็กเกจไม่ถูกต้อง ข้อความใหญ่เกินไป คีย์ข้อมูลไม่ถูกต้อง TTL ไม่ถูกต้อง หรือพารามิเตอร์อื่นๆ ไม่ถูกต้อง การลงทะเบียนไม่ถูกต้อง: ตรวจสอบรูปแบบของโทเค็นการลงทะเบียนที่คุณส่งไปยังเซิร์ฟเวอร์ ตรวจสอบว่าตรงกับโทเค็นการลงทะเบียนที่แอปไคลเอ็นต์ได้รับจากการลงทะเบียนกับ FCM อย่าตัดโทเค็นให้สั้นลงหรือเพิ่มอักขระอื่น ชื่อแพ็กเกจไม่ถูกต้อง: ตรวจสอบว่าข้อความส่งถึงโทเค็นการลงทะเบียนที่มีชื่อแพ็กเกจตรงกับค่าที่ส่งในคำขอ ข้อความมีขนาดใหญ่เกินไป: ตรวจสอบว่าขนาดรวมของข้อมูลเพย์โหลดที่รวมอยู่ในข้อความไม่เกินขีดจํากัดของ FCM ซึ่งก็คือ 4096 ไบต์สําหรับข้อความส่วนใหญ่ หรือ 2048 ไบต์ในกรณีที่เป็นข้อความไปยังหัวข้อ ซึ่งรวมถึงทั้งคีย์และค่า คีย์ข้อมูลไม่ถูกต้อง: ตรวจสอบว่าข้อมูลเพย์โหลดไม่มีคีย์ (เช่น from หรือ gcm หรือค่าใดๆ ที่มีคำนำหน้าเป็น google) ที่ FCM ใช้ภายใน โปรดทราบว่า FCM ใช้คําบางคํา (เช่น collapse_key) ด้วย แต่อนุญาตให้ใช้ในเพย์โหลดได้ ในกรณีนี้ ค่า FCM จะลบล้างค่าเพย์โหลด TTL ไม่ถูกต้อง: ตรวจสอบว่าค่าที่ใช้ใน ttl เป็นจำนวนเต็มซึ่งแสดงระยะเวลาเป็นวินาทีระหว่าง 0 ถึง 2,419,200 (4 สัปดาห์) พารามิเตอร์ไม่ถูกต้อง: ตรวจสอบว่าพารามิเตอร์ที่ระบุมีชื่อและประเภทถูกต้อง
UNREGISTERED (รหัสข้อผิดพลาด HTTP = 404) อินสแตนซ์แอปไม่ได้ลงทะเบียนกับ FCM ซึ่งโดยปกติหมายความว่าโทเค็นที่ใช้ไม่ถูกต้องอีกต่อไป และต้องเปลี่ยนไปใช้โทเค็นใหม่	ข้อผิดพลาดนี้อาจเกิดจากโทเค็นการลงทะเบียนขาดหายไปหรือโทเค็นไม่ได้ลงทะเบียน การลงทะเบียนขาดหายไป: หากเป้าหมายของข้อความคือค่า token ให้ตรวจสอบว่าคําขอมีโทเค็นการลงทะเบียน ไม่ได้ลงทะเบียน: โทเค็นการลงทะเบียนที่มีอยู่อาจใช้งานไม่ได้ในบางกรณี ซึ่งรวมถึง - หากแอปไคลเอ็นต์ยกเลิกการลงทะเบียนกับ FCM - หากแอปไคลเอ็นต์ไม่ได้ลงทะเบียนโดยอัตโนมัติ ซึ่งอาจเกิดขึ้นได้หากผู้ใช้ถอนการติดตั้งแอปพลิเคชัน ตัวอย่างเช่น ใน iOS หากบริการความคิดเห็นของ APNs รายงานว่าโทเค็น APNs ไม่ถูกต้อง - หากโทเค็นการลงทะเบียนหมดอายุ (เช่น Google อาจตัดสินใจรีเฟรชโทเค็นการลงทะเบียน หรือโทเค็น APNs หมดอายุสำหรับอุปกรณ์ iOS) - หากอัปเดตแอปไคลเอ็นต์แล้ว แต่ไม่ได้กำหนดค่าเวอร์ชันใหม่ให้รับข้อความ สำหรับกรณีเหล่านี้ทั้งหมด ให้นำโทเค็นการลงทะเบียนนี้ออกจากเซิร์ฟเวอร์ของแอปและหยุดใช้โทเค็นดังกล่าวเพื่อส่งข้อความ
SENDER_ID_MISMATCH (รหัสข้อผิดพลาด HTTP = 403) รหัสผู้ส่งที่ตรวจสอบสิทธิ์แล้วแตกต่างจากรหัสผู้ส่งสำหรับโทเค็นการลงทะเบียน	โทเค็นการลงทะเบียนจะเชื่อมโยงกับผู้ส่งบางกลุ่ม เมื่อแอปไคลเอ็นต์ลงทะเบียนสำหรับ FCM จะต้องระบุผู้ส่งที่ได้รับอนุญาตให้ส่งข้อความ คุณควรใช้รหัสผู้ส่งรหัสใดรหัสหนึ่งเมื่อส่งข้อความไปยังแอปไคลเอ็นต์ หากเปลี่ยนไปใช้ผู้ส่งรายอื่น โทเค็นการลงทะเบียนที่มีอยู่จะไม่ทำงาน
QUOTA_EXCEEDED (รหัสข้อผิดพลาด HTTP = 429) ส่งข้อความถึงเป้าหมายครบจำนวนสูงสุดที่ส่งได้ ระบบจะแสดงผลส่วนขยายประเภท google.rpc.QuotaFailure เพื่อระบุโควต้าที่เกิน	ข้อผิดพลาดนี้อาจเกิดจากโควต้าอัตราการส่งข้อความเกิน โควต้าอัตราการส่งข้อความของอุปกรณ์เกิน หรือโควต้าอัตราการส่งข้อความของหัวข้อเกิน อัตราการส่งข้อความเกิน: อัตราการส่งข้อความสูงเกินไป คุณต้องลดอัตราโดยรวมในการส่งข้อความ ใช้ Exponential Backoff ด้วยการหน่วงเวลาเริ่มต้นขั้นต่ำ 1 นาทีเพื่อลองส่งข้อความที่ถูกปฏิเสธอีกครั้ง อัตราข้อความของอุปกรณ์เกิน: อัตราข้อความที่ส่งไปยังอุปกรณ์หนึ่งๆ สูงเกินไป โปรดดูขีดจำกัดอัตราการส่งข้อความไปยังอุปกรณ์เครื่องเดียว ลดจำนวนข้อความที่ส่งไปยังอุปกรณ์นี้ และใช้ Exponential Backoff เพื่อส่งอีกครั้ง อัตราการส่งข้อความถึงผู้ติดตามหัวข้อหนึ่งๆ เกินขีดจำกัด: อัตราการส่งข้อความถึงผู้ติดตามหัวข้อหนึ่งๆ สูงเกินไป ลดจำนวนข้อความที่ส่งสำหรับหัวข้อนี้ และใช้ Exponential Backoff ด้วยการหน่วงเวลาเริ่มต้นขั้นต่ำ 1 นาทีเพื่อลองส่งอีกครั้ง
UNAVAILABLE (รหัสข้อผิดพลาด HTTP = 503) เซิร์ฟเวอร์ทำงานหนักเกินไป	เซิร์ฟเวอร์ประมวลผลคำขอไม่ทัน ลองส่งคําขอเดิมอีกครั้ง แต่ต้องดำเนินการดังนี้ - ปฏิบัติตามส่วนหัว Retry-After หากมีอยู่ในคำตอบจากเซิร์ฟเวอร์การเชื่อมต่อ FCM - ใช้ Exponential Backoff ในกลไกการลองใหม่ (เช่น หากรอ 1 วินาทีก่อนลองอีกครั้งครั้งแรก ให้รออย่างน้อย 2 วินาทีก่อนลองอีกครั้งถัดไป จากนั้นให้รอ 4 วินาที และเพิ่มเวลาขึ้นไปเรื่อยๆ) หากส่งข้อความหลายรายการ ให้ลองใช้ Jitter ดูข้อมูลเพิ่มเติมได้ที่การจัดการการลองอีกครั้ง ผู้ส่งที่ทำให้เกิดปัญหาอาจถูกเพิ่มลงในรายการที่ปฏิเสธ
INTERNAL (รหัสข้อผิดพลาด HTTP = 500) เกิดข้อผิดพลาดภายในที่ไม่ทราบสาเหตุ	เซิร์ฟเวอร์พบข้อผิดพลาดขณะพยายามประมวลผลคำขอ คุณลองส่งคำขอเดิมอีกครั้งได้โดยทำตามคำแนะนำในการจัดการการลองอีกครั้ง หากข้อผิดพลาดยังคงอยู่ โปรดติดต่อทีมสนับสนุนของ Firebase
THIRD_PARTY_AUTH_ERROR (รหัสข้อผิดพลาด HTTP = 401) ใบรับรอง APN หรือคีย์การตรวจสอบสิทธิ์ Push บนเว็บไม่ถูกต้องหรือไม่มี	ไม่สามารถส่งข้อความที่กำหนดเป้าหมายไปยังอุปกรณ์ iOS หรือการลงทะเบียน Push ทางเว็บ ตรวจสอบความถูกต้องของข้อมูลเข้าสู่ระบบสำหรับการพัฒนาและข้อมูลเข้าสู่ระบบสำหรับเวอร์ชันที่ใช้งานจริง

รหัสข้อผิดพลาดของผู้ดูแลระบบ

ตารางต่อไปนี้แสดงรหัสข้อผิดพลาด FCM API ของผู้ดูแลระบบ Firebase และคำอธิบาย รวมถึงขั้นตอนแก้ปัญหาที่แนะนำ

รหัสข้อผิดพลาด	คําอธิบายและขั้นตอนการแก้ปัญหา
messaging/invalid-argument	มีการใช้อาร์กิวเมนต์ที่ไม่ถูกต้องกับเมธอด FCM ข้อความแสดงข้อผิดพลาดควรมีข้อมูลเพิ่มเติม
messaging/invalid-recipient	ผู้รับข้อความที่ต้องการไม่ถูกต้อง ข้อความแสดงข้อผิดพลาดควรมีข้อมูลเพิ่มเติม
messaging/invalid-payload	ระบุออบเจ็กต์เพย์โหลดข้อความที่ไม่ถูกต้อง ข้อความแสดงข้อผิดพลาดควรมีข้อมูลเพิ่มเติม
messaging/invalid-data-payload-key	เพย์โหลดข้อความข้อมูลมีคีย์ที่ไม่ถูกต้อง ดูเอกสารอ้างอิงสำหรับ DataMessagePayload เกี่ยวกับคีย์ที่ถูกจํากัด
messaging/payload-size-limit-exceeded	เพย์โหลดข้อความที่ระบุมีขนาดใหญ่เกินขีดจำกัด FCM ขีดจำกัดคือ 4096 ไบต์สำหรับข้อความส่วนใหญ่ สำหรับข้อความที่ส่งไปยังหัวข้อ ขีดจำกัดคือ 2048 ไบต์ ขนาดของเพย์โหลดทั้งหมดจะรวมทั้งคีย์และค่า
messaging/invalid-options	ระบุออบเจ็กต์ตัวเลือกข้อความที่ไม่ถูกต้อง ข้อความแสดงข้อผิดพลาดควรมีข้อมูลเพิ่มเติม
messaging/invalid-registration-token	โทเค็นการลงทะเบียนที่ระบุไม่ถูกต้อง ตรวจสอบว่าตรงกับโทเค็นการลงทะเบียนที่แอปไคลเอ็นต์ได้รับจากการลงทะเบียนกับ FCM อย่าตัดให้สั้นลงหรือเพิ่มอักขระอื่น
messaging/registration-token-not-registered	โทเค็นการลงทะเบียนที่ระบุไม่ได้ลงทะเบียน โทเค็นการลงทะเบียนที่ใช้งานได้ก่อนหน้านี้อาจยกเลิกการลงทะเบียนได้เนื่องด้วยเหตุผลหลายประการ ซึ่งรวมถึงเหตุผลต่อไปนี้ แอปไคลเอ็นต์ยกเลิกการลงทะเบียนตัวเองจาก FCM ระบบจะยกเลิกการลงทะเบียนแอปไคลเอ็นต์โดยอัตโนมัติ กรณีนี้อาจเกิดขึ้นหากผู้ใช้ถอนการติดตั้งแอปพลิเคชัน หรือในแพลตฟอร์ม Apple หากบริการความคิดเห็นของ APNs รายงานว่าโทเค็น APNs ไม่ถูกต้อง โทเค็นการลงทะเบียนหมดอายุแล้ว ตัวอย่างเช่น Google อาจตัดสินใจที่จะรีเฟรชโทเค็นการลงทะเบียน หรือโทเค็น APN อาจหมดอายุสำหรับอุปกรณ์ Apple แอปไคลเอ็นต์ได้รับการอัปเดตแล้ว แต่เวอร์ชันใหม่ไม่ได้กำหนดค่าให้รับข้อความ สำหรับกรณีเหล่านี้ทั้งหมด ให้นำโทเค็นการลงทะเบียนนี้ออกและหยุดใช้เพื่อส่งข้อความ
messaging/invalid-package-name	ข้อความส่งถึงโทเค็นการลงทะเบียนที่มีชื่อแพ็กเกจไม่ตรงกับตัวเลือก restrictedPackageName ที่ระบุ
messaging/message-rate-exceeded	อัตราข้อความที่ส่งไปยังเป้าหมายหนึ่งๆ สูงเกินไป ลดจำนวนข้อความที่ส่งไปยังอุปกรณ์หรือหัวข้อนี้ และอย่าพยายามส่งไปยังเป้าหมายนี้อีกครั้งในทันที
messaging/device-message-rate-exceeded	อัตราการส่งข้อความไปยังอุปกรณ์หนึ่งๆ สูงเกินไป ลดจำนวนข้อความที่ส่งไปยังอุปกรณ์นี้ และอย่าพยายามส่งไปยังอุปกรณ์นี้อีกครั้งในทันที
messaging/topics-message-rate-exceeded	อัตราข้อความที่ส่งไปยังผู้ติดตามหัวข้อหนึ่งๆ สูงเกินไป ลดจำนวนข้อความที่ส่งสำหรับหัวข้อนี้ และอย่าลองส่งไปยังหัวข้อนี้อีกครั้งในทันที
messaging/too-many-topics	โทเค็นการลงทะเบียนได้สมัครรับหัวข้อถึงจำนวนสูงสุดแล้ว และไม่สามารถสมัครรับหัวข้อได้อีก
messaging/invalid-apns-credentials	ไม่สามารถส่งข้อความที่กำหนดเป้าหมายไปยังอุปกรณ์ Apple ได้เนื่องจากไม่ได้อัปโหลดใบรับรอง SSL ของ APNs ที่จำเป็นหรือใบรับรองดังกล่าวหมดอายุแล้ว ตรวจสอบความถูกต้องของใบรับรองสำหรับเวอร์ชันพัฒนาและเวอร์ชันที่ใช้งานจริง
messaging/mismatched-credential	ข้อมูลเข้าสู่ระบบที่ใช้ตรวจสอบสิทธิ์ SDK นี้ไม่มีสิทธิ์ส่งข้อความไปยังอุปกรณ์ที่สอดคล้องกับโทเค็นการลงทะเบียนที่ระบุ ตรวจสอบว่าข้อมูลเข้าสู่ระบบและโทเค็นการลงทะเบียนเป็นของโปรเจ็กต์ Firebase เดียวกัน ดูเอกสารประกอบเกี่ยวกับวิธีตรวจสอบสิทธิ์ Firebase Admin SDK ได้ที่หัวข้อเพิ่ม Firebase ลงในแอป
messaging/authentication-error	SDK ตรวจสอบสิทธิ์กับเซิร์ฟเวอร์ FCM ไม่ได้ ตรวจสอบว่าคุณตรวจสอบสิทธิ์ Firebase Admin SDK ด้วยข้อมูลเข้าสู่ระบบที่มีสิทธิ์ที่เหมาะสมในการส่งข้อความ FCM ดูเอกสารประกอบเกี่ยวกับวิธีตรวจสอบสิทธิ์ Firebase Admin SDK ได้ที่หัวข้อเพิ่ม Firebase ลงในแอป
messaging/server-unavailable	เซิร์ฟเวอร์ FCM ประมวลผลคําขอไม่ทัน คุณควรลองส่งคำขอเดิมอีกครั้ง แต่ต้องมีคุณสมบัติดังนี้ ปฏิบัติตามส่วนหัว Retry-After หากมีอยู่ในคำตอบจากเซิร์ฟเวอร์การเชื่อมต่อ FCM ใช้ Exponential Backoff ในกลไกการลองใหม่ ตัวอย่างเช่น หากคุณรอ 1 วินาทีก่อนที่จะลองอีกครั้งครั้งแรก ให้รออย่างน้อย 2 วินาทีก่อนที่จะลองอีกครั้ง จากนั้นรอ 4 วินาที และต่อไปเรื่อยๆ หากคุณส่งข้อความหลายรายการ ให้เลื่อนเวลาข้อความแต่ละรายการแบบอิสระโดยสุ่มระยะเวลาเพิ่มเติมเพื่อหลีกเลี่ยงการส่งคำขอใหม่สำหรับข้อความทั้งหมดพร้อมกัน ผู้ส่งที่ทำให้เกิดปัญหาอาจถูกเพิ่มลงในรายการที่ไม่ได้รับอนุญาต
messaging/internal-error	เซิร์ฟเวอร์ FCM พบข้อผิดพลาดขณะพยายามประมวลผลคำขอ คุณสามารถลองส่งคำขอเดิมอีกครั้งโดยทำตามข้อกำหนดที่ระบุไว้ในแถว messaging/server-unavailable ด้านบน หากข้อผิดพลาดยังคงอยู่ โปรดรายงานปัญหาไปยังช่องทางการสนับสนุนรายงานข้อบกพร่อง
messaging/unknown-error	ระบบแสดงข้อผิดพลาดของเซิร์ฟเวอร์ที่ไม่รู้จัก ดูรายละเอียดเพิ่มเติมในการตอบกลับแบบดิบจากเซิร์ฟเวอร์ในข้อความแสดงข้อผิดพลาด หากได้รับข้อผิดพลาดนี้ โปรดรายงานข้อความแสดงข้อผิดพลาดฉบับเต็มไปยังแชแนลการสนับสนุนรายงานข้อบกพร่อง

ส่งข้อความโดยใช้โปรโตคอลเซิร์ฟเวอร์แอปเดิม

ข้อควรระวัง: เราได้เลิกใช้งานการส่งข้อความ (รวมถึงข้อความขาเข้า) ด้วย FCM API เดิมของ XMPP และ HTTP ไปเมื่อวันที่ 20 มิถุนายน 2023 และจะนำออกตั้งแต่เดือนมิถุนายน 2024 หากคุณใช้ FCM Send API รุ่นเดิม เราขอแนะนําอย่างยิ่งให้คุณย้ายข้อมูลไปยัง HTTP v1 API หรือพิจารณาใช้ Admin SDK เพื่อสร้างคําขอส่ง

หากคุณใช้โปรโตคอลเดิมอยู่ ให้สร้างคำขอข้อความตามที่แสดงในส่วนนี้ โปรดทราบว่าหากส่งไปยังแพลตฟอร์มหลายแห่งผ่าน HTTP โปรโตคอล v1 จะช่วยให้คำขอข้อความของคุณง่ายขึ้นอย่างมาก

ส่งข้อความไปยังอุปกรณ์ที่ต้องการ

หากต้องการส่งข้อความไปยังอุปกรณ์ที่เฉพาะเจาะจง ให้ตั้งค่าคีย์ to เป็นโทเค็นการลงทะเบียนสําหรับอินสแตนซ์แอปที่เฉพาะเจาะจง ดูข้อมูลเพิ่มเติมเกี่ยวกับโทเค็นการลงทะเบียนได้ในข้อมูลการตั้งค่าไคลเอ็นต์สำหรับแพลตฟอร์มของคุณ

คำขอ 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..."
}

การตอบกลับ HTTP

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

ข้อความ XMPP

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

การตอบกลับ XMPP

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

เซิร์ฟเวอร์การเชื่อมต่อ XMPP มีตัวเลือกอื่นๆ สำหรับการตอบกลับ ดูรูปแบบการตอบกลับของเซิร์ฟเวอร์

ดูรายการตัวเลือกข้อความทั้งหมดที่ใช้ได้เมื่อส่งข้อความดาวน์สตรีมไปยังแอปไคลเอ็นต์ได้ที่ข้อมูลอ้างอิงสำหรับโปรโตคอลเซิร์ฟเวอร์การเชื่อมต่อที่เลือก ซึ่งได้แก่ HTTP หรือ XMPP

ส่งข้อความไปยังหัวข้อ

การส่งข้อความไปยังหัวข้อ Firebase Cloud Messaging นั้นคล้ายกับการส่งข้อความไปยังอุปกรณ์แต่ละเครื่องหรือกลุ่มผู้ใช้ เซิร์ฟเวอร์แอปตั้งค่าคีย์ to ด้วยค่าอย่างเช่น /topics/yourTopic นักพัฒนาแอปสามารถเลือกชื่อหัวข้อใดก็ได้ที่ตรงกับนิพจน์ทั่วไป "/topics/[a-zA-Z0-9-_.~%]+"

หากต้องการส่งไปยังชุดค่าผสมของหลายหัวข้อ เซิร์ฟเวอร์แอปต้องตั้งค่าคีย์ condition (แทนคีย์ to) เป็นเงื่อนไขบูลีนที่ระบุหัวข้อเป้าหมาย ตัวอย่างเช่น หากต้องการส่งข้อความไปยังอุปกรณ์ที่ติดตาม TopicA และ TopicB หรือ TopicC ให้ทำดังนี้

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

FCM จะประเมินเงื่อนไขในวงเล็บก่อน แล้วจึงประเมินนิพจน์จากซ้ายไปขวา ในนิพจน์ข้างต้น ผู้ใช้ที่สมัครรับข้อมูลหัวข้อใดหัวข้อหนึ่งจะไม่ได้รับข้อความ ในทำนองเดียวกัน ผู้ใช้ที่ไม่ได้ติดตาม TopicA ก็จะไม่ได้รับข้อความ รายการต่อไปนี้จะได้รับส่วนลด

• TopicA และ TopicB
• TopicA และ TopicC

คุณสามารถใส่หัวข้อในนิพจน์เงื่อนไขได้สูงสุด 5 หัวข้อ และระบบรองรับวงเล็บ โอเปอเรเตอร์ที่รองรับ: &&, ||

คำขอ HTTP POST ของหัวข้อ

ส่งไปยังหัวข้อเดียว

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

ส่งไปยังอุปกรณ์ที่ติดตามหัวข้อ "สุนัข" หรือ "แมว"

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

การตอบกลับ HTTP ของหัวข้อ

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

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

ข้อความ XMPP ของหัวข้อ

ส่งไปยังหัวข้อเดียว

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


  </gcm>
</message>

ส่งไปยังอุปกรณ์ที่ติดตามหัวข้อ "สุนัข" หรือ "แมว"

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


  </gcm>
</message>

การตอบกลับ XMPP ของหัวข้อ

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

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

โปรดรอสูงสุด 30 วินาทีก่อนที่FCMเซิร์ฟเวอร์จะแสดงการตอบกลับว่าส่งคำขอหัวข้อสำเร็จหรือไม่ อย่าลืมตั้งค่าการหมดเวลาของเซิร์ฟเวอร์แอปในคําขอให้สอดคล้องกัน

หมายเหตุ: คุณยังกําหนดเป้าหมายข้อความไปยังหลายหัวข้อได้โดยการตั้งค่าคีย์ condition ดูข้อมูลเพิ่มเติมได้ที่คู่มือการรับส่งข้อความในหัวข้อสำหรับแพลตฟอร์มของคุณ

ส่งข้อความไปยังกลุ่มอุปกรณ์

ข้อควรระวัง: เราได้เลิกใช้งานการส่งข้อความ (รวมถึงข้อความขาเข้า) ด้วย FCM API เดิมของ XMPP และ HTTP ไปเมื่อวันที่ 20 มิถุนายน 2023 และจะนำออกตั้งแต่เดือนมิถุนายน 2024 หากคุณใช้ FCM Send API รุ่นเดิม เราขอแนะนําอย่างยิ่งให้คุณย้ายข้อมูลไปยัง HTTP v1 API หรือพิจารณาใช้ Admin SDK เพื่อสร้างคําขอส่ง

การส่งข้อความไปยังกลุ่มอุปกรณ์โดยใช้ API รุ่นเดิมที่เลิกใช้งานแล้วนั้นคล้ายกับการส่งข้อความไปยังอุปกรณ์แต่ละเครื่อง ตั้งค่าพารามิเตอร์ to เป็นคีย์การแจ้งเตือนที่ไม่ซ้ำกันสำหรับกลุ่มอุปกรณ์ ตัวอย่างในส่วนนี้จะแสดงวิธีส่งข้อความข้อมูลไปยังกลุ่มอุปกรณ์ในโปรโตคอล HTTP และ XMPP รุ่นเดิม

คำขอ HTTP POST ของกลุ่มอุปกรณ์

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!",
   }
}

การตอบกลับ HTTP ของกลุ่มอุปกรณ์

ต่อไปนี้คือตัวอย่าง "สำเร็จ" notification_key มีโทเค็นการลงทะเบียน 2 รายการที่เชื่อมโยงอยู่ และระบบส่งข้อความไปยังทั้ง 2 รายการเรียบร้อยแล้ว

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

ต่อไปนี้คือตัวอย่าง "บางส่วนสำเร็จ" notification_key มีการเชื่อมโยงโทเค็นการลงทะเบียน 3 รายการ ระบบส่งข้อความไปยังโทเค็นการลงทะเบียน 1 รายการเรียบร้อยแล้ว ข้อความตอบกลับจะแสดงรายการโทเค็นการลงทะเบียน (registration_ids) ที่ไม่ได้รับการตอบกลับข้อความ

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

เมื่อส่งข้อความไปยังโทเค็นการลงทะเบียนอย่างน้อย 1 รายการที่เชื่อมโยงกับ notification_key ไม่สำเร็จ เซิร์ฟเวอร์แอปควรลองส่งอีกครั้งโดยมีการหยุดพักระหว่างการส่งซ้ำ

หากเซิร์ฟเวอร์พยายามส่งข้อความไปยังกลุ่มอุปกรณ์ที่ไม่มีสมาชิก การตอบกลับจะมีลักษณะดังต่อไปนี้ โดยมี 0 รายการที่สำเร็จและ 0 รายการที่ล้มเหลว

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

ข้อความ XMPP ของกลุ่มอุปกรณ์

<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>

การตอบกลับ XMPP ของกลุ่มอุปกรณ์

เมื่อส่งข้อความไปยังอุปกรณ์ใดอุปกรณ์หนึ่งในกลุ่มเรียบร้อยแล้ว เซิร์ฟเวอร์การเชื่อมต่อ XMPP จะตอบกลับด้วย ACK หากข้อความทั้งหมดที่ส่งไปยังอุปกรณ์ทั้งหมดในกลุ่มไม่สำเร็จ เซิร์ฟเวอร์การเชื่อมต่อ XMPP จะตอบกลับด้วย NACK

ต่อไปนี้คือตัวอย่าง "สำเร็จ" notification_key มีโทเค็นการลงทะเบียน 3 รายการที่เชื่อมโยงอยู่ และระบบส่งข้อความไปยังโทเค็นทั้งหมดเรียบร้อยแล้ว

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

ต่อไปนี้คือตัวอย่าง "บางส่วนสำเร็จ" notification_key มีการเชื่อมโยงโทเค็นการลงทะเบียน 3 รายการ ระบบส่งข้อความไปยังโทเค็นการลงทะเบียน 1 รายการเรียบร้อยแล้ว ข้อความตอบกลับจะแสดงรายการโทเค็นการลงทะเบียนที่ไม่ได้รับข้อความ

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

เมื่อเซิร์ฟเวอร์การเชื่อมต่อ FCM ส่งข้อมูลไปยังอุปกรณ์ทั้งหมดในกลุ่มไม่สำเร็จ เซิร์ฟเวอร์แอปจะได้รับการตอบกลับ nack

ดูรายการตัวเลือกข้อความทั้งหมดได้ที่ข้อมูลอ้างอิงสำหรับโปรโตคอลเซิร์ฟเวอร์การเชื่อมต่อที่คุณเลือก ซึ่งได้แก่ HTTP หรือ XMPP

Firebase Admin SDK วิธีการส่งแบบเดิม

ข้อควรระวัง: เราเลิกใช้งาน API ของ Node.js Admin SDK ที่อธิบายในส่วนนี้ไปเมื่อวันที่ 21 กุมภาพันธ์ 2023 และจะนําฟังก์ชันการทํางานออกในเดือนกุมภาพันธ์ 2024 ใช้ send() แทน sendToDevice() และ sendToDeviceGroup()

Firebase Admin Node.js SDK รองรับวิธีการส่งข้อความ (FCM) ตาม Legacy FCM Server API วิธีการเหล่านี้ยอมรับอาร์กิวเมนต์ที่แตกต่างจากเมธอด send() คุณควรใช้เมธอด send() ทุกครั้งที่เป็นไปได้ และใช้เฉพาะเมธอดที่อธิบายไว้ในหน้านี้เมื่อส่งข้อความไปยังอุปกรณ์แต่ละเครื่องหรือกลุ่มอุปกรณ์

หมายเหตุ: API เหล่านี้ใช้ได้ใน Admin Node.js SDK เท่านั้น

ส่งไปยังอุปกรณ์แต่ละเครื่อง

คุณสามารถส่งโทเค็นการลงทะเบียนไปยังเมธอด sendToDevice() เพื่อส่งข้อความไปยังอุปกรณ์นั้นได้ โดยทำดังนี้

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);
  });

นอกจากนี้ เมธอด sendToDevice() ยังส่งข้อความ multicast (นั่นคือข้อความไปยังอุปกรณ์หลายเครื่อง) ได้โดยส่งอาร์เรย์ของโทเค็นการลงทะเบียนแทนโทเค็นการลงทะเบียนเพียงรายการเดียว ดังนี้

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);
  });

หมายเหตุ: คุณส่งข้อความไปยังอุปกรณ์ได้สูงสุด 1,000 เครื่องในคำขอเดียว หากคุณระบุอาร์เรย์ที่มีโทเค็นการลงทะเบียนมากกว่า 1, 000 รายการ คำขอจะดำเนินการไม่สำเร็จพร้อมmessaging/invalid-recipientข้อผิดพลาด

เมธอด sendToDevice() จะแสดงผลพรอมต์ที่แก้ไขด้วยออบเจ็กต์ MessagingDevicesResponse ที่มีคำตอบจาก FCM ประเภทผลลัพธ์จะมีรูปแบบเดียวกันเมื่อส่งโทเค็นการลงทะเบียนรายการเดียวหรืออาร์เรย์ของโทเค็นการลงทะเบียน

บางกรณี เช่น ข้อผิดพลาดในการตรวจสอบสิทธิ์หรือการจำกัดอัตราทำให้ระบบประมวลผลข้อความทั้งหมดไม่สำเร็จ ในกรณีเหล่านี้ ระบบจะปฏิเสธ Promise ที่ sendToDevice() แสดงผลพร้อมข้อผิดพลาด ดูรายการรหัสข้อผิดพลาดทั้งหมด รวมถึงคำอธิบายและขั้นตอนการแก้ปัญหาได้ที่ข้อผิดพลาด FCM API ของส่วนผู้ดูแลระบบ

ส่งไปยังกลุ่มอุปกรณ์

วิธีการ sendToDeviceGroup() ให้คุณส่งข้อความไปยังกลุ่มอุปกรณ์ได้โดยระบุคีย์การแจ้งเตือนสำหรับกลุ่มอุปกรณ์นั้น

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);
  });

เมธอด sendToDeviceGroup() จะแสดงผลพรอมิสที่แก้ไขด้วยออบเจ็กต์ MessagingDevicesResponse ที่มีคำตอบจาก FCM

บางกรณี เช่น ข้อผิดพลาดในการตรวจสอบสิทธิ์หรือการจำกัดอัตราทำให้ระบบประมวลผลข้อความทั้งหมดไม่สำเร็จ ในกรณีเหล่านี้ ระบบจะปฏิเสธ Promise ที่ sendToDeviceGroup() แสดงผลพร้อมข้อผิดพลาด ดูรายการรหัสข้อผิดพลาดทั้งหมด รวมถึงคำอธิบายและขั้นตอนการแก้ปัญหาได้ที่ข้อผิดพลาด FCM API ของส่วนผู้ดูแลระบบ

การกําหนดเพย์โหลดข้อความ

วิธีการข้างต้นซึ่งอิงตามFCMโปรโตคอลเดิมรับพายโหลดข้อความเป็นอาร์กิวเมนต์ที่ 2 และรองรับทั้งข้อความแจ้งเตือนและข้อความข้อมูล คุณสามารถระบุข้อความประเภทใดประเภทหนึ่งหรือทั้ง 2 ประเภทได้โดยสร้างออบเจ็กต์ที่มีคีย์ data และ / หรือ notification ตัวอย่างเช่น วิธีกําหนดเพย์โหลดข้อความประเภทต่างๆ มีดังนี้

ข้อความแจ้งเตือน

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.'
  }
};

ข้อความข้อมูล

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

ข้อความแบบรวม

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'
  }
};

เพย์โหลดข้อความการแจ้งเตือนจะมีชุดย่อยของพร็อพเพอร์ตี้ที่ถูกต้องซึ่งกําหนดไว้ล่วงหน้า และแตกต่างกันเล็กน้อยโดยขึ้นอยู่กับระบบปฏิบัติการบนอุปกรณ์เคลื่อนที่ที่คุณกําหนดเป้าหมาย ดูรายการทั้งหมดได้ในเอกสารอ้างอิงสำหรับ NotificationMessagePayload

เพย์โหลดข้อความข้อมูลประกอบด้วยคู่คีย์-ค่าที่กำหนดเองที่มีข้อจำกัดบางอย่าง ซึ่งรวมถึงข้อกำหนดที่ว่าค่าทั้งหมดต้องเป็นสตริง ดูรายการข้อจำกัดทั้งหมดได้ในเอกสารอ้างอิงสำหรับ DataMessagePayload

การกําหนดตัวเลือกข้อความ

วิธีการข้างต้นซึ่งอิงตามFCMโปรโตคอลเดิมรับอาร์กิวเมนต์ที่ 3 ที่ไม่บังคับซึ่งระบุตัวเลือกบางอย่างสำหรับข้อความ ตัวอย่างเช่น ตัวอย่างต่อไปนี้จะส่งข้อความที่มีลําดับความสําคัญสูงไปยังอุปกรณ์ที่หมดอายุหลังผ่านไป 24 ชั่วโมง

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);
  });

ดูรายการตัวเลือกทั้งหมดที่พร้อมใช้งานในเอกสารอ้างอิงสำหรับ MessagingOptions