设置指定消息附件的存储方式

大约 4 分钟

设置指定消息附件的存储方式

环信服务器支持对用户指定的消息附件设置存储方式,可延长存储时间或实现永久存储,支持通过客户端和 RESTful API 发送图片、语音、视频、文件消息和合并消息时上传的附件(包括图片和视频的缩略图)。

对于永久存储的消息附件,用户可以随时获取这些附件。

提示

若使用该接口,需联系环信商务开通。

调用频率:100 次/秒/App Key

HTTP 请求

POST https://{host}/{org_name}/{app_name}/users/{username}/chatfiles/lifetime
路径参数
参数类型是否必需描述
usernameString调用该接口的用户 ID。

其他参数及说明详见 公共参数

请求 Header
参数类型是否必需描述
Content-TypeString内容类型。请填 application/json
AcceptString内容类型。请填 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。
请求 body
参数类型是否必需描述
lifetimeString消息附件保存时间:
- (默认)default:配置的消息附件的默认有效期;
- refresh:刷新消息附件的有效期,相当于重新设置存储时间,延长了存储时长。例如,消息附件可存储 7 天,在存储的第五天时调用了该接口,即将附件的存储时间设置为 7 天,则附件的剩余存储时间为 7 天。该设置可用于延长合并消息的附件存储时间,例如,发送合并消息时,原始图片的存储时间只剩余 1 天,调用该接口时利用该设置可将存储时间延长。
- forever:永久有效。
chatfile_idsArray消息附件的文件 UUID,最多可传入 100 个。

HTTP 响应

响应 body

如果返回的 HTTP 状态码为 200,表示请求成功,响应包体中包含以下字段:

参数类型描述
pathString请求路径,属于请求 URL 的一部分,开发者无需关注。
uriString请求 URL。
timestampLongHTTP 响应的 Unix 时间戳,单位为毫秒。
organizationString环信即时通讯 IM 为每个公司(组织)分配的唯一标识,与请求参数 org_name 相同。
applicationString系统内为应用生成的唯一标识,开发者无需关心。
actionString请求方法。
dataJSON是否成功设置消息附件的存储:
- success:成功;
- failed:失败。
durationLong从发送 HTTP 请求到响应的时长, 单位为毫秒。
applicationNameString你在环信即时通讯云控制台创建应用时填入的应用名称,与请求参数 app_name 相同。

响应字段及说明详见 公共参数

如果返回的 HTTP 状态码非 200,表示请求失败。你可以参考 错误码了解可能的原因。

示例

请求示例
# 将 <YourUserToken> 替换为你的用户 Token
curl -X PUT -L "http://localhost/{org}/{app}/users/{username}/chatfiles/lifetime" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YourUserToken>" \
-d '{
          "lifetime": "default",
          "chatfile_ids": [
            "2fe7f0b0-0b55-XXXX-XXXX-231441e42458"
          ]
    }'
响应示例
{
  "path": "/users/test/chatfiles/lifetime",
  "uri": "https://XXXX/XXXX/XXXX/users/test/chatfiles/lifetime",
  "timestamp": 1731382587142,
  "organization": "XXXX",
  "application": "2a8f5b13-XXXX-XXXX-958a-838fd47f1223",
  "action": "put",
  "data": {
      "359f9c50-XXXX-XXXX-92cd-07eff71e8a37": "success"
  },
  "duration": 102,
  "applicationName": "XXXX"
}

错误码

如果返回的 HTTP 状态码非 200,表示请求失败,可能提示以下错误码:

HTTP 状态码错误类型错误提示可能原因处理建议
403forbidden_op设置消息附件存储的功能未开通。联系环信商务开通该功能。
400illegal_argumentchatfile_ids size is too large请求中传入的消息附件的文件 ID chatfile_ids 超过了上限 100.消息附件的文件 ID 最多可传 100 个。
400illegal_argumentlifetime must be either 'forever' or 'default' or 'refresh'。消息附件保存时间 lifetime 传入了 foreverdefaultrefresh 之外的值。消息附件保存时间 lifetime 只能设置为 foreverdefaultrefresh,不能传入其他值。
401unauthorizedUnable to authenticate (OAuth)token 不合法,可能过期或 token 错误。使用新的 token 访问。

关于其他错误,你可以参考 错误码 了解可能的原因。