> For the complete documentation index, see [llms.txt](https://series-1.gitbook.io/rundot-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://series-1.gitbook.io/rundot-docs/v5.22.0/readme/in_app_messaging.md).

# In-App Messaging API

Display lightweight toast notifications and in-app messages without building custom UI per platform.

## Toasts

Toasts are lightweight, auto-dismissing messages that appear at the screen edge. Use them for confirmations, status updates, or quick actions.

### Quick Start

```typescript
import RundotGameAPI from '@series-inc/rundot-game-sdk/api'

// Simple toast
await RundotGameAPI.popups.showToast('Progress saved!')

// Toast with options
const actionTriggered = await RundotGameAPI.popups.showToast('Progress saved!', {
  duration: 3000,
  variant: 'success',
  action: { label: 'Undo' },
})

if (actionTriggered) {
  undoLastAction()
}
```

### Toast Options

| Option     | Type                | Default  | Description                                                 |
| ---------- | ------------------- | -------- | ----------------------------------------------------------- |
| `duration` | `number`            | `3000`   | Display time in milliseconds                                |
| `variant`  | `string`            | `'info'` | Visual style: `'success'`, `'error'`, `'warning'`, `'info'` |
| `action`   | `{ label: string }` | -        | Optional action button; returns `true` if tapped            |

### Toast Variants

```typescript
// Success - green checkmark style
await RundotGameAPI.popups.showToast('Level complete!', { variant: 'success' })

// Error - red alert style
await RundotGameAPI.popups.showToast('Connection lost', { variant: 'error' })

// Warning - yellow caution style
await RundotGameAPI.popups.showToast('Low battery', { variant: 'warning' })

// Info - neutral style (default)
await RundotGameAPI.popups.showToast('New content available', { variant: 'info' })
```

### Actionable Toasts

```typescript
const tapped = await RundotGameAPI.popups.showToast('Item purchased!', {
  variant: 'success',
  action: { label: 'View' },
})

if (tapped) {
  openInventory()
}
```

## Engagement prompts

These let your game ask the platform to show its own trusted engagement UI for the running game. The platform renders the UI and the **player** acts — your game never likes on the player's behalf and never receives comment content or commenter identities. You don't pass a game id; the platform targets the running game automatically.

### `popups.showLikeDialog(): Promise<LikeDialogResult>`

Asks the platform to show its Like prompt. Resolves when the player acts or dismisses, or immediately with `{ shown: false, reason: 'unavailable' }` if the platform suppresses it (not enabled for your app, post-load window, cooldown, or per-session cap).

```typescript
type LikeDialogResult =
  | { shown: true; dismissed: boolean; liked: boolean }
  | { shown: false; reason: 'unavailable' }

const result = await RundotGameAPI.popups.showLikeDialog()
if (result.shown && result.liked) {
  // e.g. "Thanks for the like!"
}
```

A good moment to call this is after a win or a satisfying beat — never on load, and never in a loop.

### `popups.canShowLikeDialog(): Promise<{ available: boolean }>`

Feature-detect before rendering a Like call-to-action. Reflects **capability only** (platform support + whether the prompt is enabled for your app) — not the transient cooldown. Hide your CTA when `available` is `false`.

### `popups.showCommentsPanel(): Promise<CommentsPanelResult>`

Opens the platform's Comments panel for your game. Resolves `{ shown: true, dismissed: true }` when the panel closes, or `{ shown: false, reason: 'unavailable' }` if suppressed (including when comments are disabled for your game). No comment text or commenter identities are returned.

```typescript
type CommentsPanelResult =
  | { shown: true; dismissed: boolean }
  | { shown: false; reason: 'unavailable' }

await RundotGameAPI.popups.showCommentsPanel()
```

### `popups.canShowCommentsPanel(): Promise<{ available: boolean }>`

Capability check for the Comments panel — same semantics as `canShowLikeDialog`, and additionally `false` when comments are disabled for your game.

### `popups.getLikeState(): Promise<LikeStateResult>`

Read the running player's like state for your game. Read-only and not throttled — use it to decide whether to render a Like call-to-action or call `showLikeDialog()` at all (for example, skip players who already liked).

```typescript
interface LikeStateResult {
  isLiked: boolean // has the current player already liked this game
  likesCount: number // total likes for this game
}

const { isLiked } = await RundotGameAPI.popups.getLikeState()
if (!isLiked) {
  // only nudge players who haven't liked yet
  await RundotGameAPI.popups.showLikeDialog()
}
```

> **Anti-abuse.** These prompts are rate-limited, suppressed right after load, and capped per session. Calling them in a loop will not inflate engagement — only a real player tap mutates a like, and apps that abuse the prompts can be disabled by the platform.

## API Reference

| Method                                | Returns                           | Description                                                       |
| ------------------------------------- | --------------------------------- | ----------------------------------------------------------------- |
| `popups.showToast(message, options?)` | `Promise<boolean>`                | Show toast; returns `true` if action was triggered                |
| `popups.showLikeDialog()`             | `Promise<LikeDialogResult>`       | Show the platform Like prompt; player performs the like           |
| `popups.canShowLikeDialog()`          | `Promise<{ available: boolean }>` | Whether the Like prompt is enabled for your app (capability only) |
| `popups.showCommentsPanel()`          | `Promise<CommentsPanelResult>`    | Open the platform Comments panel for your game                    |
| `popups.canShowCommentsPanel()`       | `Promise<{ available: boolean }>` | Whether the Comments panel is available for your game             |
| `popups.getLikeState()`               | `Promise<LikeStateResult>`        | The player's like state (`isLiked`, `likesCount`) — read-only     |

## Best Practices

* Keep copy short; long text can be truncated on mobile.
* Avoid stacking; await each toast before showing another when actions are present.
* Use appropriate variants to communicate message importance.
* Don't overuse toasts; reserve them for meaningful status updates.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://series-1.gitbook.io/rundot-docs/v5.22.0/readme/in_app_messaging.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.