Core Concepts›Message Lifecycle

Message Lifecycle

Last updated 2026-02-07

End-to-end flow

  1. Client calls POST /v1/agents/:id/messages.
  2. Rooaak verifies API key + project:message scope.
  3. Rooaak ensures runtime is running.
  4. Rooaak inserts messages row with status: pending.
  5. Runtime pulls pending messages via GET /runtime/messages/stream (SSE).
  6. Runtime posts response via POST /runtime/messages or POST /runtime/messages/:id.
  7. Rooaak updates messages.response, status: responded, response_time_ms.
  8. Client gets sync 200 responded or fallback 202 pending and later polls GET /v1/messages/:id or listens via webhook.

Events emitted

  • message.received on accepted inbound message (best-effort webhook dispatch)
  • message.responded on runtime response write (best-effort)