wecomcli-message

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

企业微信发送消息

WeCom Message Sending

执行任何
wecom-cli
命令前，必须先读取并完成
wecomcli-shared
技能的公共前置检查。

可以向授权人发送消息。
可以向授权人以外的、机器人最近有消息往来的聊天会话（单聊和群聊）发送消息。

Before executing any
wecom-cli
command, you must first read and complete the public pre-checks of the
wecomcli-shared
skill.

You can send messages to the authorized user.
You can send messages to chat sessions (one-on-one chats and group chats) that the robot has recently exchanged messages with, excluding the authorized user.

适用范围

Scope of Application

适用

Applicable Scenarios

适用于给授权人发消息，使用
```
wecom-cli identity whoami
```
获取授权人ID，可作为
```
chat_id
```
使用，无需调用
```
sessions list
```
。
适用于查询当前有权限发送消息的聊天会话范围并给这些范围中的成员或群聊发送 Markdown 消息、图片、文件、AMR 语音或视频

Applicable for sending messages to the authorized user: Use
```
wecom-cli identity whoami
```
to obtain the authorized user ID, which can be used as
```
chat_id
```
without calling
```
sessions list
```
.
Applicable for querying the scope of chat sessions where you have permission to send messages, and sending Markdown messages, images, files, AMR voice or videos to members or group chats within these scopes

不适用

Inapplicable Scenarios

发送对象不是授权人且不在本次
```
sessions list
```
返回结果中 → 告知用户当前只能向最近活跃的会话或授权人发送

The recipient is not the authorized user and not in the result returned by this
```
sessions list
```
→ Inform the user that currently messages can only be sent to recent active sessions or the authorized user

技能依赖

Skill Dependencies

调用依赖技能前，必须先完整读取对应

SKILL.md

。

依赖技能	触发场景	数据流向
`wecomcli-media`	发送图片、文件、语音或视频时只有本地文件路径，没有可直接复用的 `media_id`	包含媒体上传接口，如没有已有的 `media_id` ，必须先阅读该技能获取 `media_id` ，上传时传入的 `type` 应和发送时的 `msg_type` 对齐

Before calling dependent skills, you must fully read the corresponding

SKILL.md

Dependent Skill	Trigger Scenario	Data Flow
`wecomcli-media`	When sending images, files, voice or videos, only the local file path is available and there is no reusable `media_id`	Includes media upload interfaces. If there is no existing `media_id` , you must first read this skill to obtain `media_id` . The `type` passed during upload must align with the `msg_type` used during sending

获取能发送消息的会话列表

Get the List of Sessions Where Messages Can Be Sent

命令

Command

bash

wecom-cli message aibot sessions list

bash

wecom-cli message aibot sessions list

Return Value

字段	类型	说明
`sessions`	array	会话列表，按最后一条消息时间从新到旧排序，具体数量以实际回包为准
`sessions[].chat_id`	string	会话 ID
`sessions[].chat_name`	string	群名称或单聊名称
`sessions[].chat_type`	string	`single` 单聊或 `group` 群聊
`sessions[].last_msg_time`	string	最后一条消息时间，格式 `YYYY-MM-DD HH:MM:SS`
`sessions_count`	integer	`sessions` 数组元素数量

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

chat_id

来源

Source of

chat_id

向授权人以外的用户发送消息，调用

wecom-cli message aibot send

前，需要先调用一次

sessions list

，然后从本次返回的

sessions[]

中选定目标项，把该项的

chat_id

原样复制到

send.chat_id

。

以下值都不能直接作为

send.chat_id

：

用户输入的 ID
之前轮次或历史上下文保存的
```
chat_id
```
```
wecomcli-contact
```
返回的
```
userid
```
根据姓名、群名或其他字段自行构造的值

这些值最多只能作为匹配线索；最终发送参数必须重新取自本次

sessions list

的匹配项。

When sending messages to users other than the authorized user, before calling

wecom-cli message aibot send

, you need to call

sessions list

first, then select the target item from the

sessions[]

returned this time, and copy the

chat_id

of that item to

send.chat_id

as is.

The following values cannot be directly used as

send.chat_id

ID entered by the user
```
chat_id
```
saved in previous rounds or historical context
```
userid
```
returned by
```
wecomcli-contact
```
Values constructed by yourself based on names, group names or other fields

