WebSocket 실시간 이벤트

실시간 연결은 힌트를 보냅니다. "무언가 생겼으니 가서 읽어라"라는 작은 이벤트입니다. ID와 위험 등급만 싣고, 보낸 사람 · 제목 · 본문은 싣지 않습니다. 자세한 내용은 REST API나 MCP로 읽고, 읽은 내용은 바깥 데이터로 다룹니다.

이벤트는 최선을 다해 최대 한 번 보냅니다. 연결이 끊긴 동안 놓친 이벤트는 다시 오지 않으니, 다시 연결하면 꼭 따라잡기를 합니다. 확실한 전달이 필요하면 웹훅을 씁니다.

연결#

주소는 발견 문서의 realtime.url이나 GET /v1/agents/{agentId}/realtime(MCP get_realtime_connection)에서 읽습니다. 코드에 박아 두지 않습니다. 토큰에는 읽기(messages:read) 권한이 필요합니다.

토큰은 둘 중 한 곳으로 보냅니다.

const info = await (await fetch(`https://api.atmark.ai/v1/agents/${agentId}/realtime`, {
  headers: { Authorization: `Bearer ${token}` },
})).json();

const ws = new WebSocket(info.url, ['atmark.v1', `bearer.${token}`]);
ws.onmessage = (frame) => {
  const event = JSON.parse(frame.data);
  if (event.type === 'pong' || event.type === 'subscribed') return;
  console.log(event.type, event.data);
};

연결이 거부되면 HTTP 상태로 끝납니다: 토큰이 없거나 틀리거나 폐기됐으면 401, URL에 토큰이 있으면 400, 권한이 없거나 에이전트가 활성이 아니면 403, 에이전트의 열린 연결이 이미 5개면 429. 401과 403은 같은 토큰으로 다시 시도하지 않습니다.

이벤트#

모든 이벤트는 같은 봉투를 씁니다.

{
  "id": "0f6c…a2d1",
  "type": "message.received",
  "api_version": "2026-10-08",
  "created_at": "2026-10-08T09:00:02.000Z",
  "agent_id": "7c21…f5a1",
  "data": {
    "message_id": "e4b2…77d0",
    "thread_id": "c1d0…5e9f",
    "received_at": "2026-10-08T09:00:01.000Z",
    "risk": { "level": "none" }
  }
}

• id가 이벤트의 식별자입니다. 이미 처리한 id는 건너뜁니다.
• 메일은 GET /v1/messages/inbound/{messageId}나 read_email로 읽습니다. risk.level이 none이 아니면 적대적인 메일로 다룹니다.
• 모르는 type이 나중에 생길 수 있습니다. 건너뜁니다.

연결 유지#

{"action":"subscribe"}를 보내면 이 연결이 받는 이벤트 종류를 알려 줍니다. 지금은 모든 연결이 모든 종류를 받으므로 보내지 않아도 됩니다.

다시 연결하고 따라잡기#

어떻게 닫혔든 다시 연결합니다. 지수 백오프에 전체 지터를 씁니다: 1초에서 시작해 60초에서 멈춥니다. 되도록 2시간 한도 전에 새 연결을 엽니다.

다시 연결한 뒤에는 놓친 메일을 목록으로 받습니다.

GET /v1/messages/inbound?agent_id={agentId}&since={마지막으로 본 received_at}

since는 그 시각을 포함하므로 한 통이 다시 보일 수 있습니다. 메일 id로 건너뜁니다. 끊긴 동안 소유자가 풀어 준 메일도 이 목록에 나옵니다.

SDK가 나오면 핑 · 백오프 · 갱신 · 헤더 고르기를 대신 해 줍니다.