Giao thức HTTP của Giải pháp gửi thông báo qua đám mây của Firebase

Lưu ý: Tính năng gửi tin nhắn (bao gồm cả tin nhắn ngược dòng) bằng API XMPP và HTTP cũ của FCM đã ngừng hoạt động từ ngày 20 tháng 6 năm 2023 và sẽ bị loại bỏ vào tháng 6 năm 2024. Nếu đang sử dụng API gửi FCM cũ, bạn nên chuyển sang API HTTP v1 hoặc cân nhắc sử dụng SDK dành cho quản trị viên để tạo yêu cầu gửi.

Tài liệu này cung cấp thông tin tham khảo về cú pháp HTTP dùng để truyền thông báo từ máy chủ ứng dụng sang các ứng dụng khách thông qua Giải pháp gửi thông báo qua đám mây của Firebase.

Các ứng dụng sử dụng API HTTP cũ của FCM nên cân nhắc chuyển sang API HTTP v1. Hãy xem hướng dẫn di chuyển để biết thêm thông tin về các ưu điểm của API phiên bản 1 và xem hướng dẫn di chuyển.

Khi bạn sử dụng giao thức HTTP cũ, máy chủ ứng dụng của bạn phải chuyển tất cả các yêu cầu HTTP đến điểm cuối sau:

https://fcm.googleapis.com/fcm/send

Các thông số và tuỳ chọn có sẵn thuộc các danh mục lớn sau đây:

• Cú pháp thông báo xuôi dòng
• Mã phản hồi lỗi thông báo truyền xuống

Cú pháp thông báo xuôi dòng

Phần này cung cấp cú pháp để gửi thông báo về sau và diễn giải phản hồi HTTP qua Giải pháp gửi thông báo qua đám mây của Firebase.

Thông báo HTTP xuôi dòng (JSON)

Bảng sau đây liệt kê các mục tiêu, tuỳ chọn và tải trọng cho thông báo HTTP JSON.

Bảng 1. Mục tiêu, tuỳ chọn và tải trọng cho thông báo HTTP xuôi dòng (JSON).

