wecomcli-message

wecom-cli is a tool provided by the plugin, not a terminal command: all operations are completed by calling this tool, and parameters should be passed using args . It is prohibited to use it through command-line methods such as exec / shell / terminal.

⚠️ Prerequisite: Before calling wecom-cli for the first time, you must perform the prerequisite check according to the wecomcli-preflight skill to ensure the tool has been added to the whitelist.

WeCom send message

Messages can be sent to the authorized person.
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 for sending messages to the authorized person, use wecom-cli identity whoami to obtain the authorized person ID, which can be used as chat_id , no need to call sessions list。
Applicable for querying the chat session scope currently authorized to receive messages and sending Markdown messages, images, files, AMR voice, or videos to members or group chats within these scopes

Not applicable

The sending target is not the authorized person and is not in the result 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 no directly reusable `media_id`	includes a 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 the`msg_type` used when sending

Get the session list to which messages can be sent

How to call

Use the wecom-cli tool and call it in the following format

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 specific 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	Last message time, 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：

User-input ID
saved in previous turns or historical context chat_id
wecomcli-contact returned userid
Values constructed by oneself based on names, group names, or other fields

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

Target session matching

Chat name: in this sessions[] by non-empty chat_name Exact match; if no exact match, ask the user to confirm the send target; when there is a unique hit, copy from the matched item chat_id。
the most recent first/most recent certain conversation: according to sessions[] original order, select the item explicitly specified by the user.
User provides ID: it can only be checked for exact equality against this sessions[].chat_id ; after a hit, still copy from the matched item chat_id, and the user input value must not be reused directly.

Matching result handling:

When there is a unique match, continue sending.
When there are multiple chat conversation candidates, display the chat name and last message time in the returned order and let the user choose.
After the user completes the selection, you must call sessions listagain, then use the selected object 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 conversations; do not accept external chat_id to bypass the restriction.
sessions_count=0 When this occurs, stop sending and inform the user that there is currently no recent conversation available for sending.
When displaying the conversation 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:

Select and call based on the send target wecom-cli message aibot sessions listto get chat_id or wecom-cli identity whoami to get the authorizer ID.
Uniquely match the target in this list.
If sending to an object other than the authorizer, copy verbatim from the matched item in the list sessions[].chat_id。
When the target is a media message, also prepare the corresponding media_id。

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

Invocation method

Use the wecom-cli tool to call according to the format below

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 the `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 passed when `msg_type="markdown"` Only pass when msg_type="markdown"
`image`	object	Conditionally required	Only passed when `msg_type="image"` Only pass when msg_type="image"
`file`	object	Conditionally required	Only passed when `msg_type="file"` Only pass when msg_type="file"
`voice`	object	Conditionally required	Only passed when `msg_type="voice"` Only pass when msg_type="voice"
`video`	object	Conditionally required	Only passed when `msg_type="video"` Only pass when msg_type="video"

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.

Use the wecom-cli tool to call according to the format below

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 the media upload API with type=image upload.

Use the wecom-cli tool to call according to the format below

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 the media upload API with type=file upload; the file name is the original file name at upload time.

Use the wecom-cli tool to call according to the format below

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 the media upload API with type=voice Obtained by uploading; the source file only supports the AMR format, and you cannot just change the extension to pass it off as AMR.

Use the wecom-cli tool to call it in the following format

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 via the media upload interface with `type=video` upload
`video.title`	No	Maximum 128 UTF-8 bytes; if omitted, the original filename at upload time is used
`video.description`	No	Maximum 512 UTF-8 bytes; if omitted, no description is displayed

Use the wecom-cli tool to call it in the following format

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 consecutively, there is no need to call send again before every sessions list or wecom-cli identity whoami, but if the context is compressed midway through consecutive sending, 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 users.
The Markdown body, video title, and description limits 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 interface fails, truthfully relay the error, and do not use curl / Python or other methods to bypass wecom-cli。

About this skill

Scope of application

Applicable

Not applicable

Skill dependencies

Get the session list to which messages can be sent

How to call

Return

chat_id Source

Target session matching

Send message

Prerequisites

Invocation method

Common parameters

Markdown message

Image message

File message

Voice message

Video message

Key constraints

`chat_id` Source