my-phone-app/ ├── fxmanifest.lua ├── client.lua ├── server.lua └── ui/ └── build/ ├── index.html ├── icon.webp ├── assets/ └── static/ local result = exports['qs-smartphone']:call('555-0100', 'audio', { callerNumberOverride = '555-9999', }) if result.success then print('Call started', json.encode(result.data)) else print(result.error, result.message) end bridge.onEvent((event, data) => { if (event === 'phone.locale.changed') { console.log('Language changed:', data.language) } }) Custom app exports React or jQuery-based custom apps TriggerClientEvent('phone:pushNotification', source, { appId = 'my_app', title = 'Title', text = 'Body text', }) You can open a specific phone app while the phone is visible. Client helpers are exports used from your client-side Lua files. Example: Stop recorder: App label Example: and other internal phone applications. local apps = exports['qs-smartphone']:getCustomApps()print(json.encode(apps)) await api.openPhoneApp('camera') This is useful for: Event Use phone:pushNotification Shows a phone notification using the same payload as server push. phone:notification Shows a simple ox_lib or qs-interface toast using msg and type . phone:usable:open Triggered when the player uses the phone item. Useful if you need to open the UI manually. phone:incomingCall Triggered when the player receives an incoming call. phone:callState Triggered when the call session state changes. Get phone scope identifier if exports['qs-smartphone']:IsPhoneOpen() then print('The phone is currently open') else print('The phone is closed') end Common bridge API methods Example: Use this to make your app adapt to the player phone language. Show toast notification Use this for custom apps that need voice notes, reports, audio logs or immersive roleplay recordings. app-specific data This allows you to create apps using: Pick GIF which app is active exports['qs-smartphone']:removeCustomApp('my_app') local result = exports['qs-smartphone']:call('555-0100', 'audio', { callerNumberOverride = 'Anonymous' }) const { api } = QSPhoneBridge.create({ appId: 'my_app', targetOrigin: 'https://cfx-nui-qs-smartphone', }) const locale = await api.getPhoneLocale() const title = await api.translateText('apps.settings.language') console.log('active locale', locale, 'sample translation', title) audiovideo photos videos all This means you can build your app in React or jQuery and still use the same smartphone bridge methods. Send notification using phone scope push = { title = 'City Hall', text = 'You have a new message', closeTimeout = 4500 } Automatic app removal Example: Example: any modern web framework that supports iframe usage exports['qs-smartphone']:updateCustomApp('my_app', { price = 900}) The scope ID is a persistent identifier used for: Push metadata This opens a text input prompt inside the phone. Use this when your custom app needs to exit itself or return the player to the phone interface. const photo = await api.pickCameraMedia() local result = exports['qs-smartphone']:call('555-0100', 'video') You can also trigger a client notification directly from Lua: Do not recreate phone systems manually if the bridge already provides them. Recommended usage: Remove an app It gives your app access to phone features such as: a charger position is removed Best practices From React, Vue, jQuery or plain JavaScript, use the standard FiveM fetchNui pattern targeting your own resource name. Full Configuration Available templates: Custom apps are automatically removed when the owner resource stops. Get current phone number CreateThread(function() Wait(2000) local ui = 'https://cfx-nui-' .. GetCurrentResourceName() .. '/ui/build/' local ok, err = exports['qs-smartphone']:addCustomApp({ id = 'my_app', label = 'My App', icon = ui .. 'icon.webp', category = 'Utilities', creator = 'Your Name', description = 'My first custom QS Smartphone app.', appStoreOnly = true, price = 0, sizeMb = 5, iframe = { url = ui .. 'index.html' }, custom = { enabled = true, bridge = { enabled = true, allowedOrigins = { 'https://cfx-nui-' .. GetCurrentResourceName() }, }, }, }) if not ok then print('addCustomApp failed:', err) end end) RegisterNUICallback('my-app:action', function(data, cb) print('Custom app action:', json.encode(data)) cb({ ok = true, result = 'done' }) end) Use QSPhoneBridge.create() . Start a call metadata = { reason = 'job_offer' } Example filters: Bank notification Load the bridge SDK in your HTML. ensure my-custom-phone-app await api.startRecorder() Check if the phone is open Use this for small app notifications inside the phone UI. await api.showToastNotification({ title: 'Done', text: 'Saved successfully', }) Push notification Example returned state: const { api } = QSPhoneBridge.create({ appId: 'my_app', targetOrigin: 'https://cfx-nui-qs-smartphone', }) const locale = await api.getPhoneLocale() const title = await api.translateText('apps.settings.language') console.log( 'active locale', locale, 'sample translation', title ) if the phone is visible This is useful if your app wants to reuse phone translations or stay consistent with the global smartphone language system. Send the message silently without showing a notification. identifying the active phone environment camera picker You can target a player using either their server ID or phone number. Example video call: Template usage Example: option pickers Bad: If you use qs-housing , you can register or remove phone battery charger points inside houses. Get theme mode Register the callback inside your own client resource: Recommended icon format: Offline delivery a housing instance is closed Error Meaning INVALID_SOURCE The player source is invalid. NO_SCOPE The player does not have an active phone scope. INVALID_PAYLOAD The notification data is missing or invalid. requireOnline = true bridge.onEvent((event, data) => { if (event === 'my:event') { console.log('Received custom event:', data) } }) the app ID is invalid Player must be online or the message will not be sent. Get all custom apps id = 'my_bank_app' Displays a notification when the message arrives. Client events Custom app iframe integration const theme = await api.getThemeMode() Use this when you want to redirect players to a specific app from another script. appLabel = 'City Hall' Theme change example -- Disable phone usage exports['qs-smartphone']:ToggleDisabled(true) -- Enable phone usage exports['qs-smartphone']:ToggleDisabled(false) -- Check if the phone is disabled local disabled = exports['qs-smartphone']:IsDisabled() current language radiocrime Create your resource. const name = await api.openTextPrompt({ title: 'Create contact', placeholder: 'Contact name', }) if (name) { console.log('Player entered:', name) } Method Description getPhoneState() Returns current phone state. getPhoneLocale() Returns current phone language. openPhoneApp(appId) Opens another phone app. closeCurrentPhoneApp() Closes the current app. getThemeMode() Returns current theme mode. translateText(key) Returns translated text from a locale key. showToastNotification(payload) Shows a phone toast notification. openTextPrompt(payload) Opens a text input prompt. openOptionPicker(payload) Opens an option selector. pickGalleryMedia(payload) Opens gallery picker. pickCameraMedia() Opens camera capture flow. pickGif() Opens GIF picker. startRecorder() Starts audio recording. stopRecorder() Stops audio recording and returns data. 'en' Emit a custom event Register the app from client.lua . React Example client.lua This is useful when you want to: Start recorder: RegisterNetEvent('phone:incomingCall', function(payload) print('Incoming call:', json.encode(payload)) end) Recorder API phone data isolation Add your UI inside ui/build/ . targetPhone = '555-0100' api.pickGalleryMedia() api.pickCameraMedia() api.openTextPrompt() api.showToastNotification() api.translateText() RegisterNUICallback('my-app:action', function(data, cb) print('Received data from custom app:', json.encode(data)) cb({ ok = true, result = 'done' }) end) The phone can send built-in events to your iframe app. You can use bridge events to communicate between your iframe UI and your Lua resource. start external phone interactions notifications This lets the player select media from the phone gallery. This is useful for advanced integrations where your custom app needs to send actions to your game logic. Message is saved and delivered even if the player is offline. Returns false if the phone is closed. instead of building separate duplicated systems. Examples The JavaScript bridge allows your custom iframe app to communicate with the smartphone. Sends a message directly to the Messages app as if it were sent by a system application or server script. The export automatically creates (or reuses) a conversation using the provided app name and can optionally display a push notification to the player. job notifications { id: 25, url: 'https://...', location: 'Los Santos', createdAt: 1710000000 } exports['qs-smartphone']:BatteryRegisterHousingCharger(houseId, vector3(x, y, z), 2.0) price = 450 exports['qs-smartphone']:addCustomAppsBatch({ { id = 'app_one', label = 'App One', icon = ui .. 'app_one.webp', category = 'Utilities', iframe = { url = ui .. 'app_one.html' }, custom = { enabled = true } }, { id = 'app_two', label = 'App Two', icon = ui .. 'app_two.webp', category = 'Business', iframe = { url = ui .. 'app_two.html' }, custom = { enabled = true } } }) Quasar Smartphone includes starter templates to help developers create custom applications faster. await api.openPhoneApp('messages') Use this when your app needs GIF selection support. bridge.emit('my:event', { value: true }) [phone]/[template]/phone-custom-react [phone]/[template]/phone-custom-jquery Parameter Description houseId Unique house identifier. vector3(x, y, z) Charger position inside the house. 2.0 Interaction distance. This allows your iframe app to detect if the phone is using light or dark mode. Custom apps are external UIs that run inside the smartphone using an iframe. a house is deleted Use NUI callbacks to communicate with Lua. Example: custom bridge events RegisterNetEvent('phone:callState', function(payload) print('Call state changed:', json.encode(payload)) end) These exports allow you to get the player phone identity. phone state Keep icons optimized exports['qs-smartphone']:ToggleDisabled(true) Iframe JavaScript bridge Use: App Store price Open option picker const media = await api.pickGalleryMedia({ mediaFilter: 'photos' }) custom UI integration exports['qs-smartphone']:SendNewMessageFromApp( playerId, 'Bank', 'Your account has been credited with $500.' ) Send notification using player server ID Always wait for the bridge to be ready before using phone API methods. Good: the phone is closed exports['qs-smartphone']:SendNewMessageFromApp({ targetPhone = '555-0100', appLabel = 'Job Center', message = 'Your application has been approved.', requireOnline = false }) Register apps after qs-smartphone starts Use allowedOrigins correctly This is the recommended way to connect your custom app interface with Lua actions. theme mode the app does not exist These templates already include the recommended structure for: Listen to incoming call exports['qs-smartphone']:SendNewMessageFromApp({ source = playerId, appLabel = 'Police Department', message = 'Case file updated.', push = false }) This is simpler when you already have the player source. const { bridge, api } = QSPhoneBridge.create({ appId: 'my_app', targetOrigin: 'https://cfx-nui-qs-smartphone', }) api.onReady(() => { console.log('Phone bridge ready') }) const state = await api.getPhoneState() // { visible, mode, activeApp, screen } const locale = await api.getPhoneLocale() // e.g. "tr", "en", "de" await api.showToastNotification({ title: 'Done', text: 'Saved successfully', }) const value = await api.openTextPrompt({ title: 'Rename', placeholder: 'Name', }) const media = await api.pickGalleryMedia({ mediaFilter: 'photos' }) const photo = await api.pickCameraMedia() // Opens Camera → capture → returns full gallery row { id, url, location, ... } or null on cancel null bridge.onEvent((event, data) => { console.log(event, data) }) exports['qs-smartphone']:updateCustomApp('my_app', { label = 'My Updated App', price = 900, category = 'Business' }) Custom app fields price = 0 Example returned data: api.onReady(() => { console.log('Phone bridge ready') }) Registering a custom app const locale = await api.getPhoneLocale() translations Event Payload Description phone.theme.changed `{ mode: 'light' 'dark', darkMode: boolean }` phone.locale.changed { language: string } Triggered when the player changes phone language in Settings. app:opened App data Triggered when an app is opened. app:closed App data Triggered when an app is closed. business calls Listen for custom events callerNumberOverride is optional. Starter templates only execute logic while the phone is visible Example fxmanifest.lua : .webp Use the bridge for phone features trdeesfrpt plain HTML/CSS/JavaScript marketplace orders Trigger a phone notification without exports Example result: Disable smartphone local scopeId = exports['qs-smartphone']:getPhoneScopeIdentifier(source) Vue Example: local success, errorCode, data = exports['qs-smartphone']:sendPhoneNotification(source, { appId = 'my_app', title = 'Hello', text = 'World', }) if not success then print('Phone notification error:', errorCode) end Avoid using IDs that may conflict with built-in phone apps. id = 'bank' Both starter templates use the same bridge API. Add your icon as icon.webp . block certain actions while the phone is open Close current phone app Government message await api.closeCurrentPhoneApp() jQuery You can send lock-screen or banner notifications directly to a player phone. Example index.html exports['qs-smartphone']:ToggleDisabled(false) exports['qs-smartphone']:BatteryUnregisterHousingCharger(houseId) Use api methods to interact with the phone. exports['qs-smartphone']:SendNewMessageFromApp({ source = playerId, appLabel = 'City Hall', message = 'Your license has been approved.' }) When your custom iframe app needs to communicate with your Lua resource, use standard FiveM NUI callbacks. Get current phone state exports['qs-smartphone']:OpenPhoneApp('messages') Basic example: Example: const recording = await api.stopRecorder() ensure qs-smartphone ensure my-phone-app Use it when you need to: { visible: true, mode: 'default', activeApp: 'my_app', screen: 'home' } toast notifications requireOnline = false Custom bridge events Use push notifications when your app needs to alert the player. These exports are used to manage custom apps dynamically. Send New Message From App local disabled = exports['qs-smartphone']:IsDisabled() This is useful for dynamic prices, premium DLCs, temporary discounts or roleplay economy systems. Export Description addCustomApp(payload) Registers one custom app. Returns success, errorCode . addCustomAppsBatch(payloads) Registers multiple custom apps at once. updateCustomApp(appId, patch) Updates specific fields of an existing app. removeCustomApp(appId) Removes a custom app by its app ID. getCustomApps() Returns the list of registered custom apps. Toggle Disabled a house shell is unloaded Field Type Description appId string App identifier related to the notification. appName string App display name. title string Main notification title. subtitle string Optional subtitle. text string Notification body text. closeTimeout number Time in milliseconds before closing automatically. This can be useful for: Built-in native smartphone apps are excluded from automatic removal, such as: Open text prompt Example resource structure: banking messages Call types Wait until the bridge is ready You can also update the price later: exports['qs-smartphone']:BatteryUnregisterHousingCharger('house_1') recorder functions exports['qs-smartphone']:SendNewMessageFromApp({ source = playerId, appLabel = 'City Hall', message = 'Congratulations! You have been hired as a mechanic.', requireOnline = false, push = { title = 'City Hall', text = 'You have a new message', closeTimeout = 4500, metadata = { reason = 'job_offer' } } }) validate phone ownership Example: Locale change example display the player phone number If my-custom-phone-app stops, its registered apps are removed automatically. [phone]/[template]/phone-custom-react local ui = 'https://cfx-nui-' .. GetCurrentResourceName() .. '/ui/build/' local ok, err = exports['qs-smartphone']:addCustomApp({ id = 'my_app', label = 'My App', icon = ui .. 'icon.webp', category = 'Utilities', creator = 'Your Name', description = 'Short description for the store.', appStoreOnly = true, -- false = pre-installed on home screen price = 450, -- optional; if > 0 app requires payment in App Store sizeMb = 5, iframe = { url = ui .. 'index.html' }, custom = { enabled = true, bridge = { enabled = true, allowedOrigins = { 'https://cfx-nui-' .. GetCurrentResourceName() }, }, }, }) if not ok then print('addCustomApp failed:', err) end anonymous calls GIF picker Register multiple apps Your resource should start after qs-smartphone . push = false Other examples: delivery alerts Translate phone text Use this when your system needs to communicate with the correct phone instance. local ok, err = exports['qs-smartphone']:addCustomApp(payload) if not ok then print('Could not register app:', err) end iframe communication const gif = await api.pickGif() Always check return values public phones job systems Push notifications server side local open = exports['qs-smartphone']:IsPhoneOpen() If the player cancels, it returns: Example: Available call types: Example: Field Type Description id string Unique app identifier. Use lowercase and avoid spaces. label string Name displayed to the player. icon string App icon URL. Usually points to your NUI build folder. category string App Store category. Example: Utilities , Games , Business . creator string Developer or studio name. description string Short App Store description. appStoreOnly boolean If true , the app appears only in the App Store. If false , it is pre-installed. price number Optional App Store price. If greater than 0 , the player must buy it. sizeMb number Visual download size shown in the App Store. iframe.url string URL of your custom app HTML. custom.enabled boolean Enables custom app behavior. custom.bridge.enabled boolean Enables the JavaScript bridge. custom.bridge.allowedOrigins table Allowed NUI origins that can communicate with the phone. the current phone mode Examples: Use it when your script needs to display a custom caller number. Field Description appId Your custom app ID. Must match the Lua registered app ID. targetOrigin The phone NUI origin. Usually https://cfx-nui-qs-smartphone . You can make a custom app free or paid. Returns true if the phone UI is currently visible. const value = await api.openTextPrompt({ title: 'Rename', placeholder: 'Name', }) Message dispatch alerts Add this script inside your custom app HTML: Remove a housing charger My App