Thông số	Cách sử dụng	Nội dung mô tả
Mục tiêu
to	Chuỗi, không bắt buộc	Tham số này chỉ định người nhận tin nhắn. Giá trị này có thể là mã thông báo đăng ký của một thiết bị, khoá thông báo của nhóm thiết bị hoặc một chủ đề duy nhất (có tiền tố là /topics/). Để gửi đến nhiều chủ đề, hãy sử dụng tham số condition.
registration_ids	Mảng chuỗi, không bắt buộc	Tham số này chỉ định người nhận của một tin nhắn phát đa hướng, một tin nhắn được gửi đến nhiều mã thông báo đăng ký. Giá trị phải là một mảng mã thông báo đăng ký để gửi thông báo phát đa hướng. Mảng đó phải chứa ít nhất 1 và tối đa 1.000 mã thông báo đăng ký. Để gửi thông báo đến một thiết bị, hãy dùng tham số to. Tin nhắn truyền đa hướng chỉ được phép ở định dạng HTTP JSON.
condition	Chuỗi, không bắt buộc	Tham số này chỉ định một biểu thức logic của các điều kiện xác định mục tiêu của thông báo. Điều kiện được hỗ trợ: Chủ đề, có định dạng là ""yourTopic" trong các chủ đề". Giá trị này không phân biệt chữ hoa chữ thường. Các toán tử được hỗ trợ: &&, ||. Hỗ trợ tối đa 2 toán tử cho mỗi thông báo chủ đề.
notification_key Không dùng nữa	Chuỗi, không bắt buộc	Tham số này không được dùng nữa. Thay vào đó, hãy sử dụng to để chỉ định người nhận thư. Để biết thêm thông tin về cách gửi thông báo đến nhiều thiết bị, hãy xem tài liệu dành cho nền tảng của bạn.
Tuỳ chọn
collapse_key	Chuỗi, không bắt buộc	Tham số này xác định một nhóm tin nhắn (ví dụ: bằng collapse_key: "Updates Available") có thể thu gọn, để chỉ tin nhắn gần nhất được gửi khi có thể tiếp tục quá trình gửi. Điều này nhằm tránh gửi quá nhiều thư giống nhau khi thiết bị có kết nối mạng trở lại hoặc hoạt động. Xin lưu ý rằng chúng tôi không đảm bảo về thứ tự gửi tin nhắn. Lưu ý: Chỉ được phép có tối đa 4 khoá thu gọn khác nhau tại một thời điểm bất kỳ. Điều này có nghĩa là FCM có thể lưu trữ đồng thời 4 thông báo khác nhau cho mỗi ứng dụng. Nếu bạn vượt quá con số này, chúng tôi không đảm bảo sẽ giữ lại 4 phím thu gọn FCM nào.
priority	Chuỗi, không bắt buộc	Đặt mức độ ưu tiên của thông báo. Các giá trị hợp lệ là "bình thường" và "cao". Trên các nền tảng của Apple, các giá trị này tương ứng với mức độ ưu tiên 5 và 10 của APN. Theo mặc định, thông báo thông báo được gửi với mức độ ưu tiên cao và thông báo dữ liệu được gửi với mức độ ưu tiên bình thường. Chế độ ưu tiên bình thường sẽ tối ưu hoá mức tiêu thụ pin của ứng dụng khách và bạn nên dùng chế độ này trừ phi cần phân phối ngay. Đối với các thông báo có mức độ ưu tiên bình thường, ứng dụng có thể nhận được thông báo có độ trễ không xác định. Khi một thông báo được gửi ở mức độ ưu tiên cao, thông báo đó sẽ được gửi ngay lập tức và ứng dụng có thể hiển thị thông báo.
content_available	Không bắt buộc, boolean	Trên các nền tảng của Apple, hãy dùng trường này để biểu thị content-available trong tải trọng APN. Khi một thông báo hoặc tin nhắn được gửi và thiết bị này được thiết lập thành true, thì một ứng dụng khách không hoạt động sẽ được đánh thức và tin nhắn đó được gửi qua APN dưới dạng thông báo im lặng chứ không phải qua FCM. Lưu ý rằng thông báo im lặng trong APN không được đảm bảo sẽ được gửi và có thể phụ thuộc vào các yếu tố như người dùng bật Chế độ tiết kiệm pin, buộc thoát khỏi ứng dụng, v.v. Trên Android, thông báo dữ liệu sẽ đánh thức ứng dụng theo mặc định. Trên Chrome, tính năng này hiện không được hỗ trợ.
mutable_content	Không bắt buộc, boolean JSON	Trên các nền tảng của Apple, hãy dùng trường này để biểu thị mutable-content trong tải trọng APN. Khi một thông báo được gửi và giá trị này được đặt thành true, bạn có thể sửa đổi nội dung của thông báo trước khi hiển thị bằng cách sử dụng tiện ích ứng dụng Dịch vụ thông báo. Tham số này sẽ bị bỏ qua đối với Android và web.
time_to_live	Không bắt buộc, số	Tham số này chỉ định khoảng thời gian (tính bằng giây) mà tin nhắn cần được lưu trong bộ nhớ FCM nếu thiết bị không có kết nối mạng. Hỗ trợ thời gian tồn tại tối đa là 4 tuần và giá trị mặc định là 4 tuần. Để biết thêm thông tin, hãy xem phần Đặt thời gian tồn tại của một thông báo.
restricted_package_ name (chỉ dành cho Android)	Chuỗi, không bắt buộc	Tham số này chỉ định tên gói của ứng dụng mà mã thông báo đăng ký phải khớp để nhận được thông báo.
dry_run	Không bắt buộc, boolean	Khi đặt tham số này thành true, nhà phát triển có thể kiểm thử yêu cầu mà không thực sự gửi thông báo. Giá trị mặc định là false.
Tải trọng
data	Đối tượng, không bắt buộc	Tham số này chỉ định các cặp khoá-giá trị tuỳ chỉnh cho tải trọng thông báo. Ví dụ: với data:{"score":"3x1"}: Trên các nền tảng của Apple, nếu thông báo được gửi qua APN, thì tin nhắn đó sẽ đại diện cho các trường dữ liệu tuỳ chỉnh. Nếu được gửi qua FCM, dữ liệu này sẽ được thể hiện dưới dạng từ điển giá trị khoá trong AppDelegate application:didReceiveRemoteNotification:. Trên Android, điều này sẽ dẫn đến một ý định có tên bổ sung là score bằng giá trị chuỗi 3x1. Khoá này không được là một từ dành riêng ("từ", "message_type" hoặc bất kỳ từ nào bắt đầu bằng "google" hoặc "gcm"). Đừng sử dụng bất cứ từ nào được xác định trong bảng này (chẳng hạn như collapse_key). Bạn nên sử dụng các giá trị trong loại chuỗi. Bạn phải chuyển đổi các giá trị trong các đối tượng hoặc các kiểu dữ liệu không phải chuỗi khác (ví dụ: số nguyên hoặc boolean) thành chuỗi.
notification	Đối tượng, không bắt buộc	Tham số này chỉ định các cặp khoá-giá trị được xác định trước mà người dùng thấy được của tải trọng thông báo. Hãy xem phần Hỗ trợ tải trọng thông báo để biết thêm chi tiết. Để biết thêm thông tin về các tuỳ chọn thông báo và thông báo dữ liệu, hãy xem phần Các loại thông báo. Nếu tải trọng thông báo được cung cấp hoặc lựa chọn content_available được đặt thành true cho một tin nhắn tới thiết bị Apple, thì tin nhắn sẽ được gửi qua APN, nếu không thì tin nhắn sẽ được gửi qua FCM.

