Engagive API documentation

Channels · App Chat · Mobile SDK

Flutter Mobile SDK

Embed native in-app support chat in your Flutter app using the same App Chat account as your website widget. The SDK uses the visitor widget API (not the business REST API documented for WhatsApp). Your backend signs short-lived identify_token JWTs after the user is identified in your app.

Portal setup

Enable SDK available and configure chat on App Chat → Mobile SDK → Flutter. Copy credentials from Details (public key). Set chat title, colors, business hours, and welcome message on the Flutter tab. Launcher icon, tagline, and position are website Widget tab settings only.

Identity is host-driven

Mobile SDK identity is notcontrolled by the website widget's Identity mode (Anonymous Recovery vs Trusted External ID). That setting applies to the embed script only. Your app chooses one of three patterns via Engagive.identifyUser, identifyAnonymous, or upgradeUser, plus the matching identity_kind in your backend token.

Trusted

User logged in — pass stable user id only. Default production pattern.

Anonymous

Pre-login guest chat — host generates and persists a guest id.

Upgrade

After login — merge guest history into the authenticated user.

Trust model (summary)

Safe in the mobile app
  • Widget public key
  • API base URL
  • App bundle id / package name
Backend only
  • Widget secret key
  • identify_token signing (HS256, ~5 min TTL)

Quick start (Flutter)

Dart
import 'package:engagive_flutter_sdk/engagive_flutter_sdk.dart';

await Engagive.init(EngagiveConfig(
  publicKey: 'YOUR_WIDGET_PUBLIC_KEY',
  apiBaseUrl: 'https://api.engagive.io',
  appIdentifier: 'com.yourcompany.app',
));

// After login — fetch identify_token from YOUR backend
await Engagive.identifyUser(
  EngagiveUser(id: user.id, name: user.name, email: user.email),
  identifyToken: tokenFromYourBackend,
);

await Engagive.openChat(context);

// Push with custom app-bar menu icon
await Engagive.openChat(
  context,
  appBarMenuIconAsset: 'assets/icons/chat-menu.png',
);

// Embedded tab — hide back button; host handles navigation
// const EngagiveChatScreen(showBackButton: false);

Chat screen app bar (integrator)

Title and colors come from the portal Flutter tab. Back button, menu visibility, and menu icon are controlled in your app — not portal settings.

Dart
// Defaults: back button + ⋮ menu (restart conversation)
await Engagive.openChat(context);

// Custom menu trigger asset
await Engagive.openChat(
  context,
  appBarMenuIcon: Image.asset('assets/icons/chat-menu.png', width: 24, height: 24),
);

// Embedded child — no SDK back button
const EngagiveChatScreen(showBackButton: false);

// Hide app-bar menu entirely
const EngagiveChatScreen(showAppBarMenu: false);

Visitor API base

SDK REST calls use the widget visitor prefix (same origin as your Engagive API deployment):

Visitor API
POST {apiBaseUrl}/api/widget/appchat/session
GET  {apiBaseUrl}/api/widget/appchat/messages
WS   {apiBaseUrl}/ws?accountId={id}&token={sessionJwt}

Full documentation (monorepo)

Detailed integration guides live in the Engagive workspace alongside the SDK package:

  • projects/engagive-app-backend/docs/flutter-sdk/embedding-guide.md — production integration
  • projects/engagive-app-backend/docs/flutter-sdk/identity-modes.md — anonymous, trusted, upgrade
  • projects/engagive-app-backend/docs/flutter-sdk/integration-testing.md — local E2E testing
  • sdks/engagive_flutter_sdk/ — Flutter package source
  • demos/engagive-flutter-demo/ — reference demo app

Test tokens for QA: Engagive portal → App Chat → Mobile SDK → Developer test token (trusted, anonymous, and upgrade). Package version: v2.2.0.

Back to docs home