Runtime policies

Runtime policies control how IM features behave in an app and their limits, such as the recall time limit, how many devices one user can be signed in on, whether users can only message friends, token lifetimes, how long messages and files are kept, the upload size limit, and settings for chat rooms, offline push and audio/video calls.

Each app has its own app policies, set under "App policies" in app details. New apps use system defaults, and changes only affect that app. The plan gives the app its resource limits, and at runtime the stricter of the app policy and the plan limit applies.

The "App policies" page shows both the policy value and the value in effect. A policy value can stay higher than the plan limit, and is limited by the plan at runtime; after a plan upgrade, the original policy value still applies.

Different settings for test and production

For example, if a test app needs a longer recall time limit for debugging, change it only in the test app's "App policies", and the production app isn't affected.

Changing policies

Change the items you need in the "Change" column of the policy table; changed items are marked "Changed". Then click "Save changes" below, or "Discard" to undo unsaved changes. If any item in a save is invalid, nothing is saved.

If saving says "The data was changed by someone else, refresh and try again", someone changed the policies after you opened the page; refresh and make your changes again.

Who can change them

Policy	Roles that can change it
Retention days for messages, attachments and group files, erasing messages when deleting users, and the three token lifetimes	owner, admin
Everything else in app policies	All members

Retention days, erasing messages on user deletion and token lifetimes delete data or affect token security, so only owner and admin can change them.

If a change to app policies shortens the effective retention days for messages, attachments or group files, you must also verify your identity again before saving: once retention is shorter, data beyond it is deleted immediately and can't be recovered. Changing group file retention from 0 (never expire) to any positive number also counts as shortening.

When changes take effect

Changes take effect as soon as they're saved, synced across servers within about 30 seconds at most:

• Rules enforced on the server (such as the recall time limit, group size limit and friend checks) apply to later requests.
• Online clients receive the new runtime config immediately; other clients get the new values the next time they sign in or connect.
• Shortening the User Token or refresh token lifetime also applies to signed-in devices: issued User Tokens are checked against the new lifetime, and clients just renew.
• The App Token lifetime only affects App Tokens obtained afterward; ones already issued don't change.
• Lowering the number of devices signed in at once doesn't kick signed-in devices offline; the new limit applies the next time a device signs in.
• After turning presence off or narrowing who can see it, presence subscriptions no longer allowed are cancelled immediately.
• After shortening retention for messages, attachments or group files, messages and files beyond it start being deleted immediately. Attachment and group file retention counts from upload using the current retention days, so lengthening retention also applies to files not yet deleted.
• Lowering file size limits, stopping clients from uploading group files, and only accepting this service's addresses only affect later uploads and requests; existing files, messages and avatars aren't affected.
• Lowering a chat room's member limit doesn't remove users already in it; new users just can't enter.
• After turning audio/video calls off, calls in progress aren't affected and can finish normally; ring time and group call size are fixed when a call is started or someone is invited, so changes only affect later calls.

Policy items

All policy items are listed below by topic. "Name in the console" is what the policy page shows; items marked "—" aren't shown on the console's policy page for now and use the default, so contact us to change them. "Default" is the system's initial value for new apps.

Members per group, groups per user and message retention days are also limited by the app's plan, and the stricter value applies. Before the switch-over, audio/video is also limited by the plan's switch; under the new model it checks the app's positive minutes balance instead, and the app policy rtc_enabled must still be on. Admission also checks status, concurrency and the media service; see Audio/video billing.

Sign-in and token lifetimes

Field	Name in the console	Description	Default	Range
user_token_ttl_seconds	User Token lifetime (0 for never expires)	Lifetime of the User Token clients get when signing in, in seconds. With 0, User Tokens and sign-ins never expire	86400 (1 day)	0, or 300 to 31536000 (1 year)
user_refresh_ttl_seconds	Refresh token lifetime	Lifetime of the refresh token clients use to renew the User Token, in seconds. If a device's sign-in isn't renewed within the longer of the User Token and refresh token lifetimes after its last renewal, it must sign in again	604800 (7 days)	3600 to 31536000
app_token_ttl_seconds	App Token lifetime	Lifetime of the App Token servers get, in seconds	604800 (7 days)	300 to 31536000

Multi-device sign-in

Field	Name in the console	Description	Default	Range
max_online_devices_per_user	Devices online per user	The most devices one user can be signed in on, counted by sign-ins, including devices signed in but not currently connected	4	1 to 20
device_overflow_policy	When exceeded	When signed-in devices exceed the limit: kick_oldest (sign out the oldest device) lets the new device sign in and the oldest go offline; reject_new (refuse the new sign-in) refuses the new device	kick_oldest	kick_oldest, reject_new
device_limits_by_platform	—	Separate device limits per platform, such as {"mobile": 1, "desktop": 1} for at most one phone and one computer. Groups are mobile (iOS, Android, HarmonyOS), desktop (Windows, macOS, Linux), web, mini_program and other, each limited to 1 to 20, handled by device_overflow_policy when exceeded; groups not listed are only limited by the total. null means no per-platform limit	null	Object; see the description

Messages

Field	Name in the console	Description	Default	Range
recall_window_seconds	Recall time limit	How long senders can recall their own messages, in seconds; 0 means senders can't recall. The group owner recalling any message, group admins recalling regular members' messages, and server recalls aren't limited by it. It applies to chat room messages too, where the owner recalling anyone's messages and admins recalling regular users' messages aren't limited either	120 (2 minutes)	0 to 604800 (7 days)
max_message_body_bytes	Message size limit	The size limit for a message's type, content (body), extension fields (ext), mentions and quote together, in bytes, counted as JSON	5120 (5 KB)	1024 to 32768 (32 KB)
single_read_ack_enabled	One-to-one read receipts	Whether one-to-one read receipts are on	true	true, false
group_read_ack_enabled	Group read receipts	Whether group read receipts are on	false	true, false
message_reaction_enabled	Reactions	Whether reactions on messages are allowed	false	true, false
max_reactions_per_message	—	The most kinds of reactions per message	20	1 to 50
max_pinned_messages_per_conversation	Pinned messages per conversation	The most pinned messages per conversation	20	1 to 100
max_recipients_per_message	—	The most recipients per server batch send of one-to-one messages	600	1 to 1000

Offline messages

How much each conversation returns when a client reconnects and catches up on messages from while it was offline. Earlier messages are fetched as history when the user scrolls back, so nothing is lost.

Field	Name in the console	Description	Default	Range
offline_message_retention_days	—	Catch up on messages from at most this many days	7	1 to 30
offline_single_message_limit	—	The most messages caught up per one-to-one conversation	500	1 to 10000
offline_group_message_limit	—	The most messages caught up per group conversation	200	1 to 10000

Retention and deleting users

Field	Name in the console	Description	Default	Range
message_retention_days	Message retention days	How many days history is kept; older messages are deleted and can't be queried by clients or servers. Can't exceed the plan's message retention days	90	1 to 3650
erase_messages_on_user_delete	Erase a user's messages when deleting them	When deleting an IM user, whether to clear the content of every message they sent and delete the message attachments and group files they uploaded. The messages themselves stay in conversations, shown as deleted	false	true, false

Shortening retention deletes messages

After lowering message_retention_days, messages beyond the new retention are deleted immediately and can't be recovered, even if you raise it again later. For chat records you need to keep long term, export messages with the server API before lowering it. Changing it needs identity verification.

Erasing messages when deleting users

With erase_messages_on_user_delete on, deleting a user clears the content of every message they sent in all one-to-one and group chats and deletes the message attachments and group files they uploaded, so the other side and other group members can't see them either, and they can't be recovered. Only turn it on for compliance requirements (such as having to delete what a user said when they close their account). With it off, their attachments are deleted according to attachment retention and group files stay in the group.

Files

Images, voice, video and files in messages (message attachments), group files and avatars can all be uploaded to this service; see Files overview. These policy items control file size, how long files are kept, and which addresses clients can use.

