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

Thận trọng: Tính năng gửi tin nhắn (bao gồm cả tin nhắn ngược dòng) bằng API cũ FCM XMPP và HTTP đã ngừng hoạt động kể từ ngày 20 tháng 6 năm 2023 và sẽ bị xoá kể từ tháng 6 năm 2024. Nếu đang sử dụng API gửi FCM cũ, bạn nên di chuyển sang API HTTP phiên bản 1 hoặc cân nhắc sử dụng SDK quản trị để tạo yêu cầu gửi.

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

Các ứng dụng sử dụng API HTTP cũ của FCM nên cân nhắc việc di 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à hướng dẫn di chuyển.

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

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

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

Cú pháp thông báo hạ nguồn

Phần này cung cấp cú pháp để gửi thông báo hạ nguồn và diễn giải phản hồi HTTP từ Firebase Cloud Messaging.

Thông báo HTTP hạ nguồn (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 điệp JSON HTTP.

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	Mô tả
Mục tiêu
to	Chuỗi tùy chọn	Tham số này chỉ định người nhận thư. Giá trị này có thể là mã thông báo đăng ký của 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	Không bắt buộc, mảng chuỗi	Tham số này chỉ định người nhận của một thông báo phát đa hướng. Đây là một tin nhắn được gửi đến nhiều mã thông báo đăng ký. Giá trị này phải là một mảng gồm các mã thông báo đăng ký để gửi thông báo truyền tin nhiều điểm. Mảng phải chứa tối thiểu 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 sử dụng tham số to. Bạn chỉ được phép sử dụng định dạng JSON HTTP cho thông điệp truyền nhiều địa chỉ.
condition	Không bắt buộc, chuỗi	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 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 tin nhắn chủ đề.
notification_key Không dùng nữa	Không bắt buộc, chuỗi	Thông số này không còn đượ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 tin nhắn đến nhiều thiết bị, hãy xem tài liệu dành cho nền tảng của bạn.
Lựa chọn
collapse_key	Không bắt buộc, chuỗi	Tham số này xác định một nhóm thông báo (ví dụ: có collapse_key: "Updates Available") có thể được thu gọn để chỉ thông báo cuối cùng được gửi khi có thể tiếp tục phân phối. Điều này nhằm tránh gửi quá nhiều thông báo giống nhau khi thiết bị kết nối lại mạng hoặc hoạt động trở lại. Xin lưu ý rằng chúng tôi không thể đảm bảo thứ tự gửi thư. Lưu ý: Tại mỗi thời điểm, bạn chỉ được phép sử dụng tối đa 4 khoá thu gọn khác nhau. Điều này có nghĩa là FCM có thể đồng thời lưu trữ 4 thông báo khác nhau cho mỗi ứng dụng khách. Nếu bạn vượt quá số lượng này, thì không có gì đảm bảo FCM sẽ giữ lại 4 khoá thu gọn nào.
priority	Không bắt buộc, chuỗi	Đặt mức độ ưu tiên của thông báo. Các giá trị hợp lệ là "normal" (bình thường) và "high". Trên các nền tảng của Apple, các mức 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 sẽ được gửi với mức độ ưu tiên cao và thông báo dữ liệu sẽ được gửi với mức độ ưu tiên bình thường. Mức độ ưu tiên thông thường tối ưu hoá mức tiêu thụ pin của ứng dụng khách và bạn nên sử dụng mức độ ưu tiên này trừ phi cần phân phối ngay lập tức. Đố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 với độ trễ không xác định. Khi một tin nhắn được gửi với mức độ ưu tiên cao, tin nhắn đó sẽ được gửi ngay lập tức và ứng dụng có thể hiển thị thông báo.
content_available	Giá trị boolean	Trên các nền tảng của Apple, hãy sử 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à được đặt thành true, một ứng dụng khách không hoạt động sẽ được đánh thức và tin nhắn sẽ được gửi qua APN dưới dạng thông báo im lặng chứ không phải thông qua FCM. Xin lưu ý rằng thông báo không âm thanh trong APN không được đảm bảo sẽ được phân phố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 ứng dụng, v.v. Trên Android, theo mặc định, thông báo dữ liệu sẽ đánh thức ứng dụng. Trên Chrome, 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 sử dụng trường này để biểu thị mutable-content trong tải trọng APNs. Khi một thông báo được gửi và được đặt thành true, bạn có thể sửa đổi nội dung của thông báo trước khi thông báo đó hiển thị bằng cách sử dụng tiện ích ứng dụng Dịch vụ thông báo. Thông số này sẽ bị bỏ qua đối với Android và web.
time_to_live	Không bắt buộc, số	Thông số này chỉ định khoảng thời gian (tính bằng giây) mà thông báo sẽ được lưu trữ trong bộ nhớ FCM nếu thiết bị không có kết nối mạng. Thời gian tối đa để phát trực tiếp được hỗ trợ 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 lượng tồn tại của thông báo.
restricted_package_ name (chỉ dành cho Android)	Chuỗi tùy chọn	Thông 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 được đặt thành true, tham số này cho phép nhà phát triển kiểm thử một yêu cầu mà không cần thực sự gửi thông báo. Giá trị mặc định là false.
Trọng tải
data	Đối tượng (không bắt buộc)	Thông số này chỉ định các cặp khoá-giá trị tuỳ chỉnh trong tải trọng của 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ì thông báo đó đạ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 biểu thị dưới dạng từ điển giá trị khoá trong AppDelegate application:didReceiveRemoteNotification:. Trên Android, thao tác này sẽ dẫn đến một ý định bổ sung có tên score với giá trị chuỗi 3x1. Khoá không được là từ dành riêng ("from", "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). Bạn nên sử dụng giá trị thuộc loại chuỗi. Bạn phải chuyển đổi các giá trị trong đối tượng hoặc các kiểu dữ liệu khác không phải chuỗi (ví dụ: số nguyên hoặc boolean) thành chuỗi.
notification	Không bắt buộc, đối tượng	Thông số này chỉ định các cặp khoá-giá trị được xác định trước, hiển thị với người dùng của tải trọng thông báo. Hãy xem phần Hỗ trợ gói dữ liệu thông báo để biết thông tin chi tiết. Để biết thêm thông tin về các tuỳ chọn tin nhắn thông báo và dữ liệu, hãy xem Loại thông báo. Nếu bạn cung cấp tải trọng thông báo hoặc đặt tuỳ chọn content_available thành true cho một thông báo gửi đến thiết bị của Apple, thì thông báo đó sẽ được gửi qua APN, nếu không thì sẽ được gửi qua FCM.

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

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

Bảng 2a. iOS – khoá cho thông báo

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

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

Thông số	Cách sử dụng	Mô tả
title	Không bắt buộc, chuỗi	Tiêu đề của thông báo.
body	Không bắt buộc, chuỗi	Văn bản nội dung của thông báo.
android_channel_id	Không bắt buộc, chuỗi	Mã 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 trước khi nhận được bất kỳ thông báo nào có mã nhận dạng kênh này. Nếu bạn không gửi mã kênh này trong yêu cầu hoặc nếu ứng dụng chưa tạo mã kênh được cung cấp, FCM sẽ sử dụng mã kênh được chỉ định trong tệp kê khai ứng dụng.
icon	Không bắt buộc, chuỗi	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	Không bắt buộc, chuỗi	Â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	Không bắt buộc, chuỗi	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 không được chỉ định, mỗi yêu cầu sẽ tạo 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	Không bắt buộc, chuỗi	Màu biểu tượng của thông báo, được thể hiện ở định dạng #rrggbb.
click_action	Không bắt buộc, chuỗi	Hành động liên quan đến lượt nhấp của người dùng vào thông báo. Nếu được chỉ định, một hoạt động có bộ lọc ý định phù hợp sẽ khởi chạy khi người dùng nhấp vào thông báo.
body_loc_key	Chuỗi tùy chọn	Khoá cho chuỗi nội dung trong tài nguyên chuỗi của ứng dụng dùng để bản địa hoá văn bản nội dung theo nội dung 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	Không bắt buộc, mảng JSON dưới dạng chuỗi	Giá trị chuỗi biến sẽ được sử dụng thay cho chỉ định định dạng trong body_loc_key để bản địa hoá văn bản nội dung theo ngôn ngữ 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	Không bắt buộc, chuỗi	Khoá cho chuỗi tiêu đề trong tài nguyên chuỗi của ứng dụng để sử dụng nhằm bản địa hoá văn bản tiêu đề theo ngôn ngữ 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	Không bắt buộc, mảng JSON dưới dạng chuỗi	Giá trị chuỗi biến sẽ được sử dụng thay cho chỉ định định dạng trong title_loc_key để sử dụng nhằm bản địa hoá văn bản tiêu đề theo ngôn ngữ 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) – khoá cho thông báo

Thông số	Cách sử dụng	Mô tả
title	Không bắt buộc, chuỗi	Tiêu đề của thông báo.
body	Không bắt buộc, chuỗi	Văn bản nội dung của thông báo.
icon	Không bắt buộc, chuỗi	URL sử dụng cho biểu tượng của thông báo.
click_action	Chuỗi tùy chọn	Hành động liên kết với một lượt nhấp của người dùng vào thông báo. Tất cả giá trị URL đều phải sử dụng giao thức HTTPS.

Thông báo HTTP hạ nguồn (Văn bản thuần tuý)

Bảng sau đây liệt kê cú pháp cho các mục tiêu, tuỳ chọn và tải trọng trong thông điệp HTTP hạ nguồn 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 điệp HTTP văn bản thuần tuý ở hạ nguồn.

Thông số	Cách sử dụng	Mô tả
Mục tiêu
registration_id	Bắt buộc, chuỗi	Tham số này chỉ định những ứng dụng khách (mã thông báo đăng ký) nhận được thông báo. Chỉ cho phép gửi tin nhắn đa hướng (gửi đến nhiều mã thông báo đăng ký) bằng định dạng JSON HTTP.
Lựa chọn
collapse_key	Chuỗi tùy chọn	Hãy xem bảng 1 để biết thông tin chi tiết.
time_to_live	Số (không bắt buộc)	Hãy xem bảng 1 để biết thông tin chi tiết.
restricted_package_name	Chuỗi tùy chọn	Hãy xem bảng 1 để biết thông tin chi tiết.
dry_run	Không bắt buộc, boolean	Hãy xem bảng 1 để biết thông tin chi tiết.
Trọng tải
data.<key>	Chuỗi tùy chọn	Thông số này chỉ định các cặp khoá-giá trị của tải trọng của thông báo. Không có giới hạn về số lượng tham số khoá-giá trị, nhưng tổng kích thước thông báo có giới hạn là 4096 byte. Ví dụ: trong Android, "data.score"."3x1" sẽ dẫn đến một ý định bổ sung có tên là score kèm theo giá trị chuỗi là 3x1. Khoá không được là một từ dành riêng ("from", "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).

Giải thích phản hồi tin nhắn ở hạ nguồn

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

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

Phản hồi	Mô tả
200	Thư đã được xử lý thành công. Phần 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 của phần nội dung này sẽ phụ thuộc vào việc yêu cầu là JSON hay văn bản thuần tuý. Hãy 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 trong khi dự kiến là số). Lý do chính xác dẫn đến lỗi được mô tả trong phản hồi và bạn cần giải quyết vấn đề 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, tuân thủ mọi tiêu đề Retry-After 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 tiếp theo (JSON).

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

Thông số	Cách sử dụng	Mô tả
multicast_id	Bắt buộc, số	Mã nhận dạng (số) duy nhất xác định thông báo truyền tin nhiều điểm.
success	Bắt buộc, số	Số lượng thư được xử lý mà không gặp lỗi.
failure	Bắt buộc, số	Số lượng thư không thể xử lý.
results	Bắt buộc, mảng đối tượng	Mảng các đối tượng đại diện cho trạng thái của các thông báo đã xử lý. Các đối tượng được liệt kê theo thứ tự giống như 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 mã đó đượ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ông báo 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 theo chủ đề (JSON).

Thông số	Cách sử dụng	Mô tả
message_id	Không bắt buộc, số	Mã nhận dạng của tin nhắn chủ đề khi FCM nhận được yêu cầu và sẽ cố gắng gửi đến tất cả thiết bị đã đăng ký.
error	Không bắt buộc, chuỗi	Lỗi xảy ra 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	Mô tả
id	Bắt buộc, chuỗi	Tham số này chỉ định mã thông báo duy nhất FCM đã được xử lý thành công.
registration_id	Chuỗi tùy chọn	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	Mô tả
Error	Bắt buộc, chuỗi	Thông số này chỉ định giá trị lỗi trong khi xử lý thông báo cho người nhận. Hãy xem bảng 9 để biết thông tin chi tiết.

Mã phản hồi lỗi thông báo hạ nguồn

Bảng sau đây liệt kê các mã phản hồi lỗi cho thông báo truyền xuống.

Bảng 9. Mã phản hồi lỗi thông báo hạ nguồn.

Lỗi	Mã HTTP	Việc nên làm
Thiếu mã thông báo đăng ký	200 + error:MissingRegistration	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 hoặc registration_ids ở định dạng JSON).
Mã thông báo đăng ký không hợp lệ	200 + lỗi:InvalidRegistration	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 ký tự khác.
Thiết bị chưa đăng ký	200 + error:NotRegistered	Mã thông báo đăng ký hiện có có thể hết hiệu lực trong một số trường hợp, trong đó có: 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 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 APNs đã hết hạn đối với thiết bị iOS). Nếu ứng dụng khách được cập nhật nhưng phiên bản mới chưa được định cấu hình để nhận thông báo. Đối với tất cả các trường hợp nà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ã thông báo này để gửi thông báo.
Tên gói không hợp lệ	200 + error:InvalidPackageName	Đảm bảo thông báo được gửi đến một mã thông báo đăng ký có tên gói khớp với giá trị được truyền trong yêu cầu.
Lỗi xác thực	401	Không xác thực được tài khoản người gửi dùng để gửi thư. Có thể là do các nguyên nhân sau: Thiếu tiêu đề uỷ quyền hoặc có cú pháp không hợp lệ trong yêu cầu HTTP. Dự án Firebase mà khoá máy chủ được chỉ định thuộc về 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 có trong danh sách IP của khoá máy chủ. Kiểm tra để đảm bảo 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. Hãy 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 sử dụng khoá máy chủ cũ, bạn nên nâng cấp lên khoá mới không có quy định hạn chế về IP. Xem phần Di chuyển khoá máy chủ cũ.
Người gửi không khớp	200 + error:MismatchSenderId	Mã đăng ký được liên kết với một nhóm người gửi nhất định. Khi đăng ký FCM, ứng dụng khách phải chỉ định những người gửi được phép gửi thông báo. Bạn nên sử dụng một trong những mã nhận dạng người gửi đó khi gửi thông báo đến ứng dụng khách. Nếu bạn chuyển sang một trình 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 rằng thông báo JSON được định dạng đúng cách và chứa các trường hợp hợp lệ (ví dụ: đảm bảo truyền đúng loại dữ liệu).
Thông số không hợp lệ	400 + lỗi:InvalidParameters	Kiểm tra để đảm bảo các thông số được cung cấp có tên và loại chính xác.
Tin nhắn quá lớn	200 + error:MessageTooBig	Kiểm tra để đảm bảo tổng kích thước của dữ liệu tải trọng có trong một thông báo không vượt quá giới hạn FCM: 4096 byte đối với hầu hết thông báo hoặc 2048 byte đối với thông báo đến chủ đề. Dữ liệu 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 hay 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 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 + error:InvalidTtl	Kiểm tra để đảm bảo giá trị được sử dụng trong time_to_live là một số nguyên biểu thị thời lượng tính bằng giây trong khoảng từ 0 đến 2.419.200 (4 tuần).
Hết giờ	Lỗi 5xx hoặc 200 trở lên: Không có	Máy chủ không thể xử lý yêu cầu kịp thời. Thử gửi lại yêu cầu đó, nhưng bạn phải: Tuân thủ tiêu đề Retry-After nếu tiêu đề này có trong phản hồi từ Máy chủ kết nối FCM. Triển khai thuật toán thời gian đợi luỹ thừa trong cơ chế thử lại của bạn. (ví dụ: nếu bạn đợi một giây trước khi thử lại lần đầu tiên, hãy đợi ít nhất hai giây trước lần thử lại tiếp theo, sau đó là 4 giây, v.v.). Nếu bạn đang gửi nhiều tin nhắn, hãy trì hoãn từng tin nhắn một cách độc lập bằng một số lượng ngẫu nhiên bổ sung để tránh đưa ra một yêu cầu mới cho tất cả tin nhắn cùng một lúc. Những người gửi gây ra vấn đề có nguy cơ bị đưa vào danh sách đen.
Lỗi máy chủ nội bộ	500 hoặc 200 + error: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 cùng một yêu cầu theo các yêu cầu nêu trong phần "Hết thời gian chờ" (xem hàng trên). Nếu lỗi này vẫn tiếp diễn, vui lòng liên hệ với nhóm hỗ trợ Firebase.
Đã vượt quá giới hạn tần suất gửi tin nhắn trên thiết bị	200 + lỗi: DeviceMessageRate Đã vượt quá	Tốc độ tin nhắn gửi đến một thiết bị cụ thể quá cao. Nếu một ứng dụng của Apple gửi thông báo ở tốc độ vượt quá giới hạn của APN, thì ứng dụng đó có thể nhận được thông báo lỗi nà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 luỹ thừa để thử gửi lại.
Đã vượt quá tốc độ gửi tin nhắn về chủ đề	Lỗi 200 trở lên: TopicsMessageRate Vượt quá	Tỷ lệ tin nhắn gửi đến người đăng ký một chủ đề cụ thể quá cao. Giảm số lượng thư được gửi cho chủ đề này và sử dụng thời gian đợi luỹ thừa để thử gửi lại.
Thông tin xác thực APN không hợp lệ	Lỗi 200 trở lên: InvalidApnsCredential	Không thể gửi thông báo nhắm đến 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 xác thực phát triển và phát hành công khai.

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ị, 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	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ừ thao tác 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à bắt buộc đối với 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ả các mã thông báo đăng ký hiện có khỏi một nhóm thiết bị, thì FCM sẽ xoá nhóm thiết bị đó.