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

# In-App Messaging

> Display and handle in-app messages with the Zixflow Flutter SDK.

In-app messages appear while users are active in your app. The Flutter SDK displays them automatically when you enable the in-app module and identify the user.

### Enable in-app messaging

Pass an `InAppConfig` when you initialize the SDK:

```dart theme={null}
import 'package:zixflow/zixflow.dart';

final config = ZixflowConfig(
  apiKey: 'YOUR_API_KEY',
  inAppConfig: InAppConfig(),
);

await Zixflow.initialize(config: config);
```

### Identify users

You must identify a user before personalized in-app messages can be delivered:

```dart theme={null}
Zixflow.instance.identify(
  userId: 'user-123',
  traits: {
    'email': 'user@example.com',
  },
);
```

### How messages appear

Once in-app is enabled and the user is identified:

1. Create and launch an in-app campaign in the Zixflow dashboard.
2. When campaign conditions match, the SDK fetches and displays the message in your app.
3. No extra UI code is required for standard modal/banner messages—the SDK renders them.

Track screen views with `Zixflow.instance.screen(title: ...)` if your campaigns target specific screens.

### Listen for in-app events

Subscribe to events when messages are shown, dismissed, or when a user takes an action:

```dart theme={null}
import 'dart:async';
import 'package:zixflow/zixflow.dart';
import 'package:zixflow/messaging_in_app.dart';

StreamSubscription? subscription;

void listenForInAppEvents() {
  subscription = Zixflow.inAppMessaging.subscribeToEventsListener((event) {
    switch (event.eventType) {
      case EventType.messageShown:
        print('Message shown ${event.message.messageId}');
        break;
      case EventType.messageDismissed:
        print('Message dismissed ${event.message.messageId}');
        break;
      case EventType.messageActionTaken:
        print('Action ${event.actionName} ${event.actionValue}');
        break;
      case EventType.errorWithMessage:
        print('In-app error ${event.message.messageId}');
        break;
    }
  });
}

// Cancel when done
// subscription?.cancel();
```

| Event type           | When it fires              |
| -------------------- | -------------------------- |
| `messageShown`       | Message is displayed       |
| `messageDismissed`   | Message is closed          |
| `messageActionTaken` | User taps a message action |
| `errorWithMessage`   | Message fails to display   |

### Dismiss a message

Dismiss the currently visible in-app message from your app code:

```dart theme={null}
Zixflow.inAppMessaging.dismissMessage();
```

### Inline in-app messages

Use `InlineInAppMessageView` to render a message inline in your layout. The `elementId` must match the placement ID configured in your campaign.

```dart theme={null}
import 'package:flutter/material.dart';
import 'package:zixflow/zixflow.dart';

class PromoBanner extends StatelessWidget {
  const PromoBanner({super.key});

  @override
  Widget build(BuildContext context) {
    return InlineInAppMessageView(
      elementId: 'home-banner',
      onActionClick: (message, actionValue, actionName) {
        print('Inline action: $actionName $actionValue');
      },
    );
  }
}
```

### Notification inbox

Access persistent inbox messages with `Zixflow.inAppMessaging.inbox`:

```dart theme={null}
import 'package:zixflow/zixflow.dart';
import 'package:zixflow/messaging_in_app.dart';

final inbox = Zixflow.inAppMessaging.inbox;

// One-shot fetch
final messages = await inbox.getMessages();

// Live updates
final subscription = inbox.messages().listen((messages) {
  // Rebuild your inbox UI
});

// Mark read / unread / delete / track clicks
inbox.markMessageOpened(message);
inbox.markMessageUnopened(message);
inbox.markMessageDeleted(message);
inbox.trackMessageClicked(message, actionName: 'cta');
```

Optionally filter by topic: `inbox.getMessages(topic: 'promotions')` or `inbox.messages(topic: 'promotions')`.

For the full method list, see the [API Reference](/documentation/sdk/flutter/api-reference).

***