Field	Name in the console	Description	Default	Range
attachment_retention_days	Attachment retention days	How many days message attachments are kept, counted from upload. When they expire the files are deleted while the messages stay, and clients are told the file has expired when downloading. Attachments uploaded but never sent are deleted after this too	30	1 to 3650
max_upload_bytes	Size limit for attachments and group files	The size limit for one message attachment or group file, in bytes. Images also have a fixed 20 MB limit and voice 5 MB, and the smaller applies. Avatars are always within 5 MB, unaffected by this item	104857600 (100 MB)	1048576 to 2147483648 (1 MB to 2 GB)
group_file_enabled	Allow clients to upload group files	When off, group members can't upload group files from the client; servers and the console still can, and existing group files can still be viewed and downloaded	true	true, false
group_file_retention_days	Group file retention days (0 for never expires)	How many days group files are kept, counted from upload, after which they're deleted. 0 means never expire, kept until deleted or the group is dissolved	0	0 to 3650
media_url_only	Only accept this service's file and avatar addresses	When on, addresses in message attachments sent by clients (url, thumbnail_url) must be this service's file addresses, and user and group avatars set by clients must be avatar addresses uploaded to this app; https addresses on hosts in media_allowed_hosts are also allowed. Otherwise the request returns 400 invalid_argument with details.reason url_not_allowed. Addresses written by servers and the console aren't checked	false	true, false
media_allowed_hosts	Allowed external hosts	Extra host names allowed when media_url_only is on, such as your own CDN. Enter host names only, without https://, paths or ports, such as cdn.example.com; *.example.com matches any one-level subdomain of example.com but not example.com itself. Saved lowercase with duplicates removed. null or an empty array allows no external hosts	null	Up to 20 host names

• With media_url_only off (the default), message attachments and avatars can be any http or https address. Content at arbitrary addresses can be swapped at any time, and senders can see from their own server's access logs who viewed an image or avatar and when. Once your clients all upload to this service, we recommend turning media_url_only on.
• Clearing "Allowed external hosts" in "App policies" means the app allows no external hosts; once saved, the app uses the empty list.

Shortening retention deletes files

After lowering attachment_retention_days or group_file_retention_days (including changing group file retention from 0 to a positive number), attachments and group files already expired under the new days are deleted immediately and can't be recovered, even if you raise it again later. Changing them needs identity verification, and only owner and admin can.

Friends and blocklist

Field	Name in the console	Description	Default	Range
friend_check_enabled	Only message friends one-to-one	When on, clients can only send one-to-one messages to friends. It only limits clients; servers sending as a user aren't affected, and group chat isn't affected	false	true, false
friend_limit	Friend limit	The most friends per user	3000	1 to 100000
user_blacklist_enabled	Blocklist blocks messages	Whether the blocklist is enforced: when on, blocked users can't send the other person one-to-one messages or add them as friends. When off, blocklist data is kept but not enforced, and clients can no longer add people to it; servers and the console still manage blocklists as usual	true	true, false
default_friend_add_mode	Default way to add friends	How others can add a user who hasn't set it themselves: need_confirm (needs approval) means they become friends once the user agrees; allow_any (anyone) needs no approval; deny_any (nobody) accepts no friend requests	need_confirm	need_confirm, allow_any, deny_any

For users' own friend settings, see Friend add mode.

Groups

Field	Name in the console	Description	Default	Range
max_group_members	Group member limit	The most members per group, including the owner, not exceeding the plan quota. Servers can set a smaller limit for a single group	500	2 to 5000
max_groups_per_user	Groups per user	The most groups each user can join, including groups they own, not exceeding the plan quota	500	1 to 5000
client_group_create_enabled	Allow clients to create groups	When off, clients can't create groups; only servers or the console can	true	true, false
default_group_invite_mode	Default way of being added to groups	How users who haven't set it themselves are added when invited: allow_any (join directly); need_confirm (needs their approval)	allow_any	allow_any, need_confirm
group_invite_friends_only	Only invite friends to groups	When on, clients can only invite their own friends to groups (including initial members when creating a group). Servers adding members and users requesting to join aren't affected	false	true, false
group_invite_cooldown_enabled	24-hour cooldown after leaving or declining	When on, users who left a group or declined an invitation can't be invited to the same group again for 24 hours; when off they can be invited again right away, still subject to their approval or admin review as before. The cooldown after a declined join request isn't affected by this switch	false	true, false

