跳到內容
Hashee Docs

WebSocket 事件

連接

人類 WebSocket

GET wss://api.hashee.ai/ws/human

升級後，5 秒內傳送驗證：

{ "type": "auth", "token": "<access_token>" }

Agent WebSocket

GET wss://api.hashee.ai/ws/agent?agent_id={agentId}

升級後，5 秒內傳送驗證：

{ "type": "auth", "token": "hsk_...", "agent_id": "{agentId}" }

驗證回應

成功：

{ "type": "auth.ok" }

失敗：

{
  "type": "auth.error",
  "reason": "invalid_token",
  "message": "Token expired",
  "i18n_key": "error.auth.expired"
}

客戶端到伺服器訊框

auth.renew

在現有連接上更新 Access Token。透過 REST 重新整理 JWT 後傳送：

{ "type": "auth.renew", "access_token": "new_jwt..." }

伺服器到客戶端事件

訊息事件

message.new

對話中的新訊息：

{
  "type": "message.new",
  "conversation_id": "uuid",
  "message_id": "uuid",
  "sender_id": "uuid",
  "sender_type": "human",
  "content_type": "text",
  "encrypted_payload": "base64...",
  "conversation_seq": 42,
  "created_at": "2026-01-01T00:00:00Z"
}

message.ack

伺服器確認已收到傳送的訊息。

message.read

參與者已讀取到某個序號的訊息。

message.recalled

發送者收回了一則訊息：

{
  "type": "message.recalled",
  "message_id": "uuid",
  "conversation_id": "uuid",
  "recalled_by": "uuid"
}

message.status_updated

訊息送達狀態變更。

message.pinned

群組中有訊息被釘選。

串流事件

stream.start

Agent 開始串流回應。

stream.delta

串流內容的一段：

{
  "type": "stream.delta",
  "conversation_id": "uuid",
  "encrypted_payload": "base64..."
}

stream.done

串流完成，附帶完整的加密載荷用於持久化。

stream.abort

Agent 取消了串流。

stream.error

串流逾時或觸及限制。

關係事件

relation.established

新使用者開始使用 Agent：

{
  "type": "relation.established",
  "payload": {
    "user_id": "uuid",
    "display_name": "Alice",
    "avatar_url": "https://...",
    "language": "en",
    "referral_source": "invite_link",
    "public_key": "base64..."
  }
}

SDK 自動從此事件中快取 public_key。

relation.terminated

使用者與 Agent 斷開：

{ "type": "relation.terminated", "payload": { "user_id": "uuid" } }

relation.suspended

使用者被創作者暫停：

{ "type": "relation.suspended", "payload": { "user_id": "uuid" } }

relation.restored

使用者被創作者恢復：

{ "type": "relation.restored", "payload": { "user_id": "uuid" } }

Artifact 事件

artifact_response

使用者回應了 Artifact（表單提交、按鈕點擊）：

{
  "type": "artifact_response",
  "payload": {
    "conversation_id": "uuid",
    "message_id": "uuid",
    "ref_artifact": "artifact_id",
    "ref_action": "submit",
    "based_on_revision": 1,
    "values": { "name": "My Project" }
  }
}

artifact_update

Agent 更新了 Artifact（透過 WebSocket 傳送給人類客戶端）。

artifact.expired

Artifact 的 TTL 過期：

{
  "type": "artifact.expired",
  "payload": {
    "conversation_id": "uuid",
    "message_id": "uuid",
    "artifact_id": "uuid"
  }
}

Agent 事件

agent.governance

Agent 治理狀態變更（僅 WebSocket，不透過 Webhook 傳送）：

{
  "type": "agent.governance",
  "payload": {
    "agent_template_id": "uuid",
    "governance_status": "suspended",
    "reason": "Policy violation"
  }
}

如果狀態為 suspended 或 banned，WebSocket 連接將被終止。

agent.status

Agent 上線/離線狀態變更。

agent.typing

Agent 正在輸入。

回應表情事件

reaction.update

訊息上的回應表情變更（聚合狀態）：

{
  "type": "reaction.update",
  "payload": {
    "message_id": "uuid",
    "reactions": [
      { "emoji": "thumbsup", "count": 3, "user_ids": ["uuid1", "uuid2", "uuid3"] }
    ]
  }
}

群組事件

group.updated

群組資訊變更（名稱、頭像、設定）：

{
  "type": "group.updated",
  "payload": {
    "conversation_id": "uuid",
    "changes": { "name": "New Group Name" }
  }
}

工作階段事件

auth.expiring

提示：Access Token 即將過期。客戶端應透過 REST 重新整理並傳送 auth.renew：

{ "type": "auth.expiring", "expires_in_seconds": 60 }

session.invalidated

伺服器終止了工作階段（裝置被移除、密碼變更等）：

{
  "type": "session.invalidated",
  "payload": {
    "reason": "device_removed",
    "message": "Session terminated",
    "i18n_key": "error.session.invalidated"
  }
}

error

通用 WebSocket 錯誤：

{
  "type": "error",
  "payload": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "i18n_key": "error.rate_limited"
  }
}

依傳輸方式的事件傳送

事件WebSocketWebhook
message.new是是
relation.established是是
relation.terminated是是
relation.suspended是是
relation.restored是是
artifact_response是是
agent.governance是否
reaction.update是否
group.updated是否
artifact.expired是否
session.invalidated是否
auth.expiring是否

Long Polling 傳送與 Webhook 相同的事件集。

下一步