Skip to content

Contacts

Use the same account for discovery and the resulting friend request. Discovery returns a short-lived recipientRef; keep tickets and request history private.

List saved contacts

Terminal window
wx contacts list
wx contacts list --all

The default lists confirmed saved contacts. --all includes cached non-contacts and people whose relationship is unknown. Exact contact reads still work for cached people.

Find and add someone

  1. Search your saved contacts or discover someone by WeChat ID:

    Terminal window
    wx contacts find Alice
    wx --json contacts search WECHAT_ID

    Server discovery returns recipientRef, displayName and expiresAt. The displayed name is your query. A match does not establish friendship. If recipientRef is null, that response cannot send a request. contactId identifies an already saved contact.

  2. Send a greeting using the returned reference:

    Terminal window
    wx --json contacts requests send RECIPIENT_REF \
    --message "Hello, it's Alice" --idempotency-key add-alice-1

    The command returns an operation with kind: "contact_mutation". Retain the operation ID and key if the response is lost. Reuse that key to follow the original attempt.

  3. List incoming and outgoing history:

    Terminal window
    wx contacts requests list
    wx contacts requests list --direction incoming --actionable
    wx --json contacts requests get REQUEST_ID

Accept or remove

Accept the version you just inspected:

Terminal window
wx contacts requests accept REQUEST_ID --expected-version VERSION \
--idempotency-key accept-alice-1

A changed row returns stale_contact_request; read it again before deciding. An accepted server response and a confirmed saved contact are separate states. The contact sync stream confirms membership.

Delete a request’s entire local conversation, or remove an existing contact:

Terminal window
wx contacts requests delete REQUEST_ID --expected-version VERSION \
--idempotency-key delete-alice-history-1
wx contacts remove CONTACT_ID --idempotency-key remove-alice-1

Deleting local history does not withdraw a sent request or notify the other person of rejection. Removing a contact preserves your chat history; the other person manages their own list.

In the app

Focus sidebar search or press Command/Ctrl+K. Tabs separate All, Friends, Other people, Groups and Messages. Contacts search opens Friends; Contacts + opens Other people for adding someone. In All, typing also searches cached people under Other people. Server discovery appears under Add someone on WeChat. Friends say Contact; confirmed non-contacts say Not friends yet; unknown membership uses a local-history source label in search.

Each section loads independently and has its own Load more control. Message results show their original date and time in your local timezone when available. Choose Message to open the conversation or Details to open the shared contact card.

Friend requests appears in the Contacts sidebar. The Contacts icon also shows the number of incoming requests needing review while Chats is open. A saved contact or group opens its conversation with Message. Contact rows also expose Details on hover or keyboard focus. See Privacy for privacy updates.

The saved-contact list includes only people with stored friendship evidence. A cached person with an unknown relationship can still be messaged or added from their contact card. Add contact first looks them up on WeChat, then opens the greeting and privacy choices; it does not send until you choose Send request.

HTTP and Rust

All paths below are relative to /v1/accounts/ACCOUNT_ID/:

Method and pathPurpose
GET contactsList confirmed saved contacts; relation=friend is the default
GET contacts?relation=allInclude all cached people; unknown and non_contact select those categories
POST search/contactsDiscover with { "query": "WECHAT_ID" }
GET contact-requestsPage incoming and outgoing history; supports direction, actionable, search, limit, cursor
GET contact-requests/IDInspect history and its current version
POST contact-requestsSend with recipientRef and message
POST contact-requests/ID/acceptAccept with expectedVersion
DELETE contact-requests/IDDelete local history with expectedVersion
DELETE contacts/IDRemove the saved contact
GET contact-mutations/by-idempotency-key?key=KEYRecover the original operation

Keep relation and the search text unchanged when following nextCursor; filtering occurs before pagination. The Friends tab uses the saved-friend default; Other people searches the other local relationship categories.

Reads require read; mutations and operation-by-key recovery require admin. Every mutation requires Idempotency-Key. Follow the returned ID through GET operations/ID. An uncertain operation stops at needs_review; recovery never resends automatically.

The protocol crate exposes typed discovery, send, accept and removal operations. The profile crate reads official-format request history and applies staged, version-checked changes. The daemon coordinates credentials, idempotency and sync; applications should use its API when it owns the profile.

Rename a contact

Your private name for a contact (WeChat calls it a remark) is shown instead of the name they chose, as displayName.

In the app, open the friend’s contact card and type in Remark. It saves when you stop typing or leave the field, and the heading shows Saving…, then Syncing with WeChat…, then Saved. Empty the field to clear it. From the CLI:

Terminal window
wx contacts set CONTACT_ID --remark "Monster"
wx contacts set CONTACT_ID --clear-remark

wx --json contacts get CONTACT_ID shows remark and displayName. The new name appears a few seconds after WeChat accepts it; until then the contact has remarkPending: true. Change privacy and the name in separate commands.

Privacy

Use the contact card to choose Chats Only, Hide My Posts and Hide Their Posts. Open it from a contact’s Details button, a search result, or a friend request. Initial settings are submitted with Send request or Accept. For an existing friend, changes save on their own; the Privacy heading shows when a change is saving, saved or needs a retry. Remove contact requires confirmation and preserves chat history.

Change privacy from the CLI

Read the current settings:

Terminal window
wx --json contacts get CONTACT_ID

The response contains privacy and privacyVersion. Change only the options you specify:

Terminal window
wx contacts set CONTACT_ID --chats-only true \
--idempotency-key privacy-alice-1

Omitted flags retain their current values. Use --hide-my-posts true|false and --hide-their-posts true|false for the other settings. The command saves its resolved settings before submission. Reusing the same key follows that original edit, even if newer settings exist.

For a new request or acceptance, the same optional flags select initial privacy. Omitted initial options use the default full-access/off/off settings. Changing to Chats Only retains the hide selections, so changing back can restore them.

Privacy API and Rust

Reading and refreshing contacts require read. Edits require admin for the selected account. Paths are relative to /v1/accounts/ACCOUNT_ID/.

Method and pathPurpose
GET contactsList contacts with privacy and privacyVersion where available.
GET contacts/CONTACT_IDRead a contact with remark, privacy and privacyVersion. privacyPending or remarkPending is true while an earlier change is still settling.
POST contacts/CONTACT_ID/refreshRefresh contact details and privacy together. Poll the returned operation, then read the contact.
PATCH contacts/CONTACT_IDUpdate privacy or remark with expectedVersion (the contact’s privacyVersion); requires Idempotency-Key

The PATCH takes either a complete privacy value or a remark, not both:

{
"privacy": { "chatsOnly": true, "hideMyPosts": false, "hideTheirPosts": false },
"expectedVersion": "PRIVACY_VERSION_FROM_CONTACT"
}
{ "remark": "Monster", "expectedVersion": "PRIVACY_VERSION_FROM_CONTACT" }

A null remark clears it. Other contact fields remain unchanged. A stale version returns stale_contact_privacy; read the contact again before deciding on another edit. When a friend has no privacy or privacyVersion, privacyUnavailable says why: contact_privacy_unresolved means refresh the contact first, and ordinary_contact_required means this kind of contact can’t be edited. The returned operation distinguishes server acceptance from confirmation in the saved contact.

The Rust protocol crate provides ContactPrivacySettings, contact_remark_request, request builders and correlated reply decoding. The core crate provides ContactUpdate and update_contact, coordinating idempotency, account ownership and saved-contact confirmation. In OpenClaw, private owner sessions can see available settings through wechat_contacts list, find, and get.