Hỗ trợ tải trọng thông báo

Bảng sau đây liệt kê các khoá được xác định trước hiện có để tạo thông báo cho iOS và Android.

Bảng 2a. iOS – phím cho thông báo

Thông số	Cách sử dụng	Nội dung mô tả
title	Chuỗi, không bắt buộc	Tiêu đề của thông báo. Trường này không hiển thị trên điện thoại và máy tính bảng.
body	Chuỗi, không bắt buộc	Văn bản nội dung của thông báo.
sound	Chuỗi, không bắt buộc	Âm thanh sẽ phát khi thiết bị nhận được thông báo. Chuỗi chỉ định các tệp âm thanh trong gói chính của ứng dụng khách hoặc trong thư mục Library/Sounds của vùng chứa dữ liệu của ứng dụng. Hãy xem Thư viện nhà phát triển iOS để biết thêm thông tin.
badge	Chuỗi, không bắt buộc	Giá trị của huy hiệu trên biểu tượng ứng dụng trên màn hình chính. Nếu bạn không chỉ định thì huy hiệu sẽ không thay đổi. Nếu bạn đặt thành 0, huy hiệu này sẽ bị xoá.
click_action	Chuỗi, không bắt buộc	Hành động liên quan đến việc người dùng nhấp vào thông báo. Tương ứng với category trong tải trọng APN.
subtitle	Chuỗi, không bắt buộc	Tiêu đề phụ của thông báo.
body_loc_key	Chuỗi, không bắt buộc	Khoá cho chuỗi nội dung trong tài nguyên chuỗi của ứng dụng để dùng cho việc bản địa hoá văn bản nội dung theo thông tin bản địa hoá hiện tại của người dùng. Tương ứng với loc-key trong tải trọng APN. Xem các bài viết Tham khảo về khoá tải trọng và Bản địa hoá nội dung thông báo từ xa để biết thêm thông tin.
body_loc_args	Mảng JSON dưới dạng chuỗi (không bắt buộc)	Các giá trị chuỗi biến được dùng thay cho thông số định dạng trong body_loc_key nhằm sử dụng nhằm bản địa hoá văn bản nội dung theo thông tin bản địa hoá hiện tại của người dùng. Tương ứng với loc-args trong tải trọng APN. Xem các bài viết Tham khảo về khoá tải trọng và Bản địa hoá nội dung thông báo từ xa để biết thêm thông tin.
title_loc_key	Chuỗi, không bắt buộc	Khoá cho chuỗi tiêu đề trong tài nguyên chuỗi của ứng dụng để dùng cho việc bản địa hoá văn bản tiêu đề theo thông tin bản địa hoá hiện tại của người dùng. Tương ứng với title-loc-key trong tải trọng APN. Xem các bài viết Tham khảo về khoá tải trọng và Bản địa hoá nội dung thông báo từ xa để biết thêm thông tin.
title_loc_args	Mảng JSON dưới dạng chuỗi (không bắt buộc)	Các giá trị chuỗi của biến được dùng thay cho thông số định dạng trong title_loc_key nhằm dùng cho việc bản địa hoá văn bản tiêu đề theo thông tin bản địa hoá hiện tại của người dùng. Tương ứng với title-loc-args trong tải trọng APN. Xem các bài viết Tham khảo về khoá tải trọng và Bản địa hoá nội dung thông báo từ xa để biết thêm thông tin.

