wecomcli-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 through wecom-cli msg <接口名> '<json入参>' .

---

API list

get_msg_chat_list — get chat 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 chats that have messages within a time range, with pagination support. See API details。

get_message — pull chat 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"}'

Pull message records within a specified time range based on chat type and ID, with pagination support. Supports text/image/file/voice/video message types, and only supports 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 obtain 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 most recent 7 days by default (7 days back from the current time)
• Restrictions: 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 chat 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 matching result: inform the user that none was found
• chat_type determination：get_msg_chat_list The returned result does not contain a chat 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 name

Process：

1. Call wecomcli-contact skill's get_userlist to get the user list
2. Establish a mapping relationship from userid to name
3. Display strategy：
   • Exact match: display name
   • 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, and must be executed even if the user does not actively ask:

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

---

Typical workflow

View session list

User query example：

• "See what chats I've had in the last week"
• "Who has sent me messages these past few days"

Execution flow：

1. Determine the time range (specified by the user 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, inform the user that there are more sessions available to continue viewing

View chat history

User query example：

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

Execution flow：

1. Determine the time range (specified by the user or default to the last 7 days)
2. Use chatid lookup rules to determine the target session's chatid and chat_type
3. Call get_message to fetch the message list
4. Call the wecomcli-contact skill's get_userlist to get the contacts and build a userid→name mapping
5. Count non-text messages: Iterate through the message list and count msgtype non- text messages (image/file/voice/video) by quantity and type
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: Inform the user of 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 get_msg_media one by one; the interface will automatically download the files and return local_path
   • Check the file extension: After each file download is complete, 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), automatically add the correct extension based on content_type (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 that the file can be read normally (file size > 0); if the file is empty or corrupted, inform the user that the file download is abnormal
   • ⚠️ Do not use this on downloaded files MEDIA: Instruction: These files are historical attachments downloaded from the chat history; you only need to inform the user of the local storage path,strictly prohibitedvia MEDIA: instruction to resend to the user
8. ⚠️ must proactively inform the file location(this step cannot be skipped): after all files are downloaded and checked,must immediately and proactivelypresent the file storage directory and the full path of each file to the user 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 under 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 available to continue viewing

Send message

User query examples：

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

Execution flow：

1. Via chatid lookup rule determine the target conversation's chatid and 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 as text）
4. Display sending result

View messages and reply

User query examples：

• "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 (requires confirmation before sending)

---

Error handling

• Time range exceeded: inform the user of the 7-day limit and adjust to a valid range
• Conversation not found: clearly inform the user that the corresponding conversation was not found
• API error: display the specific error information, and retry if necessary
• Network issue: on HTTP error, proactively retry up to 3 times