BeeIn OA API

#介紹

BeeIn 官方帳號（OA）讓你的服務能跟使用者透過 BeeIn 對話 — 推送通知、接收訊息、整合 AI 客服 / CRM / 排程系統都行。所有 OA 開發者面向的端點都在 https://webhook.beein.app/。

OA 整合分兩個方向：

• 主動：你呼叫 Bot API（/bot/*）發訊息給追蹤者、推媒體、查資料
• 被動：使用者跟你的 OA 互動時（傳訊、追蹤、HereLink 到點）我們戳你預設的 webhook URL

#驗證

每個官方帳號發行的 Bot API token 形如 oa_<short>_<random>，永遠以 oa_ 開頭。 Token 在 OA 後台「開發者 → Bot Token」頁面建立，建立時可指定權限（如 send_message、 broadcast、read_followers）。

所有請求都帶上：

Authorization: Bearer oa_xxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx

#快速開始 — 30 秒發第一封訊息

curl -X POST https://webhook.beein.app/bot/message \
  -H "Authorization: Bearer oa_xxxxxx_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientUserId": "69cecc429fc0e1d5abce2f24",
    "type": "text",
    "text": "Hello from BeeIn OA!"
  }'

成功回：

{
  "messageId": "69f558...",
  "sentAt": "2026-05-02T14:00:00.000Z",
  "delivered": true
}

#發送訊息給追蹤者

對「已追蹤你 OA 的使用者」單發一則訊息。沒追蹤過 OA 的使用者會被拒。

支援的 type

範例 — 文字

{
  "recipientUserId": "69cecc...",
  "type": "text",
  "text": "訂單已出貨，預計明天送達"
}

範例 — 卡片

{
  "recipientUserId": "69cecc...",
  "type": "oa.card",
  "payload": {
    "title": "今日特餐",
    "image": "https://your-cdn.com/menu.jpg",
    "body": "宮保雞丁套餐 NT$180",
    "actions": [
      { "label": "立即訂購", "url": "https://your-shop.com/order/123" }
    ]
  }
}

#推送媒體（圖片 / 影片 / 音訊 / 檔案）

媒體推送是兩步：先拿一個一次性 upload token（5 分鐘有效），把 bytes 直接 PUT 到 worker 寫入 R2， 再用拿到的 mediaId 發訊息。BeeIn 不會把任何 R2 credential 給你 — 你拿到的是經過簽章的 token， 只能寫到我們指定的 key。

Step 1 — 拿 upload token

{
  "mimeType": "image/png",
  "size": 234567
}

回：

{
  "uploadUrl": "https://webhook.beein.app/bot/media/upload",
  "token": "eyJ0aWQ...U2YzM4ZA",
  "tokenId": "69f5...",
  "expiresAt": "2026-05-02T14:05:00.000Z",
  "maxSize": 5242880,
  "mimeType": "image/png"
}

Step 2 — PUT bytes

curl -X PUT https://webhook.beein.app/bot/media/upload \
  -H "Authorization: Bearer eyJ0aWQ...U2YzM4ZA" \
  -H "Content-Type: image/png" \
  --data-binary @invoice.png

成功回：

{
  "ok": true,
  "mediaId": "69f5...",
  "downloadUrl": "/api/v1/media/69f5...",
  "expiresAt": "2026-05-16T14:00:00.000Z"
}

Step 3 — 用 mediaId 發訊息

{
  "recipientUserId": "69cecc...",
  "type": "image",
  "payload": { "mediaId": "69f5..." }
}

限制

#廣播給所有追蹤者

對「全部追蹤者」一次發一則訊息。後端做 batch 投遞 + 速率控管。

{
  "type": "text",
  "text": "今晚 10pm 系統維護，預計 30 分鐘完成"
}

#追蹤者列表

列出 / 查詢個別追蹤者。回傳僅含 OA 已被授權看到的欄位（displayName / avatarUrl / followedAt 等）， 不包含 email / phone 等隱私資料。

#輸入中 / 挑選貼圖中… 指示器

告訴對方「對方正在輸入…」或「對方挑選貼圖中…」。送或不送，由開發者自己決定 — 回應快的機器人可以完全不送；走 LLM / 慢後端的機器人送這個指示器，使用者體感會好很多。

請求欄位

範例 — 開始打字

{
  "recipientUserId": "69cecc...",
  "action": "start"
}

範例 — 開始挑貼圖

{
  "recipientUserId": "69cecc...",
  "action": "start",
  "intent": "sticker_picker"
}

範例 — 停止

{
  "recipientUserId": "69cecc...",
  "action": "stop"
}

客戶端收到的 WS 事件

{
  "event": "oa:typing",
  "data": {
    "oaId": "...",
    "oaName": "...",
    "conversationId": "...",
    "typing": true,
    "intent": "text",
    "senderType": "official_account",
    "source": "bot",
    "expiresAt": "2026-05-30T13:34:01.000Z"
  }
}

#取得 OA 可用貼圖

列出 OA 可發送的所有貼圖包 + 包內貼圖。BeeIn 的貼圖屬於使用者（不屬於 OA 本身） — OA 透過 OA 擁有者 (owner) 的貼圖授權發送：

• OA owner 在他自己帳號裡安裝的貼圖包 (UserSticker)
• OA owner 自己創作的貼圖包 (StickerPack.authorId)
• 只列已發佈 (status: "published") 的包；draft / removed 不列

回應

{
  "owner": "<OA owner userId>",
  "packs": [
    {
      "packId": "6a18...",
      "shortName": "neko01",
      "name": "貓貓貼圖",
      "isPublic": true,
      "status": "published",
      "authorId": "...",
      "stickers": [
        {
          "stickerId": "6a19...",
          "imageUrl": "https://r2.beein.app/stickers/.../01.png",
          "mimeType": "image/png",
          "tags": ["happy"],
          "order": 0
        }
      ]
    }
  ]
}

#發送貼圖

沿用 /bot/message 路徑，type 設 "sticker"， 帶 packId + stickerId。imageUrl 由 server 自動填， API 只處理 ID。

範例

{
  "recipientUserId": "69cecc...",
  "type": "sticker",
  "packId": "6a18...",
  "stickerId": "6a19..."
}

存取規則

跟 取得 OA 可用貼圖 一致 — 必須是 OA owner 安裝或創作的貼圖包，且包必須 status: "published"。 若 owner 沒這個包，發送會被擋下並回對應 error code。

錯誤碼

追蹤者收到的 message:new

{
  "event": "message:new",
  "data": {
    "message": {
      "id": "...",
      "senderId": "<oaId>",
      "type": "sticker",
      "text": "[貼圖]",
      "stickerImageUrl": "https://r2.../...png",
      "stickerId": "...",
      "packId": "..."
    }
  }
}

#接收事件 — Webhook 設定

當使用者跟你的 OA 互動（傳訊、追蹤、HereLink 到點觸發等），BeeIn 會主動 HTTP POST 你預設的 webhook URL。 這部分**從 OA 後台 → 開發者 → Webhook** 設定，不需要 API 呼叫。

必要條件

• HTTPS（不接受 http://、不接受 IP literal、不接受私網 hostname）
• Port 限 443 或 8443
• 儲存時必做 handshake：BeeIn 送 {"event":"webhook.test","challenge":"..."}， 你的 server 必須回 {"challenge_response":"<HMAC-SHA256(secret, challenge)>"}
• 之後每筆事件 timeout 10s，5xx 會 retry（5s → 30s → 2m → 10m → 30m，共 5 次）

Headers（每筆事件都會帶）

回應

回 2xx 表示已收到。回應 body 可選擇帶上立即回覆：

{
  "replies": [
    { "type": "text", "text": "收到，馬上請老師回覆" }
  ]
}

#事件清單

OA 在後台訂閱要接收的事件。建議只訂你真的會處理的，避免 retry 佔頻寬。

對話 — Conversation

追蹤 / 成員

HereLink（接送通知）

Event envelope

所有事件 body 都長這樣：

{
  "eventId": "evt_01HX...",
  "event": "oa.user.message",
  "version": "2026-05-02",
  "oaId": "69f4b404...",
  "conversationId": "69f4b9e1...",
  "timestamp": "2026-05-02T12:00:00.000Z",
  "deliveryAttempt": 1,
  "data": { /* 事件特定欄位 */ }
}