Bảng 2b. Android – phím cho tin nhắn thông báo

Thông số	Cách sử dụng	Nội dung mô tả
title	Chuỗi, không bắt buộc	Tiêu đề của thông báo.
body	Chuỗi, không bắt buộc	Văn bản nội dung của thông báo.
android_channel_id	Chuỗi, không bắt buộc	mã nhận dạng kênh của thông báo (mới có trong Android O). Ứng dụng phải tạo một kênh có mã nhận dạng kênh này thì mới nhận được thông báo có mã nhận dạng kênh này. Nếu bạn không gửi mã nhận dạng kênh này trong yêu cầu hoặc nếu mã nhận dạng kênh mà ứng dụng cung cấp chưa được ứng dụng tạo, thì FCM sẽ sử dụng mã nhận dạng kênh được chỉ định trong tệp kê khai ứng dụng.
icon	Chuỗi, không bắt buộc	Biểu tượng của thông báo. Đặt biểu tượng thông báo thành myicon cho tài nguyên có thể vẽ myicon. Nếu bạn không gửi khoá này trong yêu cầu, FCM sẽ hiển thị biểu tượng trình chạy được chỉ định trong tệp kê khai ứng dụng.
sound	Chuỗi, không bắt buộc	Âm thanh sẽ phát khi thiết bị nhận được thông báo. Hỗ trợ "default" hoặc tên tệp của tài nguyên âm thanh đi kèm trong ứng dụng. Các tệp âm thanh phải nằm trong /res/raw/.
tag	Chuỗi, không bắt buộc	Giá trị nhận dạng dùng để thay thế các thông báo hiện có trong ngăn thông báo. Nếu bạn không chỉ định, mỗi yêu cầu sẽ tạo ra một thông báo mới. Nếu được chỉ định và một thông báo có cùng thẻ đang hiển thị, thì thông báo mới sẽ thay thế thông báo hiện có trong ngăn thông báo.
color	Chuỗi, không bắt buộc	Màu biểu tượng của thông báo, được thể hiện ở định dạng #rrggbb.
click_action	Chuỗi, không bắt buộc	Hành động liên quan đến việc người dùng nhấp vào thông báo. Nếu được chỉ định, một hoạt động có bộ lọc ý định trùng khớp sẽ được chạy khi người dùng nhấp vào thông báo.
body_loc_key	Chuỗi, không bắt buộc	Khoá cho chuỗi nội dung trong tài nguyên chuỗi của ứng dụng để dùng cho việc bản địa hoá văn bản nội dung theo thông tin bản địa hoá hiện tại của người dùng. Hãy xem phần Tài nguyên chuỗi để biết thêm thông tin.
body_loc_args	Mảng JSON dưới dạng chuỗi (không bắt buộc)	Các giá trị chuỗi biến được dùng thay cho thông số định dạng trong body_loc_key nhằm sử dụng nhằm bản địa hoá văn bản nội dung theo thông tin bản địa hoá hiện tại của người dùng. Hãy xem phần Định dạng và định kiểu để biết thêm thông tin.
title_loc_key	Chuỗi, không bắt buộc	Khoá cho chuỗi tiêu đề trong tài nguyên chuỗi của ứng dụng để dùng cho việc bản địa hoá văn bản tiêu đề theo thông tin bản địa hoá hiện tại của người dùng. Hãy xem phần Tài nguyên chuỗi để biết thêm thông tin.
title_loc_args	Mảng JSON dưới dạng chuỗi (không bắt buộc)	Các giá trị chuỗi của biến được dùng thay cho thông số định dạng trong title_loc_key nhằm dùng cho việc bản địa hoá văn bản tiêu đề theo thông tin bản địa hoá hiện tại của người dùng. Hãy xem phần Định dạng và định kiểu để biết thêm thông tin.

