wecom-msg

WeCom message skill

wecom_mcp is an MCP tool; all operations are completed by calling this tool.

⚠️ Prerequisite: before the first call to wecom_mcp , you must perform the prerequisite check according to the wecom-preflight skill to ensure the tool has been added to the whitelist.

Interact with the WeCom message system through wecom_mcp call msg <接口名> '<json入参>' .

---

API list

get_msg_chat_list — get conversation list

Use the wecom_mcp tool to call wecom_mcp call 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 — pull conversation messages

Use the wecom_mcp tool to call wecom_mcp call 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 according to the conversation 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

Use the wecom_mcp tool to call wecom_mcp call 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

Use the wecom_mcp tool to call wecom_mcp call 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)
• 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 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 and let the user choose
     • No matching result: inform the user that it was not found
• chat_type determination：get_msg_chat_list The return does not contain a conversation type field; 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 wecom-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 does not proactively ask:

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

---

Typical workflows

View conversation list

Example user queries：

• "Show me what chats I had in the past week"
• "Who 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 conversation list
3. Display the conversation name, last message time, and message count
4. If has_more is true, inform the user that there are more conversations to continue viewing

View chat history

Example user queries：

• "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. Determine chatid lookup rules to determine the target conversation's chatid and chat_type
3. Call get_message to pull the message list
4. Call wecom-contact '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 messages that are not text (image/file/voice/video) by count 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 file extensions: After each file download is complete, check local_path whether the corresponding file has the correct extension:
     • Based on get_msg_media 's returned content_type(MIME type) and name fields, determine:
       • If the filename is missing 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 matches content_type Inconsistent, use content_type as the standard for correction
     • After completing or correcting the suffix, rename the file to the correct filename
     • 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 MEDIA: instructions on downloaded files: These files are historical attachments downloaded from chat records. You only need to inform the user of the local storage path,strictly prohibitedto resend them to the user via MEDIA: instructions
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 files
   • If the user does not need to delete them, 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: The meeting tomorrow is changed to 3 PM"
• "Send a message in the project group: The meeting is at 3 PM this afternoon"

Execution flow：

1. Determine the target session's chatid lookup rule and chatid and chat_type
2. Confirm before sending: Confirm the recipient and content with the user (e.g., "About to send to Zhang San: 'The meeting tomorrow is changed to 3 PM'. Confirm sending?"), and execute after the user confirms
3. Call send_message to send (msgtype is fixed to text）
4. Show 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 records" 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
• Session not found: Clearly inform the user that the corresponding session was not found
• API error: Show the specific error message and retry if necessary
• Network issue: On HTTP errors, proactively retry up to 3 times`