Bot API Reference

// Success
{
  "success": true,
  "data": {
    "message_id": "6530ab12c9a0ff00123abc88",
    "chat": { "id": "6530ab12c9a0ff00123abc55", "type": "group" },
    "from": { "id": "<bot_user_id>", "is_bot": true },
    "text": "Hello",
    "date": 1735692000
  }
}

// Failure
{
  "success": false,
  "code": "VALIDATION",
  "message": "chat_id is required"
}

// 1) 文本消息（type=message）
{
  "update_id": "3fb4e65c-4d6b-4b0d-9d9a-3a1b9c4f0e12",
  "type": "message",
  "bot_id": "6530ab12c9a0ff00123abc01",
  "message": {
    "message_id": "6530ab12c9a0ff00123abc88",
    "from": { "id": "6530ab12c9a0ff00123ab801", "username": "alice", "is_bot": false },
    "chat": { "id": "6530ab12c9a0ff00123abc55", "type": "group", "title": "研发协作群" },
    "text": "/deploy status",
    "date": 1735689600
  }
}

// 2) 图片消息（type=photo；文件元数据在 message.file；width / height 等元数据若已知会一并带出）
{
  "update_id": "5ac9d1d4-3f9e-4a17-8dd6-7b0a1a3a8a01",
  "type": "photo",
  "bot_id": "6530ab12c9a0ff00123abc01",
  "message": {
    "message_id": "6530ab12c9a0ff00123abc91",
    "from": { "id": "6530ab12c9a0ff00123ab801", "username": "alice", "is_bot": false },
    "chat": { "id": "6530ab12c9a0ff00123abc55", "type": "group", "title": "研发协作群" },
    "text": "看下这张截图 @bot",
    "file": {
      "file_id": "6530ab12c9a0ff00123abcf2",
      "file_name": "screenshot.png",
      "mime_type": "image/png",
      "file_size": 204800,
      "url": "https://s3.example.com/bots/6530.../screenshot.png",
      "thumbnail_url": "https://s3.example.com/bots/6530.../screenshot_thumb.png",
      "width": 1920,
      "height": 1080
    },
    "date": 1735692000
  }
}

// 3) 消息编辑（type=edited_message，由 editMessage 触发）
{
  "update_id": "7c33b8f2-7d24-4f4b-8a2c-1f4b2e0e10bd",
  "type": "edited_message",
  "bot_id": "6530ab12c9a0ff00123abc01",
  "message": {
    "message_id": "6530ab12c9a0ff00123abc88",
    "chat": { "id": "6530ab12c9a0ff00123abc55" },
    "text": "/deploy status — 已更新",
    "date": 1735693500
  }
}

// 4) 消息撤回（type=message_deleted，由 deleteMessage 触发）
{
  "update_id": "91dd6d01-3c52-4c98-907e-6b8e8a01dd3a",
  "type": "message_deleted",
  "bot_id": "6530ab12c9a0ff00123abc01",
  "message": {
    "message_id": "6530ab12c9a0ff00123abc88",
    "chat": { "id": "6530ab12c9a0ff00123abc55" },
    "date": 1735695000
  }
}

// 5) 按钮点击（type=callback_query，5 秒内须调 answerCallbackQuery）
{
  "update_id": "8b3a1c0c-12cd-4e08-9def-2a7c33b9bd44",
  "type": "callback_query",
  "bot_id": "6530ab12c9a0ff00123abc01",
  "callback_query": {
    "id": "6530ab12c9a0ff00123abccb",
    "from": { "id": "6530ab12c9a0ff00123ab801", "username": "alice", "is_bot": false },
    "message": {
      "message_id": "6530ab12c9a0ff00123abc88",
      "chat": { "id": "6530ab12c9a0ff00123abc55", "type": "group" }
    },
    "data": "approve:order:123",
    "chat_instance": "6530ab12c9a0ff00123abc55"
  }
}