These values can only be used as matching clues at most; the final sending parameters must be re-obtained from the matching items of this

sessions list

目标会话匹配

Target Session Matching

聊天名称：在本次
```
sessions[]
```
中按非空
```
chat_name
```
精确匹配；不能精确匹配需要向用户反问确认发送目标，唯一命中时从匹配项复制
```
chat_id
```
。
最近第一个/最近某个会话：按
```
sessions[]
```
原始顺序选择用户明确指定的项。
用户提供 ID：只能与本次
```
sessions[].chat_id
```
做完全相等校验；命中后仍从匹配项复制
```
chat_id
```
，不能直接复用用户输入值。

匹配结果处理：

唯一匹配时继续发送。
多个聊天会话候选时，按返回顺序展示聊天名和最后消息时间，让用户选择。
用户完成选择后，必须重新调用
```
sessions list
```
，再用选定对象匹配当次返回值。
无匹配时停止发送，如实告知目标不在最近 10 个会话中；不要接受外部
```
chat_id
```
绕过限制。
```
sessions_count=0
```
时停止发送，告知当前没有可发送的最近会话。
展示会话列表时保持接口原始顺序；展示名称和时间，不展示内部
```
chat_id
```
。

Chat Name: Exact match by non-empty
```
chat_name
```
in this
```
sessions[]
```
; if exact match is not possible, ask the user to confirm the sending target. Copy
```
chat_id
```
from the matching item when there is a unique hit.
First Recent/Recent Session: Select the item explicitly specified by the user according to the original order of
```
sessions[]
```
.
User-provided ID: Only perform exact equality check with this
```
sessions[].chat_id
```
; after hitting, still copy
```
chat_id
```
from the matching item, do not directly reuse the user-input value.

Processing of Matching Results:

Proceed to send when there is a unique match.
When there are multiple chat session candidates, display the chat names and last message times in the returned order and let the user choose.
After the user completes the selection, you must re-call
```
sessions list
```
, then match the selected object with the current return value.
Stop sending when there is no match, and truthfully inform the user that the target is not in the recent 10 sessions; do not accept external
```
chat_id
```
to bypass restrictions.
Stop sending when
```
sessions_count=0
```
, and inform the user that there are no recent sessions available for sending.
Keep the original order of the interface when displaying the session list; display the name and time, do not show the internal
```
chat_id
```
.

发送消息

Send Messages

前置条件

Preconditions

调用本接口前必须完成以下步骤：

根据发送对象选择调用

wecom-cli message aibot sessions list

获取

chat_id

或

wecom-cli identity whoami

获取授权人ID。

在本次列表中唯一匹配目标。
如果发送授权人以外的对象，从列表中匹配项原样复制
```
sessions[].chat_id
```
。
目标是媒体消息时，再准备对应的
```
media_id
```
。

在目标会话匹配成功前，不上传媒体，也不调用

send

。

Before calling this interface, you must complete the following steps:

Choose to call
```
wecom-cli message aibot sessions list
```
to obtain
```
chat_id
```
or
```
wecom-cli identity whoami
```
to obtain the authorized user ID according to the recipient.
Uniquely match the target in this list.
If sending to an object other than the authorized user, copy
```
sessions[].chat_id
```
from the matching item in the list as is.
Prepare the corresponding
```
media_id
```
when sending media messages.

Do not upload media or call

send

before the target session is successfully matched.

命令

Command

bash

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

bash

wecom-cli message aibot send --json '<JSON Parameters>'

公共参数

Public Parameters

字段	类型	必填	说明
`chat_id`	string	是	必须取自 `wecom-cli identity whoami` 或当前发送流程中刚调用的 `sessions list` 返回的目标 `sessions[].chat_id`
`msg_type`	string	是	`markdown` / `image` / `file` / `voice` / `video`
`markdown`	object	条件必填	仅 `msg_type="markdown"` 时传
`image`	object	条件必填	仅 `msg_type="image"` 时传
`file`	object	条件必填	仅 `msg_type="file"` 时传
`voice`	object	条件必填	仅 `msg_type="voice"` 时传
`video`	object	条件必填	仅 `msg_type="video"` 时传

每次请求必须且只能携带一个与

msg_type

同名的内容对象。不要传空对象，也不要同时传多个消息对象。

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

