Skip to main content
POST
Send a message to a session's inbox

Path Parameters

sessionId
string<uuid>
required

The session's id.

Body

application/json

A message from one session to another. kind ask expects an answer and returns an askId; kind message is one-way. Delivery is durable: a busy recipient gets it when free, and it survives a restart.

from
string
required

The sending session's id. It is a SELECTION among the sessions the caller can already reach, never a claim the host takes on trust: an id outside the caller's reach is refused with the same "no such session" an id that never existed gets. Where the request already carries a sender of its own — the session a tool call runs under — that session is the sender and this field is not consulted at all.

Maximum string length: 256
content
string
required

The message text.

Minimum string length: 1
kind
enum<string>
default:message
Available options:
message,
ask,
answer
askId
string<uuid>

Required when kind is answer, ignored otherwise: the ask being resolved. The answer is posted to the ASKING session's inbox, so this id and the path's sessionId must describe the same ask — answering a question nobody asked you is refused rather than recorded.

Response

Accepted for delivery — delivered now, or durably queued until the recipient is free.

Delivery acknowledgement. queued means the recipient is busy and the message is durably held — it is delivered when the recipient next goes idle, and survives a restart of the host in between. "Held" is bounded by the retention window configured for intercom_messages, not by forever: with no window configured nothing sweeps it, and with one configured narya retention status says how long it has and narya doctor reports the oldest message still waiting.

status
enum<string>
required
Available options:
delivered,
queued
deliveryId
string<uuid>

This delivery's identity, stable across every redelivery attempt. Transport is at-least-once with an idempotent append: a host that dies between landing a message and recording that it landed offers the message again, and this id is what makes the second attempt recognise the first rather than saying it twice. Content is never an identity — the same sentence said twice is two messages.

askId
string<uuid>

Present when kind was ask; poll GET /v1/asks/{askId} or watch events for the answer.