#簽章驗證

每筆 webhook 事件你都該驗章，否則任何人知道你 URL 都能偽造事件。

Node.js

const crypto = require('crypto');

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const ts  = req.headers['x-herelink-timestamp'];
  const sig = (req.headers['x-herelink-signature'] || '').replace('v1=', '');

  // 拒絕 5 分鐘外的時間戳（防 replay）
  if (Math.abs(Date.now() / 1000 - ts) > 300) return res.sendStatus(400);

  const expected = crypto.createHmac('sha256', MY_WEBHOOK_SECRET)
    .update(`${ts}.${req.body.toString('utf8')}`)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) {
    return res.sendStatus(401);
  }

  const body = JSON.parse(req.body);
  // ... 用 eventId 去重後處理 ...
  res.json({});
});

PHP

$ts = $_SERVER['HTTP_X_HERELINK_TIMESTAMP'] ?? '';
$sig = str_replace('v1=', '', $_SERVER['HTTP_X_HERELINK_SIGNATURE'] ?? '');
$body = file_get_contents('php://input');

if (abs(time() - $ts) > 300) http_response_code(400);

$expected = hash_hmac('sha256', "$ts.$body", $MY_WEBHOOK_SECRET);
if (!hash_equals($expected, $sig)) http_response_code(401);

#站台帳號連動（Linked Site）

讓你站台上的使用者可以聯絡上「不想公開 BeeIn 帳號」的站長 / 副站長 / 客服 / 業務， 同時讓那位被聯絡的人能看到「對方在我站台是誰」 — 而對方完全不知道自己連到了哪個 BeeIn 帳號。 隱私雙向保護：

• 對主動方（聯絡人）：只看到「副站長 Mark」字樣，不會知道對方 BeeIn 是 @mark
• 對被加方（管理員）：看到「@while = 論壇上的大白鯨（會員 5 年, 發文 200 篇）」，連動之後即使忘了也能查

