wecomcli-msg

WeChat Work Message Skill

wecom-cli is the command-line program provided by WeChat Work. All operations are performed by executing the wecom-cli command.

Interact with the WeChat Work message system via wecom-cli msg <接口名> '<json入参>'.

---

API List

get_msg_chat_list — Get session list

wecom-cli msg get_msg_chat_list '{"begin_time": "2026-03-11 00:00:00", "end_time": "2026-03-17 23:59:59"}'

Query the list of sessions with messages within a time range, supports pagination. See API details.

get_message — Retrieve session messages

wecom-cli msg get_message '{"chat_type": 1, "chatid": "zhangsan", "begin_time": "2026-03-17 09:00:00", "end_time": "2026-03-17 18:00:00"}'

Retrieve message records within a specified time range based on session type and ID, supports pagination. Supports text/image/file/voice/video message types, only within the last 7 days. See API details.

get_msg_media — Get message file content

wecom-cli msg get_msg_media '{"media_id": "MEDIAID_xxxxxx"}'

Automatically download a file to local based on file ID, returning the local path (local_path), name, type, size, and MIME type. Used to retrieve actual content of non-text messages such as images, files, voice, and video. See API details.

send_message — Send text message

wecom-cli msg send_message '{"chat_type": 1, "chatid": "zhangsan", "msgtype": "text", "text": {"content": "hello world"}}'

Send a text message to a single chat or group chat. See API details.

---

Core Rules

Time Range Rules

• Format: All time parameters use YYYY-MM-DD HH:mm:ss format
• Default Range: If not specified by the user, default to the last 7 days (current time minus 7 days)
• Limitation: Start time cannot be earlier than 7 days before current time, and cannot be later than current time
• Relative Time Support: Supports automatic calculation for "yesterday", "last three days", etc.

chatid Lookup Rules

• When the user provides a person or group name instead of an ID:
  1. Call get_msg_chat_list to get the session list (time range consistent with the target query)
  2. Match by chat_name in chats
  3. Matching Strategy:
     • Exact match with unique result: use directly
     • Fuzzy match with multiple results: show candidate list for user selection
     • No match: inform the user that no session was found
• chat_type Determination: get_msg_chat_list response does not include a session type field; infer from context: use chat_type=2 when the user explicitly mentions "group", otherwise default to chat_type=1 (single chat)

userid to Name Mapping

Process:

1. Call the get_userlist API of the wecomcli-contact skill to get the user list
2. Build a mapping from userid to name
3. Display Strategy:
   • Exact match: show name
   • No match: keep showing userid

Mandatory Interaction Steps (Cannot Be Skipped)

The following steps must be performed one by one when downloading non-text messages, and cannot be combined, omitted, or skipped, even if the user does not ask:

1. Must proactively inform file location: After download completes, immediately show the user all file paths and the storage directory
2. Must ask whether to delete: After informing the location, immediately ask the user if they need to clean up the temporary files

---

Typical Workflows

View Session List

User query examples:

• "Show me my chats from the past week"
• "Who sent me messages recently"

Execution flow:

1. Determine the time range (user-specified or default last 7 days)
2. Call get_msg_chat_list to get the session list
3. Display session name, last message time, and message count
4. If has_more is true, inform the user that more sessions are available

View Chat History

User query examples:

• "Show me the recent chat history with Zhang San"
• "Check the recent messages in the project group"

Execution flow:

1. Determine the time range (user-specified or default last 7 days)
2. Use chatid lookup rules to determine the target session's chatid and chat_type
3. Call get_message to retrieve the message list
4. Call the get_userlist API of the wecomcli-contact skill to get the address book and build userid→name mapping
5. Count non-text messages: Iterate through the message list, count the number and types of messages where msgtype is not text (image/file/voice/video)
6. When displaying messages, replace userid with readable names, format:
   • Text message: 姓名 [时间]: 内容
   • Image message: 姓名 [时间]:[图片]
   • File message: 姓名 [时间]:[文件] 文件名称
   • Voice message: 姓名 [时间]:[语音] 语音内容
   • Video message: 姓名 [时间]:[视频]
7. Non-text message handling: After displaying messages, if there are non-text messages:
   • Proactively ask whether to download: Inform the user of the count and types of non-text messages (e.g., "The chat above contains 2 images and 1 file. Would you like to download them locally?")
   • After user confirmation, call get_msg_media for each file; the API automatically downloads the file and returns local_path
   • Check file extension: After each file download, check if the file at local_path has the correct extension:
     • Based on the content_type (MIME type) and name fields returned by get_msg_media:
       • If the filename lacks an extension (e.g., screenshot instead of screenshot.png), automatically append the correct extension based on content_type (e.g., image/png → .png, application/pdf → .pdf, audio/amr → .amr, video/mp4 → .mp4)
       • If the filename extension does not match content_type, correct it based on content_type
     • After appending or correcting the extension, rename the file to the correct filename
     • Confirm the file is readable (file size > 0); if the file is empty or corrupted, inform the user that the download was abnormal
   • ⚠️ Do not use the MEDIA: directive for downloaded files: These files are historical attachments downloaded from chat records; only inform the user of the local storage path, do not resend them via the MEDIA: directive
8. ⚠️ Must proactively inform file location (this step cannot be skipped): After all files are downloaded and checked, immediately and proactively show the user the storage directory and the full path of each file in a summary format, without waiting for the user to ask. Example:

   📁 Files have been downloaded to the following locations:

   • Image: xxx/yyy.png
   • File: xxx/yyy.pdf

   You can find all downloaded files in the xxx/yyy/ directory.

9. ⚠️ Must ask whether to delete (this step cannot be skipped): After informing the file location, immediately and proactively ask the user if they want to delete the downloaded temporary files (e.g., "If you no longer need these files, would you like me to clean them up?")
   • If the user confirms deletion, delete the files corresponding to local_path
   • If the user does not want to delete, keep the files
10. If next_cursor is not empty, inform the user that more messages are available

Send Message

User query examples:

• "Send a message to Zhang San: tomorrow's meeting is moved to 3 PM"
• "Send a message in the project group: meeting at 3 PM today"

Execution flow:

1. Use chatid lookup rules to determine the target session's chatid and chat_type
2. Confirm before sending: Ask the user to confirm the recipient and content (e.g., "About to send to Zhang San: 'tomorrow's meeting is moved to 3 PM'. Confirm sending?"), then send after user confirmation
3. Call send_message to send (msgtype is fixed to text)
4. Display the send result

View Messages and Reply

User query examples:

• "Check what Zhang San sent me, then reply 'received'"

Execution flow:

1. First execute the "View Chat History" flow (reuse the already obtained chatid and chat_type)
2. After displaying messages, execute the "Send Message" flow (requires confirmation before sending)

---

Error Handling

• Time range exceeded: Inform the user of the 7-day limit and adjust to a valid range
• Session not found: Clearly inform the user that the session was not found
• API error: Display specific error information, retry if necessary
• Network issues: On HTTP errors, automatically retry up to 3 times