Each request must carry exactly one content object with the same name as

msg_type

. Do not pass empty objects, and do not pass multiple message objects at the same time.

Markdown 消息

Markdown Messages

markdown.content

必填，最长 20480 UTF-8 字节。普通文本也按 Markdown 发送。

bash

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

markdown.content

is required, with a maximum length of 20480 UTF-8 bytes. Plain text is also sent as Markdown.

bash

wecom-cli message aibot send --json '{
  "chat_id": "<Current sessions[].chat_id>",
  "msg_type": "markdown",
  "markdown": {
    "content": "<Markdown Message Content>"
  }
}'

图片消息

Image Messages

image.media_id

必填，必须由媒体上传接口以

type=image

上传获得。

bash

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

image.media_id

is required, which must be obtained by uploading via the media upload interface with

type=image

bash

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

文件消息

File Messages

file.media_id

必填，必须由媒体上传接口以

type=file

上传获得；文件名取上传时的原始文件名。

bash

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

file.media_id

is required, which must be obtained by uploading via the media upload interface with

type=file

; the file name is the original file name used during upload.

bash

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

语音消息

Voice Messages

voice.media_id

必填，必须由媒体上传接口以

type=voice

上传获得；源文件仅支持 AMR 格式，不能只改扩展名冒充 AMR。

bash

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

voice.media_id

is required, which must be obtained by uploading via the media upload interface with

type=voice

; the source file only supports AMR format, and you cannot pretend it is AMR by only changing the file extension.

bash

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

视频消息

Video Messages

字段	必填	说明
`video.media_id`	是	由媒体上传接口以 `type=video` 上传获得
`video.title`	否	最长 128 UTF-8 字节；省略时使用上传时的原始文件名
`video.description`	否	最长 512 UTF-8 字节；省略时不展示描述

bash

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

用户没有提供视频标题或描述时直接省略对应字段，不传空字符串，也不追问非必填字段。

Field	Required	Description
`video.media_id`	Yes	Obtained by uploading via the media upload interface with `type=video`
`video.title`	No	Maximum length of 128 UTF-8 bytes; if omitted, the original file name used during upload is used
`video.description`	No	Maximum length of 512 UTF-8 bytes; if omitted, no description is displayed

bash

wecom-cli message aibot send --json '{
  "chat_id": "<Current sessions[].chat_id>",
  "msg_type": "video",
  "video": {
    "media_id": "<media_id>",
    "title": "Product Demo",
    "description": "Core function demo of this week's version"
  }
}'

When the user does not provide a video title or description, directly omit the corresponding fields, do not pass empty strings, and do not ask about non-required fields.

关键约束

Key Constraints

用户明确要求发送且目标与内容完整时直接执行，不重复追问确认；缺少目标、内容或本地文件时只追问缺失项。
连续发送多条时，不用每次
```
send
```
前都重新调用
```
sessions list
```
或
```
wecom-cli identity whoami
```
，但连续发送中途上下文发生压缩时重新调用确保
```
chat_id
```
正确。
```
chat_id
```
、
```
userid
```
、
```
media_id
```
都是内部调用值，禁止面向用户展示。
Markdown 正文、视频标题和描述限制按 UTF-8 字节数计算；超限时不静默截断，请用户缩短或明确同意拆分。
发送成功后只说明目标和消息类型，不编造消息 ID。
接口失败时如实转达错误，不使用 curl / Python 等方式绕过
```
wecom-cli
```
。

Execute directly when the user clearly requests to send and the target and content are complete; do not repeatedly ask for confirmation. Only ask for missing items when the target, content or local file is missing.
When sending multiple messages continuously, you do not need to re-call
```
sessions list
```
or
```
wecom-cli identity whoami
```
before each
```
send
```
, but re-call to ensure the correctness of
```
chat_id
```
when the context is compressed during continuous sending.
```
chat_id
```
,
```
userid
```
, and
```
media_id
```
are internal call values, and it is forbidden to display them to users.
The length limits for Markdown content, video title and description are calculated by UTF-8 bytes; do not silently truncate when exceeding the limit, ask the user to shorten or explicitly agree to split.
After successful sending, only explain the target and message type, do not fabricate message IDs.
Truthfully convey errors when the interface fails, do not bypass
```
wecom-cli
```
using curl / Python or other methods.