WebSocket Olayları

Kết Nối

WebSocket Người Dùng

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

Sau khi upgrade, gửi auth trong 5 giây:

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

WebSocket Agent

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

Sau khi upgrade, gửi auth trong 5 giây:

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

Phản Hồi Auth

Thành công:

{ "type": "auth.ok" }

Thất bại:

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

Frame Client-to-Server

`auth.renew`

Làm mới access token trên kết nối hiện có. Gửi sau khi refresh JWT qua REST:

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

Sự Kiện Server-to-Client

Sự Kiện Tin Nhắn

`message.new`

Tin nhắn mới trong hội thoại:

{
  "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`

Xác nhận máy chủ đã nhận tin nhắn gửi.

`message.read`

Người tham gia đã đọc tin nhắn đến sequence number nhất định.

`message.recalled`

Tin nhắn đã bị người gửi thu hồi:

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

`message.status_updated`

Trạng thái gửi tin nhắn thay đổi.

`message.pinned`

Tin nhắn được ghim trong nhóm.

Sự Kiện Stream

`stream.start`

Agent bắt đầu streaming phản hồi.

`stream.delta`

Chunk nội dung streaming:

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

`stream.done`

Stream hoàn thành với payload mã hóa đầy đủ để lưu trữ.

`stream.abort`

Stream bị agent hủy.

`stream.error`

Stream timeout hoặc đạt giới hạn.

Sự Kiện Quan Hệ

`relation.established`

Người dùng mới bắt đầu sử dụng agent:

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

SDK tự động cache public_key từ sự kiện này.

`relation.terminated`

Người dùng ngắt kết nối khỏi agent:

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

`relation.suspended`

Người dùng bị người tạo tạm ngừng:

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

`relation.restored`

Người dùng được người tạo khôi phục:

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

Sự Kiện Artifact

`artifact_response`

Người dùng phản hồi artifact (gửi biểu mẫu, nhấn nút):

{
  "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 cập nhật artifact (gửi qua WebSocket cho client người dùng).

`artifact.expired`

TTL artifact đã hết:

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

Sự Kiện Agent

`agent.governance`

Trạng thái quản trị agent thay đổi (chỉ WebSocket, không gửi qua webhook):

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

Nếu trạng thái là suspended hoặc banned, kết nối WebSocket bị ngắt.

`agent.status`

Trạng thái trực tuyến/ngoại tuyến agent thay đổi.

`agent.typing`

Agent đang gõ.

Sự Kiện Phản Ứng

`reaction.update`

Phản ứng trên tin nhắn thay đổi (trạng thái tổng hợp):

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

Sự Kiện Nhóm

`group.updated`

Thông tin nhóm thay đổi (tên, avatar, cài đặt):

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

Sự Kiện Phiên

`auth.expiring`

Cảnh báo: access token sắp hết hạn. Client nên refresh qua REST và gửi auth.renew:

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

`session.invalidated`

Máy chủ ngắt phiên (thiết bị bị xóa, đổi mật khẩu, v.v.):

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

`error`

Lỗi WebSocket chung:

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

Gửi Sự Kiện Theo Phương Thức

Sự kiện	WebSocket	Webhook
`message.new`	Có	Có
`relation.established`	Có	Có
`relation.terminated`	Có	Có
`relation.suspended`	Có	Có
`relation.restored`	Có	Có
`artifact_response`	Có	Có
`agent.governance`	Có	Không
`reaction.update`	Có	Không
`group.updated`	Có	Không
`artifact.expired`	Có	Không
`session.invalidated`	Có	Không
`auth.expiring`	Có	Không

Long Polling gửi cùng tập sự kiện như Webhook.

Bước Tiếp Theo

REST Endpoint — Tham chiếu HTTP endpoint
Mã Lỗi — Bảng mã lỗi
Streaming — Hướng dẫn streaming SDK