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, and fails with no_user_context from a webhook’s execute or a LuaJob (see execution contexts). 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.

{ 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.
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