角色分工

典型場景

• 論壇 / 社群：站長不想公開 BeeIn @id；用戶看到「聯絡副站長」按鈕點下去就能加上
• 客服 / 商家：客戶想找客服老闆；客服在 BeeIn 端看得到「VIP, 訂單 5 筆」站台資訊
• 學校 / 機構：家長想聯絡老師；老師在 BeeIn 看得到「某某學生家長」
• 供應商系統：供應商想找採購；採購看得到「合作 Tier-2, 交付 12 案」

整體流程（以論壇為例）

場景：XXX 討論區 — 站長 Monkey、副站長 Mark / Andy；論壇用戶大白鯨想找副站長 Mark。

1. 大白鯨在論壇上按「聯絡副站長 Mark」
2. 論壇後端 POST /linked-sites/qr：
   • targetBeeInId = @mark（被加方 — Mark 的 BeeIn ID，論壇後端記在 DB，前端絕不顯示）
   • siteUserInfoUrl = 大白鯨在論壇的 profile URL（給 Mark 之後查身份用）
   • siteUserId / siteUserName = 大白鯨在論壇的 ID / 帳號
   • displayName = 「大白鯨（會員 5 年）」
   • siteName = 「XXX 討論區」
3. 論壇拿到 qrContent + webUrl，顯示給大白鯨「請用 BeeIn 掃描 / 點此打開 BeeIn」
4. 大白鯨用 BeeIn app 開啟連結 → scanner = @while
5. BeeIn UI 顯示：「你正在加 XXX 討論區的副站長 Mark 為好友」（沒有 @mark 字樣）→ 大白鯨按確認
6. BeeIn server 建立連動：把 @while 跟 XXX 討論區的 whale123（QR 帶的 userName）綁起來，寫進 Mark 端的「連動列表」。不會主動 GET 你的站台 — 所有 member 細節都等被加方點卡片時才用 WebView 載。
7. Mark 的 BeeIn app 收到通知卡：「@while 連動到你 — 來自 XXX 討論區（大白鯨）」（卡片上只顯示建 QR 時帶的 displayName / inviteName，沒有 member 詳細欄位）。Mark 點卡片 → BeeIn 用 WebView 開 siteUserInfoUrl?username=whale123&beeinToken=… → 你的站台回 HTML 頁面，秀「會員 5 年, 發文 200 篇」等內容。
8. BeeIn 推 member.linked webhook 給論壇後端：「@mark 與大白鯨已連動」
9. 之後雙方在 BeeIn 一般訊息聊天 — Mark 即使忘了 @while 是誰，去「連動列表」一查就知道是論壇大白鯨

取得 Site API Key（bsk_xxx）

請在 BeeIn App 內申請 Site API Key — 一張獨立的長期金鑰，跟 OA Bot Token（oa_）完全分開。路徑：開啟 BeeIn App → 設定 → 開發者 / Linked Site → 新增站台金鑰，填入站名 / 用途 / 預估 MAU 等基本資訊，送出後即可取得 bsk_xxx（只顯示一次，請妥善 保存）。

#建立連動 QR

建一張一次性 QR，預設 1 小時有效，被掃過 / 被同意綁定就立即失效。

Body(v2.7.96 最精簡)

舊欄位 siteUserId / siteUserName 仍然接受,等同 userName / displayName。siteUserInfoUrl / siteName / webhookUrl 仍然接受但直接忽略(避免舊 client 收 400)。

範例

curl -X POST https://webhook.beein.app/linked-sites/qr \
  -H "Authorization: Bearer bsk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "targetBeeInId": "@mark",
    "userName":      "whale123",
    "displayName":   "大白鯨 (會員 5 年, 發文 200 篇)",
    "inviteName":    "大白鯨",
    "expiresIn":     1800
  }'

欄位對照:targetBeeInId = 被加方(管理員)的 BeeIn @username · userName = 主動方在你站台的 unique ID · displayName = 連動後卡片顯示名 · inviteName = QR 公開 landing page 顯示名 · expiresIn = QR 有效秒數

注意:範例為了講解可能會看到 // 註解,但實際 POST 時 body 不能含註解 — JSON 規格不支援,送出去會被 400 BAD_JSON 退回。

回應:

{
  "qrCode": {
    "_id":            "69f5...",                                              // ← linkId 雛形,App 內部用,不顯示給人
    "qrContent":      "beein://link/69f5...",                                 // App 掃這個 / 自己畫 QR
    "webUrl":         "https://beein.app/link/69f5...",                       // 手機點這個(著陸頁)
    "qrImageUrl":     "https://webhook.beein.app/linked-sites/qr/69f5.../image", // v2.7.99 ← 直接 <img src> 用
    "qrImageDataUri": "data:image/png;base64,iVBORw0K...",                    // v2.7.99 ← inline 預渲染好的 PNG
    "expiresAt":      "2026-05-02T15:00:00.000Z",
    "status":         "pending"
  }
}

直接拿圖用(v2.7.99)

不想自己跑 QR library?Server 已經幫你畫好 BeeIn 品牌 QR(中央 BeeIn icon、白色圓角底盤、H-level 容錯),兩種拿法:

