執行策略

執行策略控制應用中 IM 功能的行為和上限，如訊息的撤回時限、同一使用者可以同時登入的裝置數、是否只能給好友發訊息、令牌的有效期、訊息和檔案的保留天數、上傳檔案的大小上限，以及聊天室、離線推送和音視訊通話的設定。

每個應用都有一份獨立的應用策略，在應用詳情的“應用策略”中設定。新應用使用系統預設值，修改後隻影響當前應用。套餐為應用提供資源上限，實際執行值按應用策略和套餐上限中更嚴格的一項執行。

“應用策略”頁面同時顯示策略值和實際生效值。策略值可以保留為高於套餐上限的配置，執行時會按套餐限制；套餐升級後，原來的策略值仍然有效。

測試和生產用不同的設定

例如測試應用需要更長的撤回時限便於除錯，只在測試應用的“應用策略”中修改即可，生產應用不受影響。

修改策略

在策略表格的“修改”一列中修改需要的項，已修改的項旁邊顯示“已修改”，然後點選下方的“儲存修改”；點選“放棄”撤銷尚未儲存的修改。一次儲存中有任何一項不合法時，全部修改都不會儲存。

如果儲存時提示“資料已被其他人修改，請重新整理後重試”，說明在你開啟頁面之後有人修改過策略，請重新整理頁面後重新修改。

誰可以修改

策略	可以修改的角色
應用策略中的訊息、附件和群檔案的保留天數，刪除使用者時擦除訊息，三種令牌的有效期	owner、admin
應用策略中的其他項	全部成員

保留天數、刪除使用者時擦除訊息和令牌有效期會刪除資料或影響令牌的安全性，所以只有 owner 和 admin 能修改。

修改應用策略後，如果訊息、附件或群檔案的實際保留天數變小，儲存前還要重新驗證身份：保留天數變小後，超出保留期的資料隨即被刪除，不能恢復。群檔案保留天數由 0（不過期）改為任何正數也算變小。

生效時間

儲存後立即生效，多臺伺服器之間最遲約 30 秒同步完成：

• 服務端執行的規則（如撤回時限、群人數上限、好友校驗）對之後的請求生效；
• 線上的客戶端立即收到新的執行配置，其他客戶端在下次登入或連線時獲得新值；
• 調短 User Token 或續期令牌的有效期，對已登入的裝置同樣生效：已簽發的 User Token 按新的有效期判斷是否過期，客戶端續期即可；
• App Token 的有效期隻影響之後換取的 App Token，已簽發的不變；
• 調小同時登入的裝置數，已登入的裝置不會被踢下線，新的上限在之後有裝置登入時執行；
• 關閉線上狀態或縮小可見範圍後，不再允許的線上狀態訂閱隨即被取消；
• 調短訊息、附件或群檔案的保留天數後，超出保留期的訊息和檔案隨即開始刪除。附件和群檔案的保留期從上傳時算起，按當前的保留天數計算，所以調長保留天數對尚未刪除的檔案同樣生效；
• 調小檔案的大小上限、關閉客戶端上傳群檔案、開啟只接受本服務的地址，都隻影響之後的上傳和請求，已有的檔案、訊息和頭像不受影響；
• 調低聊天室的人數上限不會移出已經在聊天室裡的使用者，只是新使用者不能再進入；
• 關閉音視訊通話後，進行中的通話不受影響，可以正常完成；振鈴時間和群通話人數上限在發起或邀請時確定，修改後隻影響之後的來電和通話。

策略項

下面按主題列出全部策略項。“控制檯中的名稱”是策略頁面上顯示的名稱；為 “—” 的專案前不在控制檯的策略頁面中顯示，取預設值，需要修改請聯絡我們。“預設值”是新應用的系統初始值。

群人數、每人可加入群數和訊息保留天數同時受應用套餐限制，執行更嚴格的值。音影片在切換前還受套餐開關限制，新模式改為檢查當前應用的正時長餘額，應用策略 rtc_enabled 仍須開啟。實際准入還檢查狀態、併發和媒體服務，見音影片計費。

登入與令牌有效期

欄位	控制檯中的名稱	說明	預設值	取值範圍
user_token_ttl_seconds	User Token 有效期（0 為不過期）	客戶端登入後獲得的 User Token 的有效期，單位為秒。設為 0 時 User Token 和登入都不過期	86400（1 天）	0，或 300 到 31536000（1 年）
user_refresh_ttl_seconds	續期令牌有效期	客戶端用來續期 User Token 的續期令牌的有效期，單位為秒。一臺裝置的登入在最近一次續期之後，經過 User Token 和續期令牌有效期中較長的一個仍沒有續期，就需要重新登入	604800（7 天）	3600 到 31536000
app_token_ttl_seconds	App Token 有效期	服務端換取的 App Token 的有效期，單位為秒	604800（7 天）	300 到 31536000

多端登入

欄位	控制檯中的名稱	說明	預設值	取值範圍
max_online_devices_per_user	每人同時線上的裝置數	同一使用者同時登入的裝置數上限，按登入計算，已登入但當前沒有連線的裝置也計入	4	1 到 20
device_overflow_policy	超出時	登入的裝置數超出上限時：kick_oldest（踢掉最早登入的裝置）讓新裝置登入、最早登入的裝置下線；reject_new（拒絕新登入）拒絕新裝置登入	kick_oldest	kick_oldest、reject_new
device_limits_by_platform	—	按平臺分別限制裝置數，如 {"mobile": 1, "desktop": 1} 表示手機和電腦各最多 1 臺。分組為 mobile（iOS、Android、HarmonyOS）、desktop（Windows、macOS、Linux）、web、mini_program（小程式）、other，每組的上限為 1 到 20，超出時按 device_overflow_policy 處理；沒有列出的分組只受總數限制。為 null 時不按平臺限制	null	物件，見說明

訊息

欄位	控制檯中的名稱	說明	預設值	取值範圍
recall_window_seconds	撤回時限	傳送者撤回自己的訊息的時限，單位為秒；0 表示傳送者不能撤回。群主撤回任何訊息、群管理員撤回普通成員的訊息、服務端撤回都不受這個限制。聊天室訊息同樣適用，聊天室的所有者撤回任何使用者的訊息、管理員撤回普通使用者的訊息也不受這個限制	120（2 分鐘）	0 到 604800（7 天）
max_message_body_bytes	單條訊息體積上限	一條訊息的型別、內容（body）、擴充套件欄位（ext）、@ 提及和引用合計的大小上限，單位為位元組，按 JSON 編碼計算	5120（5 KB）	1024 到 32768（32 KB）
single_read_ack_enabled	單聊已讀回執	是否開啟單聊的已讀回執	true	true、false
group_read_ack_enabled	群聊已讀回執	是否開啟群聊的已讀回執	false	true、false
message_reaction_enabled	表情回應	是否允許對訊息新增表情回應	false	true、false
max_reactions_per_message	—	每條訊息最多的表情回應種類數	20	1 到 50
max_pinned_messages_per_conversation	每個會話的置頂訊息數	每個會話最多置頂的訊息數	20	1 到 100
max_recipients_per_message	—	服務端批次傳送單聊訊息時，一次最多的接收人數	600	1 到 1000

離線訊息

客戶端重新連線後補齊離線期間的訊息時，每個會話最多返回的範圍。更早的訊息在使用者向前翻頁時按歷史訊息拉取，不會丟失。

欄位	控制檯中的名稱	說明	預設值	取值範圍
offline_message_retention_days	—	最多補齊多少天內的訊息	7	1 到 30
offline_single_message_limit	—	單聊每個會話最多補齊的條數	500	1 到 10000
offline_group_message_limit	—	群聊每個會話最多補齊的條數	200	1 到 10000

保留期與刪除使用者

欄位	控制檯中的名稱	說明	預設值	取值範圍
message_retention_days	訊息保留天數	歷史訊息的保留天數，超過的訊息被刪除，客戶端和服務端都不能再查詢。不超過套餐的訊息保留天數	90	1 到 3650
erase_messages_on_user_delete	刪除使用者時擦除他發過的訊息	刪除 IM 使用者時，是否清空他發過的全部訊息的內容，並刪除他上傳的訊息附件和群檔案。訊息本身仍在會話中，顯示為已刪除	false	true、false

調短保留天數會刪除訊息

把 message_retention_days 調小後，超出新保留期的訊息隨即被刪除，不能恢復，即使之後再調大也找不回來。需要長期留存的聊天記錄，請在調小之前用服務端介面匯出訊息。修改前要重新驗證身份。

刪除使用者時擦除訊息

開啟 erase_messages_on_user_delete 後，刪除使用者會清空他在所有單聊和群聊中發過的訊息內容，並刪除他上傳的訊息附件和群檔案，對方和其他群成員也看不到了，不能恢復。只在有合規要求（如使用者登出時必須刪除其發言）時開啟。沒有開啟時，他上傳的附件按附件保留天數刪除，群檔案保留在群中。

檔案

訊息中的圖片、語音、影片和檔案（訊息附件）、群檔案和頭像都可以上傳到本服務，見檔案概述。以下策略項控制這些檔案的大小、保留時間，以及客戶端可以使用哪些地址。

欄位	控制檯中的名稱	說明	預設值	取值範圍
attachment_retention_days	附件保留天數	訊息附件的保留天數，從上傳時算起。到期後檔案被刪除，訊息仍在，客戶端下載時提示檔案已過期。上傳後沒有發出去的附件同樣按這個天數刪除	30	1 到 3650
max_upload_bytes	附件和群檔案的大小上限	單個訊息附件或群檔案的大小上限，單位為位元組。圖片另有 20 MB、語音另有 5 MB 的固定上限，取兩者中較小的一個。頭像固定為 5 MB 以內，不受這一項影響	104857600（100 MB）	1048576 到 2147483648（1 MB 到 2 GB）
group_file_enabled	允許客戶端上傳群檔案	關閉後，群成員不能在客戶端上傳群檔案；服務端和控制檯仍可以上傳，已有的群檔案照常檢視和下載	true	true、false
group_file_retention_days	群檔案保留天數（0 為不過期）	群檔案的保留天數，從上傳時算起，到期後被刪除。0 表示不過期，一直保留到被刪除或群解散	0	0 到 3650
media_url_only	只接受本服務的檔案和頭像地址	開啟後，客戶端傳送的訊息附件中的地址（url、thumbnail_url）只能是本服務的檔案地址，客戶端設定的使用者頭像、群頭像只能是本應用上傳的頭像地址；另外允許 media_allowed_hosts 中主機的 https 地址。不符合時請求返回 400 invalid_argument，details.reason 為 url_not_allowed。服務端和控制檯寫入的地址不檢查	false	true、false
media_allowed_hosts	允許的外部主機	media_url_only 開啟時另外允許的主機名，如你自己的 CDN。只填主機名，不帶 https://、路徑和埠，如 cdn.example.com；*.example.com 匹配 example.com 的任意一級子域名，但不匹配 example.com 本身。儲存時轉為小寫並去掉重複項。為 null 或空陣列時不允許任何外部主機	null	最多 20 個主機名

• 關閉 media_url_only 時（預設），訊息附件和頭像可以是任意 http、https 地址。任意地址的內容可以隨時被替換，傳送者還可以透過自己伺服器的訪問記錄知道誰在什麼時候檢視了圖片或頭像。客戶端都改為上傳到本服務之後，建議開啟 media_url_only；
• 在“應用策略”中把“允許的外部主機”清空，表示這個應用不允許任何外部主機；儲存後這個應用就按空列表執行。

調短保留天數會刪除檔案

調小 attachment_retention_days 或 group_file_retention_days（包括把群檔案保留天數由 0 改為正數）後，按新的天數已經過期的附件和群檔案隨即被刪除，不能恢復，即使之後再調大也找不回來。修改前要重新驗證身份，只有 owner 和 admin 可以修改。

好友與黑名單

欄位	控制檯中的名稱	說明	預設值	取值範圍
friend_check_enabled	只能給好友發單聊訊息	開啟後，客戶端只能給好友發單聊訊息。只限制客戶端，服務端以使用者身份傳送不受影響；群聊不受影響	false	true、false
friend_limit	好友數上限	每個使用者的好友數上限	3000	1 到 100000
user_blacklist_enabled	黑名單攔截訊息	是否按黑名單攔截：開啟時，被拉黑的人不能給對方發單聊訊息、加對方為好友。關閉後黑名單資料保留但不攔截，客戶端也不能再把人加入黑名單；服務端和控制檯照常管理黑名單	true	true、false
default_friend_add_mode	預設加好友方式	使用者沒有自己設定時的加好友方式：need_confirm（需要驗證）對方同意後才成為好友；allow_any（允許任何人）不需要對方同意；deny_any（拒絕任何人）不接受好友申請	need_confirm	need_confirm、allow_any、deny_any

使用者自己的加好友方式見加好友方式。

群組

欄位	控制檯中的名稱	說明	預設值	取值範圍
max_group_members	群人數上限	每個群的人數上限，含群主，不超過套餐的額度。服務端可以為單個群設定更小的上限	500	2 到 5000
max_groups_per_user	每人可加入的群數	每個使用者最多加入的群數，含自己是群主的群，不超過套餐的額度	500	1 到 5000
client_group_create_enabled	允許客戶端建群	關閉後客戶端不能建群，只能由服務端或在控制檯中建群	true	true、false
default_group_invite_mode	被拉進群的預設方式	使用者沒有自己設定時，被邀請進群的方式：allow_any（直接加入）；need_confirm（需要本人同意）	allow_any	allow_any、need_confirm
group_invite_friends_only	只能邀請好友進群	開啟後，客戶端邀請他人進群（包括建群時的初始成員）只能邀請自己的好友。服務端新增成員、使用者申請入群不受影響	false	true、false
group_invite_cooldown_enabled	退群或拒絕邀請後冷卻 24 小時	開啟後，使用者主動退群或拒絕邀請的 24 小時內不能再次被邀請進入同一群；關閉後可立即再次邀請，仍按原有規則執行本人確認或管理員審批。入群申請被拒絕後的冷卻不受此開關影響	false	true、false

