> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masivo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# In-app messages

> Deliver personalized messages inside your mobile app through templates, journeys, and the Storefront API.

In-app messages let you show modals, banners, and bottom sheets inside your mobile app. Templates are created in the Masivo dashboard; your app fetches eligible messages and reports impressions through the Storefront API.

## How in-app messages work

```mermaid theme={null}
flowchart LR
  T[Template created] --> M[Message materialized]
  M --> F[App fetches eligible messages]
  F --> S[App shows message]
  S --> E[App logs shown / clicked / dismissed]
  E --> A[Analytics & tracking events]
```

Messages are **materialized per customer** when a template is scheduled to an audience, sent as a test, or delivered through a journey. Each row in `inapp_messages` stores the rendered content, display rules, and delivery metadata.

Your mobile app:

1. Calls `GET /inapp/capabilities` to know whether in-app is enabled and which journey event types support real-time delivery.
2. Calls `GET /customers/{id}/inapp-messages` after app open or when a trigger event fires.
3. Renders the message using the `type` and `content` fields.
4. Calls `POST /customers/{id}/inapp-messages/{messageId}/events` for each impression action.

## Message lifecycle

```mermaid theme={null}
stateDiagram-v2
  [*] --> pending: Message materialized
  pending --> shown: shown event (under cap)
  pending --> clicked: clicked event
  pending --> dismissed: dismissed event
  shown --> pending: shown event (more impressions left)
  shown --> clicked: clicked event
  shown --> dismissed: dismissed event
  pending --> expired: expires_at passed
  clicked --> [*]
  dismissed --> [*]
  expired --> [*]
```

| Status      | Description                                                                           |
| ----------- | ------------------------------------------------------------------------------------- |
| `pending`   | Eligible for display; may still accept more `shown` events if under `max_impressions` |
| `shown`     | Last action was `shown` and impression cap was reached                                |
| `clicked`   | Customer tapped a button or primary action                                            |
| `dismissed` | Customer closed the message                                                           |
| `expired`   | `expires_at` is in the past                                                           |

## Message types

| Type         | Use case                                |
| ------------ | --------------------------------------- |
| `modal`      | Centered dialog over the current screen |
| `fullscreen` | Full-screen takeover                    |
| `slideup`    | Bottom sheet style panel                |
| `banner`     | Top or bottom banner                    |

## Template configuration

| Field                                | Type       | Description                                           |
| ------------------------------------ | ---------- | ----------------------------------------------------- |
| `name`                               | `string`   | Unique template name per account                      |
| `message_type`                       | enum       | One of the message types above                        |
| `content.title`                      | `string`   | Headline text                                         |
| `content.body`                       | `string`   | Main copy (required in dashboard)                     |
| `content.image_url`                  | `string`   | Optional hero image URL                               |
| `content.buttons`                    | array      | Primary, dismiss, and deeplink buttons                |
| `display_rules.max_impressions`      | `number`   | Max times a customer can see the message (default 1)  |
| `display_rules.min_interval_seconds` | `number`   | Minimum gap between `shown` events                    |
| `display_rules.priority`             | `number`   | Higher values win when multiple messages are eligible |
| `team_ids`                           | `string[]` | Restrict analytics visibility to assigned teams       |

## Delivery sources

| Source      | Trigger                              |
| ----------- | ------------------------------------ |
| `scheduled` | Audience schedule from the dashboard |
| `test`      | Test send to a selected audience     |
| `journey`   | Journey node with an in-app action   |

Journey-connected templates can also trigger **real-time delivery**: when a qualifying event is emitted, Masivo materializes the message and sends a silent push to customers with a registered device token and push consent. Your app should handle that payload and refresh via `GET /customers/{id}/inapp-messages`. Use `GET /inapp/capabilities` to read the supported `eventTypes`.

## Tracking events

Each impression action emits a resolved tracking event:

| Action      | Event type        |
| ----------- | ----------------- |
| `shown`     | `INAPP_SHOWN`     |
| `clicked`   | `INAPP_CLICKED`   |
| `dismissed` | `INAPP_DISMISSED` |

Pass optional `metadata` (for example `button_id`) on click events for button-level analytics.

## Comparison with push notifications

|                       | In-app messages                                                  | Push notifications           |
| --------------------- | ---------------------------------------------------------------- | ---------------------------- |
| Surface               | Inside the app UI                                                | OS notification tray         |
| Requires device token | Only for real-time silent push (journeys); not for on-open fetch | Yes                          |
| Rich layout           | Full templates (modal, banner, slideup, fullscreen)              | Title, body, image, deeplink |
| Real-time trigger     | Journey events + silent push refresh                             | FCM/APNs delivery            |
| Impression tracking   | Explicit API events                                              | Open/delivery analytics      |

## Related documentation

* [In-app messages](/guides/create-in-app-templates) — dashboard setup
* [Integrate in-app messages](/guides/in-app-messages) — end-to-end app integration
* [Integrate in-app messages](/api-reference/guides/integrate-in-app-messages) — Storefront API reference guide