• qrImageDataUri — base64 inline PNG。適合「建好之後直接渲染」場景,response 一拿到就能塞 <img src="...">,不會有額外 HTTP request。約 10–15 KB。
• qrImageUrl — 公開 GET endpoint,回傳一樣的 PNG。適合「QR 出現在第三方頁面、想吃 browser cache」場景。不需要 auth — payload 本來就公開(著陸頁 webUrl 顯示的也是同一張 QR)。掃過 / 過期後 image 仍可取(只是掃了會被 server 端拒收),所以 cache 5 分鐘是安全的。

<!-- 第三方站台一條 tag 把 BeeIn 品牌 QR 嵌進去 -->
<img src="https://webhook.beein.app/linked-sites/qr/69f5.../image"
     alt="Scan to add Moderator Mark on BeeIn"
     width="240" height="240" />

Server 自動串 ?username=(v2.7.96)

bsk_xxx 的 siteUserInfoUrl 設成 base URL 即可,每次 BeeIn 開啟某個 user 的頁面時自動 append:

用 Node URL API 處理,自動分辨 ? / &、自動 URL-encode 特殊字元。

⚠️ siteUserInfoUrl 必須回 HTML,不是 JSON

被加方點開 BeeIn 上的連動站台卡片 → BeeIn App 用 WebView 直接開 siteUserInfoUrl?username=…&viewer=…&beeinToken=… 給人類看。所以你必須在這個 URL 回 HTML(專屬呈現該 user 內容的頁面),不是 JSON。三個 query:

• username — 建 QR 時你帶的 userName(你站台 user 的 unique ID),用來反查要顯示哪個 user 的內容。
• viewer — 正在開這個 WebView 的 BeeIn 使用者的 @username(例: mark)。給你做 access log / 顯示「您好,@mark」之類用。v2.7.99 新增。
• beeinToken — 簽好的 short-lived JWT,證明這個 request 來自 BeeIn WebView 而不是有人偽造你的 URL。強烈建議驗。

<!doctype html>
<html lang="zh-TW">
<head>
  <meta charset="utf-8">
  <title>Alice 的會員資料</title>
  <style>body{font:15px/1.5 -apple-system,sans-serif;padding:24px;}</style>
</head>
<body>
  <h1>Alice ★</h1>
  <p>會員等級:VIP</p>
  <p>發文數:1,234 篇</p>
  <p>加入時間:2024-03-15</p>
  <!-- 你想擺什麼都行,完全你站台的設計 -->
</body>
</html>

驗 beeinToken JWT(v2.7.99)

用什麼當 HMAC secret:如果你的 bsk_xxx 沒設 webhookSecret(大部分人都沒設), BeeIn 會 fallback 用 sha256(bsk_xxx) 當 secret 來簽。你站台這邊 1 行 code 算出同樣的 secret 就能驗:

// PHP
$secret = hash('sha256', $BSK_XXX);  // 或用 $linkSite->webhookSecret 如果你有設

$decoded = \Firebase\JWT\JWT::decode(
  $_GET['beeinToken'],
  new \Firebase\JWT\Key($secret, 'HS256')
);
// $decoded->viewerUserId      = BeeIn user _id
// $decoded->viewerUsername    = @username (= $_GET['viewer'])
// $decoded->linkedSiteId      = 連動關係 _id
// $decoded->scannerId         = 主動方 BeeIn user _id
// $decoded->targetBeeInId     = 被加方 BeeIn user _id

// Node.js
const crypto = require('crypto');
const jwt = require('jsonwebtoken');
const secret = crypto.createHash('sha256').update(BSK_XXX).digest('hex');
const payload = jwt.verify(req.query.beeinToken, secret, { algorithms: ['HS256'] });

#改連動會員顯示名(v2.7.96)

當站台使用者在你站上改名時,呼叫這支同步更新 BeeIn 端連動卡片顯示名 —— 不用知道 BeeIn 內部的 linkId,用你站上的 userName(就是建 QR 時帶的那個 unique ID)當 key:

curl -X PATCH https://webhook.beein.app/linked-sites/member \
  -H "Authorization: Bearer bsk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "userName":    "alice123",        // 改名前後不變的 unique ID
    "displayName": "Alice ★ (VIP)"    // 新顯示名
  }'

回應:

{ "success": true, "updated": 1 }

錯誤碼

成功後 server 自動清掉相關連動的 member-info cache,下次 BeeIn UI refresh 就會看到新名字。

#連動站台 Webhook 簽章（v2.7.96）

BeeIn 主動 POST 你的 webhookUrl（建 bsk_xxx 時設的那個）時，會像 OA webhook 一樣 帶 HMAC-SHA256 簽章 header。驗章方式跟 OA webhook 完全一樣 — 直接看 #簽章驗證 的 Node.js / PHP 範例即可， 差別只在 secret 換成 bsk_xxx 的 webhookSecret。

會帶簽章的事件

Headers

每筆事件都會帶兩組 header(新舊並行,你選一組驗即可):

member.linked body 範例

