コンテンツにスキップ
Hashee Docs

WebSocketイベント

接続

Human 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

既存の接続でアクセストークンを更新します。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

エージェントがレスポンスのストリーミングを開始した。

stream.delta

ストリーミングされたコンテンツのチャンク：

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

stream.done

永続化のための完全な暗号化ペイロードでストリームが完了。

stream.abort

エージェントによりストリームがキャンセルされた。

stream.error

ストリームがタイムアウトまたは制限に達した。

リレーションシップイベント

relation.established

新しいユーザーがエージェントの利用を開始した：

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

ユーザーがエージェントとの接続を解除した：

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

ユーザーがアーティファクトに応答した（フォーム送信、ボタンクリック）：

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

エージェントがアーティファクトを更新した（人間クライアントへのWebSocket配信）。

artifact.expired

アーティファクトのTTLが期限切れになった：

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

エージェントイベント

agent.governance

エージェントのガバナンスステータスが変更された（WebSocket専用、Webhookでは配信されない）：

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

ステータスがsuspendedまたはbannedの場合、WebSocket接続は切断されます。

agent.status

エージェントのオンライン/オフラインステータスが変更された。

agent.typing

エージェントが入力中。

リアクションイベント

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

通知：アクセストークンの期限がまもなく切れます。クライアントは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と同じイベントセットを配信します。

次のステップ