Overview
The relationship module manages friend relationships, friend requests, relationship metadata, and blacklists from trusted backend services. A blacklist has governance implications, but its data ownership remains within user relationships rather than content moderation.
Capability scope
| Capability | Description |
|---|---|
| Friend requests | Send requests, list received or sent requests, and accept or reject them. |
| Friend queries | Page through a friend list or retrieve selected friend profiles in batches. |
| Friend management | Delete or import relationships and update remarks, pinned state, and extension data in batches. |
| Blacklists | Add users to a blacklist, remove them, and page through blacklist records. |
| Request record governance Enterprise | Delete friend request records sent or received by a user. |
Common APIs
- Apply to add a friend
- Respond to a friend request
- List received friend requests
- List sent friend requests
- List friends
- Get designated friends
- Delete a friend
- Import friends
- Update friends
- Add a user to a blacklist
- List blacklist records
- Remove a user from a blacklist
- Delete sent friend requests Enterprise
- Delete received friend requests Enterprise
Resource representations
Relationship resources describe state between users, including friendships, friend requests, and blacklists.
FriendInfo
FriendInfo represents the relationship between an owner and a friend.
| Field | Type | Description |
|---|---|---|
| ownerUserID | string | User ID that owns the friend record. |
| remark | string | Owner-defined friend remark. |
| createTime | int64 | Relationship creation time, normally a Unix timestamp in milliseconds. |
| friendUser | object | Friend profile represented by UserInfo. |
| addSource | int | How the relationship was established. See AddSource. |
| operatorUserID | string | User that created or updated the relationship. |
| ex | string | Relationship extension data. |
| isPinned | boolean | Whether the friend record is pinned. |
FriendRequestInfo
FriendRequestInfo represents a friend request record.
| Field | Type | Description |
|---|---|---|
| fromUserID | string | Requesting user ID. |
| fromNickname | string | Requesting user's nickname. |
| fromFaceURL | string | Requesting user's avatar URL. |
| toUserID | string | Recipient user ID. |
| toNickname | string | Recipient's nickname. |
| toFaceURL | string | Recipient's avatar URL. |
| handleResult | int | Request result. See FriendRequestResult. |
| reqMsg | string | Request message. |
| createTime | int64 | Request creation time. |
| handlerUserID | string | User that handled the request. |
| handleMsg | string | Handling message. |
| handleTime | int64 | Time when the request was handled. |
| ex | string | Friend request extension data. |
BlackInfo
BlackInfo represents a user blacklist relationship.
| Field | Type | Description |
|---|---|---|
| ownerUserID | string | User ID that owns the blacklist record. |
| createTime | int64 | Time when the user was added to the blacklist. |
| blackUserInfo | object | Public profile of the blocked user, represented by PublicUserInfo. |
| addSource | int | How the blacklist record was created. See AddSource. |
| operatorUserID | string | User that performed the operation. |
| ex | string | Blacklist extension data. |
Enums
AddSource
AddSource describes how a friendship or blacklist relationship was established.
| Value | Name | Description |
|---|---|---|
| 1 | BecomeFriendByImport | Imported by an administrator or backend service. |
| 2 | BecomeFriendByApply | Established through a friend request. |
FriendRequestResult
| Value | Name | Description |
|---|---|---|
| -1 | Refuse | Rejected. |
| 0 | NotHandle | Pending. |
| 1 | Agree | Accepted. |
Integration advice
Your backend should decide whether a relationship may be created, deleted, or imported. Confirm both users exist in your business system and record the operator, source, and reason before calling OpenIM. Combine these APIs with Webhooks or a business approval workflow when risk controls are required.
Treat blacklists as relationship data. A product may link to blacklist operations from a moderation surface, but the API remains in this module so that users do not mistake it for channel or message moderation.
Related pages
Was this page helpful?