Skip to main content
The ourguide_flutter package adds Ourguide to any Flutter app. Use OurguideWidget for a floating chat button that overlays your existing app, drop in OurguideChatView for a full-screen chat experience.

​
Installation

flutter pub add ourguide_flutter

​
Quick Start

Add OurguideWidget inside a Stack to get a floating chat button that slides up a chat sheet — zero extra UI work: 
import 'package:ourguide_flutter/ourguide_flutter.dart';
import 'package:flutter/material.dart';

void main() => runApp(
  const OurguideScope(
    productId: 'YOUR_PRODUCT_ID',
    apiUrl:'https://dashboard.ourguide.ai',
    child: MyApp(),
  ),
);

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      // builder wraps every route — OurguideWidget appears on all pages
      builder: (context, child) => Stack(
        children: [child!, const OurguideWidget()],
      ),
      home: const HomeScreen(),
    );
  }
}
Placing OurguideWidget in MaterialApp.builder means it automatically appears on every page and route in your app — no need to add it to each screen individually. Tapping the button slides up a chat sheet at 85% screen height.

​
Full-Screen Chat

Wrap your app with OurguideScope and drop in OurguideChatView as the full body: 
import 'package:ourguide_flutter/ourguide_flutter.dart';
import 'package:flutter/material.dart';

void main() => runApp(
  const OurguideScope(
    productId: 'YOUR_PRODUCT_ID',
    child: MyApp(),
  ),
);

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

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: Scaffold(body: OurguideChatView()),
    );
  }
}
OurguideChatView includes message bubbles, streaming, conversation history, suggested actions, and a “Powered by Ourguide” footer — no additional setup required.

​
OurguideScope Props

OurguideScope is an InheritedWidget that provides the client and state down the widget tree.
PropRequiredDescription
productIdYesYour product ID from the dashboard
apiUrlYesAPI URL
identityTokenNoJWT token for authenticated users

​
OurguideWidget Props

PropRequiredDescription
themeNoOurguideTheme instance to customize the chat sheet appearance

​
OurguideChatView Props

PropRequiredDescription
themeNoOurguideTheme instance to customize appearance

​
Theming

Customize colors and styles via OurguideTheme: 
OurguideChatView(
  theme: OurguideTheme(
    backgroundColor: Colors.white,
    userBubbleColor: Colors.white,
    userBubbleTextColor: const Color(0xFF111827),
    assistantBubbleColor: Colors.black,
    assistantBubbleTextColor: Colors.white,
    inputBorderColor: const Color(0xFFE5E7EB),
    sendButtonColor: Colors.black,
    bubbleBorderRadius: 18.0,
    poweredByColor: const Color(0xFF9CA3AF),
  ),
)

​
Theme Properties

PropertyDescription
backgroundColorChat background color
userBubbleColorUser message bubble background
userBubbleTextColorUser message text color
assistantBubbleColorAssistant bubble background
assistantBubbleTextColorAssistant message text color
sendButtonColorSend button color
bubbleBorderRadiusCorner radius for message bubbles
inputBorderColorInput bar border color
inputBorderLoadingColorInput border color while streaming
poweredByColor”Powered by Ourguide” text color
headerBorderColorBottom border of the header
messageTextStyleFull TextStyle override for message text

​
User Identity

Identify users to enable conversation history and personalized responses: 
final notifier = OurguideScope.chatOf(context);

// From a login handler
final token = await fetchTokenFromYourBackend();
notifier.identify(IdentifyOptions(token: token));

// Or pass via OurguideScope props (auto-updates when token changes)
OurguideScope(
  productId: 'YOUR_PRODUCT_ID',
  identityToken: userToken,
  child: MyApp(),
)

// Logout
notifier.resetUser();
See Identity Verification for generating tokens on your backend.

​
Client-Side Tools

Register tools that run natively in your Flutter app: 
final notifier = OurguideScope.chatOf(context);

notifier.registerTools({
  'navigateToScreen': (params) async {
    final screen = params['screen'] as String;
    Navigator.pushNamed(context, '/$screen');
    return {'navigated_to': screen};
  },
  'addToCart': (params) async {
    final productId = params['product_id'] as String;
    await cartController.add(productId);
    return {'added': productId};
  },
});
Upload tool definitions on the Actions page so the agent knows when to call them.

​
Platform Support

PlatformSupport
iOS✅
Android✅
macOS✅
Web✅

​
iOS / macOS

No additional configuration needed. For macOS apps, add the outbound networking entitlement — required for all network calls, including production: 
<!-- macos/Runner/DebugProfile.entitlements -->
<key>com.apple.security.network.client</key>
<true/>

​
Differences from Other SDKs

FeatureWeb (@ourguide/ui)React NativeFlutter
LanguageTypeScriptTypeScriptDart
Drop-in UI<OurguideWidget /><OurguideWidget />OurguideWidget
StateuseChat() hookuseChat() hookOurguideChatNotifier
StoragelocalStorageAsyncStorage adapterSharedPreferences (built-in)
Provider<OurguideProvider><OurguideProvider>OurguideScope

Identity Verification

Generate JWT tokens on your backend

Client-Side Tools

Register tools the agent can call

Embed Widget

Web widget installation guide