Sessions
A session is one conversation between a user and an agent. Sessions can run over text, browser voice, voice+text, widget, or telephony.
Lifecycle
Section titled “Lifecycle”POST /sessions creates a conversation row in pending status and returns signed URLs for WebSocket clients. When a WebSocket connects, Hyponema transitions the session to in_progress. A normal close transitions the session to completed; failures transition it to failed.
Text chat over Server-Sent Events can use the same session ID without opening a WebSocket.
Modalities
Section titled “Modalities”| Modality | Use for |
|---|---|
text | Server-Sent Events chat or chat-mode WebSocket. |
voice | Real-time microphone and speaker sessions. |
voice+text | Voice sessions where the client also sends or displays text. |
Signed session URLs
Section titled “Signed session URLs”Signed session URLs are short-lived and bound to the session. Create them from your backend, then pass only the returned WebSocket URL or token to the browser.
Reconnect
Section titled “Reconnect”If a voice WebSocket drops before a graceful close, Hyponema can park recent LLM context for a short resume window. Reconnect with the same session ID and signed token within that window to continue the pipeline with the parked state.