API
Bot API 索引
本页是接口目录：下方每条 JWT 接口已含参数与返回说明；运行时接口请点开主题分类。如何拿 Token、拼请求头见「怎么接」。
怎么接（先看这里）
- 5 分钟上手 ：控制台申请机器人 → 审核通过 → 复制 Bot Token。
- 鉴权 ：控制台管理用账号 JWT；发消息 / Webhook 运行时用
Authorization: Bearer sbot_…。 - API 前缀形如
https://api.49chatapp.com/api/v1（以你环境网关为准；SDK 的 baseUrl 指到此处）。 - Node SDK / Java SDK 可少手写 HTTP；也可用 curl 直接调。
# 运行时（Bot Token）
curl -X POST "$API/bots/sendMessage" \
-H "Authorization: Bearer $SOCHAT_BOT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"chat_id":"<chat_id>","text":"hello"}'
# 控制台（账号 JWT）
curl -X GET "$API/bots/my" \
-H "Authorization: Bearer $SOCHAT_USER_JWT"开发者控制台 API（JWT）
申请、Token、Webhook 与投递日志——每条下方列出参数与返回；鉴权为账号 JWT。
POST
JWT/api/v1/bots/applicationsapplications提交机器人申请
登录用户提交创建申请，等待平台审核。审核通过前不会签发 Token。
- 鉴权：
Authorization: Bearer <账号 JWT>（开放平台控制台登录后获得，不是 sbot_ Token） - 必填：
name（≤100）、username（小写字母开头，仅 a-z0-9_，3–64，全局唯一） - 可选：
description、avatar（https URL）、scopes[]（默认["messages:send","messages:receive"]） - 返回：机器人对象（
review_status=pending）
GET
JWT/api/v1/bots/mymy我的机器人列表
列出当前账号提交的机器人，含审核态、运行态、Token 前缀。
- 鉴权：账号 JWT
- 返回：
{ items: [{ id, name, username, review_status, status, has_token, token_prefix, … }] }
GET
JWT/api/v1/bots/my/:id:id机器人详情
审核通过后首次读取可能返回仅显示一次的 one_time_token，请立即保存。
- 路径参数：
id（机器人 ID） - 返回：机器人资料、
webhook（脱敏）、command_menus、has_token/token_prefix - 可能含
one_time_token（仅首次可读，响应后即销毁——请立刻保存）
GET
JWT/api/v1/bots/my/:id/vouchers/templatestemplates联享券模板列表
查询机器人当前可用的联享券模板。
- 鉴权：账号 JWT；路径参数：
id（机器人 ID） - 机器人须审核通过、处于启用状态，并具有
vouchers:read权限 - 返回：
{ items: [{ id, externalTemplateId, name, status, issueLimit, issuedCount, … }] }
POST
JWT/api/v1/bots/my/:id/vouchers/templatestemplates创建联享券模板
为机器人创建联享券模板草稿；已关联开放应用时，草稿保存在该应用中。
- 鉴权：账号 JWT；机器人须具有
vouchers:templates:write权限 - 必填：
external_template_id、name、type、issuer_name、fulfiller_name、fulfillment_category、acquisition_source、validity、issue_limit；issue_limit为0时不限制累计发放量 - 当前履约范围：
physical_goods、offline_service、ecommerce_discount、app_credit；返回草稿模板
POST
JWT/api/v1/bots/my/:id/vouchers/templates/:templateId/submitsubmit提交联享券模板审核
将草稿或已驳回的联享券模板提交平台审核。
- 鉴权：账号 JWT；路径参数：
id（机器人 ID）、templateId（模板 ID） - 机器人须具有
vouchers:templates:write权限 - 仅
draft/rejected可提交；成功后状态变为reviewing
PATCH
JWT/api/v1/bots/my/:id:id更新机器人资料
审核通过后更新名称、头像、短描述/关于、外链、Inline/好友策略/群隐私等。
- 路径参数：
id；仅review_status=approved可改 - 可选 body：
name、avatar、description、short_description、about、cover_url、links、contact - 可选：
supports_inline_queries、friend_request_mode、group_privacy等（与控制台「资料展示」一致） username不开放自助修改；返回更新后的机器人对象
POST
JWT/api/v1/bots/my/:id/webhookwebhook配置 Webhook
用账号 JWT 登记 HTTPS Webhook，无需 Bot Token。
- 路径参数：
id - 必填：
url（必须https://；平台会做 SSRF 校验） - 强烈建议 / 投递必需：
secret_token（未配置则投递失败） - 可选：
allowed_updates[]、allowed_ips[]、max_connections(1..100)、drop_pending_updates - 副作用：
Bot.delivery_mode = webhook；也可用 Bot Token 调POST /bots/setWebhook
DELETE
JWT/api/v1/bots/my/:id/webhookwebhook删除 Webhook
删除后投递模式切到 polling，可用 getUpdates。
- 路径参数：
id - 可选 body/query：
drop_pending_updates - 返回：
bot_id/delivery_mode=polling等；随后可用POST /bots/getUpdates
GET
JWT/api/v1/bots/my/:id/deliveriesdeliveries投递日志
分页查看 Webhook 投递状态，含 failed / dead_letter。
- 路径参数：
id - 可选 query：
page（默认 1）、limit（1–100，默认 20） - 返回：
{ items: [{ id, update_id, status, attempts, last_http_status, last_error, … }], pagination }
POST
JWT/api/v1/bots/my/:id/regenerate-tokenregenerate-token重新生成 Token
旧 Token 立即失效；响应中的 one_time_token 仅本次可见。
- 路径参数：
id；要求review_status=approved - 返回：
{ bot_id, one_time_token, token_prefix }——请立刻保存one_time_token
GET
JWT/api/v1/bots/my/:id/metricsmetrics机器人用量指标
查看该机器人近期调用量、错误与配额相关摘要（开发者控制台用）。
- 路径参数：
id（机器人 ID） - 返回：机器人运行指标摘要
POST
JWT/api/v1/bots/my/:id/deliveries/:deliveryId/retryretry重试投递
对 failed / 可重试的投递记录手动触发一次重新投递。
- 路径参数：
id（机器人 ID）、deliveryId（投递记录 id 或 update_id） - 返回：重试后的投递状态
运行时 API（按主题）
点开分类查看每个方法的参数与返回；均需 Authorization: Bearer sbot_…
机器人信息查询与更新机器人自身资料、命令菜单。15 个方法Webhook / 长轮询setWebhook 与 getUpdates 互斥；本地调试先删 Webhook。4 个方法消息发送文本、媒体、位置等发送能力。16 个方法编辑 / 撤回 / 转发修改或撤回机器人自己发出的消息，以及转发/复制。5 个方法文件上传先 upload 拿 file_id，再用于 send*。3 个方法富交互 / Inline ModeInline Keyboard、Callback、Inline Query。2 个方法群信息读取读取会话与成员信息；机器人须为活跃参与者。5 个方法群信息修改改群资料、置顶等；通常需要管理员权限。6 个方法群治理踢人 / 封禁 / 解封（群管理员权限）。3 个方法调度成员虚拟成员调度相关接口。2 个方法联享券附属联享券能力：关联开放应用后，以机器人身份在会话中发券。3 个方法