运行策略

运行策略控制应用中 IM 功能的行为和上限，如消息的撤回时限、同一用户可以同时登录的设备数、是否只能给好友发消息、令牌的有效期、消息和文件的保留天数、上传文件的大小上限，以及聊天室、离线推送和音视频通话的设置。

策略分两层：

• 租户策略：在菜单“租户策略”中设置，是租户下全部应用的默认值。创建租户时取下文表格中的默认值；
• 应用策略：在应用详情的“应用策略”中设置，可以为单个应用覆盖其中任意一项。没有覆盖的项沿用租户策略，之后修改租户策略时随之变化。

“应用策略”页面的“当前值”是这个应用实际生效的值，旁边的标签说明它的来源：“应用覆盖”表示应用单独设置了这一项，“继承租户”表示沿用租户策略。点击“恢复继承”可以取消应用的单独设置，改回沿用租户策略。

测试和生产用不同的设置

例如测试应用需要更长的撤回时限便于调试，只在测试应用的“应用策略”中修改即可，生产应用不受影响。

修改策略

在策略表格的“修改”一列中修改需要的项，已修改的项旁边显示“已修改”，然后点击下方的“保存修改”；点击“放弃”撤销尚未保存的修改。一次保存中有任何一项不合法时，全部修改都不会保存。

如果保存时提示“数据已被其他人修改，请刷新后重试”，说明在你打开页面之后有人修改过策略，请刷新页面后重新修改。

谁可以修改

策略	可以修改的角色
租户策略	owner、admin。developer 只能查看
应用策略中的消息、附件和群文件的保留天数，删除用户时擦除消息，三种令牌的有效期	owner、admin
应用策略中的其他项	全部成员

保留天数、删除用户时擦除消息和令牌有效期会删除数据或影响令牌的安全性，所以在应用策略中也只有 owner 和 admin 能修改（包括“恢复继承”）。

修改后任何一个应用实际生效的消息、附件或群文件的保留天数变小时，保存前还要重新验证身份：保留天数变小后，超出保留期的数据随即被删除，不能恢复。群文件保留天数由 0（不过期）改为任何正数也算变小。修改租户策略时，单独设置了这项保留天数的应用不受影响，不会因此要求重新验证。

生效时间

保存后立即生效，多台服务器之间最迟约 30 秒同步完成：

• 服务端执行的规则（如撤回时限、群人数上限、好友校验）对之后的请求生效；
• 在线的客户端立即收到新的运行配置，其他客户端在下次登录或连接时获得新值；
• 调短 User Token 或续期令牌的有效期，对已登录的设备同样生效：已签发的 User Token 按新的有效期判断是否过期，客户端续期即可；
• App Token 的有效期只影响之后换取的 App Token，已签发的不变；
• 调小同时登录的设备数，已登录的设备不会被踢下线，新的上限在之后有设备登录时执行；
• 关闭在线状态或缩小可见范围后，不再允许的在线状态订阅随即被取消；
• 调短消息、附件或群文件的保留天数后，超出保留期的消息和文件随即开始删除。附件和群文件的保留期从上传时算起，按当前的保留天数计算，所以调长保留天数对尚未删除的文件同样生效；
• 调小文件的大小上限、关闭客户端上传群文件、开启只接受本服务的地址，都只影响之后的上传和请求，已有的文件、消息和头像不受影响；
• 调低聊天室的人数上限不会移出已经在聊天室里的用户，只是新用户不能再进入；
• 关闭音视频通话后，进行中的通话不受影响，可以正常完成；振铃时间和群通话人数上限在发起或邀请时确定，修改后只影响之后的来电和通话。

策略项

下面按主题列出全部策略项。“控制台中的名称”是策略页面上显示的名称；为 “—” 的项目前不在控制台的策略页面中显示，取默认值，需要修改请联系我们。“默认值”是租户策略的初始值。

群人数上限、每人可加入的群数、消息保留天数和开启音视频通话这四项，同时受应用套餐的额度限制，实际按策略和套餐中较严格的一个执行：策略设得比套餐宽时按套餐执行，策略页面中显示的仍是策略本身的值。客户端的运行配置中是实际执行的值。

登录与令牌有效期

字段	控制台中的名称	说明	默认值	取值范围
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

聊天室

聊天室的规则见聊天室管理。

字段	控制台中的名称	说明	默认值	取值范围
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	群通话人数上限（含发起人）	群通话同时在通话中的人数上限，含发起人	16	3 到 32
rtc_call_record_enabled	通话结束后在会话中写入通话记录	通话结束后是否在单聊或群聊的会话中写入一条通话记录	true	true、false

举报

字段	控制台中的名称	说明	默认值	取值范围
report_enabled	—	是否允许用户在客户端举报消息、用户、群和聊天室。关闭后客户端举报返回 403 permission_denied，details.reason 为 report_disabled；你的服务端代用户举报不受影响	true	true、false

独立频道开关

独立频道也需要 rtc_enabled 与套餐音视频权限；此外平台须启用频道全局能力和应用灰度。群通话人数、振铃和通话记录策略不控制独立频道。灰度关闭只阻止新建、新加入和票据签发，已有会话仍可续凭据；rtc_enabled 关闭、应用只读或套餐不允许时不能续发。详见RTC 频道管理。