Bảng 2c. Web (JavaScript) – phím cho nội dung thông báo

Thông số	Cách sử dụng	Nội dung mô tả
title	Chuỗi, không bắt buộc	Tiêu đề của thông báo.
body	Chuỗi, không bắt buộc	Văn bản nội dung của thông báo.
icon	Chuỗi, không bắt buộc	URL để sử dụng cho biểu tượng của thông báo.
click_action	Chuỗi, không bắt buộc	Hành động liên quan đến việc người dùng nhấp vào thông báo. Đối với tất cả các giá trị URL, HTTPS là bắt buộc.

Thông báo HTTP xuôi dòng (Văn bản thuần tuý)

Bảng sau đây liệt kê cú pháp cho mục tiêu, tuỳ chọn và tải trọng trong các thông điệp HTTP truyền xuống dưới dạng văn bản thuần tuý.

Bảng 3. Mục tiêu, tuỳ chọn và tải trọng cho thông báo HTTP văn bản thuần tuý hạ nguồn.

Thông số	Cách sử dụng	Nội dung mô tả
Mục tiêu
registration_id	Bắt buộc, chuỗi	Tham số này chỉ định các ứng dụng khách (mã thông báo đăng ký) nhận thông báo. Chỉ cho phép gửi tin nhắn đa hướng (gửi tới nhiều mã thông báo đăng ký) ở định dạng HTTP JSON.
Tuỳ chọn
collapse_key	Chuỗi, không bắt buộc	Xem bảng 1 để biết thông tin chi tiết.
time_to_live	Không bắt buộc, số	Xem bảng 1 để biết thông tin chi tiết.
restricted_package_name	Chuỗi, không bắt buộc	Xem bảng 1 để biết thông tin chi tiết.
dry_run	Không bắt buộc, boolean	Xem bảng 1 để biết thông tin chi tiết.
Tải trọng
data.<key>	Chuỗi, không bắt buộc	Tham số này chỉ định các cặp khoá-giá trị của tải trọng thông báo. Không có giới hạn về số lượng thông số khoá-giá trị, nhưng có tổng kích thước thông báo là 4.096 byte. Ví dụ: trong Android, "data.score"."3x1" sẽ dẫn đến một ý định có tên bổ sung là score với giá trị chuỗi 3x1. Khoá này không được là một từ dành riêng ("từ", "message_type" hoặc bất kỳ từ nào bắt đầu bằng "google" hoặc "gcm"). Không sử dụng bất kỳ từ nào được xác định trong bảng này (chẳng hạn như collapse_key).

Diễn giải phản hồi thông báo xuôi dòng

Máy chủ ứng dụng sẽ đánh giá cả tiêu đề phản hồi tin nhắn và nội dung để diễn giải phản hồi tin nhắn được gửi từ FCM. Bảng sau đây mô tả các phản hồi có thể có.

Bảng 4. Tiêu đề phản hồi thông báo HTTP xuôi dòng.

Phản hồi	Nội dung mô tả
200	Đã xử lý thư thành công. Nội dung phản hồi sẽ chứa thêm thông tin chi tiết về trạng thái thông báo, nhưng định dạng sẽ phụ thuộc vào việc yêu cầu là JSON hay văn bản thuần tuý. Xem bảng 5 để biết thêm thông tin chi tiết.
400	Chỉ áp dụng cho các yêu cầu JSON. Cho biết không thể phân tích cú pháp yêu cầu dưới dạng JSON hoặc yêu cầu chứa các trường không hợp lệ (ví dụ: truyền một chuỗi với một số được mong đợi). Lý do không thành công được mô tả chính xác trong phản hồi và vấn đề cần được giải quyết trước khi có thể thử lại yêu cầu.
401	Đã xảy ra lỗi khi xác thực tài khoản người gửi.
5xx	Các lỗi trong phạm vi 500-599 (chẳng hạn như 500 hoặc 503) cho biết đã xảy ra lỗi nội bộ trong phần phụ trợ FCM khi cố gắng xử lý yêu cầu hoặc máy chủ tạm thời không hoạt động (ví dụ: do hết thời gian chờ). Người gửi phải thử lại sau, tôn trọng bất kỳ tiêu đề Retry-After nào có trong phản hồi. Máy chủ ứng dụng phải triển khai thời gian đợi luỹ thừa.

