API
Send messages
Text, media, location, and related send methods.
Auth: Authorization: Bearer sbot_…
POST
Bot Token/api/v1/bots/sendMessagesendMessageSend Text消息
向指定会话发送文本消息，对外以机器人系统账号身份发送。
- Required:
chat_id(conversation ID),text(1-5000 UTF-16 code units after trimming leading and trailing whitespace). - Length behavior: one
sendMessagecall creates one message. The API never truncates or splits text automatically; oversized text returns HTTP 400, so callers may split it explicitly when needed. - Optional：
reply_to_message_id(引用回复：被引用消息的 ID，与 TG 同义)、reply_markup - Each InlineKeyboard button must choose exactly one target:
url(http(s) external link),callback_data(deliverscallback_query), oraction(in-app navigation). - Open a bot or regular user profile:
action: { type: "user_profile", user_id: "<system_user_id>" }. - Open a public group detail page:
action: { type: "public_group", group_id: "<group_id>" }; private, missing, or dissolved groups return 400. actionis handled by internal routing on Web, App, and desktop clients; it neither opens an external browser nor deliverscallback_query.- Returns：消息对象（含
message_id、chat、from、date） - 多媒体请使用
sendPhoto / sendDocument / sendVideo / sendAudio - 提示：
reply_to_message_id同样适用于sendPhoto/sendDocument/sendVideo/sendAudio/sendVoice/sendVideoNote/sendAnimation/sendSticker/sendLocation/sendVenue/sendDice/sendPoll/sendContact/sendMediaGroup（媒体组作用于首条）
POST
Bot Token/api/v1/bots/sendPhotosendPhoto发送图片消息
以图片形式发送已上传的文件，`file_id` 来自 `/files/complete`，或 credentials 秒传（`uploadRequired: false`）响应。
- Required：
chat_id、file_id - Optional：
caption(图片说明文字，附件配文本即混合消息)、reply_to_message_id(引用回复)、width/height(像素，数值，>0 时写入metadata.width / height) file_id对应 File 文档若已写入metadata.dimensions，平台会自动补齐- Returns：消息对象（
message_type=image）
POST
Bot Token/api/v1/bots/sendDocumentsendDocumentSend Document消息
以文档 / 附件形式发送已上传的文件。
- Required：
chat_id、file_id - Optional：
caption(附件配文本即混合消息)、reply_to_message_id(引用回复)、thumbnail_url(文件缩略图 URL，写入metadata.thumbnailUrl) - Returns：消息对象（
message_type=file）
POST
Bot Token/api/v1/bots/sendVideosendVideoSend Video消息
以视频形式发送已上传的文件。
- 必填：
chat_id、file_id - 可选：
caption(附件配文本即混合消息)、reply_to_message_id(引用回复)、duration(秒)、width/height(像素)、thumbnail_url - 所有可选字段
>0/ 非空时才写入metadata.*；未提供时客户端会在播放时自动读取元数据 - 返回：消息对象（
message_type=video）
POST
Bot Token/api/v1/bots/sendAudiosendAudioSend audio message
Send an audio file (music/podcast). Use sendVoice for voice-note bubbles.
- Required：
chat_id、file_id - Optional:
caption,reply_to_message_id,duration(seconds),performer,title performer/title主要面向音乐 / 播客场景，进入metadata与 Webhook Updatemessage.file- Returns：消息对象（
message_type=audio）
POST
Bot Token/api/v1/bots/sendLocationsendLocation发送位置消息
发送一个包含经纬度和可选地名的位置消息。
- Required：
chat_id、latitude、longitude - Optional：
name(地点名)、address(结构化地址) - Returns：消息对象（
message_type=location）
POST
Bot Token/api/v1/bots/sendVenuesendVenue发送地点
在 `sendLocation` 基础上要求标题；客户端会以「带标题地址卡片」样式展示。
- Required：
chat_id、latitude、longitude、title - Optional：
address、reply_markup - Returns：消息对象（
message_type=venue，metadata.isVenue=true）
POST
Bot Token/api/v1/bots/sendVoicesendVoiceSend Voice消息
与 `sendAudio` 同样上传后用 `file_id` 发送；客户端按「语音气泡」样式渲染。
- Required：
chat_id、file_id - Optional：
caption、duration(秒)、performer、title - Returns：消息对象（
message_type=voice）
POST
Bot Token/api/v1/bots/sendVideoNotesendVideoNoteSend Video笔记
圆形短视频；客户端会按 `width = height` 圆形播放器渲染。
- Required：
chat_id、file_id - Optional：
duration或length(秒)、width/height(像素)、thumbnail_url - Returns：消息对象（
message_type=video_note）
POST
Bot Token/api/v1/bots/sendAnimationsendAnimation发送动图
通常是 GIF / MP4 短动画；客户端按视频自动循环播放。
- Required：
chat_id、file_id - Optional：
caption、duration(秒)、width/height(像素)、thumbnail_url - Returns：消息对象（
message_type=animation）
POST
Bot Token/api/v1/bots/sendStickersendStickerSend Sticker
`file_id` 来源同其他多媒体；推荐 webp / lottie。
- Required：
chat_id、file_id - Optional：
width/height、thumbnail_url - Returns：消息对象（
message_type=sticker）
POST
Bot Token/api/v1/bots/sendDicesendDiceSend Dice / Random Emoji
服务端掷点；🎲 / 🎯 / 🏀 / ⚽ / 🎳 / 🎰 等表情各自有不同取值区间。
- Required：
chat_id - Optional：
emoji(默认🎲；🎰 → 1–64，⚽/🏀 → 1–5，其余默认 1–6)、reply_markup - Returns：消息对象（
message_type=dice；metadata.diceEmoji/metadata.diceValue，text形如🎲 4）
POST
Bot Token/api/v1/bots/sendPollsendPollSend Poll
当前仅支持 `regular` / `quiz` 两种类型；客户端以投票气泡渲染。
- Required：
chat_id、question、options[](2..12) - Optional:
is_anonymous(defaulttrue),type(regular/quiz),correct_option_id(Required forquiz),reply_markup - Returns：消息对象（
message_type=poll；metadata.poll = { question, options, ... }）
POST
Bot Token/api/v1/bots/sendContactsendContactSend Contact
客户端以名片气泡展示电话号码与姓名。
- Required：
chat_id、phone_number、first_name - Optional：
last_name、reply_markup - Returns：消息对象（
message_type=contact；metadata.contact = { phone_number, first_name, last_name }）
POST
Bot Token/api/v1/bots/sendMediaGroupsendMediaGroupSend Media Group
将 2..10 条媒体作为一组发送；平台会拆分为多条独立消息存储，仅最后一条带 `reply_markup`。
- 必填：
chat_id、media[](2..10) media[i]必填：type(photo/video/document/audio)、media或file_id；可选caption- 可选：
reply_markup(仅作用于最后一条)、reply_to_message_id(引用回复，仅作用于首条) - 返回：消息对象数组
POST
Bot Token/api/v1/bots/sendChatActionsendChatAction
Broadcast chat action（`typing` / `upload_photo` 等）。Client shows "typing..." for 3..5s.
- Required：
chat_id、action（如typing/upload_photo/record_voice等） - Returns：
{ ok: true }