add mini app card docs

Author: ling

docs-src/advanced-kits/imessage/getting-started.mdx.vel

@@ -159,7 +159,7 @@ The client is organized by resource:
 
 | Namespace | What it does |
 |---|---|
-| `im.messages` | Send text, attachments, multipart messages, replies, reactions, stickers, edits, unsends, list queries, and message events |
+| `im.messages` | Send text, attachments, mini app cards, multipart messages, replies, reactions, stickers, edits, unsends, list queries, and message events |
 | `im.chats` | Create chats, read chat state, count chats, mark read, set typing, share contact cards, and manage chat backgrounds |
 | `im.groups` | Rename groups, manage participants, set group icons, and leave groups |
 | `im.attachments` | Upload files, read metadata, and stream downloads |
@@ -172,7 +172,7 @@ The client is organized by resource:
 
 Core path:
 
-1. [Messages](/advanced-kits/imessage/messages) — send text, attachments, multipart messages, reactions, edits, unsends, and subscribe to message events
+1. [Messages](/advanced-kits/imessage/messages) — send text, attachments, mini app cards, multipart messages, reactions, edits, unsends, and subscribe to message events
 2. [Chats](/advanced-kits/imessage/chats) — create chats, mark read, set typing, and manage chat backgrounds
 3. [Events](/advanced-kits/imessage/events) — catch up on durable events after a disconnect
 4. [Error Handling](/advanced-kits/imessage/error-handling) — understand error classes, retries, and idempotency keys

docs-src/advanced-kits/imessage/messages.mdx.vel

@@ -22,6 +22,7 @@ Get a `chat.guid` before calling message APIs. `chat.guid` is the server's chat
 | Add a message effect | `effect: MessageEffect.*` |
 | Format text | `formatting: [...]` |
 | Send an attachment | Upload with `im.attachments.upload(...)`, then call `im.messages.sendAttachment(...)` |
+| Send a mini app card | `im.messages.sendMiniApp(chat.guid, { url, preview })` |
 | Reply to a message | `replyTo` on `sendText(...)`, `sendAttachment(...)`, or `sendMultipart(...)` |
 | Send multipart content | `im.messages.sendMultipart(...)` |
 | Add or remove a reaction | `im.messages.setReaction(...)` |
@@ -183,6 +184,66 @@ await im.messages.sendAttachment(chat.guid, audio.attachment.guid, {
   <img src="/images/advanced-kits/imessage/messages/audio-message.avif" alt="iMessage audio message bubble with play button and waveform" />
 </Frame>
 
+## Send Mini App Cards
+
+`sendMiniApp(...)` sends a tappable iMessage card that opens a URL. Use it when you want a custom preview card instead of an automatic link preview.
+
+```ts
+const sent = await im.messages.sendMiniApp(chat.guid, {
+  url: "https://photon.codes",
+  preview: {
+    title: "Photon",
+    subtitle: "photon.codes",
+    body: "Build messaging agents with advanced iMessage support.",
+  },
+});
+
+console.log(sent.guid);
+```
+
+<Frame>
+  <img src="/images/advanced-kits/imessage/messages/mini-app-card.avif" alt="Mini app card preview showing a Spectrum landing page card" />
+</Frame>
+
+The SDK only asks for the destination URL and the preview content shown on the card. The server handles the iMessage app-card details internally.
+
+Only `url` and `preview.title` are required. Most cards should also set `subtitle`, `body`, and `imageJpeg` when that content is available. To include an image, pass JPEG bytes as `preview.imageJpeg`:
+
+```ts
+await im.messages.sendMiniApp(chat.guid, {
+  url: "https://photon.codes",
+  preview: {
+    title: "Photon",
+    subtitle: "photon.codes",
+    imageJpeg: await readFile("preview.jpg"),
+  },
+});
+```
+
+| Field | Required | Meaning |
+|---|---|---|
+| `url` | Yes | URL opened when the recipient taps the card |
+| `preview.title` | Yes | Primary text shown on the card |
+| `preview.subtitle` | No | Secondary text |
+| `preview.body` | No | Supporting text |
+| `preview.imageJpeg` | No | JPEG preview image bytes |
+| `preview.caption` | No | Additional small label when the card layout has room |
+| `preview.footer` | No | Additional footer label when the card layout has room |
+| `preview.detail` | No | Additional detail label when the card layout has room |
+| `preview.summary` | No | Fallback summary for surfaces that cannot show the full card |
+
+| Option | Meaning |
+|---|---|
+| `clientMessageId` | Optional third-argument idempotency key for job retries |
+
+<Warning>
+  Pass JPEG bytes to `imageJpeg`. If your source image is PNG, WebP, HEIC, or another format, convert it to JPEG before calling `sendMiniApp(...)`.
+</Warning>
+
+<Note>
+  `sendMiniApp(...)` is its own send operation. It does not upload files first, does not take an attachment GUID, and does not use `replyTo` or message effects.
+</Note>
+
 ## Reply to a Message
 
 To reply to a message, pass the target message GUID as `replyTo`: