User.Inbox

User.Inbox.push() files a card in the current end user’s inbox and returns a receipt at once; the end user acts on the card whenever they next open it. It takes no recipient. The card goes to the end user of the execution context, so it works in tools, dynamic jobs, and trigger-fired turns. From the agent’s background work, such as a webhook’s execute or a LuaJob, there is no end user: the push fails with no_user_context (see execution contexts), unless the agent is a public agent with approvers and notification recipients. Then a notice goes to each notification recipient and a question goes to the approvers; notification recipients who are not approvers don’t receive questions. To send a message instead of filing a card, use Channels. Verified against lua-cli 3.33.0.

import { User } from 'lua-cli';

Quick example

import { User } from 'lua-cli';

const receipt = await User.Inbox.push({
  title: 'Approve the Q3 renewal quote',
  body: 'Northstar Ltd renewal is ready to send at $48,000.',
  actions: ['approve'],
  key: 'northstar-q3-renewal',
});

if (receipt.outcome === 'capped') {
  console.warn(`Not filed: ${receipt.reason}`);
}

Methods

push()

Files a card, or revises the card that already carries the same key.

User.Inbox.push(input: InboxPushInput): Promise<InboxPushReceipt>

string

required

The card’s first line. Trimmed; the first 140 characters are kept.

string

required

The card’s context line and the prose of its detail pane. The first 1,000 characters are kept.

string

Longer text shown only when the end user opens the card. The first 4,000 characters are kept.

string

A source link rendered on the card and never opened automatically. Must start with http:// or https://.

'urgent' | 'high' | 'normal' | 'low'

How loudly the card announces itself. Urgent pushes are limited per day; see Limits.

('approve' | 'redirect' | 'fix')[]

What the card offers. approve without options synthesizes an Approve/Decline pair; fix requires connection.

{ label: string; description?: string }[]

One-click answers; two or more make the card a question. Labels keep their first 60 characters and descriptions their first 200. Entries with an empty label are ignored, and entries past the fourth are dropped.You pass no ids: the platform numbers the options "0", "1", and so on, in the order given. From a shared agent’s background work, a question goes to the agent’s approvers only, never to notification recipients who are not approvers; with no approvers it behaves as before. With the agent’s Require someone other than the person who triggered it setting on, the person who triggered the work gets no copy and can’t answer. If they are the only approver, the question goes to the organization’s owners and admins instead, leaving out the person who triggered it; only when there is no other owner or admin does it go back to them. A question sent to a shared agent’s approvers is answered only by choosing an option; a free-text answer is refused with 400 ROUTED_QUESTION_OPTION_ONLY, a reply typed in the chat does not answer it, and the first answer wins, so a later one gets 409 QUESTION_ALREADY_ANSWERED with answeredBy. The agent continues with Answered by <name>: <option label>.

{ type: string; name: string }

Required with actions: ['fix']. type is the integration’s catalog slug and name its display name; each keeps its first 60 characters.

string

Idempotency and revision key: 1 to 120 characters from A-Z, a-z, 0-9, ., _, :, and -. A push with an existing key revises that card in place. Omit it for one-shot notices.

boolean

On a notice push that carries a key, the literal true declares that this notice resolves the open question card with the same key; that card is settled and no further notification is sent. An answer the end user already gave stands. Ignored without key, and on question and fix pushes.

string

The conversation the card hands off into when the end user acts. Defaults to the current thread. The first 200 characters are kept.

Returns

InboxPushReceipt

What happened to the push.

Show properties

'deposited' | 'updated' | 'exists' | 'capped'

deposited filed a card, updated revised the card with this key, exists found it unchanged, and capped filed nothing because a limit was reached.

'input_request' | 'connection_fix' | 'agent_notice'

The card kind the push routed to. Reported on capped too.

string

The key the card is filed under: yours, or a generated one. Reuse it to revise the card.

string

Present on capped: why nothing was filed.

Example

import { User } from 'lua-cli';

const filed = await User.Inbox.push({
  key: 'weekly-pipeline-review',
  title: 'Pipeline review ready',
  body: '12 deals need a status update.',
});

const revised = await User.Inbox.push({
  key: 'weekly-pipeline-review',
  title: 'Pipeline review ready',
  body: '9 deals need a status update.',
});

console.log(filed.outcome, revised.outcome); // deposited updated

Errors — a reached limit resolves capped; everything else throws an error whose code you can branch on:

invalid_input — title and body are required, deeplink must be an http(s) URL, key must be 1..120 chars of [A-Za-z0-9._:-], or fix without a connection.
no_user_context — Inbox.push requires a user context: the execution context has no end user, and the push is not from a public agent’s background work with recipients chosen (see Approvers and notifications for shared agents).
deposit_failed — the card could not be stored. Safe to retry.

Card kinds

The kind follows from the input, checked in this order.

Input	Kind	What the end user sees
`options` with two or more entries, or `actions` with `approve` and no `fix`	`input_request`	A question answered in one click
`actions` with `fix` and a `connection`	`connection_fix`	A prompt to reconnect the named integration
Anything else, including `actions: ['redirect']`	`agent_notice`	A read-only notice

Limits

Limit	Default	When exceeded
Cards per agent, per end user, per day, counted per kind	500	The push resolves `capped` and files nothing
`priority: 'urgent'` per agent, per end user, per day	5	The card lands demoted to `high`
Organization switch for agent pushes	On	When an admin turns it off, every push resolves `capped` with a `reason`

Defaults are platform settings and can change; the outcomes are the contract. When the platform cannot read the day’s count, the push is treated as capped.

Types

InboxPushInput and InboxPushReceipt are not exported. Derive them from the method when you need to name them.

import { User } from 'lua-cli';

type InboxPushInput = Parameters<typeof User.Inbox.push>[0];
type InboxPushReceipt = Awaited<ReturnType<typeof User.Inbox.push>>;

export async function notify(input: InboxPushInput): Promise<InboxPushReceipt> {
  return User.Inbox.push(input);
}

SDK

CLI

REST API

Quick example

Methods

push()

Card kinds

Limits

Types

See also

​Quick example

​Methods

​push()

​Card kinds

​Limits

​Types

​See also

Quick example

Methods

push()

Card kinds

Limits

Types

See also