Bảng sau đây liệt kê các trường trong nội dung phản hồi thông báo xuôi dòng (JSON).

Bảng 5. Nội dung phản hồi thông báo HTTP xuôi dòng (JSON).

Thông số	Cách sử dụng	Nội dung mô tả
multicast_id	Bắt buộc, số	Mã nhận dạng duy nhất (số) xác định thông điệp phát đa hướng.
success	Bắt buộc, số	Số thư đã được xử lý mà không có lỗi.
failure	Bắt buộc, số	Số thư không thể xử lý được.
results	Mảng đối tượng bắt buộc	Mảng gồm các đối tượng biểu thị trạng thái của các thông báo đã được xử lý. Các đối tượng được liệt kê theo cùng thứ tự với yêu cầu (tức là đối với mỗi mã đăng ký trong yêu cầu, kết quả của yêu cầu đó sẽ được liệt kê trong cùng một chỉ mục trong phản hồi). message_id: Chuỗi chỉ định một mã nhận dạng duy nhất cho mỗi thông báo được xử lý thành công. error: Chuỗi chỉ định lỗi xảy ra khi xử lý thư cho người nhận. Bạn có thể xem các giá trị có thể có trong bảng 9.

Bảng 6. Nội dung phản hồi HTTP của thông báo chủ đề (JSON).

Thông số	Cách sử dụng	Nội dung mô tả
message_id	Không bắt buộc, số	Mã nhận dạng tin nhắn chủ đề khi FCM nhận được yêu cầu thành công và sẽ tìm cách gửi tới tất cả các thiết bị đã đăng ký.
error	Chuỗi, không bắt buộc	Đã xảy ra lỗi khi xử lý thư. Bạn có thể xem các giá trị có thể có trong bảng 9.

Bảng 7. Phản hồi thành công cho nội dung phản hồi thông báo HTTP xuôi dòng (Văn bản thuần tuý).

Thông số	Cách sử dụng	Nội dung mô tả
id	Bắt buộc, chuỗi	Tham số này chỉ định mã nhận dạng tin nhắn duy nhất FCM được xử lý thành công.
registration_id	Chuỗi, không bắt buộc	Tham số này chỉ định mã thông báo đăng ký cho ứng dụng khách mà thông báo đã được xử lý và gửi đến.

Bảng 8. Phản hồi lỗi cho nội dung phản hồi thông báo HTTP xuôi dòng (Văn bản thuần tuý).

Thông số	Cách sử dụng	Nội dung mô tả
Error	Bắt buộc, chuỗi	Tham số này chỉ định giá trị lỗi trong khi xử lý thư cho người nhận. Xem bảng 9 để biết thông tin chi tiết.

Mã phản hồi lỗi thông báo xuôi dòng

Bảng sau đây liệt kê các mã phản hồi lỗi cho các thông báo tiếp theo.

Bảng 9. Mã phản hồi lỗi thông báo xuôi dòng.

Lỗi	Mã HTTP	Việc nên làm
Thiếu mã thông báo đăng ký	200 + lỗi:MissingSubscription	Kiểm tra để đảm bảo yêu cầu chứa mã thông báo đăng ký (trong registration_id trong tin nhắn văn bản thuần tuý hoặc trong trường to hay registration_ids trong JSON).
Mã thông báo đăng ký không hợp lệ	200 + lỗi:Đăng ký không hợp lệ	Kiểm tra định dạng của mã thông báo đăng ký mà bạn truyền đến máy chủ. Hãy đảm bảo mã này khớp với mã thông báo đăng ký mà ứng dụng khách nhận được khi đăng ký bằng Thông báo Firebase. Đừng cắt bớt hoặc thêm các ký tự bổ sung.
Thiết bị chưa đăng ký	200 + lỗi:Chưa đăng ký	Mã thông báo đăng ký hiện có có thể không còn hiệu lực trong một số trường hợp, bao gồm: Nếu ứng dụng khách huỷ đăng ký với FCM. Nếu ứng dụng khách tự động bị huỷ đăng ký, điều này có thể xảy ra nếu người dùng gỡ cài đặt ứng dụng. Ví dụ: trên iOS, nếu Dịch vụ phản hồi của APN báo cáo mã thông báo APN là không hợp lệ. Nếu mã thông báo đăng ký hết hạn (ví dụ: Google có thể quyết định làm mới mã thông báo đăng ký hoặc mã thông báo APN đã hết hạn đối với các thiết bị iOS). Nếu ứng dụng khách đã được cập nhật nhưng phiên bản mới không được định cấu hình để nhận thông báo. Đối với tất cả những trường hợp như vậy, hãy xoá mã thông báo đăng ký này khỏi máy chủ ứng dụng và ngừng sử dụng mã đó để gửi thông báo.
Tên gói không hợp lệ	200 + error:InvalidPackageName	Đảm bảo thư được gửi tới một mã thông báo đăng ký có tên gói khớp với giá trị được chuyển trong yêu cầu.
Lỗi xác thực	401	Không thể xác thực tài khoản người gửi dùng để gửi thư. Nguyên nhân có thể là: Tiêu đề uỷ quyền bị thiếu hoặc có cú pháp không hợp lệ trong yêu cầu HTTP. Dự án Firebase chứa khoá máy chủ đã chỉ định không chính xác. Chỉ khoá máy chủ cũ – yêu cầu bắt nguồn từ một máy chủ không thuộc danh sách cho phép trong IP khoá máy chủ. Kiểm tra để đảm bảo rằng mã thông báo bạn đang gửi bên trong tiêu đề Xác thực là khoá máy chủ chính xác được liên kết với dự án của bạn. Xem phần Kiểm tra tính hợp lệ của khoá máy chủ để biết thông tin chi tiết. Nếu đang dùng khoá máy chủ cũ, bạn nên nâng cấp lên một khoá mới không có quy tắc hạn chế về IP. Xem nội dung Di chuyển khoá máy chủ cũ.
Người gửi không khớp	200 + lỗi:MismatchSenderId	Mã thông báo đăng ký được liên kết với một nhóm người gửi nhất định. Khi ứng dụng khách đăng ký FCM, ứng dụng khách phải chỉ định người gửi nào được phép gửi tin nhắn. Bạn nên sử dụng một trong các mã nhận dạng người gửi đó khi gửi tin nhắn đến ứng dụng khách. Nếu chuyển sang một người gửi khác, mã thông báo đăng ký hiện có sẽ không hoạt động.
JSON không hợp lệ	400	Kiểm tra để đảm bảo thông báo JSON được định dạng đúng cách và chứa các trường hợp lệ (ví dụ: đảm bảo truyền đúng loại dữ liệu).
Tham số Không hợp lệ	400 + lỗi:InvalidParameters	Kiểm tra để đảm bảo rằng các thông số đã cung cấp có tên và loại đúng.
Thư quá lớn	200 + lỗi:MessageTooBig	Kiểm tra để đảm bảo rằng tổng kích thước của dữ liệu tải trọng có trong một tin nhắn không vượt quá giới hạn FCM: 4096 byte đối với hầu hết tin nhắn hoặc 2048 byte đối với tin nhắn đến chủ đề. Phương thức này bao gồm cả khoá và giá trị.
Khoá dữ liệu không hợp lệ	200 + lỗi: InvalidDataKey	Kiểm tra để đảm bảo rằng dữ liệu tải trọng không chứa khoá (chẳng hạn như from hoặc gcm hoặc bất kỳ giá trị nào có tiền tố google) mà FCM sử dụng nội bộ. Xin lưu ý rằng một số từ (chẳng hạn như collapse_key) cũng được FCM sử dụng nhưng được cho phép trong tải trọng. Trong trường hợp này, giá trị tải trọng sẽ bị giá trị FCM ghi đè.
Thời gian tồn tại không hợp lệ	200 + lỗi:InvalidTtl	Kiểm tra để đảm bảo giá trị dùng trong time_to_live là một số nguyên đại diện cho thời lượng tính bằng giây từ 0 đến 2.419.200 (4 tuần).
Lần bị tạm ngừng	5xx hoặc 200 + lỗi:Không có sẵn	Máy chủ không thể xử lý yêu cầu kịp thời. Thử gửi lại cùng một yêu cầu, nhưng bạn phải: Tuân thủ tiêu đề Retry-After nếu tiêu đề đó được đưa vào phản hồi từ Máy chủ kết nối FCM. Triển khai thời gian đợi luỹ thừa trong cơ chế thử lại. (ví dụ: nếu bạn đợi một giây trước lần thử lại đầu tiên, hãy đợi ít nhất 2 giây trước lần thử tiếp theo, sau đó 4 giây, v.v.). Nếu bạn đang gửi nhiều thông báo, hãy trì hoãn từng thông báo một cách độc lập bằng một số tiền ngẫu nhiên bổ sung để tránh gửi một yêu cầu mới cho tất cả các thông báo cùng một lúc. Người gửi gây ra sự cố có nguy cơ bị đưa vào danh sách đen.
Lỗi máy chủ nội bộ	Giá trị 500 hoặc 200 + lỗi:InternalServerError	Máy chủ đã gặp lỗi trong khi cố gắng xử lý yêu cầu. Bạn có thể thử lại yêu cầu tương tự theo các yêu cầu liệt kê trong phần "Thời gian chờ" (xem hàng ở trên). Nếu lỗi vẫn tiếp diễn, vui lòng liên hệ với bộ phận hỗ trợ của Firebase.
Đã vượt quá tốc độ tin nhắn trên thiết bị	200 trở lên: DeviceMessageRate Đã vượt quá	Tốc độ tin nhắn đến một thiết bị cụ thể quá cao. Nếu một ứng dụng của Apple gửi tin nhắn với tốc độ vượt quá giới hạn của APN, ứng dụng đó có thể nhận được thông báo lỗi này Hãy giảm số lượng tin nhắn gửi đến thiết bị này và sử dụng thời gian đợi theo cấp số nhân để thử gửi lại.
Đã vượt quá tốc độ tin nhắn chủ đề	Hơn 200 lỗi: TopicsMessageRate Đã vượt quá	Tỷ lệ tin nhắn đến người đăng ký tới một chủ đề cụ thể quá cao. Hãy giảm số lượng tin nhắn được gửi cho chủ đề này và sử dụng thời gian đợi theo cấp số nhân để thử gửi lại.
Thông tin xác thực APN không hợp lệ	200 + lỗi: InvalidApnsCredential	Không thể gửi một thông báo nhắm đến một thiết bị Apple vì khoá xác thực APN bắt buộc chưa được tải lên hoặc đã hết hạn. Kiểm tra tính hợp lệ của thông tin đăng nhập vào quá trình phát triển và phát hành chính thức.

Quản lý nhóm thiết bị

Bảng sau đây liệt kê các khoá để tạo nhóm thiết bị cũng như cách thêm và xoá thành viên. Để biết thêm thông tin, hãy xem hướng dẫn dành cho nền tảng của bạn, iOS+ hoặc Android.

Bảng 10. Khoá quản lý nhóm thiết bị.

Thông số	Cách sử dụng	Nội dung mô tả
operation	Bắt buộc, chuỗi	Thao tác cần chạy.Các giá trị hợp lệ là create, add và remove.
notification_key_name	Bắt buộc, chuỗi	Tên do người dùng xác định của nhóm thiết bị cần tạo hoặc sửa đổi.
notification_key	Bắt buộc (ngoại trừ toán tử create, chuỗi	Giá trị nhận dạng duy nhất của nhóm thiết bị. Giá trị này được trả về trong phản hồi cho một thao tác create thành công và là giá trị bắt buộc cho tất cả các thao tác tiếp theo trên nhóm thiết bị.
registration_ids	Mảng chuỗi bắt buộc	Mã thông báo thiết bị cần thêm hoặc xoá. Nếu bạn xoá tất cả mã thông báo đăng ký hiện có khỏi một nhóm thiết bị, FCM sẽ xoá nhóm thiết bị đó.