49热聊 49Hot49热聊49Hot
浏览文档目录

API

消息发送

文本、媒体、位置等发送能力。

返回索引

鉴权： Authorization: Bearer sbot_…

POST/api/v1/bots/sendMessage
Bot Token

sendMessage发送文本消息

向指定会话发送文本消息，对外以机器人系统账号身份发送。

  • 必填：chat_id (会话 ID)、text (文本内容，去除首尾空白后为 1-5000 个 UTF-16 code units)
  • 长度行为：sendMessage 一次只创建一条消息，不会自动截断或拆分；超出上限返回 HTTP 400，调用方可按业务需要自行分条发送
  • 可选：reply_to_message_id (引用回复：被引用消息的 ID，与 TG 同义)、reply_markup
  • InlineKeyboard 按钮目标三选一：url (http(s) 外链)、callback_data (产生 callback_query)、action (App 内跳转)
  • 打开机器人或普通用户资料：action: { type: "user_profile", user_id: "<system_user_id>" }
  • 打开公开群详情：action: { type: "public_group", group_id: "<group_id>" }；私有 / 不存在 / 已解散群返回 400
  • action 用于 Web、App 和桌面客户端的站内跳转，不打开外部浏览器，也不会投递 callback_query
  • 返回：消息对象（含 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/api/v1/bots/sendPhoto
Bot Token

sendPhoto发送图片消息

以图片形式发送已上传的文件；`file_id` 来自 `/files/complete`，或 credentials 秒传（`uploadRequired: false`）响应。

  • 必填：chat_id、file_id
  • 可选：caption (图片说明文字，附件配文本即混合消息)、reply_to_message_id (引用回复)、width / height (像素，数值，>0 时写入 metadata.width / height)
  • file_id 对应 File 文档若已写入 metadata.dimensions，平台会自动补齐
  • 返回：消息对象（message_type=image）
POST/api/v1/bots/sendDocument
Bot Token

sendDocument发送文件消息

以文档 / 附件形式发送已上传的文件。

  • 必填：chat_id、file_id
  • 可选：caption (附件配文本即混合消息)、reply_to_message_id (引用回复)、thumbnail_url (文件缩略图 URL，写入 metadata.thumbnailUrl)
  • 返回：消息对象（message_type=file）
POST/api/v1/bots/sendVideo
Bot Token

sendVideo发送视频消息

以视频形式发送已上传的文件。

  • 必填：chat_id、file_id
  • 可选：caption (附件配文本即混合消息)、reply_to_message_id (引用回复)、duration (秒)、width / height (像素)、thumbnail_url
  • 所有可选字段 >0 / 非空时才写入 metadata.*；未提供时客户端会在播放时自动读取元数据
  • 返回：消息对象（message_type=video）
POST/api/v1/bots/sendAudio
Bot Token

sendAudio发送音频消息

以音频文件形式发送（音乐 / 播客等）；语音气泡请用 sendVoice。

  • 必填：chat_id、file_id
  • 可选：caption (附件配文本即混合消息)、reply_to_message_id (引用回复)、duration (秒)、performer (表演者 / 上传者)、title (曲目 / 标题)
  • performer / title 主要面向音乐 / 播客场景，进入 metadata 与 Webhook Update message.file
  • 返回：消息对象（message_type=audio）
POST/api/v1/bots/sendLocation
Bot Token

sendLocation发送位置消息

发送一个包含经纬度和可选地名的位置消息。

  • 必填：chat_id、latitude、longitude
  • 可选：name (地点名)、address (结构化地址)
  • 返回：消息对象（message_type=location）
POST/api/v1/bots/sendVenue
Bot Token

sendVenue发送地点

在 `sendLocation` 基础上要求标题；客户端会以「带标题地址卡片」样式展示。

  • 必填：chat_id、latitude、longitude、title
  • 可选：address、reply_markup
  • 返回：消息对象（message_type=venue，metadata.isVenue=true）
POST/api/v1/bots/sendVoice
Bot Token

sendVoice发送语音消息

与 `sendAudio` 同样上传后用 `file_id` 发送；客户端按「语音气泡」样式渲染。

  • 必填：chat_id、file_id
  • 可选：caption、duration (秒)、performer、title
  • 返回：消息对象（message_type=voice）
POST/api/v1/bots/sendVideoNote
Bot Token

sendVideoNote发送视频笔记

圆形短视频；客户端会按 `width = height` 圆形播放器渲染。

  • 必填：chat_id、file_id
  • 可选：duration 或 length (秒)、width / height (像素)、thumbnail_url
  • 返回：消息对象（message_type=video_note）
POST/api/v1/bots/sendAnimation
Bot Token

sendAnimation发送动图

通常是 GIF / MP4 短动画；客户端按视频自动循环播放。

  • 必填：chat_id、file_id
  • 可选：caption、duration (秒)、width / height (像素)、thumbnail_url
  • 返回：消息对象（message_type=animation）
POST/api/v1/bots/sendSticker
Bot Token

sendSticker发送贴纸

`file_id` 来源同其他多媒体；推荐 webp / lottie。

  • 必填：chat_id、file_id
  • 可选：width / height、thumbnail_url
  • 返回：消息对象（message_type=sticker）
POST/api/v1/bots/sendDice
Bot Token

sendDice发送骰子 / 随机表情

服务端掷点；🎲 / 🎯 / 🏀 / ⚽ / 🎳 / 🎰 等表情各自有不同取值区间。

  • 必填：chat_id
  • 可选：emoji (默认 🎲；🎰 → 1–64，⚽/🏀 → 1–5，其余默认 1–6)、reply_markup
  • 返回：消息对象（message_type=dice；metadata.diceEmoji / metadata.diceValue，text 形如 🎲 4）
POST/api/v1/bots/sendPoll
Bot Token

sendPoll发送投票

当前仅支持 `regular` / `quiz` 两种类型；客户端以投票气泡渲染。

  • 必填：chat_id、question、options[] (2..12)
  • 可选：is_anonymous (默认 true)、type (regular / quiz)、correct_option_id (quiz 时必填)、reply_markup
  • 返回：消息对象（message_type=poll；metadata.poll = { question, options, ... }）
POST/api/v1/bots/sendContact
Bot Token

sendContact发送联系人名片

客户端以名片气泡展示电话号码与姓名。

  • 必填：chat_id、phone_number、first_name
  • 可选：last_name、reply_markup
  • 返回：消息对象（message_type=contact；metadata.contact = { phone_number, first_name, last_name }）
POST/api/v1/bots/sendMediaGroup
Bot Token

sendMediaGroup发送媒体组

将 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/api/v1/bots/sendChatAction
Bot Token

sendChatAction发送输入状态

广播聊天状态（`typing` / `upload_photo` 等）。客户端展示 3..5s 的「正在输入…」。

  • 必填：chat_id、action（如 typing / upload_photo / record_voice 等）
  • 返回：{ ok: true }