Key concepts
The mobile app shares most of its vocabulary with Hilal Software and Hilal Chatbot. This page covers the mobile-specific additions and the concepts you’ll see most.
Audience
The app serves two audiences: Amazon Seller subscribers and Hilal Chatbot subscribers. Many users are both. Articles in the docs that target one audience start with a callout like “For Amazon Seller subscribers.”
The app itself doesn’t make you pick — it shows the features your subscriptions and permissions unlock, hides the rest.
Sign-in (Hilal Auth)
The mobile app uses Hilal Auth, the same SSO that powers every Hilal web product, via OAuth 2.0 with PKCE. One account, one session, used across the mobile app, the web products, and the Chrome extension.
Tokens are stored encrypted on the device (iOS Keychain via expo-secure-store, Android Keystore equivalent). The session is invalidated automatically when the token expires; if you stay signed in for a long time, the app re-authorizes silently in the background.
Permissions
Permissions are read live from your Hilal Auth token’s claims. The app asks the token “what is this user allowed to do?” on every navigation event and:
- Hides sections you don’t have permission for (they don’t appear in the drawer).
- Returns to an
Unauthorizedscreen if you somehow land on a route you can’t access. - Refreshes on org switch so a permission change on the web takes effect on mobile within seconds.
Permissions are server-authoritative — the UI gates are convenience, not security. Every API call the app makes is re-checked server-side.
Organization
You belong to one or more Hilal organizations. The mobile app shows the active one in the drawer header; switching is one tap. Each org has its own sub/permission/data scope.
Sync
Most data on mobile is fetched live from the relevant backend (Hilal Software API, Chatbot API, or Chat Server) on demand and cached briefly via React Query. The app is not offline-first today — see the Offline-first sync Coming-soon entry on What’s new for the roadmap.
What this means in practice:
- Pull-to-refresh works on every list.
- Brief network drops (a tunnel, an elevator) are handled by retry — you may see a spinner.
- A long offline stretch produces stale data; the offline banner tells you so.
Push notification channels
Notifications are grouped into channels so you can opt in or out per-type. The full plan:
- Account — sign-in events, security warnings.
- Note reminders — local notifications you scheduled on a note.
- Inbox — new buyer messages or chatbot conversations needing attention.
- Amazon activity— orders received, listing changes, listing-hijack alerts, low stock.Coming soon
- Chatbot activity— customer-to-human escalations, agent auto-update events, live workflow status.Coming soon
- System — version updates, maintenance, OTA updates.
See Push notifications for the full mapping.
OTA updates
The app uses Expo EAS Update for over-the-air updates: when we ship a non-native change (most UI tweaks, copy fixes, bug fixes), the app fetches it on next open without you visiting the App Store. Native updates (when we add a new native module) still require an App Store / Play Store update.
The app shows a small “update available” banner when a new OTA bundle is ready; tap to apply and reload.
Modes
The app has a light and dark theme, configurable under Settings → Profile & theme. The current theme persists across sessions.
Audio and transcription
Voice notes are recorded locally (using the system microphone), uploaded to Hilal’s transcription service, and the transcript is attached to your note. The original audio is also kept and can be played back from the note’s detail.
Embedding ID (forward-looking)
Notes carry an embedding_id field. Today it’s empty for everyone — it’s the hook that makes the AI Notes → Chatbot KB integration possible. When you opt a note into chatbot knowledge (coming soon), the embedding pipeline runs, the ID is filled, and the note becomes a searchable chunk in your chatbot’s brain. See Notes → Chatbot KB for the full plan.