FAQ

Is RoadPhone Fold included with Pro?

Yes. RoadPhone Fold is included with RoadPhone Pro and runs in the same roadphone resource. Follow the Fold guide for item setup, controls, saved state and the included 3D props. It uses the same exports.

I found a bug — what should I do?

Please post a detailed bug report in our Discord channel #errors. Include steps to reproduce, screenshots, and logs if possible. We’ll try to fix it as soon as we can.

How do I give myself or others permission to approve music?

Songs that players submit through the Music app have to be approved before they land in the library. The approval permission is handed out in-game with /music-verify:

/music-verify PLAYERID

The command toggles: no permission → grants it, already has it → revokes it
PLAYERID is the server ID of the player (visible in the player list / txAdmin)
Only administrators can run the command

All Commands

Full command reference including verification commands

My Music Library is empty — what do I do?

A fresh library only fills up once songs have been submitted and approved. Work through this checklist:

Add songs through the Music app

Players submit songs directly in the app. They land in the pending queue first, not in the library.

Approve the pending songs

Someone with the music approval permission (see above) has to approve them. Once approved, they show up in the library for everyone.

I don’t hear music in the Music app

Make sure you’re using our xSound version and start xSound before RoadPhone.

Checklist

Clear your client cache.
Check that GTA music is turned on.
Verify your Windows volume mixer isn’t at 0% (this is independent of FiveM).

If your loading screen uses YouTube and you muted it there, the sound is muted everywhere. Unmute the loading screen.

How can I remove apps?

Open /public/static/config/config.json, search for AppStore, and remove the block for the app(s) you want to disable. Remove apps from AppStore config

Images / Videos are not saved in the Gallery

Make sure you entered your Fivemanage MEDIA KEY correctly in API.lua.

Upload Setup

Fivemanage keys, or your own S3/presigned upload endpoint

Add jobs to the Service App / Add dispatches

Open /public/static/config/config.json, search for Business, then copy an example job and change: job, name, shortName, icon, number, openingHours, minGradeToManage and the coords. Service app jobs config

Add my own notifications

In ClientAPI.lua, find sendNotification(text) and replace Bridge.Notification.Show(text) with your notification trigger.

Talk on the radio and voice at the same time

If you use SaltyChat, set EnableHardCoreMode to false in your SaltyChat config.

Mouse stuck in the center when opening the phone

Go to Settings → Keyboard/Mouse → Mouse Input Method → Raw Input. Raw input setting

Notify EMS when someone is down

ESX
QBCore / Qbox

This example refers to esx-ambulancejob. If you use a different script, adapt accordingly.

In esx_ambulancejob/client/main.lua, find SendDistressSignal() and replace:

SendDistressSignal()

function SendDistressSignal()
    exports['roadphone']:sendDispatch("Injured person", "ambulance", nil)
end

This example refers to qb-ambulancejob. If you use a different script, adapt accordingly.

In qb-ambulancejob/client/dead.lua, search for “hospital:server:ambulanceAlert” and replace with:

qb-ambulancejob

exports['roadphone']:sendDispatch("Injured person", "ambulance", nil)

Phone doesn't open after reviving

If you’re using an old Ambulancejob or a custom one, go to bridge/modules/events/shared.lua and change the PlayerSpawn events from your framework you using to the custom event. Spawn event setting

Disable cryptocurrency

In config.lua, set Config.Crypto = false.

Lock radio channels

In config.lua, configure Config.lockedRadioChannels with the channel list. Locked radio channels config

Change the phone language

App names are excluded from translation. To localize app names, change them in config.json.

In config.lua, set the locale to your preferred language.

SaltyChat: Radio doesn’t work

If you have SaltyRadio on the server, remove it.
If not, try our SaltyChat version.

Car is locked after valet delivery

RoadPhone auto-detects the running key system and hands over the keys itself — qb-vehiclekeys, qbx_vehiclekeys, qs-vehiclekeys, wasabi_carlock, Renewed-Vehiclekeys, fast-vehiclekeys, filo_vehiclekey, is_vehiclekeys, mm_carkeys, MrNewbVehicleKeys, tc_keys and tgiann-hotwire. In that case there is nothing to configure.Only if your key system is not in that list, add it manually in clientAPI.lua:

