wecomcli-message

WeCom send message

Before executing any wecom-cli command, you must first read and complete the common prerequisite check of the wecomcli-shared skill.

1. Messages can be sent to the authorized person.
2. Messages can be sent to chat sessions (single chats and group chats) other than the authorized person with which the bot has recently exchanged messages.

Scope of application

Applicable

• Applicable to sending messages to the authorized person, use wecom-cli identity whoami to obtain the authorized person ID, which can be used as chat_id , without calling sessions list。
• Applicable to querying the range of chat sessions to which messages can currently be sent and sending Markdown messages, images, files, AMR voice, or videos to members or group chats within these ranges

Not applicable

• The send target is not the authorized person and is not in the results returned by this sessions list → inform the user that currently messages can only be sent to recently active sessions or the authorized person

Skill dependencies

Before calling a dependent skill, you must first fully read the corresponding SKILL.md。

Dependent skill	Trigger scenario	Data flow
wecomcli-media	When sending images, files, voice, or videos, there is only a local file path, and there is no directly reusable media_id	Contains the media upload interface; if there is no existing media_id, you must first read that skill to obtain media_id; the type passed during upload should be aligned with themsg_type used when sending

Get the list of sessions to which messages can be sent

Command

wecom-cli message aibot sessions list

Return

Field	Type	Description
sessions	array	Session list, sorted from newest to oldest by the time of the last message; the exact number is subject to the actual response
sessions[].chat_id	string	Session ID
sessions[].chat_name	string	Group name or single chat name
sessions[].chat_type	string	single Single chat or group Group chat
sessions[].last_msg_time	string	Time of the last message, format YYYY-MM-DD HH:MM:SS
sessions_count	integer	sessions Number of array elements

chat_id Source

To send messages to users other than the authorized person, before calling wecom-cli message aibot send , you need to first call sessions listonce, then select the target item from the sessions[] returned this time, and copy that item's chat_id as-is to send.chat_id。

None of the following values can be directly used as send.chat_id：

• ID entered by the user
• Saved from previous rounds or historical context chat_id
• wecomcli-contact returned by userid
• Values constructed by oneself based on name, group name, or other fields

These values can at most serve as matching clues; the final send parameters must be newly taken from the matching item of this sessions list .

Target session matching

• Chat name: In this sessions[] , match exactly by non-empty chat_name ; if an exact match cannot be made, ask the user to confirm the send target; when there is a unique hit, copy chat_id。
• The most recent first/most recent certain session: Select the item explicitly specified by the user according to the original order of sessions[] .
• User-provided ID: can only be checked for exact equality with this sessions[].chat_id ; after a match, still copy from the matched item chat_id, and must not directly reuse the user input value.

Match result handling:

• When there is a unique match, continue sending.
• When there are multiple chat session candidates, display the chat name and last message time in the returned order, and let the user choose.
• After the user completes the selection, sessions listmust be called again, and then the selected object must be used to match the return value of that call.
• When there is no match, stop sending and truthfully inform the user that the target is not among the most recent 10 sessions; do not accept an external chat_id to bypass the restriction.
• sessions_count=0 , stop sending and inform the user that there is currently no recent session available to send to.
• When displaying the session list, keep the API's original order; display the name and time, and do not display internal chat_id。

Send message

Prerequisites

Before calling this API, the following steps must be completed:

1. Choose to call wecom-cli message aibot sessions listto get chat_id or wecom-cli identity whoami to get the authorizer ID, according to the send target.
2. Uniquely match the target in this list.
3. If sending to an object other than the authorizer, copy sessions[].chat_id。
4. When the target is a media message, also prepare the corresponding media_id。

Before the target session is successfully matched, do not upload media, and do not call send。

Command

wecom-cli message aibot send --json '<JSON 参数>'

Common parameters

Field	Type	Required	Description
chat_id	string	Yes	Must be taken from wecom-cli identity whoami or the target returned by sessions list just called in the current sending flow sessions[].chat_id
msg_type	string	Yes	markdown / image / file / voice / video
markdown	object	Conditionally required	Only msg_type="markdown" when
image	object	Conditionally required	Only msg_type="image" when
file	object	Conditionally required	Only msg_type="file" when
voice	object	Conditionally required	Only msg_type="voice" when
video	object	Conditionally required	Only msg_type="video" when

Each request must carry exactly one content object with the same name as msg_type . Do not pass an empty object, and do not pass multiple message objects at the same time.

Markdown message

markdown.content Required, maximum 20480 UTF-8 bytes. Plain text is also sent as Markdown.

wecom-cli message aibot send --json '{
  "chat_id": "<本次 sessions[].chat_id>",
  "msg_type": "markdown",
  "markdown": {
    "content": "<markdown 消息内容>"
  }
}'

Image message

image.media_id Required, must be obtained by uploading through the media upload API with type=image .

wecom-cli message aibot send --json '{
  "chat_id": "<本次 sessions[].chat_id>",
  "msg_type": "image",
  "image": {
    "media_id": "<media_id>"
  }
}'

File message

file.media_id Required, must be obtained by uploading through the media upload API with type=file ; the file name uses the original file name at upload time.

wecom-cli message aibot send --json '{
  "chat_id": "<本次 sessions[].chat_id>",
  "msg_type": "file",
  "file": {
    "media_id": "<media_id>"
  }
}'

Voice message

voice.media_id Required, must be obtained by uploading through the media upload API with type=voice ; the source file only supports AMR format, and it is not allowed to just change the extension to fake AMR.

wecom-cli message aibot send --json '{
  "chat_id": "<本次 sessions[].chat_id>",
  "msg_type": "voice",
  "voice": {
    "media_id": "<media_id>"
  }
}'

Video message

Field	Required	Description
video.media_id	Yes	Obtained by uploading through the media upload API with type=video Upload to obtain
video.title	No	Maximum 128 UTF-8 bytes; if omitted, the original file name at upload time is used
video.description	No	Maximum 512 UTF-8 bytes; if omitted, no description is displayed

wecom-cli message aibot send --json '{
  "chat_id": "<本次 sessions[].chat_id>",
  "msg_type": "video",
  "video": {
    "media_id": "<media_id>",
    "title": "产品演示",
    "description": "本周版本的核心功能演示"
  }
}'

When the user does not provide a video title or description, omit the corresponding field directly; do not pass an empty string, and do not ask follow-up questions about non-required fields.

Key constraints

• When the user explicitly requests sending and the target and content are complete, execute directly without repeatedly asking for confirmation; when the target, content, or local file is missing, ask only about the missing item.
• When sending multiple messages in succession, there is no need to call send again before each sessions list or wecom-cli identity whoami, but if the context is compressed midway through consecutive sends, call it again to ensure chat_id is correct.
• chat_id、userid、media_id are all internal call values and must not be shown to the user.
• The limits for Markdown body text, video title, and description are calculated in UTF-8 bytes; when exceeded, do not silently truncate, ask the user to shorten it or explicitly agree to split it.
• After a successful send, only state the target and message type; do not fabricate a message ID.
• When the API fails, truthfully relay the error; do not use curl / Python or other methods to bypass wecom-cli。