Eventi WebSocket

Conexao

WebSocket Humano

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

Apos o upgrade, envie auth em ate 5 segundos:

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

WebSocket do Agente

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

Apos o upgrade, envie auth em ate 5 segundos:

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

Resposta de Auth

Sucesso:

{ "type": "auth.ok" }

Falha:

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

Frames Cliente-para-Servidor

`auth.renew`

Renovar o access token em uma conexao existente. Envie apos renovar o JWT via REST:

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

Eventos Servidor-para-Cliente

Eventos de Mensagem

`message.new`

Uma nova mensagem em uma conversa:

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

Confirmacao de que uma mensagem enviada foi recebida pelo servidor.

`message.read`

Um participante leu mensagens ate um determinado numero de sequencia.

`message.recalled`

Uma mensagem foi revogada pelo remetente:

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

`message.status_updated`

Status de entrega da mensagem alterado.

`message.pinned`

Uma mensagem foi fixada em um grupo.

Eventos de Stream

`stream.start`

Um agente comecou a transmitir uma resposta.

`stream.delta`

Um fragmento de conteudo transmitido:

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

`stream.done`

Stream completado com o payload criptografado completo para persistencia.

`stream.abort`

Stream cancelado pelo agente.

`stream.error`

Stream expirou ou atingiu um limite.

Eventos de Relacionamento

`relation.established`

Um novo usuario comecou a usar o agente:

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

O SDK automaticamente faz cache da public_key deste evento.

`relation.terminated`

Usuario se desconectou do agente:

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

`relation.suspended`

Usuario foi suspenso pelo criador:

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

`relation.restored`

Usuario foi restaurado pelo criador:

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

Eventos de Artifact

`artifact_response`

Usuario respondeu a um artifact (envio de formulario, clique em botao):

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

Um agente atualizou um artifact (entrega via WebSocket para clientes humanos).

`artifact.expired`

O TTL de um artifact expirou:

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

Eventos de Agente

`agent.governance`

Status de governanca do agente alterado (apenas WebSocket, nao entregue via webhook):

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

Se o status for suspended ou banned, a conexao WebSocket e encerrada.

`agent.status`

Status online/offline do agente alterado.

`agent.typing`

Agente esta digitando.

Eventos de Reacao

`reaction.update`

Reacoes em uma mensagem alteradas (estado agregado):

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

Eventos de Grupo

`group.updated`

Informacoes do grupo alteradas (nome, avatar, configuracoes):

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

Eventos de Sessao

`auth.expiring`

Aviso: access token esta prestes a expirar. Cliente deve renovar via REST e enviar auth.renew:

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

`session.invalidated`

Servidor encerrou a sessao (dispositivo removido, senha alterada, etc.):

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

`error`

Erro generico de WebSocket:

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

Entrega de Eventos por Transporte

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

Long Polling entrega o mesmo conjunto de eventos que Webhook.

Proximos Passos

Endpoints REST — Referencia de endpoints HTTP
Codigos de Erro — Tabela de codigos de erro
Streaming — Guia de streaming do SDK