发送短信加急

调用该接口把指定消息加急给目标用户，加急将通过飞书客户端和短信进行通知。了解加急可参见加急功能。

Warning: 注意：短信加急将消耗企业的加急额度（可通过管理后台 > 费用中心 > 权益数据 > 短信/电话加急 查看当前额度），请慎重调用。

前提条件

• 应用需要开启机器人能力 。
• 确保机器人在被加急消息所属会话中。如果是群组，还需要确保群管理中设置了 所有群成员可以加急，或者设置了 仅群主或管理员可以加急 且机器人是管理员。

使用限制

• 只能加急当前机器人自己发送的消息。
• 加急用户的未读加急总数不能超过 200 条。
• 不支持加急批量发送的消息。
• 加急折叠会话内的消息时，仅会在应用内推送提醒通知。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/im/v1/messages/:message_id/urgent_sms
HTTP Method	PATCH
接口频率限制	1000 次/分钟、50 次/秒
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可	im:message.urgent:sms 发送短信加急消息 im:message.urgent:sms_send 发送短信加急消息（历史版本）
字段权限要求	> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头

名称	类型	必填	描述
Authorization	string	是	tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Type	string	是	固定值："application/json; charset=utf-8"

路径参数

名称	类型	描述
message_id	string	待加急的消息 ID。ID 获取方式： - 调用发送消息接口后，从响应结果的 message_id 参数获取。 - 监听接收消息事件，当触发该事件后可以从事件体内获取消息的 message_id。 - 调用获取会话历史消息接口，从响应结果的 message_id 参数获取。 注意：不支持加急批量发送的消息（对应的消息ID 格式为 bm_xxx）。 示例值："om_dc13264520392913993dd051dba21dcf"

查询参数

名称	类型	必填	描述
user_id_type	string	是	用户 ID 类型 示例值：open_id 可选值有： - open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？ 默认值：open_id 当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID

请求体

名称	类型	必填	描述
user_id_list	string\[\]	是	加急的目标用户 ID 列表。ID 类型与查询参数 user_id_type 取值一致，推荐使用 open_id。 注意：需要确保目标用户在加急消息所属的会话内。如果 ID 列表中有用户不在消息所属的会话内，则接口会将这些无效的 ID 返回（响应参数 invalid_user_id_list），只加急有效的用户 ID。如果 ID 列表内的所有 ID 均无效，则会返回 230001 错误码。 数据校验规则：列表长度不能大于 200。 示例值：["ou_6yf8af6bgb9100449565764t3382b168"]

请求体示例

{
    "user_id_list": [
        "ou_6yf8af6bgb9100449565764t3382b168"
    ]
}

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ invalid_user_id_list	string\[\]	无效的用户 ID。当传入的用户 ID 列表内存在部分用户 ID 有效时，将对有效的用户进行加急操作，同时返回无效的用户 ID。当所有的用户 ID 无效时，将返回 230001 错误码。

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "invalid_user_id_list": [
            "ou_6yf8af6bgb9100449565764t3382b168"
        ]
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	230001	Your request contains an invalid request parameter.	参数错误，请根据接口返回的错误信息并参考接口文档检查输入参数是否正确。
400	230002	The bot can not be outside the group.	机器人不在对应群组中。你需要将应用机器人添加到接收消息的群组中。如何添加机器人参考机器人使用指南。
400	230006	Bot ability is not activated.	应用未启用机器人能力。启用方式参见如何启用机器人能力。
400	230012	Bot is NOT the sender of the message.	机器人不是消息的发送者，无法加急该消息。应用机器人只能操作自己发送的消息。
400	230013	Bot has NO availability to this user.	目标用户（以用户的 user_id/open_id/union_id/email 指定的消息接收者）或单聊用户（以群聊的 chat_id 指定的消息接收者，但 chat_id 对应的群聊类型为单聊 p2p）不在应用机器人的可用范围内，或者是在应用的禁用范围内。 注意：如果目标用户已离职，也会报错 230013。 解决方案： 1. 登录开发者后台，找到并进入指定应用详情页。 2. 在左侧导航栏进入 应用发布 > 版本管理与发布 页面，点击 创建版本。 3. 在 版本详情 页面，找到 可用范围 区域，点击 编辑。 4. 在弹出的对话框内，配置应用的可用范围，将用户添加至可用范围内。 5. 在页面底部点击 保存，并发布应用使配置生效。 6. （可选）如果以上配置完成后仍报错，则需要联系企业管理员登录管理后台，在 工作台 > 应用管理 中进入指定应用详情页，在 应用可用范围 内查看该用户是否被设置为了 禁用成员。 具体操作参见配置应用可用范围。
400	230023	The user has too many unread urgent messages.	用户未读的加急消息过多。加急用户的未读加急总数不能超过 200 条，需要用户处理一部分被加急的消息，在不超过 200 条未读加急消息时，才可以继续加急。处理方式： - 用户在客户端的会话内阅读加急消息（必须在会话内阅读消息，点掉终端弹出的加急提醒弹框不会视为已读加急消息）。 - 如果某一群聊内存在大量加急消息，在确保不需要一条条阅读的情况下，可以通过群聊的 设置 > 清空聊天记录 功能清理群聊内的加急消息。
400	230024	Reach the upper limit of urgent message.	加急额度超限，请联系企业管理员。相关说明参见加急功能。
400	230027	Lack of necessary permissions.	暂不支持在外部群中进行本操作。
400	230052	Can not urgent this message.	无权加急或被鉴别为风险操作。请排查群聊内是否已开启 仅群主和管理员可加急，或联系企业管理员。
400	230098	The message is fold, not support urgent.	被聚合的消息不支持加急。
400	230110	Action unavailable as the message has been deleted.	消息已删除，不支持当前操作。
400	232009	Your request specifies a chat which has already been dissolved.	相关群组已被解散，无法进行当前操作。

其他未列出的错误码请参见服务端通用错误码。