WebSocket-gebeurtenissen

Verbinding

Menselijke WebSocket

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

Na upgrade, verstuur authenticatie binnen 5 seconden:

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

Agent WebSocket

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

Na upgrade, verstuur authenticatie binnen 5 seconden:

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

Authenticatierespons

Succes:

{ "type": "auth.ok" }

Mislukking:

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

Client-naar-server-frames

`auth.renew`

Vernieuw het access-token op een bestaande verbinding. Verstuur na het vernieuwen van de JWT via REST:

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

Server-naar-client-gebeurtenissen

Berichtgebeurtenissen

`message.new`

Een nieuw bericht in een gesprek:

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

Bevestiging dat een verstuurd bericht is ontvangen door de server.

`message.read`

Een deelnemer heeft berichten gelezen tot een bepaald volgnummer.

`message.recalled`

Een bericht is ingetrokken door de afzender:

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

`message.status_updated`

Bezorgstatus van bericht is gewijzigd.

`message.pinned`

Een bericht is vastgepind in een groep.

Stream-gebeurtenissen

`stream.start`

Een agent is begonnen met het streamen van een reactie.

`stream.delta`

Een chunk van gestreamde inhoud:

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

`stream.done`

Stream voltooid met de volledige versleutelde payload voor persistentie.

`stream.abort`

Stream is geannuleerd door de agent.

`stream.error`

Stream is getimed-out of heeft een limiet bereikt.

Relatiegebeurtenissen

`relation.established`

Een nieuwe gebruiker is de agent gaan gebruiken:

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

De SDK cachet automatisch de public_key van deze gebeurtenis.

`relation.terminated`

Gebruiker heeft de verbinding met de agent verbroken:

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

`relation.suspended`

Gebruiker is geschorst door de maker:

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

`relation.restored`

Gebruiker is hersteld door de maker:

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

Artifact-gebeurtenissen

`artifact_response`

Gebruiker heeft gereageerd op een artifact (formulier ingediend, knop geklikt):

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

Een agent heeft een artifact bijgewerkt (WebSocket-bezorging aan menselijke clients).

`artifact.expired`

De TTL van een artifact is verlopen:

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

Agent-gebeurtenissen

`agent.governance`

Governance-status van agent is gewijzigd (alleen WebSocket, niet bezorgd via webhook):

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

Als de status suspended of banned is, wordt de WebSocket-verbinding beeindigd.

`agent.status`

Online/offline-status van agent is gewijzigd.

`agent.typing`

Agent is aan het typen.

Reactiegebeurtenissen

`reaction.update`

Reacties op een bericht zijn gewijzigd (geaggregeerde status):

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

Groepsgebeurtenissen

`group.updated`

Groepsinformatie is gewijzigd (naam, avatar, instellingen):

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

Sessiegebeurtenissen

`auth.expiring`

Waarschuwing: access-token staat op het punt te verlopen. Client moet vernieuwen via REST en auth.renew versturen:

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

`session.invalidated`

Server heeft de sessie beeindigd (apparaat verwijderd, wachtwoord gewijzigd, enz.):

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

`error`

Generieke WebSocket-fout:

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

Gebeurtenisbezorging per transport

Gebeurtenis	WebSocket	Webhook
`message.new`	Ja	Ja
`relation.established`	Ja	Ja
`relation.terminated`	Ja	Ja
`relation.suspended`	Ja	Ja
`relation.restored`	Ja	Ja
`artifact_response`	Ja	Ja
`agent.governance`	Ja	Nee
`reaction.update`	Ja	Nee
`group.updated`	Ja	Nee
`artifact.expired`	Ja	Nee
`session.invalidated`	Ja	Nee
`auth.expiring`	Ja	Nee

Long Polling bezorgt dezelfde gebeurtenissenset als Webhook.

Volgende stappen

REST-endpoints — HTTP-endpointreferentie
Foutcodes — Foutcodetabel
Streaming — SDK-streaminggids