{
  "event":          "member.linked",
  "qrCodeId":       "69f5...",           // 你建的 QR _id
  "scannerId":      "69ab...",           // 主動方 BeeIn userId
  "targetBeeInId":  "69cd...",           // 被加方 BeeIn userId
  "linkedSiteId":   "69ef...",           // BeeIn 端 LinkedSite 紀錄 _id
  "externalUserId": "whale123"           // 建 QR 時帶的 userName(你站台的 unique ID)
}

#用 BeeIn 登入 — 簡介

讓追蹤你官號 (OA) 的使用者用 BeeIn App 掃 QR 登入你的網站。共 4 步:OA 設定 → 放登入按鈕 → 處理 callback → 用 authCode 換 user。同意畫面內建,scope (email / avatar / phone) 由使用者勾選後 server 才會送對應欄位。

Base URL: https://webhook.beein.app · 設定 PATCH: https://api.beein.app/api/v1/oa/<OA_ID>/login-config

#Step 1 — OA 設定 (一次)

OA 後台到 Bot API Token 設定相關區域,新增 Token 時必須選取 manage_login_config 權限。

curl -X PATCH https://webhook.beein.app/bot/login-config \
  -H "Authorization: Bearer oa_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "notifyURL":  "https://your-site.example/auth/beein/notify",
    "successURL": "https://your-site.example/auth/beein/callback",
    "cancelURL":  "https://your-site.example/auth/beein/cancel",
    "allowedRedirectHosts":  ["your-site.example"],
    "allowedFrameAncestors": ["your-site.example"],
    "requestedScopes": ["email"]
  }'

Response 回傳目前設定。沒有 webhookSecret — notify body 是 server 發出的非機密資料(不含信用卡之類的東西),不需要簽章。真正驗證使用者身分的關卡是 Step 4 /exchange,那邊需要 Bot API token 才能換到使用者資料,所以即使有人亂猜 / 攔截到 notify payload 或 code,沒有你 OA 的 Bot API token 也換不出任何使用者身分。

讀目前設定:GET https://webhook.beein.app/bot/login-config(同樣的 token 認證)。

#Step 2 — 網站放登入按鈕

兩種方式擇一:

方式 A:redirect

<a href="https://webhook.beein.app/oa-login?oa=YOUR_OA_ID&state=RANDOM_NONCE">
  Sign in with BeeIn
</a>

方式 B:iframe 嵌入

<iframe src="https://webhook.beein.app/oa-login?oa=YOUR_OA_ID&state=RANDOM_NONCE"
  width="380" height="520" frameborder="0"></iframe>

官方登入按鈕 (建議使用)

直接複製下面這段 HTML 到你的網頁,使用者一眼就知道是 BeeIn 登入。預覽:

Sign in with BeeIn

<a href="https://webhook.beein.app/oa-login?oa=YOUR_OA_ID&state=RANDOM_NONCE"
   style="display:inline-flex;align-items:center;gap:10px;padding:10px 18px;
          border-radius:10px;background:#FFC107;color:#1a1a1a;
          font:600 15px/1 -apple-system,'Helvetica Neue','Noto Sans TC',sans-serif;
          text-decoration:none;box-shadow:0 1px 3px rgba(0,0,0,.12);">
  <img src="https://beein.app/assets/beein-signin-icon.png"
       alt="BeeIn" width="22" height="22"
       style="display:block;border-radius:5px;">
  Sign in with BeeIn
</a>

按鈕文字可改成你的語系(例:用 BeeIn 登入 / BeeIn でサインイン / 用 BeeIn 登录)。Icon 跟黃色 #FFC107 是 BeeIn 識別色,建議保留不要改 — 跟 LINE / Google / Apple 的官方登入按鈕同理,品牌一致使用者一眼認得。

URL 參數

支援的 lang 值

例:?oa=XXX&state=YYY&lang=ja → 強制日文介面;?oa=XXX&state=YYY(不帶 lang) → 自動偵測。

頁面行為:每 180 秒自動換 QR、掃描後即時隱藏 QR (顯示「已掃描」)、同意後跳 successURL、取消或逾時跳 cancelURL。

#Step 3 — 處理 callback

成功 callback

https://your-site.example/auth/beein/callback?authCode=ABC123XYZ&code=ABC123XYZ&state=RANDOM_NONCE

URL 同時帶 authCode 跟 code 兩個 query param,值一樣 — 建議讀 authCode(語意比較清楚);code 是 legacy 別名為了相容舊整合,任何一個都行。

1. 驗證 state 跟 Step 2 存下來的一樣 (CSRF)。不一樣 → 拒絕。
2. 拿 authCode 去 Step 4 換 user 身分。一次性,60 秒過期。

取消 callback

https://your-site.example/auth/beein/cancel?reason=cancelled|expired&state=RANDOM_NONCE

reason:cancelled (使用者按取消) 或 expired (3 分鐘沒掃 / 沒同意)。

#Step 4 — code 換 user 身分

必須帶 Bot API token(就是 Step 1 那把 oa_xxx,同一個 manage_login_config 權限)。server 會檢查 authCode 所屬的 OA 跟你的 token 所屬的 OA 是否一致 — 不一致一律回 404,所以即使有人攔截到 code 也換不出資料(他沒你的 token)。

