发送消息

建议先从文本消息开始调试，确认鉴权和目标会话都正确后，再继续扩展图片和文件消息。

支持的会话场景

TypeX Bot 支持向单聊和群聊发送消息。

如果你的场景是单聊，只需要确认目标单聊会话 ID 正确
如果你的场景是群聊，需要先确保 Bot 已经进入目标群聊

接口说明

基本信息

项目	说明
地址	`https://api-coco.typex.im/open/robot/send_message`
方法	`POST`
Content-Type	`application/json`

请求头

Authorization: Bearer <bot_token>
Content-Type: application/json

请求参数

参数	类型	必填	说明
`msg_type`	int	是	消息类型：0-文本, 1-图片, 3-音频, 4-视频, 5-文件, 9-名片, 11-图文消息, 15-文件组消息, 16-卡片消息
`content`	object	是	消息内容，结构因 msg_type 而异（见下方示例）
`chat_id`	string	是	目标会话 ID
`thread_msg_id`	string	否	用于创建线程的主消息 ID，即本 API 返回的 id
`thread_id`	string	否	线程 ID，在该线程下发送消息
`visible_ids`	string[]	否	指定可见用户（TypeX UID 数组），不传则全员可见

响应格式

{
  "code": 0,
  "data": {
    "id": "",
    "chat_id": "",
    "thread_id": ""
  },
  "msg": "ok"
}

字段	说明
`data.id`	消息 ID
`data.chat_id`	会话 ID
`data.thread_id`	线程 ID（请求传了 thread_msg_id 时返回）

发送示例

发送文本

curl --location 'https://api-coco.typex.im/open/robot/send_message' \
--header 'Authorization: Bearer <bot_token>' \
--header 'Content-Type: application/json' \
--data '{
  "chat_id": "123456",
  "msg_type": 0,
  "content": {
    "text": "<p>Hello from TypeX Bot</p>"
  }
}'

发送 Markdown 文本

curl --location 'https://api-coco.typex.im/open/robot/send_message' \
--header 'Authorization: Bearer <bot_token>' \
--header 'Content-Type: application/json' \
--data-raw '
{
    "msg_type": 0,
    "content": {
        "is_markdown": true,
        "text": "<markdown text>"
    },
    "chat_id": "7602566729281049630"
}'

发送 @ 提及文本

curl --location 'https://api-coco.typex.im/open/robot/send_message' \
--header 'Authorization: Bearer <bot_token>' \
--header 'Content-Type: application/json' \
--data-raw '
{
    "msg_type": 0,
    "content": {
        "at_user_ids": [
            "7569868447471902876"
        ],
        "chat_id": "7602566729281049630",
        "reply_msg_id": "0",
        "text": "<p><at userid=\"7569868447471902876\">用户昵称</at>&nbsp;你好</p>"
    },
    "chat_id": "7602566729281049630"
}'

发送图片

需先通过上传接口获取资源地址。

curl --location 'https://api-coco.typex.im/open/robot/send_message' \
--header 'Authorization: Bearer <bot_token>' \
--header 'Content-Type: application/json' \
--data '{
    "msg_type": 1,
    "content": {
        "object_url": "https://api-coco.typex.im/chat/get/...",
        "width": 932,
        "height": 114
    },
    "chat_id": "7602566729281049630"
}'

content 字段	说明
`object_url`	上传接口返回的 address
`width`	上传接口返回的 width
`height`	上传接口返回的 height

发送音频

curl --location 'https://api-coco.typex.im/open/robot/send_message' \
--header 'Authorization: Bearer <bot_token>' \
--header 'Content-Type: application/json' \
--data '
{
    "msg_type": 3,
    "content": {
        "object_url": "https://api-coco.typex.im/chat/file?object_key=...",
        "duration_second": 5
    },
    "chat_id": "7602566729281049630"
}'

content 字段	说明
`object_url`	上传接口返回的资源地址
`duration_second`	音频时长（秒）

发送视频

curl --location 'https://api-coco.typex.im/open/robot/send_message' \
--header 'Authorization: Bearer <bot_token>' \
--header 'Content-Type: application/json' \
--data '
{
    "msg_type": 4,
    "content": {
        "duration_second": 11,
        "height": 760,
        "width": 1416,
        "thumb_url": "https://api-coco.typex.im/file/muti/download?object_key=...",
        "image_url": "https://api-coco.typex.im/file/muti/download?object_key=...",
        "video_url": "https://api-coco.typex.im/chat/file?object_key=..."
    },
    "chat_id": "7602566729281049630"
}'

content 字段	说明
`duration_second`	视频时长（秒）
`height` / `width`	视频缩略图尺寸
`thumb_url`	视频缩略图地址
`image_url`	视频截图地址
`video_url`	视频文件地址

发送文件

curl --location 'https://api-coco.typex.im/open/robot/send_message' \
--header 'Authorization: Bearer <bot_token>' \
--header 'Content-Type: application/json' \
--data '
{
    "msg_type": 5,
    "content": {
        "object_url": "https://api-coco.typex.im/chat/file?object_key=...",
        "file_name": "aaaa.zip",
        "file_size": 1000,
        "file_type": "application/zip"
    },
    "chat_id": "7602566729281049630"
}'

