Skip to main content
Use app() when you want to present a URL as a tappable card instead of an inline link.

​
Send an app card

The first argument is . The only thing a caller supplies: the URL. It is itself consumable — pass a string, a promise, or a thunk (sync or async). The thunk form lets the URL be computed at send time (e.g. minting a signed link).
On iMessage, the recipient gets a native mini-app card. On Slack, Telegram, WhatsApp, and terminal, Spectrum sends the URL using that platform’s normal link behavior.

​
Show the app’s live UI

The second argument is . Set live to true to request live rendering:
When live is omitted, iMessage shows the card’s static URL preview. Platforms without a live app surface ignore the option and keep their normal URL fallback.
live is a rendering hint. The recipient needs a supported platform and the corresponding app extension for its live UI to appear.

​
Update an app card in place

An iMessage app card sent through @spectrum-ts/imessage can be updated without sending a second bubble. Keep the message returned by the original send, then pass it to edit():
The recipient sees the existing card update in place. You can change its URL, generated layout, and live-rendering option. Keep using card for later updates. space.send(edit(...)) resolves to undefined; it does not return a replacement message.
In-place app-card updates require @spectrum-ts/imessage. They are not available through @spectrum-ts/imessage-local or the URL fallbacks on other providers.

​
How update sessions work

A successful iMessage mini-app send returns an iMessage message with miniAppCardSession metadata. Spectrum passes this session back to iMessage when you call edit() and refreshes it after each successful update. Most applications should treat miniAppCardSession as provider-managed metadata: keep the original returned message and let Spectrum use it. A message without this metadata cannot identify an existing mini-app card to update.

​
How iMessage delivers app cards

On iMessage, app cards open inside the Spectrum Mini App, a mini-app launcher approved by Apple. Recipients download it once on first use (they can download it directly inside the Messages app); after that, every app card you send opens directly in Messages without leaving the conversation. The launcher keeps a library of every mini app a recipient has opened, so they can reopen those apps later or share them with friends. For an iMessage extension with its own identity and layout control, see Customized mini-app cards.