设置会话置顶/草稿/提醒级别

POST/im/v2/conversation/settings需鉴权v1.0.0

接口说明​

设置会话置顶/草稿/提醒级别(服务端代操作)。

项目值
操作 IDconversation.settings
起始版本1.0.0
幂等否
回调事件—
所属模块会话

请求头​

名称必填说明示例
App-Key是应用 AppKeydemo
Nonce是随机串,8-64 字符,5 分钟内不可重复9f2a7c1b
Timestamp是epoch 毫秒,允许 ±300000ms1750000000000
Signature是hex(sha1(AppSecret + Nonce + Timestamp)) 小写372e885320aabd997aafc5491f9d90fdca94432e
X-Request-Id否可选请求头;缺省或超过 128 字符时由服务端生成,响应原值回声req_7f3a9c

请求体参数​

参数类型必填说明
userIdstring是—
conversationTypeConversationType是—
targetIdstring是—
isPinnedbool否—
draftstring否—
notificationLevelNotificationLevel否—

返回结果​

字段类型必填说明
codeint是0 表示成功;非 0 为错误码,见错误码表
msgstring否错误信息;成功响应通常不返回
dataConversation是业务数据;成功时返回,结构见下方字段表
requestIdstring是服务端生成的请求 ID,便于排查;与请求头 X-Request-Id 对应

data 字段​

字段类型必填说明
data.conversationTypeConversationType是—
data.targetIdstring是—
data.targetNamestring否—
data.unreadCountuint32是—
data.mentionedCountuint32否—
data.lastMessageMessage否—
data.updatedAtint64是—
data.isPinnedbool是—
data.draftstring否—
data.notificationLevelNotificationLevel否—
data.groupTypeGroupType否IDL rev21(additive):仅群会话有值——群存在时 "normal"|"super",群已删除或非群会话为 null。用于客户端在会话列表标注超级群,不改变 conversationType(超级群仍是 GROUP=2)。

必填列取自 IDL 的 field.required;未标注的字段按非必填展示。

请求示例​

APP_KEY="demo"
APP_SECRET="YOUR_APP_SECRET"
BASE_URL="https://im.example.com"
NONCE="$(openssl rand -hex 16)"
TIMESTAMP="$(date +%s%3N)"
SIGNATURE="$(printf '%s' "$APP_SECRET$NONCE$TIMESTAMP" | openssl sha1 | awk '{print $2}')"

curl -sS -X POST "$BASE_URL/im/v2/conversation/settings" \
  -H "Content-Type: application/json" \
  -H "App-Key: $APP_KEY" \
  -H "Nonce: $NONCE" \
  -H "Timestamp: $TIMESTAMP" \
  -H "Signature: $SIGNATURE" \
  -d '{"userId":"user1","conversationType":1,"targetId":"user2","isPinned":false,"draft":"明天见","notificationLevel":0}'
import { createHash, randomBytes } from 'node:crypto';

const APP_KEY = 'demo';
const APP_SECRET = 'YOUR_APP_SECRET';
const BASE_URL = 'https://im.example.com';
const PATH = '/im/v2/conversation/settings';

const nonce = randomBytes(16).toString('hex');
const timestamp = String(Date.now());
const signature = createHash('sha1')
  .update(APP_SECRET + nonce + timestamp)
  .digest('hex');

const res = await fetch(BASE_URL + PATH, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'App-Key': APP_KEY,
    Nonce: nonce,
    Timestamp: timestamp,
    Signature: signature,
  },
  body: JSON.stringify({"userId":"user1","conversationType":1,"targetId":"user2","isPinned":false,"draft":"明天见","notificationLevel":0}),
});
const result = await res.json();
if (result.code !== 0) throw new Error(result.code + ': ' + result.msg);
console.log(result.data);

返回示例​

JSON
{
  "code": 0,
  "data": {
    "conversationType": 1,
    "targetId": "user2",
    "targetName": "Bob",
    "unreadCount": 0,
    "mentionedCount": 0,
    "lastMessage": {
      "messageId": "msg_10001",
      "clientMsgId": "client_9f2a7c",
      "conversationType": 1,
      "targetId": "user2",
      "channelId": "channel1",
      "senderId": "user1",
      "seq": 1024,
      "timestamp": 1750000000000,
      "content": {
        "type": "text",
        "text": "你好,IM PaaS"
      },
      "direction": 1
    },
    "updatedAt": 1750000000000,
    "isPinned": false,
    "draft": "明天见",
    "notificationLevel": 0,
    "groupType": "normal"
  },
  "requestId": "req_7f3a9c"
}

错误码​

错误码名称HTTP 状态说明可重试起始版本
1001INVALID_PARAMETER400参数错误否1.0.0
1003FORBIDDEN403无权限否1.0.0
1004USER_NOT_FOUND404用户不存在否1.0.0

相关说明​