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
wx contacts listwx contacts list --allThe 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
-
Search your saved contacts or discover someone by WeChat ID:
Terminal window wx contacts find Alicewx --json contacts search WECHAT_IDServer discovery returns
recipientRef,displayNameandexpiresAt. The displayed name is your query. A match does not establish friendship. IfrecipientRefis null, that response cannot send a request.contactIdidentifies an already saved contact. -
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-1The 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. -
List incoming and outgoing history:
Terminal window wx contacts requests listwx contacts requests list --direction incoming --actionablewx --json contacts requests get REQUEST_ID
Accept or remove
Accept the version you just inspected:
wx contacts requests accept REQUEST_ID --expected-version VERSION \ --idempotency-key accept-alice-1A 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:
wx contacts requests delete REQUEST_ID --expected-version VERSION \ --idempotency-key delete-alice-history-1wx contacts remove CONTACT_ID --idempotency-key remove-alice-1Deleting 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 path | Purpose |
|---|---|
GET contacts | List confirmed saved contacts; relation=friend is the default |
GET contacts?relation=all | Include all cached people; unknown and non_contact select those categories |
POST search/contacts | Discover with { "query": "WECHAT_ID" } |
GET contact-requests | Page incoming and outgoing history; supports direction, actionable, search, limit, cursor |
GET contact-requests/ID | Inspect history and its current version |
POST contact-requests | Send with recipientRef and message |
POST contact-requests/ID/accept | Accept with expectedVersion |
DELETE contact-requests/ID | Delete local history with expectedVersion |
DELETE contacts/ID | Remove the saved contact |
GET contact-mutations/by-idempotency-key?key=KEY | Recover 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:
wx contacts set CONTACT_ID --remark "Monster"wx contacts set CONTACT_ID --clear-remarkwx --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:
wx --json contacts get CONTACT_IDThe response contains privacy and privacyVersion. Change only the options you specify:
wx contacts set CONTACT_ID --chats-only true \ --idempotency-key privacy-alice-1Omitted 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 path | Purpose |
|---|---|
GET contacts | List contacts with privacy and privacyVersion where available. |
GET contacts/CONTACT_ID | Read a contact with remark, privacy and privacyVersion. privacyPending or remarkPending is true while an earlier change is still settling. |
POST contacts/CONTACT_ID/refresh | Refresh contact details and privacy together. Poll the returned operation, then read the contact. |
PATCH contacts/CONTACT_ID | Update 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.