Platform API

Set conversations

Use Set conversations to apply the same conversation settings to multiple users, including receive options, pinned state, extensions, and message-destruction settings.

HTTP request

POST {API_ADDRESS}/conversation/set_conversations

Request example

curl --request POST "${API_ADDRESS}/conversation/set_conversations" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "operationID: ${OPERATION_ID}" \
  --header "token: ${ADMIN_TOKEN}" \
  --data-raw '{
  "userIDs": [
    "user_001",
    "user_003"
  ],
  "conversation": {
    "conversationID": "si_user_001_user_002",
    "conversationType": 1,
    "userID": "user_002",
    "groupID": "",
    "recvMsgOpt": 0,
    "isPinned": true,
    "attachedInfo": "",
    "isPrivateChat": false,
    "ex": "",
    "burnDuration": 0,
    "minSeq": 0,
    "maxSeq": 128,
    "groupAtType": 0,
    "msgDestructTime": 0,
    "isMsgDestruct": false
  }
}'

Keep administrator tokens on trusted backend services only. Client applications should use user tokens issued by your backend.

Request body

{
  "userIDs": [
    "user_001",
    "user_003"
  ],
  "conversation": {
    "conversationID": "si_user_001_user_002",
    "conversationType": 1,
    "userID": "user_002",
    "groupID": "",
    "recvMsgOpt": 0,
    "isPinned": true,
    "attachedInfo": "",
    "isPrivateChat": false,
    "ex": "",
    "burnDuration": 0,
    "minSeq": 0,
    "maxSeq": 128,
    "groupAtType": 0,
    "msgDestructTime": 0,
    "isMsgDestruct": false
  }
}

Parameter	Required	Type	Description
userIDs	Yes	array	List of OpenIM user IDs.
conversation	Yes	object	Conversation fields to apply. See `ConversationInfo`.
conversation.conversationID	Yes	string	OpenIM conversation ID.
conversation.conversationType	Yes	int	Conversation type. See `ConversationType`.
conversation.userID	No	string	Peer user ID; required for a single conversation.
conversation.groupID	No	string	Group ID; required for a group conversation.
conversation.recvMsgOpt	No	int	Receive option. See `RecvMsgOpt`.
conversation.isPinned	No	boolean	Whether the conversation is pinned.
conversation.attachedInfo	No	string	Conversation attachment data.
conversation.isPrivateChat	No	boolean	Whether private-chat behavior is enabled.
conversation.ex	No	string	Business extension field.
conversation.burnDuration	No	int	Burn-after-reading duration in seconds.
conversation.minSeq	No	int	Minimum message sequence number.
conversation.maxSeq	No	int	Maximum message sequence number.
conversation.groupAtType	No	int	Group mention state. See `GroupAtType`.
conversation.msgDestructTime	No	int	Message destruction time setting.
conversation.isMsgDestruct	No	boolean	Whether message destruction is enabled.
conversation.isMarked Enterprise	No	boolean	Whether the user marks this conversation.
conversation.remark Enterprise	No	string	User-specific conversation remark.

Response

OpenIM usually returns 200 OK when the request reaches the service. Use errCode in the JSON response to determine business success; errCode === 0 means the operation succeeded.

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": ""
}

Response fields

Field	Type	Description
errCode	int	Business error code. `0` means success.
errMsg	string	Short error message.
errDlt	string	Detailed error information for troubleshooting.

Error response

When a request fails, OpenIM returns the same error envelope. See Error codes for the full handling model.

{
  "errCode": 1004,
  "errMsg": "RecordNotFoundError",
  "errDlt": ": [1004]RecordNotFoundError"
}

Scenario	Possible cause	Recommended action
Authentication failed	`token` is missing, expired, or not an administrator token.	Issue a new administrator token and keep it on the backend.
Traceability is weak	`operationID` is missing or reused across many requests.	Generate a unique `operationID` for every request and log it with the response.
Validation failed	The request body has an invalid type, missing field, or unsupported enum value.	Compare the payload with the request table and retry after correcting the fields.

Permissions and limits

Supply conversation.userID for a single conversation and conversation.groupID for a group conversation.
A successful request means the settings were updated; conversation change notifications may then be delivered to affected clients.
isMarked and remark are available in OpenIM Enterprise.

Was this page helpful?