跳到內容

給員工用的小工具

把網站小工具放進公司的內部網站,給同事用。你們的內部系統替已經登入的同事換一張員工通行證,對話就以那位同事的身分進行。

同事已經在你們的內部網站登入了。小工具只要知道他是誰,就能以他的身分做事,不用再登入 Dot Agents。你們的系統用對內的 API 串接換一張員工通行證,交給小工具。

內部網站替同事換通行證示意圖
內部網站替登入的同事換通行證,交給小工具。對話以那位同事的身分進行。

開始之前

請設定的人準備好三件事:

  • 小工具打開 給內部員工用。見網站小工具。
  • 同一位 agent 有一個 對內 的 API 串接,給你它的金鑰。
  • 小工具的編號:安裝碼裡 data-widget 的值。

換一張通行證

POST /api/v1/staff-passes

curl -X POST "https://<你的網址>/api/v1/staff-passes" \
  -H "Authorization: Bearer dak_…" \
  -H "Content-Type: application/json" \
  -d '{"email": "mei@example.com", "widget_id": "<小工具編號>"}'

回應:

{ "pass": "sp_…", "expires_at": "…", "member": { "name": "陳怡君" } }
  • email 要是這個團隊的成員。不是成員就回 404。
  • 通行證預設 1 小時有效。用 ttl_seconds 改,可以從 60 秒到 24 小時。
  • 金鑰只能放在你們的伺服器。不要放進網頁。

交給小工具

安裝碼會帶 data-member-token-url="/dot-agents/member-token"。小工具打開時,會到你們網站的這個網址拿通行證。在內部網站加這支端點:

  1. 確認同事已經登入你們的內部網站。
  2. 用他的 email 呼叫上面的 API。
  3. 回傳 { "token": "sp_…" }。沒登入就回 { "token": null }。

這支端點要跟小工具在同一個網域,瀏覽器才會帶上你們的登入狀態。

對話裡會怎樣

  • 以那位同事的身分進行,跟他在對話頁問一樣。他的角色能做的事,agent 才能做。
  • 用量算在那位同事身上。
  • 通行證到期後,小工具會再到端點拿一張新的。

會遇到的狀況

狀況 原因 怎麼辦
400,說只有對內的串接可以 用了對外的 API 串接 改用對內的串接
404,找不到小工具 小工具不是這個串接的 agent 的 確認兩者是同一位 agent
409 conflict 小工具沒打開「給內部員工用」 請設定的人打開
404,找不到成員 email 不是這個團隊的成員 請管理員邀請他加入團隊
視窗請他從內部網站打開 小工具沒拿到通行證 檢查端點有沒有回傳 token

相關頁

本頁對應 v0.168.0