My App

Notification exports return: Pick gallery media Use this when: Phone number and scope server exports Defines the conversation name shown inside the Messages app. Custom caller number success, errorCode, data Enables or disables the smartphone completely, preventing players from opening or interacting with it. You can also check the current disabled state at any time. allowedOrigins = { 'https://cfx-nui-' .. GetCurrentResourceName() } Use square icons with a clean design for the best App Store appearance. Common errors: or Pick camera media message = 'Congratulations! You have been hired as a mechanic.' Load the bridge SDK The text content that will be delivered to the player. Use this when the player needs to choose between multiple options. This export returns false if: NUI callback custom app to game Use this to know: exports['qs-smartphone']:sendPhoneNotification(source, { appId = 'my_app', title = 'Hello', text = 'World', }) Parameters: Parameters local number = exports['qs-smartphone']:GetCurrentPhoneNumber(source) Your allowedOrigins should match your resource NUI origin: local scopeId = exports['qs-smartphone']:getPhoneScopeIdentifier(source) if not scopeId then return end local ok, err = exports['qs-smartphone']:sendPhoneNotificationToScope(scopeId, { appId = 'my_app', appName = 'My App', title = 'New order', subtitle = 'Shop', text = 'Your package is ready for pickup.', closeTimeout = 5000, }) Example server.cfg : Use these templates if you want to build your own phone application without starting from zero. Determines whether the player must be connected to receive the message. link app data to a phone number You can listen to these events inside your own client resource. Update an app Register a housing charger Paid app: text prompts source = playerId Quick example: complete custom app flow fx_version 'cerulean' game 'gta5' author 'Your Name' description 'Custom QS Smartphone App' version '1.0.0' client_scripts { 'client.lua' } server_scripts { 'server.lua' } ui_page 'ui/build/index.html' files { 'ui/build/index.html', 'ui/build/icon.webp', 'ui/build/**/*' } dependency 'qs-smartphone' Attach custom data that can be used by integrations or custom applications. The recommended template already includes an example: Require online custom app notifications FiveM NUI communication const option = await api.openOptionPicker({ title: 'Select option', options: [ { label: 'Option 1', value: 'one' }, { label: 'Option 2', value: 'two' } ] }) Only the fields included in the patch are updated. Open another phone app from iframe Check disabled state Use it to adapt your custom app style automatically. opening and closing apps This returns the active SIM or metadata phone number for the player. Custom apps must be registered from the client side of your resource, after qs-smartphone has fully started. const state = await api.getPhoneState() Disable push notification phone bridge compatibility bridge.onEvent((event, data) => { if (event === 'phone.theme.changed') { console.log('Theme changed:', data.mode) if (data.darkMode) { document.body.classList.add('dark') } else { document.body.classList.remove('dark') } } }) You can start an audio or video call from your client resource. icon = ui .. 'icon.webp' Recommended custom app structure Create the bridge connection Silent message Notification payload const title = await api.translateText('apps.settings.language') Notification return values police dispatch calls Use unique app IDs If the origin is wrong, the bridge may not communicate correctly. local opened = exports['qs-smartphone']:OpenPhoneApp('messages') if not opened then print('Could not open app. Phone may be closed or app ID is invalid.') end gallery picker Listen to call state updates Free app: Built-in bridge events which screen is currently displayed -- Send by phone number exports['qs-smartphone']:SendNewMessageFromApp( '555-0100', 'Bank', 'Your account has been credited with $500.' ) -- Send by player source exports['qs-smartphone']:SendNewMessageFromApp( playerId, 'Job Center', 'Your application has been approved.' ) avoid opening another menu over the phone scripted missions exports['qs-smartphone']:OpenPhoneApp('bank') exports['qs-smartphone']:OpenPhoneApp('messages') exports['qs-smartphone']:OpenPhoneApp('camera') exports['qs-smartphone']:OpenPhoneApp('my_app') This allows players to charge their phone inside custom housing locations. You can also send a notification directly using the player server ID: To send a scoped notification, the player must have an active phone scope. exports['qs-smartphone']:BatteryRegisterHousingCharger('house_1', vector3(123.4, 456.7, 78.9), 2.0) This opens the Camera app, allows the player to capture a photo, and returns the full gallery row. Get current phone language mission updates Housing battery charger qs-housing Enable smartphone Client helpers Open a phone app prevent duplicated UI actions Control and query the Marketplace app duty system directly from server-side scripts. This system manages the Enter Service and Exit Service actions available inside the Marketplace Profile tab. Unlike the Settings Job Duty toggle ( on_duty ), Marketplace Duty is linked to the player's active Marketplace session and determines whether they are available as staff inside the Marketplace application. All exports automatically resolve jobs configured in Config.Marketplace.Shops , so you only need to provide the framework job name. All exports are server-side and use the resource name qs-smartphone . Verify whether a framework job is configured as a Marketplace shop. if exports['qs-smartphone']:JobExists('police') then print('Police shop is available') end Return value boolean Returns true if the job exists inside Config.Marketplace.Shops . Parameters Framework job name configured in the Marketplace. 'police' Job names are case-insensitive. 'Police' 'POLICE' 'police' All values are treated as the same job. Determine whether a player is currently working in any Marketplace shop. local onDuty = exports['qs-smartphone']:IsPlayerOnDuty(source) Return value boolean Returns true when the player is currently on duty. Parameters Server ID of the target player. source Get player's active duty job Retrieve the Marketplace job currently assigned to a player. local jobName = exports['qs-smartphone']:GetDutyJob(source) Return value string | nil Returns the framework job name while on duty. 'police' 'ambulance' 'mechanic' Returns nil if the player is not currently on duty. Parameters Server ID of the target player. source Set player duty status Clock a player into a Marketplace shop or remove them from duty. Start duty exports['qs-smartphone']:SetDuty(source, 'police') Stop duty exports['qs-smartphone']:SetDuty(source) Return value boolean Returns true when the operation succeeds. Parameters Server ID of the target player. source Framework job name configured in Marketplace. 'police' If omitted, the player will be removed from duty. Check if a job has active staff Determine whether at least one employee is currently on duty for a specific Marketplace job. local available = exports['qs-smartphone']:IsJobOnDuty('police') Return value boolean Returns true when at least one staff member is currently on duty. Parameters Framework job name configured in Marketplace. 'police' Example if exports['qs-smartphone']:IsJobOnDuty('ambulance') then print('Medical staff available') end Marketplace Shop Duty Check if a job exists Check if a player is on duty