# 发送电话加急
调用该接口把指定消息加急给目标用户，加急将通过飞书客户端和电话进行通知。了解加急可参见[加急功能](https://www.feishu.cn/hc/zh-CN/articles/360024757913)。
**注意事项**：**注意**：电话加急将消耗企业的加急额度（可通过[管理后台](https://admin.feishu.cn/) > **费用中心** > **权益数据** > **短信/电话加急** 查看当前额度），请慎重调用。
## 前提条件
- 应用需要开启[机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability) 。
- 确保机器人在被加急消息所属会话中。如果是群组，还需要确保群管理中设置了 **所有群成员可以加急**，或者设置了 **仅群主或管理员可以加急** 且机器人是管理员。
## 使用限制
- 只能加急当前机器人自己发送的消息。
- 加急用户的未读加急总数不能超过 200 条。
- 不支持加急[批量发送的消息](https://open.feishu.cn/document/ukTMukTMukTM/ucDO1EjL3gTNx4yN4UTM)。
- 加急[折叠会话](https://www.feishu.cn/hc/zh-CN/articles/360025267393)内的消息时，仅会在应用内推送提醒通知。
## 请求
基本 |
---|---
HTTP URL | https://open.feishu.cn/open-apis/im/v1/messages/:message_id/urgent_phone
HTTP Method | PATCH
接口频率限制 | [1000 次/分钟、50 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 发送电话加急消息(im:message.urgent:phone)
发送电话加急消息（历史版本）(im:message.urgent:phone_send)
字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请
获取用户 user ID(contact:user.employee_id:readonly)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"
### 路径参数
名称 | 类型 | 描述
---|---|---
message_id | string | 待加急的消息 ID。ID 获取方式：
- 调用[发送消息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/create)接口后，从响应结果的 `message_id` 参数获取。
- 监听[接收消息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/events/receive)事件，当触发该事件后可以从事件体内获取消息的 `message_id`。
- 调用[获取会话历史消息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/list)接口，从响应结果的 `message_id` 参数获取。
**注意**：不支持加急[批量发送的消息](https://open.feishu.cn/document/ukTMukTMukTM/ucDO1EjL3gTNx4yN4UTM)（对应的消息ID 格式为 `bm_xxx`）。
**示例值**："om_dc13264520392913993dd051dba21dcf"
### 查询参数
名称 | 类型 | 必填 | 描述
---|---|---|---
user_id_type | string | 是 | 用户 ID 类型
**示例值**：open_id
**可选值有**：
- open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。[了解更多：如何获取 Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)
- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)
- user_id：标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。[了解更多：如何获取 User ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)
**默认值**：`open_id`
**当值为 `user_id`，字段权限要求**：
获取用户 user ID(contact:user.employee_id:readonly)
### 请求体
名称 | 类型 | 必填 | 描述
---|---|---|---
user_id_list | string\[\] | 是 | 加急的目标用户 ID 列表。ID 类型与查询参数 user_id_type 取值一致，推荐使用 open_id。
**注意**：需要确保目标用户在加急消息所属的会话内。如果 ID 列表中有用户不在消息所属的会话内，则接口会将这些无效的 ID 返回（响应参数 invalid_user_id_list），只加急有效的用户 ID。如果 ID 列表内的所有 ID 均无效，则会返回 `230001` 错误码。
**数据校验规则**：列表长度不能大于 200。
**示例值**：["ou_6yf8af6bgb9100449565764t3382b168"]
### 请求体示例
```json
{
"user_id_list": [
"ou_6yf8af6bgb9100449565764t3382b168"
]
}
```
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
invalid_user_id_list | string\[\] | 无效的用户 ID。当传入的用户 ID 列表内存在部分用户 ID 有效时，将对有效的用户进行加急操作，同时返回无效的用户 ID。当所有的用户 ID 无效时，将返回 `230001` 错误码。
当存在部分用户ID有效时将对有效的用户进行加急操作，同时返回无效的用户ID。当所有的用户ID无效时，将返回230001错误码
### 响应体示例
```json
{
"code": 0,
"msg": "success",
"data": {
"invalid_user_id_list": [
"2921304923074478100"
]
}
}
```
### 错误码
HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 230001 | Your request contains an invalid request parameter. | 参数错误，请根据接口返回的错误信息并参考接口文档检查输入参数是否正确。
400 | 230002 | The bot can not be outside the group. | 机器人不在对应群组中。你需要将应用机器人添加到接收消息的群组中。如何添加机器人参考[机器人使用指南](https://open.feishu.cn/document/ukTMukTMukTM/uATM04CMxQjLwEDN)。
400 | 230006 | Bot ability is not activated. | 应用未启用机器人能力。启用方式参见[如何启用机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)。
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. 登录[开发者后台](https://open.feishu.cn/app)，找到并进入指定应用详情页。
2. 在左侧导航栏进入 **应用发布** > **版本管理与发布** 页面，点击 **创建版本**。
3. 在 **版本详情** 页面，找到 **可用范围** 区域，点击 **编辑**。
4. 在弹出的对话框内，配置应用的可用范围，将用户添加至可用范围内。
5. 在页面底部点击 **保存**，并发布应用使配置生效。
6. （可选）如果以上配置完成后仍报错，则需要联系企业管理员登录[管理后台](https://feishu.cn/admin)，在 **工作台** > **应用管理** 中进入指定应用详情页，在 **应用可用范围** 内查看该用户是否被设置为了 **禁用成员**。
具体操作参见[配置应用可用范围](https://open.feishu.cn/document/home/introduction-to-scope-and-authorization/availability)。
400 | 230023 | The user has too many unread urgent messages. | 用户未读的加急消息过多。加急用户的未读加急总数不能超过 200 条，需要用户处理一部分被加急的消息，在不超过 200 条未读加急消息时，才可以继续加急。处理方式：
- 用户在客户端的会话内阅读加急消息（必须在会话内阅读消息，点掉终端弹出的加急提醒弹框不会视为已读加急消息）。
- 如果某一群聊内存在大量加急消息，在确保不需要一条条阅读的情况下，可以通过群聊的 **设置** > **清空聊天记录** 功能清理群聊内的加急消息。
400 | 230024 | Reach the upper limit of urgent message. | 加急额度超限，请联系企业管理员。相关说明参见[加急功能](https://www.feishu.cn/hc/zh-CN/articles/360024757913)。
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. | 相关群组已被解散，无法进行当前操作。
其他未列出的错误码请参见[服务端通用错误码](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN)。