curl -X POST https://webhook.beein.app/oa-login/exchange \
  -H "Authorization: Bearer oa_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"authCode": "ABC123XYZ"}'

Response:

{
  "userId":      "69cfe4500c5ec85a8402693f",
  "displayName": "黑貓電子科技",
  "username":    "mchotdog",
  "avatarUrl":   "https://media.beein.app/avatars/user/…webp",   ← 只有 scope 'avatar' 才有
  "email":       "[email protected]",                              ← 只有 scope 'email' 才有
  "phone":       null,                                            ← 只有 scope 'phone' 才有
  "oaId":         "69ee34c62900407b94948fa9",
  "grantedScopes": ["email", "avatar"],
  "approvedAt":   "2026-06-08T07:00:00.000Z"
}

v2.7.94 起,回傳是扁平結構:userId / displayName / username 直接在 top-level,不再 nested 在 user{} 下。

#(選) Notify webhook

除了 redirect callback,server 還會直接 POST 你的 notifyURL 通知你 — server-to-server,即使瀏覽器掉線也收得到。沒有簽章 header、沒有 HMAC、沒有 secret 要管。理由:body 內的資料是 server 發出的非敏感資訊,真正驗證身分的關卡在 /exchange(那裡才會檢查你的 Bot API token)。即使有人攔截到這個 POST 或亂猜你的 notifyURL 灌假資料,他沒你的 Bot API token 也換不出任何使用者身分。

POST <your notifyURL>
Content-Type: application/json

Body:

{
  "event":        "oa_login.approved",
  "oaId":         "69ee34c62900407b94948fa9",
  "sessionToken": "…",
  "state":        "<Step 2 帶的 state>",
  "user": {
    "userId":      "69cfe4500c5ec85a8402693f",
    "displayName": "黑貓電子科技",
    "avatarUrl":   "https://…"               ← scope 'avatar' 才有
  },
  "grantedScopes": ["email"],
  "email":      "[email protected]",          ← scope 'email' 才有
  "authCode":   "ABC123XYZ",                 ← 拿這個去 /exchange 才是權威身分
  "issuedAt":   "2026-06-08T07:00:00Z",
  "approvedAt": "2026-06-08T07:00:05Z"
}

#Scopes 規則

#錯誤碼

#MiniApp 簡介

MiniApp 是嵌在嗶應 App 中的 WebView 頁面，由 OA 自家網站 host。當追蹤者在 BeeIn 內打開你 的 MiniApp（例如下單、預約、表單），你的網頁可以直接以 OA 名義回傳訊息 到該追蹤者的對話視窗 — 不需要他先離開頁面、不需要他自己再開 chat。

授權方式 — contactToken

嗶應 App 在打開你的 MiniApp WebView 時，會自動把一個短期憑證 contactToken 透過 URL query 參數 ?ct=<token> 傳給你的網頁。 WebView 開啟期間，App 每 ~25 分鐘會自動 refresh 一次，以 postMessage 通知你的網頁更新本機變數。

你的 MiniApp 拿到這個 token，就能呼叫下方 endpoint 對該追蹤者發送訊息。

// 在 MiniApp 內讀取 token
const ct = new URLSearchParams(location.search).get('ct');

// 監聽 refresh
window.addEventListener('message', (e) => {
  if (e.data?.type === 'contactToken') {
    currentToken = e.data.token;
  }
});

限制

• contactToken 有效 30 分鐘，僅綁定當前這位追蹤者與 當前這個 OA。萬一外洩影響範圍非常小。
• 速率限制：每位追蹤者每小時最多 60 則訊息。
• 訊息固定以 OA 名義發送，落入該追蹤者與 OA 的私訊對話； 不能指定其他發送者。
• 所有 endpoint 都用 HTTPS，base URL 固定 https://webhook.beein.app。

#設計建議

• 必須 https://，不接受純 HTTP。
• 以手機優先，建議內容寬度 360 ~ 430px，自動適應大螢幕。
• 不要自製巨大頂部 nav — BeeIn 已提供 AppBar，頁面內只放業務內容。
• 每個 URL 都要能單獨重新載入（WebView 可能被系統回收或網路中斷重整）。
• 下單、預約、送出表單等關鍵動作必須由你的後端確認，不可只信前端狀態。
• 錯誤頁不要顯示 stack trace、Cloudflare 502 原始頁、內部 hostname 等內容。
• 需要更改 AppBar 標題 / 按鈕，請在 beein:ready 事件之後呼叫 window.beein.*。

#OA 管理員需要設定的內容

位置：BeeIn App → OA 管理區 → MiniApp 管理。

BeeIn 會用你貼上的公鑰加密 follower 身份，App 開 WebView 時把加密結果放在 X-BeeIn-Auth header（見下一節）。你的 server 用私鑰解密後即可建立自家網站 session。

#WebView 載入時 BeeIn 會送哪些資料

BeeIn App 在開啟 MiniApp 的 WebView 時，會把以下 header 與 query 一起送到你的網址：