GiveCarKeys

function GiveCarKeys(plate, model, vehicle)
    if Bridge.VehicleKeys.GiveKeys(vehicle or plate, model) then
        return
    end

    -- no supported system found — your own event goes here:
    TriggerEvent("vehiclekeys:client:SetOwner", plate)
end

Bridge.VehicleKeys.GetSystem() tells you which system was detected — nil means none.

Disable car delivery

Open /public/static/config/config.json and set DeliverCar to false.

GetExtendedPlayers error (es_extended 1.1/1.2)

Add this to es_extended/server/functions.lua:

GetExtendedPlayers helper

ESX.GetExtendedPlayers = function(key, val)
    local xPlayers = {}
    for _, v in pairs(ESX.Players) do
        if key then
            if (key == 'job' and v.job.name == val) or v[key] == val or v.variables[key] == val then
                xPlayers[#xPlayers+1] = v
            end
        else
            xPlayers[#xPlayers+1] = v
        end
    end
    return xPlayers
end

Problems with VideoCall

Clear your client cache.
On the first video call after clearing the cache, accept the F8 prompt to allow recording.
Accept the Windows Defender warning when it appears.

Use a fixed prefix for phone numbers

There are two number generators, and which one runs depends on your mode:

Metadata mode (default)
Without metadata

Numbers are created for the phone item in server/phone_metadata.lua → GeneratePhoneNumber(). Keep the collision check and the provider check intact, and only change how the number is composed:

local candidate = string.format("49%05d", math.random(10000, 99999))

Numbers come from server/serverAPI/serverAPI.lua → getPhoneRandomNumber():

function getPhoneRandomNumber()
  local prefix = 49
  local numBase = math.random(1000000, 9999999) -- 7 digits
  return string.format("%02d%07d", prefix, numBase)
end

Keep the total length consistent, and never hand out numbers inside a range that a number provider (phone box, Trap Phone) reserves — those calls would never arrive. With the SIM Card DLC, numbers come from the SIM registry instead.

I forgot my phone PIN ( only without metadata )

Clear your cache once — this will remove the PIN lock. Clear cache to reset PIN

Add jobs to the Jobs App

Open /public/static/config/config.json, search for JobsApp, then copy an example and change the name, coords, and icon. Jobs App config example

Finding IconsVisit Iconify, search for an icon, choose Vue + Components, and copy the icon name from the shown code.

ox_inventory with metadata

With metadata mode there is nothing to script in the item definition — RoadPhone reads and writes the item itself. Only make sure the phone item is stack = false and close = true.

Metadata System

Full setup, including the ox_inventory specifics

OxInventory snippets

If you don’t use metadata with OxInventory, use these snippets to block/unblock the phone based on inventory.The following example items block will block/unblock the phone based on inventory.

OxInventory items

  ['phone'] = {
  	label = 'Phone',
  	weight = 190,
  	stack = false,
  	consume = 0,
  	client = {
  		add = function(total)
  			if total > 0 then
  				pcall(function() return exports['roadphone']:unblockPhone() end)
  			end
  		end,

  		remove = function(total)
  			if total < 1 then
  				pcall(function() return exports['roadphone']:blockPhone() end)
  			end
  		end
  	}
  },

['purple_phone'] = {
    label = 'Phone',
    weight = 190,
    stack = false,
    consume = 0,
  	  client = {
  		add = function(total)
  			if total > 0 then
  				pcall(function() return exports['roadphone']:unblockPhone() end)
  			end
  		end,

  		remove = function(total)
  			if total < 1 then
  				pcall(function() return exports['roadphone']:blockPhone() end)
  			end
  		end
  	}
},

['green_phone'] = {
    label = 'Phone',
    weight = 190,
    stack = false,
    consume = 0,
  	  client = {
  		  add = function(total)
  			  if total > 0 then
  				  pcall(function() return exports['roadphone']:unblockPhone() end)
  			  end
  		  end,

  		  remove = function(total)
  			  if total < 1 then
  				  pcall(function() return exports['roadphone']:blockPhone() end)
  			  end
  		  end
  	   }
},

['red_phone'] = {
    label = 'Phone',
    weight = 190,
    stack = false,
    consume = 0,
  	  client = {
  		   add = function(total)
  			  if total > 0 then
  				  pcall(function() return exports['roadphone']:unblockPhone() end)
  			  end
  		   end,

  		   remove = function(total)
  			  if total < 1 then
  			  	pcall(function() return exports['roadphone']:blockPhone() end)
  			  end
  		  end
    
}
},

['blue_phone'] = {
    label = 'Phone',
    weight = 190,
    stack = false,
    consume = 0,
    client = {
  		  add = function(total)
  			  if total > 0 then
  				  pcall(function() return exports['roadphone']:unblockPhone() end)
  			  end
  		  end,

  		  remove = function(total)
  			  if total < 1 then
  				  pcall(function() return exports['roadphone']:blockPhone() end)
  			  end
  		  end
    }
},

['black_phone'] = {
    label = 'Phone',
    weight = 190,
    stack = false,
    consume = 0,
    client = {
  		  add = function(total)
  			  if total > 0 then
  				  pcall(function() return exports['roadphone']:unblockPhone() end)
  			  end
  		  end,

  		  remove = function(total)
  			  if total < 1 then
  				  pcall(function() return exports['roadphone']:blockPhone() end)
  			  end
  		  end
    }
},

A player lost their phone data / has the wrong data

With Config.UseMetadata = true the data lives on the phone item, not on the player. So:

Data “disappeared” after a trade or a death drop → it is on the phone item, wherever that item now is. Whoever holds it sees it. That is the intended behaviour.
Wrong data after a player used a second phone → each phone item has its own number and its own data.
Nothing at all → run /rpselftest. It reports whether the item was found, which slot is active and whether the inventory supports metadata.

Metadata writes are buffered (Config.PhoneWriteBehind), so another resource reading the item straight after a change can still see the old value. Flush first:

exports['roadphone']:PhoneWriteBehind_Flush(source)

Can a player get their data back after losing the phone?

Yes, if backups are on:

config.lua

Config.BackupEnabled = true
Config.AutoBackupEnabled = false   -- true = snapshot on every disconnect
Config.MaxBackupsPerPhone = 5

Players create and restore snapshots in Settings → Backup; they are stored per phone number in roadshop_backups.

SIM cards, the active SIM and the battery level are deliberately not part of a backup — restoring them would duplicate SIM cards and hand out free charge.

I forgot my phone PIN (with metadata)

Clearing the cache does not help here — the PIN sits in the item metadata. Two ways out:

In character: the mechanic NPC resets the PIN (addons/mechanic/config.lua, features.resetPin, default price $500 — set requirePayment = false to make it free).
As admin: clear it from the item metadata via UpdatePhonePin(source, nil, 0).

How do calls cost money / how do I bill for a phone?

That is the SIM Card DLC: numbers move onto SIM cards, and calls and messages draw from a prepaid balance.

config.lua

Config.SimCardDLC = true   -- needs Config.UseMetadata = true

SIM Card System

Credits, shop NPCs, eSIM, exports for jobs and shops

How do I make phones run out of battery?

config.lua

Config.BatterySystem = true   -- needs Config.UseMetadata = true

The phone drains while it is in use — extra for calls, music and the flashlight — and dies at 0%. Charging works through the phone’s own charging flow; other resources can drive it with chargeBattery, startCharging and stopCharging from the server exports.

Loop is printing money on my server

Loop’s payout ratio is decided by exactly three numbers in config.lua:

Config.Loop = {
    CoinPrice = 10,      -- what a coin costs the buyer
    DiamondRatio = 0.5,  -- coins → diamonds for the creator
    DiamondValue = 10,   -- payout per diamond
}

Payout ratio = DiamondRatio * DiamondValue / CoinPrice. With the defaults, 50% of everything spent comes back and 50% is destroyed. Lower DiamondValue or DiamondRatio to remove more money; raise MinPayout to slow payouts down. Run loopselftest in the server console to check the app’s setup.

Home

RoadVR

RoadPhone Pro

RoadPhone

RoadPad

RoadCarRadio

RoadPods

RoadBackup

All Commands

Upload Setup

Metadata System

SIM Card System