mugib_sdk 1.0.45

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

Changelog

1.0.45

• A team member's line is no longer shown as Mujib's reply. While a person has the chat, sendMessageStream used to yield their reply as MugibStreamText, so apps drew it as Mujib (and twice with watchHandoff()). It now yields one MugibStreamMetadata with humanMode: true and agentMessages (each with the member's name), and no text. Show those as the team's lines; keep watchHandoff() running for the ones that come later.
• MugibStreamMetadata gains humanMode and agentMessages (optional, default off and empty). No other change.

1.0.44

• Photos from knowledge collections. Menu dishes, packages, products and any other list with a photo column use the same attachments field as catalog items. No new endpoint.
• New: MugibChatAttachmentsView draws those photos (optional Material helper). mugibImageAttachments returns only image entries with a URL.
• Apps that already render reply.attachments / MugibStreamAttachments need no code change.

1.0.43

• Android: the microphone runs only while the call screen is open. Removed FOREGROUND_SERVICE and FOREGROUND_SERVICE_MICROPHONE, and removed MugibCallService. Locking the screen or leaving the app stops the microphone. While the call is on screen, the display stays awake so the inactivity timeout does not blank it. RECORD_AUDIO during an open call is unchanged. androidKeepAliveInBackground and the call-notification title/text are ignored.

1.0.42

• Android: native voice-call audio engine (barge-in on the loudspeaker). Calls now capture with VOICE_COMMUNICATION and play with USAGE_VOICE_COMMUNICATION under MODE_IN_COMMUNICATION, so the device's hardware echo canceller, noise suppressor and AGC work — the caller can talk over the agent on speakerphone without the agent hearing itself. Routes to a wired / USB / Bluetooth headset automatically and follows plug/unplug. Hardware volume keys control the call while it runs. Falls back to the previous plugin path automatically when a device can't open it, the mic stays silent, or capture errors mid-call. Opt out with voice.client(id, androidNativeAudio: false).
• Fix: caller not heard on some Android phones (Xiaomi/Redmi). The plugin path now records from VOICE_RECOGNITION (was UNPROCESSED, which is near-silent on many builds) and replaces the per-chunk ×16 normaliser — it lifted room noise and speaker echo to speech level and broke server VAD and barge-in — with a gated, bounded AGC that never boosts silence. A dead-mic watchdog switches source if the first 1.5 s is digital silence. Never pins the top/back noise-reference mic.
• Fix: barge-in blocked for the whole agent turn. The client echo-guard window was re-armed on every streamed audio chunk, so it never expired while the agent spoke. It now starts at playback onset only, like the server gate.
• New: MugibVoiceClient.setSpeaker(bool?) switches loudspeaker mid-call (iOS + Android); audioRoute / currentAudioRoute report speaker / earpiece / headset / bluetooth; audioInfo exposes the engine and whether hardware AEC/NS/AGC are active.
• Barge-in that doesn't cut the agent off by mistake. A barge-in now needs the caller's level above the threshold for a sustained burst (120 ms with hardware AEC, 300 ms and ≥0.5 without), so a cough, a door or the agent's own echo no longer stops it. Frames held while confirming are sent with the confirming frame, so the first syllable isn't lost. On a confirmed barge-in the client stops playback at once, drops the rest of the agent's in-flight turn until the server sends interrupted, and tells the server (client_state.barge_in) so its gate lets the rest of the sentence through. The Android software AGC freezes while the agent is audible.
• Calls can't step on each other. A new call waits for the previous call's teardown; native audio runs per call (run ids), so a late teardown of a cancelled call can no longer stop the next call's mic and speaker.
• Never stuck deaf: watchdogs force a playback drain if the player never reports one, fall back if the native mic delivers no frames, and resume agent audio if the server never confirms a barge-in. A transient focus loss (phone call) holds agent audio and uplink; a permanent one no longer mutes the mic for the rest of the call. System-silenced capture (app in background) pauses uplink instead of abandoning the native engine.
• iOS: the mic stream is reopened after a phone call / Siri interruption; setSpeaker mid-call only overrides the output port.
• MugibVoiceClient.start() no longer opens a session after dispose().
• Android: calls keep working with the screen locked or the app in the background. A microphone foreground service with an ongoing-call notification runs for the call (androidKeepAliveInBackground, default true; localize it with androidCallNotificationTitle / …Text). Adds the FOREGROUND_SERVICE and FOREGROUND_SERVICE_MICROPHONE permissions; apps on Google Play declare the microphone foreground-service use in the Play Console. Override the icon with @drawable/mugib_sdk_call_icon.
• showMugibPostCallCsat: new commentLabel / errorText for localization.
• Package is now a Flutter plugin (Android native code); no setup change.
• Voice Edge hops. /token failover[] is walked in order (next healthy Edge, then Core), each hop with its own stream token. Gemini Live and OpenAI Realtime use the same path. fallback_url stays as the last resort.

1.0.41

• Voice Core fallback. /token fallback_url is now used when the Edge stream_url is unreachable (same behavior as voice-widget.js). Reconnects stay on Core after a fallback so a dead Edge does not loop.
• Localhost / raw-IP Edge hosts are skipped on the device (self-signed certs).

1.0.40

• Inbox photos on history. MugibChatMessage.attachments now carries the same catalog images (rooms, cars, products, courses, trips) that streamed replies already expose via MugibStreamAttachments. getHistory() and poll recent turns stay in sync with the widget and desk.

1.0.39

• Docs: README now documents the optional mugib_sdk_push add-on (proactive push with automatic App ID) and updated version references. No API changes.

1.0.38

• Automatic App ID. getPushConfig({bundleId, platform}) now lets Mujib resolve the Firebase App ID for the exact app automatically (it looks up or registers the matching app in the central Firebase project and caches it), so developers never paste an App ID. Called without arguments, behavior is unchanged (globally-configured App IDs are returned).

1.0.37

• Central Firebase for push (no per-app Firebase setup). New mugib.getPushConfig() fetches the non-secret Firebase client identifiers from Mujib (project id, sender id, api key, per-platform app id). Apps initialize a dedicated Firebase app from these values — no bundled google-services.json / GoogleService-Info.plist. The Firebase service account (the send credential) stays encrypted on the Mujib server and never reaches the device.
• Adds MugibPushConfig model with androidOptions / iosOptions helpers.
• setPushToken / device_id behavior unchanged; see docs §3.6 for the full centralized push flow.

1.0.36

• Mobile SDK is now its own sdk channel. SDK traffic is separated from the web widget: every request carries an X-Channel: sdk header so Mujib tracks app installations as distinct contacts.
• Managed device identity. The SDK generates and persists a stable device_id per installation and sends it automatically as the sdk contact identity — you never add it to your business payload. Read it via mugib.deviceId() if needed.
• Outbound push. New mugib.setPushToken(...) registers the app's FCM token (sent as a top-level field, never inside payload). This lets Mujib reach the user with a push notification for follow-ups, surveys, and marketing campaigns when the app is backgrounded or closed. Configure the Firebase service account in Portal → Channels → Mobile App (SDK).
• Adds shared_preferences dependency for durable device-id storage.

1.0.35

• Adaptive barge-in. The voice barge-in threshold now rises above the caller's ambient noise floor (tracked live), so background noise in a loud room is not mistaken for an interruption. The server//token value is always kept as a lower bound.
• Self-tuning echo guard. The post-playback grace window widens automatically when residual speaker echo is detected and decays back once the environment is clean (bounded to 600 ms), improving robustness on devices with weak hardware AEC.
• Audio interruption handling. Voice calls now react to OS audio interruptions (incoming phone call, Siri/Assistant, another app taking focus): mic capture/uplink pauses and buffered agent audio is preserved, then the session reactivates and resumes automatically when focus returns.
• client_state now also reports the live noise_floor so the server can co-tune its own VAD/echo gating.
• No public API changes.

1.0.34

• Image attachments in chat. Mujib can now show/send catalog images (inbox apps: inventory, cars, hotel, courses, trips).
• MugibChatReply.attachments — List<MugibChatAttachment> on blocking replies (send()), each with type (image), url, optional caption.
• New SSE event: streamed replies emit MugibStreamAttachments (via sendStream()); the JSON contents are no longer leaked into reply text.
• New public types: MugibChatAttachment, MugibStreamAttachments, helper parseMugibAttachments.
• No breaking change. Existing send() / sendStream() / sendStreamText() callers keep working; attachments are additive and optional to render.

1.0.33

• Add UPGRADE.md — copy-paste notice for app teams (Arabic + English)
• Please upgrade: mugib_sdk: ^1.0.33
• No endpoint or call-API change. Same /token, start(), send(), payload
• Voice Edge routing is already in 1.0.29+ (Core returns stream_url)
• Optional UI: MugibCallState.searching during KB / tool waits
• App voice handoff = Inbox follow-up, not a live join; use watchHandoff() for chat
• Server strips unresolved {{VAR}} placeholders — do not substitute in the app
• Flush playback on interrupted only

1.0.32

• Example: show MugibCallState.searching ("Looking that up…") during KB/tool waits so the demo matches the live protocol
• Docs: state list includes searching; web/Flutter voice handoff flags Inbox follow-up (nobody joins the live audio); flush playback on interrupted only
• Comments: reconnect opens a new server bridge — session / resume query params are forward-compat only

1.0.31

• Chat: live-agent replies use the same session.send() and reply field as the bot — no new endpoint and no app code change required
• Additive: MugibChatReply.agentMessages and MugibHandoffPoll.recent
• sendStream accepts a JSON handoff response (same reply text)
• Compatibility: existing send() / poll() / watchHandoff() unchanged

1.0.30

• Chat: additive session.watchHandoff() auto-poll stream (cancel to stop); existing poll() unchanged
• Voice/UI: optional Material post-call CSAT via showMugibPostCallCsat and MugibPostCallCsatListener when MugibVoiceCallOptions.chatSessionId is set
• Voice: expose linkedChatSessionId / canOfferPostCallCsat after start
• Compatibility: no breaking API changes for existing apps

1.0.29

• Voice: honor Core-routed stream_url from /token so calls can land on a Mugib Edge host (with Core fallback when no Edge is online)

1.0.28

• Voice: new MugibCallState.searching when the agent runs KB / MCP / tools (server state: searching) so UIs can show a "looking that up" indicator

1.0.27

• Docs: pin install examples to ^1.0.26+ and clarify Gemini Live / OpenAI Realtime use the same SDK voice API

1.0.26

• Voice: accept OpenAI Realtime agents (openai_realtime) on the same Mugib stream path as Gemini Live — no app API changes; provider is chosen on the agent
• Voice: isMugibVoiceAi covers both gemini_live and openai_realtime
• Compatibility: Gemini Live agents and existing start() / token / stream usage are unchanged for customers

1.0.25

• Docs: explain stream-token security, 45-second handshake TTL, unlimited established-call duration, reconnect behavior, and legacy SDK migration
• Docs: update Portal examples and all Flutter dependency references

1.0.24

• Voice: authenticate WebSocket handshakes with the short-lived, single-use stream_token returned by /voice-agents/{id}/token
• Voice: request a fresh stream token for every automatic reconnect
• Compatibility: retain API-key WebSocket fallback for older Mugib backends

1.0.23

• Voice: lower playback buffer default (960 frames ≈ 40ms @ 24kHz, was 166ms) for faster time-to-first-audio and response latency
• Voice: parallel WebSocket connect + playback setup during call start

1.0.22

• Voice: echo_guard_ms and barge_in_threshold come from Mugib /token and WebSocket ready — no per-app tuning; Admin settings are the single source of truth
• Voice: MugibVoiceToken includes server echo-guard fields; VoiceEchoGuard.applyServerConfig

1.0.21

• Voice: echo guard — suppresses mic uplink during agent playback unless input level exceeds a barge-in threshold; sends client_state to the server every ~150 ms
• Voice: preferSpeaker (default false) on MugibVoiceClient / MugibVoiceSession — earpiece/receiver routing on iOS and Android for cleaner AEC; opt in to loudspeaker when needed (preferSpeaker: true)
• Voice: VoiceEchoGuard — coordinates client-side gating with VoicePlaybackCoordinator (grace window + level-based barge-in)
• Voice: Android speakerphone follows preferSpeaker instead of always forcing speaker
• Voice: iOS audio session no longer forces defaultToSpeaker unless preferSpeaker is true
• Server (Mugib backend): matching uplink gate via voice.echo_guard_ms and voice.barge_in_threshold settings (migration 130)
• Voice: MugibVoiceService.client() — forwards preferSpeaker to MugibVoiceClient

Upgrade note: If you previously worked around echo with allow_interruption: false in Portal, you can re-enable barge-in and rely on echo guard instead.

1.0.20

• Voice: rollback to the stable 1.0.12 stack — removes Silero VAD, uplink level gates, and post-greeting mic blocks that caused cut-offs, delay, and silent uplink on iOS/web
• Voice: mic uplink stays open when barge-in is enabled; pauses only when the agent has interruption disabled and PCM is still playing
• Voice: VoicePlaybackCoordinator defers listening until agent audio drains

1.0.12

• Voice: defer listening UI/state until buffered agent PCM finishes playing, so false VAD/echo signals no longer cut agent speech mid-sentence
• Voice: wire allowInterruption from /token — mic uplink stays open when barge-in is enabled (default); uplink pauses during agent playback only when the agent has interruption disabled
• Voice: VoicePlaybackCoordinator keeps playback and call state in sync; real interrupted events still flush audio immediately for user barge-in

1.0.11

• Voice: MugibVoiceClient.inputLevel — smoothed mic input level stream (0.0–1.0) for building a live level meter so users can confirm their mic is captured
• Example: full voice-call screen — connect/end, mute, live transcript bubbles, call state pill + timer, animated mic orb + input level meter, and friendly error UI mapped from MugibVoiceErrorCode
• Deps: upgrade web_socket_channel 2 → 3, record 5 → 6, http → 1.5, flutter_lints 4 → 5 (no breaking public API changes)
• Deps: drop unused permission_handler — microphone permission is handled by record.hasPermission(), so consumers no longer pull its heavier Android setup

1.0.10

• Voice: MugibTranscript.partial — server streams incremental STT; replace the last line for the same role when partial is true
• Voice: MugibVoiceClient.transcriptLines — ready-to-render transcript list (no manual partial handling in your UI)
• Voice: MugibTranscriptBuffer helper for custom transcript UIs
• Requires Mugib backend with accumulated voice transcript + partial WebSocket field

1.0.9

• Fix: configure VoIP audio session for speaker-mode voice chat (like ChatGPT/Gemini) — iOS voiceChat + defaultToSpeaker, Android VOICE_COMMUNICATION + MODE_IN_COMMUNICATION + speakerphone for hardware AEC
• Add audio_session dependency; mic stays open during agent speech (barge-in is enforced server-side via Portal allow_interruption, not in the SDK)

1.0.8

• Fix: stop clearing agent audio on state: listening (only interrupted clears playback)
• Fix: pause mic uplink while agent speaks when allow_interruption is false (reduces phone echo)
• Read allow_interruption from /token response (voice agent setting)

1.0.7

• Fix: voice userContext payload — send expect_context=1 on WebSocket URL so the server waits for the context frame (matches browser widget reliability)
• Fix: open WebSocket before PCM playback setup for faster context delivery
• Requires backend with voice payload/KB fixes (expect_context; KB via search_knowledge_base tool + prefetch)

1.0.6

• Docs: explain proactive triggers — configured in Portal (projects/{id}/triggers), optional read via getWidgetTriggers(); returns [] when none configured
• Docs: remove legacy mugib_voice package references — use mugib_sdk only
• Requires backend with fix for GET /api/v1/widget/triggers (200 + empty array, not 500)

1.0.5

• Docs: sync install version to ^1.0.4+ across repo guides
• Add @Deprecated isGeminiLive alias → isMugibVoiceAi (migration from 1.0.3)
• Remove stale gemini_session.dart from package tree

1.0.4

• Fix: SSE streaming no longer drops spaces between tokens — parse data: lines per the SSE spec (strip at most one optional separator space, not all leading whitespace). Fixes merged words in sendStream().

1.0.3

• Rebrand voice stack as Mugib Voice AI in docs and public API (remove Gemini naming)
• Rename GeminiVoiceSession → MugibVoiceSession (internal)
• Rename isGeminiLive → isMugibVoiceAi on agent/token models

1.0.2

• Docs: clarify SDK scope — app connects to Agent; KB/MCP/tools run server-side
• Docs: move handoff poll and tool approval buttons to optional Advanced section
• Docs: minimal quick-start example (send() + send("yes") for confirmations)
• Code comments: label poll() / confirmTool() as optional UI helpers

1.0.1

• Focus SDK on chat + voice + session payload; widget config/triggers read-only on [MugibClient]
• Remove KB/stats from main client facade (advanced via [MugibApiClient] / [MugibKbService])
• Add getWidgetTriggers() for /api/v1/widget/triggers

1.0.0

• Unified mugib_sdk package: chat + voice + KB + widget APIs
• Chat: sessions, messages (JSON + SSE), payload, handoff poll, tool confirmations, conversions, CSAT
• Voice: Mugib Voice AI calls (from former mugib_voice)
• KB: list / add / update / delete via tenant API
• Widget config, stats, metrics