GET https://shop.example.com/beein?ct=<contactToken>
X-BeeIn-Auth: <encrypted-auth-blob>
X-BeeIn-Theme: dark | light

#X-BeeIn-Auth 解密內容

合作方 server 用私鑰解密後，會拿到類似結構：

{
  "iss":         "beein.app",
  "aud":         "<oaId or miniapp id>",
  "sub":         "<BeeIn userId>",
  "personaId":   "<active persona id>",
  "displayName": "Mark",
  "email":       "[email protected]",
  "scopes":      ["user.id", "user.email"],
  "iat": 1779000000,
  "nbf": 1779000000,
  "exp": 1779000300,
  "nonce": "..."
}

必要驗證步驟：

1. 解密成功（私鑰可解開）。
2. iss === "beein.app"。
3. exp 未過期。
4. aud 對應到你的 OA / MiniApp。
5. 若需要會員綁定，用 sub 或 personaId 對應到自家會員。

建議第一次驗證成功後建立你自己的網站 session cookie，後續網頁內跳轉就依你自己 cookie 管理登入狀態。

#JS Bridge — window.beein

BeeIn 注入 bridge 後會觸發 beein:ready。建議用 helper 等待：

function withBeeIn(fn) {
  if (window.beein?.__installed__) return fn(window.beein);
  window.addEventListener('beein:ready', function once() {
    window.removeEventListener('beein:ready', once);
    fn(window.beein);
  });
}

常用 API

AppBar 範例

withBeeIn((beein) => {
  beein.setNav({
    title: '購物車',
    rightAction: { label: '結帳', style: 'primary', event: 'checkout' },
  });
  window.addEventListener('checkout', () => {
    document.querySelector('#checkout-form')?.requestSubmit();
  });
});

右上 icon 列

withBeeIn((beein) => {
  beein.setHeaderActions([
    { id: 'orders',  icon: 'receipt_long', tooltip: '歷史訂單' },
    { id: 'support', icon: 'support',      tooltip: '客服' },
  ]);
  window.__beein_event__ = (name, data) => {
    if (name === 'headerAction' && data.id === 'support') beein.openOaChat('<oaId>');
    if (name === 'headerAction' && data.id === 'orders')  location.href = '/orders';
  };
});

搜尋按鈕（內建建議清單）

withBeeIn((beein) => {
  beein.setHeaderActions([{
    id: 'shopSearch',
    type: 'search',
    icon: 'search',
    placeholder: '搜尋商品',
    submitTo: '/search?q={query}',
    suggestionsLabel: '熱門搜尋',
    suggestions: ['紅茶', '綠茶', '咖啡'],
  }]);
});

#MiniApp 發訊息給追蹤者

支援的 type

範例 — 文字

POST https://webhook.beein.app/miniapp/messages
Content-Type: application/json

{
  "contactToken": "eyJ...",
  "type":         "text",
  "text":         "訂單已收到，預計 30 分鐘內出餐"
}

範例 — 訂單卡片（含底部按鈕）

{
  "contactToken": "eyJ...",
  "type":         "order",
  "orderCard": {
    "orderId":     "A20260517-001",
    "status":      "pending_payment",
    "statusLabel": "待付款",
    "items": [
      { "name": "宮保雞丁套餐", "qty": 1, "price": 180 }
    ],
    "total": 180, "currency": "TWD"
  },
  "buttons": [
    {
      "id":     "view_order",
      "label":  "查看訂單",
      "style":  "primary",
      "action": "open_miniapp",
      "path":   "/order-complete/?order=A20260517-001"
    },
    {
      "id":        "tracking",
      "label":     "物流追蹤",
      "style":     "secondary",
      "action":    "open_miniapp",
      "path":      "/tracking/?order=A20260517-001",
      "textColor": "#FFFFFF",
      "bgColor":   "#FF9800"
    }
  ]
}

底部按鈕欄位 — buttons

每則訊息最多 4 個按鈕。text / order / media 任一 type 都可帶。

顏色提示：兩個欄位都不填，UI 依 style（primary / secondary / ghost）渲染預設 BeeIn 主題色。 填一個（只填文字色或只填背景色）也可，剩下的仍走預設。**對比與可讀性由你負責**—— server 不檢查白底白字之類的可用性問題。

Response

{
  "ok": true,
  "messageId":      "66e0...",
  "conversationId": "66ab...",
  "sentAt":         "2026-05-17T12:05:00.000Z"
}

PHP 範例 — 後端直接呼叫

MiniApp 後端在處理完訂單／表單後想主動推一則 OA 訊息給該追蹤者，可以從伺服器端直接打 webhook endpoint。 contactToken 由 BeeIn webview 帶到前端，你的前端再轉送給後端使用（token 30 分鐘內有效）。

<?php
// BeeIn MiniApp — 從後端送一則 OA 訊息給目前 follower
// 用法: php beein-send.php "<contactToken from BeeIn WebView>"

$contactToken = $argv[1] ?? '';
if ($contactToken === '') {
    fwrite(STDERR, "Usage: php beein-send.php <contactToken>\n");
    exit(2);
}