// 6) Inline 查询（type=inline_query，需 supports_inline_queries=true）
{
  "update_id": "2f6e6a51-c4ad-4d2f-bb6c-7f0e22115011",
  "type": "inline_query",
  "bot_id": "6530ab12c9a0ff00123abc01",
  "inline_query": {
    "id": "6530ab12c9a0ff00123abcd0",
    "from": { "id": "6530ab12c9a0ff00123ab801", "username": "alice", "is_bot": false },
    "query": "天气 北京",
    "offset": "",
    "chat_type": "private"
  }
}

// 7) 已读 / 已送达（type=message_read / message_delivered，仅原消息发送者为本机器人时触发）
{
  "update_id": "a1d92c52-2e94-44b4-be17-44b3ff97b3a4",
  "type": "message_read",
  "bot_id": "6530ab12c9a0ff00123abc01",
  "message": {
    "message_id": "6530ab12c9a0ff00123abc88",
    "chat": { "id": "6530ab12c9a0ff00123abc55", "type": "private" },
    "date": 1735695200
  }
}

// 8) 自己角色 / 群成员变化（须显式订阅 my_chat_member / chat_member / chat_join_request）
{
  "update_id": "c3e0a99a-3d5e-4f31-89e2-1c4b9c1d20a1",
  "type": "my_chat_member",
  "bot_id": "6530ab12c9a0ff00123abc01",
  "my_chat_member": {
    "chat": { "id": "6530ab12c9a0ff00123abc55", "type": "group", "title": "研发协作群" },
    "from": { "id": "6530ab12c9a0ff00123ab8aa", "username": "owner", "is_bot": false },
    "date": 1735695300,
    "old_chat_member": { "user": { "id": "<bot_user_id>", "is_bot": true }, "status": "member" },
    "new_chat_member": { "user": { "id": "<bot_user_id>", "is_bot": true }, "status": "administrator" }
  }
}

// 9) 好友申请（type=friend_request，需 friend_request_mode=manual）
{
  "update_id": "9bcb1f24-0d4b-4c1f-8b40-aaa3a4f3a201",
  "type": "friend_request",
  "bot_id": "6530ab12c9a0ff00123abc01",
  "friend_request": {
    "id": "6530ab12c9a0ff00123abccc",
    "from": { "id": "6530ab12c9a0ff00123ab801", "username": "alice", "is_bot": false },
    "request_message": "我是 ACME 客服，麻烦通过",
    "source": "search",
    "date": 1735695500
  }
}

import crypto from 'node:crypto'

/**
 * @param rawBody - 与平台计算签名时一致的原始字节
 * @param signatureHeader - 如 X-StarIM-Signature: sha256=...
 * @param secret - setWebhook 时配置的 secret_token
 */
export function verifyWebhookSignature(rawBody, signatureHeader, secret) {
  if (!signatureHeader || !secret) return false
  const body = typeof rawBody === 'string' ? Buffer.from(rawBody) : rawBody
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(body).digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(String(signatureHeader).trim())
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

const seen = new Set() // 生产环境请换 Redis / DB

function isDuplicateUpdate(updateId) {
  if (seen.has(updateId)) return true
  seen.add(updateId)
  return false
}

// POST /webhook — 验签通过后解析 Update，Echo 文本消息
app.post('/webhook/sochat', express.raw({ type: '*/*' }), async (req, res) => {
  const raw = req.body
  const sig = req.get('X-StarIM-Signature') || ''
  if (!verifyWebhookSignature(raw, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).end()
  }
  const update = JSON.parse(raw.toString('utf8'))
  if (isDuplicateUpdate(update.update_id)) {
    return res.status(200).json({ ok: true })
  }
  const text = update.message?.text
  const chatId = update.message?.chat?.id
  if (update.type === 'message' && text && chatId) {
    await fetch('https://www.sochatlive.com/api/v1/bots/sendMessage', {
      method: 'POST',
      headers: {
        Authorization: 'Bearer ' + process.env.BOT_TOKEN,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ chat_id: chatId, text }),
    })
  }
  res.status(200).json({ ok: true })
})