mugib_sdk 1.0.1

Official Flutter SDK for Mugib chat sessions, voice agents, and session payload with one apiKey.

mugib_sdk

Official unified Flutter SDK for Mugib end-user chat & voice apps.

One project API key — primary use:

• Chat — sessions, messages (JSON + SSE), payload per session, handoff, tools, CSAT, conversions
• Voice — real-time Gemini Live (same API as mugib_voice)
• Widget UI (read-only) — bot name, welcome message, quick replies, proactive triggers

Does not change tenant settings (system prompt, bot personality) — those are Portal/Admin only.
payload customizes one session only (name, balance, plan, …).

---

SDK scope

Layer	What changes	SDK access
Session	Messages, payload, CSAT, conversions	mugib.chat.* ✅ main
Voice	Call + transcripts + session context	mugib.voice.* ✅ main
Widget UI	Read branding/triggers	getWidgetConfig(), getWidgetTriggers() ✅ optional
Tenant KB	Adds/edits KB for whole project	MugibKbService(mugib.api) ⚠️ advanced only
Tenant settings	Bot prompt, personality	❌ Portal/Admin only

---

What you need

Item	Where
Project API key	Project → Settings → API Key
Voice agent id (voice only)	Project → Voice Agents → numeric id
API base URL	https://api.mugib.com (default)

---

Install

dependencies:
  mugib_sdk: ^1.0.1

flutter pub get

Requirements: Flutter 3.24+ / Dart 3.5+ · iOS & Android (voice needs microphone permissions).

---

Quick start — chat + voice

import 'package:mugib_sdk/mugib_sdk.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await MugibSdk.initialize();
  runApp(const MyApp());
}

final mugib = MugibClient(apiKey: 'YOUR_PROJECT_API_KEY');

// 1. Open chat session
final session = await mugib.chat.createSession(pageUrl: '/app');

// 2. Send message with payload (name, plan, balance, …)
final reply = await session.send(
  'What plan fits me?',
  payload: {'name': 'Ahmed', 'plan': 'trial'},
);
print(reply.reply);

// 3. Streaming reply (SSE)
await for (final event in session.sendStream('Explain Pro plan')) {
  if (event is MugibStreamText) stdout.write(event.text);
}

// 4. Voice call — same session context
final call = mugib.voice.client(34);
await call.start(options: MugibVoiceCallOptions(
  chatSessionId: session.id,
  userContext: {'name': 'Ahmed'},
));
call.transcripts.listen((t) => print('${t.role}: ${t.text}'));
await call.end();

---

Chat API

MugibClient.chat

Method	REST endpoint	Description
createSession({pageUrl})	POST /api/v1/sessions	New session (chat_…)
listSessions()	GET /api/v1/sessions	Active sessions
session(id)	—	Bind existing session id

MugibChatSession

Method	REST endpoint	Description
send(message, {payload})	POST …/messages	Blocking JSON reply
sendStream(message, {payload})	POST …/messages?stream=true	SSE token stream
sendStreamText(…)	same	Convenience: full string
getHistory()	GET …/sessions/{id}	Message history
reset()	DELETE …/sessions/{id}	Clear session
poll({agentAfter})	GET …/poll	Human-agent handoff messages
pendingConfirmations()	GET …/pending-confirmations	MCP tools awaiting approval
confirmTool(id, {confirm})	POST …/confirmations/{id}	Approve / decline tool
trackConversion({goalName, …})	POST …/conversions	Conversion event
submitCsat({rating, comment})	POST /api/v1/csat/{id}	1–5 star rating

Payload

Pass dynamic user context on every message (merged server-side):

await session.send('Check my balance', payload: {
  'name': 'أحمد',
  'account_id': 'ACC-9921',
  'balance': '45 IQD',
});

The same payload is reused when you pass chatSessionId to a voice call.

Streaming metadata

The final SSE event may be MugibStreamMetadata with KB sources:

await for (final event in session.sendStream('…')) {
  switch (event) {
    case MugibStreamText(:final text):
      print(text);
    case MugibStreamMetadata(:final sources):
      print('Sources: ${sources.map((s) => s.title)}');
  }
}

---

Voice API

Voice behaviour is identical to mugib_voice v0.6.x — see voice section in docs/flutter-sdk.md or mugib_voice README for permissions, errors, metrics.

// List agents
final agents = await mugib.voice.listAgents();

// Create call client
final call = mugib.voice.client(agents.first.id);
await call.start(); // or MugibVoiceCallOptions for payload / chatSessionId

// Analytics
final stats = await mugib.voice.analytics(34, days: 7);

Or use the legacy import (re-export):

import 'package:mugib_voice/mugib_voice.dart'; // voice-only, depends on mugib_sdk

---

Widget UI (read-only)

Load branding for a custom chat screen — does not modify tenant settings:

final config = await mugib.getWidgetConfig();
print(config.botName);
print(config.welcomeMessage);
print(config.quickReplies);

final triggers = await mugib.getWidgetTriggers();

---

Advanced (tenant-wide — use with care)

KB CRUD via API key changes the whole project KB, not one session. Prefer Portal for KB management; use only for automated sync:

final kb = MugibKbService(mugib.api);
await kb.list(search: 'pricing'); // read
// await kb.add(...) // writes tenant KB — advanced integrations only

---

Platform permissions (voice)

iOS — Info.plist

<key>NSMicrophoneUsageDescription</key>
<string>We need the microphone for voice conversations with our support agent.</string>

Android — AndroidManifest.xml

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />

minSdkVersion 23 or higher.

---

Error handling

try {
  await session.send('Hello');
} on MugibException catch (e) {
  switch (e.code) {
    case MugibErrorCode.quotaExceeded:
      // upgrade plan
    case MugibErrorCode.rateLimited:
      // slow down
    default:
      print(e.message);
  }
}

Voice errors use MugibVoiceException / MugibVoiceErrorCode (same as before).

---

Migration from mugib_voice

Before	After
mugib_voice: ^0.6.1	mugib_sdk: ^1.0.0
MugibVoiceClient(apiKey:, agentId:)	MugibClient(apiKey:).voice.client(agentId)
REST for chat	mugib.chat.createSession() + session.send()

Existing voice-only apps can keep mugib_voice: ^0.7.0 — it re-exports voice from mugib_sdk.

---

Example app

cd sdk/flutter/mugib_sdk/example
flutter pub get
flutter run --dart-define=MUGIB_API_KEY=your_key

---

Maintainers

cd sdk/flutter/mugib_sdk
make help
make check
make update   # publish to pub.dev

See PUBLISHING.md.

---

Links

• Package: https://pub.dev/packages/mugib_sdk
• Voice-only legacy: https://pub.dev/packages/mugib_voice
• Integration guide: docs/flutter-sdk.md
• Voice guide: docs/voice-integration.md
• Mugib: https://mugib.com

---

License

MIT — see LICENSE.