聊天室

聊天室的規則見聊天室管理。

欄位	控制檯中的名稱	說明	預設值	取值範圍
max_chatroom_members	—	每個聊天室同時在裡面的人數上限。聊天室還可以單獨設定自己的上限，取兩者中較小的一個；所有者和管理員不受人數上限的限制	100000	10 到 500000
chatroom_msg_per_second	—	每個聊天室每秒最多接受的普通和低優先順序訊息數，超出時普通訊息返回 429 rate_limited，低優先順序的訊息被丟棄。高優先順序的訊息另有每個聊天室每秒 20 條的上限，見訊息的優先順序與下發	40	1 到 200
max_chatroom_message_bytes	—	一條聊天室訊息的型別、內容（body）和擴充套件欄位（ext）合計的大小上限，單位為位元組，按 JSON 編碼計算	2048（2 KB）	256 到 8192（8 KB）
chatroom_history_size	—	每個聊天室儲存的最近的訊息條數，只儲存普通和高優先順序的訊息，最多保留 24 小時。0 表示不儲存	50	0 到 200
chatroom_member_notify_limit	—	線上人數不超過這個值的聊天室，成員進入和離開時其他線上成員會收到通知；人數更多的聊天室不推送進出通知。0 表示都不推送	100	0 到 1000
client_chatroom_create_enabled	—	開啟後使用者可以在客戶端建立聊天室；關閉時只能由服務端或在控制檯中建立	false	true、false

線上狀態

欄位	控制檯中的名稱	說明	預設值	取值範圍
presence_enabled	線上狀態	是否允許客戶端查詢和訂閱其他使用者的線上狀態。服務端查詢線上狀態不受影響	false	true、false
presence_scope	線上狀態可見範圍	客戶端能看到誰的線上狀態：friends（好友）只能看好友的；all（所有人）可以看應用內任何使用者的，適合客服、社群等場景	friends	friends、all
presence_last_seen_visible	顯示最後線上時間	客戶端能否看到其他使用者最近一次離線的時間。關閉後只能看到是否線上；服務端不受影響	true	true、false

離線推送

離線推送的規則見離線推送，推送憑據和通知模板在推送配置中設定。

欄位	控制檯中的名稱	說明	預設值	取值範圍
push_default_preview	—	使用者沒有選擇時通知的預覽方式：full 顯示傳送者和內容，sender_only 只顯示傳送者，none 都不顯示	full	full、sender_only、none
push_default_language	—	裝置沒有登記語言、或登記的語言沒有對應的模板時，通知使用的語言	zh-CN	BCP 47 語言標籤，如 zh-CN、en，最多 16 個字元
push_badge_enabled	—	推送中是否帶 App 角標。關閉後由 App 自行處理角標	true	true、false
push_notice_enabled	—	是否推送好友和群的通知，如收到好友申請、入群邀請、被移出群	true	true、false
push_mention_all_breaks_mute	—	使用者把群的免打擾設為只在 @ 本人時推送（mention_only）時，@ 全體成員是否也推送	true	true、false

音影片

音視訊通話的規則見音視訊通話。

欄位	控制檯中的名稱	說明	預設值	取值範圍
rtc_enabled	開啟音視訊通話	是否開放應用音影片。新模式還需本應用音影片餘額為正；切換前還受套餐開關限制。關閉後拒絕新的發起、接聽、加入和邀請	false	true、false
rtc_ring_timeout_seconds	來電振鈴時間	來電的振鈴時間，單位為秒，一對一和群通話相同	60	20 到 120
max_group_call_participants	群通話人數上限（含發起人）	群通話同時在通話中的人數上限，含發起人；0 表示不限，由套餐決定，填寫時取它和套餐中較小的一個	0	0 或不小於 3
rtc_call_record_enabled	通話結束後在會話中寫入通話記錄	通話結束後是否在單聊或群聊的會話中寫入一條通話記錄	true	true、false

舉報

欄位	控制檯中的名稱	說明	預設值	取值範圍
report_enabled	—	是否允許使用者在客戶端舉報訊息、使用者、群和聊天室。關閉後客戶端舉報返回 403 permission_denied，details.reason 為 report_disabled；你的服務端代使用者舉報不受影響	true	true、false

獨立頻道開關

獨立頻道同樣需要開啟 rtc_enabled、滿足當前計費模式的准入條件，並且平臺的頻道總開關和應用的頻道開關都允許。群通話人數上限、振鈴時間和通話記錄這幾項策略不影響頻道。關閉頻道開關只阻止新建頻道、新加入和簽發票據；已有會話續期憑據時仍要滿足應用狀態、策略和媒體准入條件，不能用舊的令牌繞過。見RTC 頻道管理。