$origin   = 'https://your-miniapp.example.com';   // 你的 MiniApp host
$endpoint = 'https://webhook.beein.app/miniapp/messages';

$payload = json_encode([
    'contactToken' => $contactToken,
    'type'         => 'text',
    'text'         => 'Probe at ' . date('c'),
], JSON_UNESCAPED_UNICODE);

$ch = curl_init($endpoint);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Origin: ' . $origin,
        'Referer: ' . $origin . '/checkout/',
        'User-Agent: YourBrand-MiniApp/1.0 (php-curl)',
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HEADER         => true,
    CURLOPT_TIMEOUT        => 10,
]);

$response   = curl_exec($ch);
$status     = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
$headerSize = (int) curl_getinfo($ch, CURLINFO_HEADER_SIZE);
curl_close($ch);

echo "==== RESPONSE (status=$status) ====\n";
echo trim(substr($response, 0, $headerSize)) . "\n\n";
echo "Body:\n" . substr($response, $headerSize) . "\n";

小提醒：Origin / Referer / User-Agent header 對 BeeIn server 而言僅作為 log 識別，**不影響授權**（授權由 body 內 contactToken 決定）； server-to-server 不會被 CORS 影響。

常見 error

#MiniApp 媒體上傳（3 步驟）

媒體（圖片/影片/音訊/檔案）採與既有 webhook 媒體同模式 — 先取一次性 upload token、PUT bytes 到 worker、confirm 後才能拿 mediaId 附到訊息上。

Step 1 — 取得 upload token

{
  "contactToken": "eyJ...",
  "mimeType":     "image/jpeg",
  "size":         123456
}

Response

{
  "uploadUrl": "https://webhook.beein.app/bot/media/upload",
  "token":     "eyJ...",
  "expiresAt": "...",
  "maxSize":   200000000,
  "mimeType":  "image/jpeg"
}

Step 2 — PUT bytes 到 uploadUrl

PUT https://webhook.beein.app/bot/media/upload
X-Token: <token from step 1>
Content-Type: image/jpeg
Body: <raw bytes>

Step 3 — confirm 拿 mediaId

{
  "contactToken": "eyJ...",
  "token":        "<token from step 1>",
  "mimeType":     "image/jpeg",
  "actualSize":   123456
}

Response

{
  "mediaId":     "66f0...",
  "downloadUrl": "/api/v1/media/66f0...",
  "expiresAt":   "..."
}

Step 4 — 用 mediaId 發訊息

POST https://webhook.beein.app/miniapp/messages
{
  "contactToken": "eyJ...",
  "type":         "media",
  "mediaId":      "66f0...",
  "text":         "附上您的取貨單"
}

#最小可用範例

<!doctype html>
<html lang="zh-Hant">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>BeeIn MiniApp Demo</title>
</head>
<body>
  <h1 id="hello">歡迎</h1>
  <button id="send">送一則 OA 訊息到 BeeIn</button>

  <script>
    // 1. 讀取 contactToken 並立刻從網址移除
    const params = new URLSearchParams(location.search);
    let contactToken = params.get('ct');
    if (contactToken) {
      params.delete('ct');
      history.replaceState({}, document.title, location.pathname);
    }

    // 2. 監聽 token refresh（兩種事件都接，跨 WebView 行為差異）
    window.addEventListener('message', (e) => {
      if (e.data?.type === 'contactToken') contactToken = e.data.token;
    });
    window.addEventListener('beein:contactToken', (e) => {
      contactToken = e.detail.token;
    });

    // 3. window.beein bridge ready helper
    function withBeeIn(fn) {
      if (window.beein?.__installed__) return fn(window.beein);
      window.addEventListener('beein:ready', function once() {
        window.removeEventListener('beein:ready', once);
        fn(window.beein);
      });
    }

    withBeeIn((beein) => {
      const user = beein.getUser();
      document.querySelector('#hello').textContent = `Hi, ${user?.displayName || 'BeeIn user'}`;
      beein.setNavTitle('Demo MiniApp');
    });

    // 4. 按鈕：代表 OA 傳訊息給目前 follower
    document.querySelector('#send').addEventListener('click', async () => {
      if (!contactToken) {
        alert('尚未取得 contactToken，請重新開啟 MiniApp');
        return;
      }
      const r = await fetch('https://webhook.beein.app/miniapp/messages', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          contactToken,
          type: 'text',
          text: '您已完成 MiniApp 操作',
        }),
      }).then(x => x.json());
      if (!r.ok) alert(r.code || '發送失敗');
    });
  </script>
</body>
</html>

#對接檢查清單

安全注意事項

• contactToken 只放記憶體，不進 DB / log / 第三方分析。
• X-BeeIn-Auth 必須在 server 端解密驗證，不要只信前端 getUser()。
• RSA 私鑰只放合作方 server，不貼 BeeIn，不放前端。
• MiniApp 訊息只能打 https://webhook.beein.app/miniapp/*。
• 所有下單 / 付款 / 核銷必須在合作方後端做權限檢查，不可只信前端。
• 若用 openExternal(url)，URL 會進系統瀏覽器歷史；不要把 token 放在外部 URL。

#使用場景

#錯誤碼