wecomcli-get-msg

WeCom message skill

wecom-cli is a command-line program provided by WeCom; all operations are completed by executing the wecom-cli command.

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

---

Interface list

get_msg_chat_list — Get conversation 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 conversations with messages by time range, with pagination support. See API details。

get_message — Retrieve conversation 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 conversation type and ID, with pagination support. Supports text/image/file/voice/video message types, and only supports messages within 7 days. See API details。

get_msg_media — Get message file content

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

Automatically download the file locally based on the file ID, and return the file's local path (local_path), name, type, size, and MIME type. Used to retrieve the 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 one-on-one chat or group chat. See API details。

---

Core rules

Time range rules

• Format: All time parameters use the YYYY-MM-DD HH:mm:ss format
• Default range: When the user does not specify, use the last 7 days by default (7 days back from the current time)
• Limit: The start time cannot be earlier than 7 days before the current time, and cannot be later than the current time
• Relative time support: Supports automatic calculation such as "yesterday" and "the last three days"

chatid lookup rules

• When the user provides a person name or group name instead of an ID:
  1. Call get_msg_chat_list to get the conversation list (the time range is consistent with the target query)
  2. In chats , match by chat_name Match
  3. Matching strategy：
     • Exact match with a unique result: use it directly
     • Fuzzy match with multiple results: display the candidate list for the user to choose
     • No match: inform the user that nothing was found
• chat_type determination：get_msg_chat_list The returned result does not contain a conversation type field, so it must be inferred from context: when the user explicitly mentions "group", use chat_type=2; otherwise default to chat_type=1(one-on-one chat)

userid to username

Process：

1. Call wecomcli-lookup-contact get_userlist to get the user list
2. Establish the mapping relationship from userid to username
3. Display strategy：
   • Exact match: display username
   • No match: keep displaying userid

Mandatory interaction steps (cannot be skipped)

The following steps, when involving non-text message downloads,must be executed one by one, and must not be merged, omitted, or skipped, even if the user did not actively ask:

1. Must proactively inform the file location: After the download is complete, the full paths and storage directories of all files must be immediately shown to the user
2. Must ask whether to delete: After informing the location, must immediately ask the user whether the temporary files need to be cleaned up

---

Typical workflow

View session list

User query example：

• "See which chats I have had in the last week"
• "Who has sent me messages these past few days"

Execution process：

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

View chat records

User query example：

• "Help me look at my recent chat records with Zhang San"
• "Look at the recent messages in the project group"

Execution process：

1. Determine the time range (user-specified or default to the last 7 days)
2. Using the chatid lookup rule determine the target session's chatid and chat_type
3. Call get_message to pull the message list
4. Call wecomcli-lookup-contact 's get_userlist to get the contacts and build a userid→name mapping
5. Count non-text messages: Traverse the message list and 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 the messages, if non-text messages exist:
   • Proactively ask whether to download: Tell the user the number and types of non-text messages (e.g.: "The above chat contains 2 images and 1 file. Do you need to download them locally?")
   • After the user confirms, call the get_msg_media interface one by one; the interface will automatically download the file and return local_path
   • Check the file extension: After each file is downloaded, check whether the file corresponding to local_path has the correct extension:
     • Based on get_msg_media returned by content_type(MIME type) and the name field, determine:
       • If the file name lacks an extension (e.g. screenshot instead of screenshot.png), based on content_type automatically add the correct extension (e.g. image/png → .png，application/pdf → .pdf，audio/amr → .amr，video/mp4 → .mp4）
       • If the file name extension is inconsistent with content_type , use content_type as the standard for correction
     • After completing or correcting the extension, rename the file to the correct file name
     • Confirm the file can be read normally (file size > 0). If the file is empty or corrupted, tell the user that the file download is abnormal
   • ⚠️ Do not use the MEDIA: instruction on downloaded files: These files are historical attachments downloaded from the chat history; it is only necessary to inform the user of the local storage path,strictly prohibitedto resend them to the user via the MEDIA: instruction
8. ⚠️ Must proactively inform the file location(this step cannot be skipped): after all files are downloaded and checked,must immediately and proactivelyshow the user the file storage directory and the complete path of each file in summary form; do not wait for the user to ask. Example:

   📁 Files have been downloaded to the following locations:

   • Images:xxx/yyy.png
   • Files: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,must immediately and proactivelyask the user whether the downloaded temporary files need to be deleted (e.g., "If you no longer need these files, would you like me to clean them up for you?")
   • After the user confirms deletion, delete the file corresponding to local_path corresponding file
   • If the user does not need deletion, keep the files
10. If next_cursor is not empty, inform the user that there are more messages to continue viewing

Send message

User query example：

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

Execution flow：

1. Determine the target session's chatid lookup rule and chatid via chat_type
2. Confirm before sending: confirm the recipient and content with the user (e.g., "About to send to Zhang San: 'tomorrow's meeting is changed to 3 PM', confirm sending?"), and execute only after the user confirms
3. Call send_message to send (msgtype is fixed to text）
4. Display sending result

View messages and reply

User query example：

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

Execution flow：

1. First execute the "View chat history" flow (reuse the already obtained chatid and chat_type）
2. After displaying the messages, execute the "Send message" flow (must confirm 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 corresponding session was not found
• API error: display the specific error information and retry if necessary
• Network issue: on HTTP errors, proactively retry up to 3 times`