content 字段	说明
`object_url`	上传接口返回的资源地址
`file_name`	文件名
`file_size`	文件大小（字节）
`file_type`	MIME 类型

发送用户名片

curl --location 'https://api-coco.typex.im/open/robot/send_message' \
--header 'Authorization: Bearer <bot_token>' \
--header 'Content-Type: application/json' \
--data '
{
    "msg_type": 9,
    "content": {
        "via_type": 0,
        "via_user_id": "7569548038616650888"
    },
    "chat_id": "7602566729281049630"
}'

content 字段	说明
`via_type`	0-用户名片, 1-群名片
`via_user_id`	用户 TypeX UID（via_type=0 时）

发送群名片

curl --location 'https://api-coco.typex.im/open/robot/send_message' \
--header 'Authorization: Bearer <bot_token>' \
--header 'Content-Type: application/json' \
--data '
{
    "msg_type": 9,
    "content": {
        "via_type": 1,
        "via_chat_id": "7616707861858492432"
    },
    "chat_id": "7602566729281049630"
}'

content 字段	说明
`via_type`	0-用户名片, 1-群名片
`via_chat_id`	群聊 ID（via_type=1 时）

发送图文消息

支持混合图片与视频的多媒体图文消息。

curl --location 'https://api-coco.typex.im/open/robot/send_message' \
--header 'Authorization: Bearer <bot_token>' \
--header 'Content-Type: application/json' \
--data-raw '
{
    "msg_type": 11,
    "content": {
        "at_user_ids": ["7568824950807606369"],
        "images": [
            {
                "height": 620,
                "object_url": "https://api-coco.typex.im/file/muti/download?object_key=...",
                "thumb_url": "https://api-coco.typex.im/file/muti/download?object_key=...",
                "width": 1672
            },
            {
                "duration_second": 11,
                "height": 760,
                "width": 1416,
                "thumb_url": "https://api-coco.typex.im/file/muti/download?object_key=...",
                "image_url": "https://api-coco.typex.im/file/muti/download?object_key=...",
                "video_url": "https://api-coco.typex.im/chat/file?object_key=..."
            }
        ],
        "text": "<p>图文消息内容</p>"
    },
    "chat_id": "7602566729281049630"
}'

images 元素字段	说明
`object_url`	图片地址
`thumb_url`	缩略图地址
`width` / `height`	图片尺寸
`video_url`	视频地址（可选，用于视频元素）
`image_url`	视频截图（可选）
`duration_second`	视频时长（可选）

发送文件组消息

curl --location 'https://api-coco.typex.im/open/robot/send_message' \
--header 'Authorization: Bearer <bot_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "msg_type": 15,
    "content": {
        "at_user_ids": ["7569868447471902876"],
        "files": [
            {
                "file_name": "aaaa_1.zip",
                "file_size": 150450,
                "file_type": "application/zip",
                "index": 0,
                "object_url": "https://api-coco.typex.im/chat/file?object_key=...",
                "status": 0
            },
            {
                "file_name": "aaaa.zip",
                "file_size": 150450,
                "file_type": "application/zip",
                "index": 1,
                "object_url": "https://api-coco.typex.im/chat/file?object_key=...",
                "status": 0
            }
        ],
        "text": "<p>文件组消息说明文字</p>"
    },
    "chat_id": "7602566729281049630"
}'

files 元素字段	说明
`file_name`	文件名
`file_size`	文件大小（字节）
`file_type`	MIME 类型
`index`	排序索引
`object_url`	文件地址
`status`	状态

发送卡片消息

支持自定义标题、内容及交互按钮。

curl --location 'https://api-coco.typex.im/open/robot/send_message' \
--header 'Authorization: Bearer <bot_token>' \
--header 'Content-Type: application/json' \
--data '
{
    "msg_type": 16,
    "content": {
        "title": "卡片标题",
        "content": "卡片正文内容，支持换行。",
        "buttons": [
            {
                "button_id": "btn_1",
                "text": "打开链接",
                "action_type": 2,
                "url": "https://example.com"
            },
            {
                "button_id": "btn_2",
                "text": "回调",
                "action_type": 1,
                "url": "https://your-callback.com/hook",
                "action_value": "{\"custom\": \"data\"}"
            }
        ]
    },
    "chat_id": "7602566729281049630"
}'

content 字段	说明
`title`	卡片标题
`content`	卡片正文
`buttons`	按钮数组

button 字段	类型	说明
`button_id`	string	按钮唯一标识
`text`	string	按钮文字
`action_type`	int	1-回调, 2-打开链接
`url`	string	回调地址或链接地址
`action_value`	string	回调时携带的额外数据（action_type=1 时）

支持的会话场景​

接口说明​

基本信息​

请求头​

请求参数​

响应格式​

发送示例​

发送文本​

发送 Markdown 文本​

发送 @ 提及文本​

发送图片​

发送音频​

发送视频​

发送文件​

发送用户名片​

发送群名片​

发送图文消息​

发送文件组消息​

发送卡片消息​

支持的会话场景

接口说明

基本信息

请求头

请求参数

响应格式

发送示例

发送文本

发送 Markdown 文本

发送 @ 提及文本

发送图片

发送音频

发送视频

发送文件

发送用户名片

发送群名片

发送图文消息

发送文件组消息

发送卡片消息