Chat rooms

For chat room rules, see Chat room management.

Field	Name in the console	Description	Default	Range
max_chatroom_members	—	The most people in a chat room at once. Chat rooms can also set their own limit, and the smaller applies; the owner and admins aren't subject to the member limit	100000	10 to 500000
chatroom_msg_per_second	—	The most normal and low-priority messages each chat room accepts per second; beyond it, normal messages return 429 rate_limited and low-priority messages are dropped. High-priority messages have a separate limit of 20 per chat room per second; see Message priority and delivery	40	1 to 200
max_chatroom_message_bytes	—	The size limit for a chat room message's type, content (body) and extension fields (ext) together, in bytes, counted as JSON	2048 (2 KB)	256 to 8192 (8 KB)
chatroom_history_size	—	How many recent messages each chat room keeps, only normal and high priority, for at most 24 hours. 0 keeps none	50	0 to 200
chatroom_member_notify_limit	—	In chat rooms with at most this many online, other online members are notified when members enter and leave; larger chat rooms don't push entry and exit notifications. 0 pushes none	100	0 to 1000
client_chatroom_create_enabled	—	When on, users can create chat rooms from the client; when off, only servers or the console can	false	true, false

Presence

Field	Name in the console	Description	Default	Range
presence_enabled	Presence	Whether clients can query and subscribe to other users' presence. Servers querying presence aren't affected	false	true, false
presence_scope	Who can see presence	Whose presence clients can see: friends only friends'; all (everyone) anyone's in the app, which suits support, communities and the like	friends	friends, all
presence_last_seen_visible	Show last seen time	Whether clients can see when other users were last online. When off, they only see whether someone is online; servers aren't affected	true	true, false

Offline push

For offline push rules, see Offline push; push credentials and notification templates are set in Push settings.

Field	Name in the console	Description	Default	Range
push_default_preview	—	The notification preview mode when the user hasn't chosen: full shows the sender and content, sender_only only the sender, none neither	full	full, sender_only, none
push_default_language	—	The notification language when the device hasn't registered a language, or there's no template for its language	zh-CN	A BCP 47 language tag such as zh-CN or en, up to 16 characters
push_badge_enabled	—	Whether pushes carry the app badge. When off, the app handles the badge itself	true	true, false
push_notice_enabled	—	Whether to push friend and group notices, such as friend requests, group invitations and being removed from a group	true	true, false
push_mention_all_breaks_mute	—	When a user set a group's Do Not Disturb to push only when mentioned (mention_only), whether mentioning everyone also pushes	true	true, false

Audio/video

For audio/video call rules, see Audio/video calls.

Field	Name in the console	Description	Default	Range
rtc_enabled	Turn on audio/video calls	Whether the app's audio/video is open. Under the new model the app's audio/video balance must also be positive; before the switch-over, the plan's switch also applies. When off, new calls, answering, joining and inviting are refused	false	true, false
rtc_ring_timeout_seconds	Ring time	How long incoming calls ring, in seconds, the same for one-to-one and group calls	60	20 to 120
max_group_call_participants	Group call size (including the caller)	The most people in a group call at once, including the caller; 0 means no limit and the plan decides, otherwise the smaller of this and the plan applies	0	0 or at least 3
rtc_call_record_enabled	Write a call record to the conversation after calls	Whether to write a call record message to the one-to-one or group conversation when a call ends	true	true, false

Reports

Field	Name in the console	Description	Default	Range
report_enabled	—	Whether users can report messages, users, groups and chat rooms from the client. When off, client reports return 403 permission_denied with details.reason report_disabled; your server reporting on a user's behalf isn't affected	true	true, false

Standalone channel switches

Standalone channels also need rtc_enabled on, the current billing model's admission conditions met, and both the platform's global channel switch and the app's channel switch to allow them. The group call size, ring time and call record policies don't affect channels. Turning the channel switch off only blocks creating channels, new joins and issuing tickets; when existing sessions renew credentials they still need the app status, policies and media admission conditions, and old tokens can't get around that. See RTC channel management.