Send a human a one-way notification
Send a human a one-way notification, fire-and-forget.
No reply is expected and nothing blocks. With a named channel the message is
sent and the call returns as soon as the medium ACCEPTED it (not that a human
saw it). With channel omitted the message is recorded to the internal
notifications sink the Studio inbox reads. One send attempt, no retry; every
failure raises loudly, never a silent no-op:
- a blank message, an unknown channel name, a blank recipient/audience, or a
caller-supplied
sender_identity→ 400; - a restricted caller addressing another identity (cross-identity denial) → 403;
- a channel that cannot notify → 501;
- a channel delivery failure → 502.
audience addresses the in-app record to an identity’s feed; it is honored
even when a channel also delivers the message (channel push AND in-app record).
sender_identity is the sending identity a channel message leaves FROM, which the
conversation bridge sets on the notification it builds to answer a route; a caller may
not supply it here and a set value is rejected loudly, never forwarded to the channel.
Returns a short confirmation string — "notification sent via '<channel>'"
for a channel send, "notification recorded to the internal sink" otherwise.
Authorizations
Body
A notification to send: the message text, an optional named channel
that carries it (omit to record to the internal sink), an optional per-call
recipient delivery address, and an optional audience identity whose in-app
inbox shows it (honored even with a channel set; distinct from recipient).
The identity (user_id) whose in-app inbox shows this (honored even with a channel set); leave unset for an operator/broadcast notification. Distinct from recipient, which is a channel delivery address.
Reserved: the sending identity a channel message leaves FROM, set by the conversation bridge on the notification it builds to answer a route. Callers MUST NOT supply it here — a set value is rejected with a 400, never forwarded.
Response
Success.

