Installation

This guide will walk you through the complete installation process for RoadPhone Pro on your FiveM server.

RoadPhone Fold is included with RoadPhone Pro. Install the same roadphone resource, then follow the Fold setup for inventory items, controls and 3D props. For existing servers, see Pro & Fold Updates.

Requirements

Framework

ESX (es_extended)
QBCore (qb-core)
Qbox (qbx_core)
Standalone

Database

mysql-async
or oxmysql

Dependencies

xsound
OneSync enabled

Optional

An inventory with metadata support — ox_inventory, one_inventory, jaksam, tgiann, qb-inventory, codem or core_inventory
Voice system (pma-voice, mumble-voip, saltychat, yaca)

Step 1: Download & Extract

Download RoadPhone Pro

Download the latest version from your purchase location (Tebex/CFX).

Extract the resource

Extract the roadphone folder to your server’s resources directory.

resources/
└── [phone]/
└── roadphone/
   ├── bridge/
   ├── client/
   ├── server/
   ├── public/
   ├── API.lua
   ├── config.lua
   └── fxmanifest.lua

Ensure the resource

Add the following to your server.cfg:

server.cfg

ensure roadphone

Make sure roadphone starts after your framework (ESX/QBCore/Qbox), database, and inventory resources.

Step 2: Database Setup

There is nothing to import. RoadPhone ships an auto-installer: on the first start it creates every table it needs, adds missing columns and indexes to tables from earlier versions, and adds phone_number and phone_bank_iban to your framework’s player table. Watch the console on first boot:

[RoadPhone] Database: created table `roadshop_contacts`
[RoadPhone] Database: created column `users`.`phone_number`
[RoadPhone] Database: all 113 tables present (113 newly created)   <- count grows with new features

Make sure the database connection works

mysql-async (default) or oxmysql must be running and mysql_connection_string set in your server.cfg. The installer runs as soon as the database reports ready.

Give the database user CREATE rights

The installer issues CREATE TABLE and ALTER TABLE. A restricted user cannot do that, and you get:

[RoadPhone] Database ERROR: 12 table(s) could not be created: ...

Start the resource once, then check the console

Every newly created table and column is logged. A second verification pass runs afterwards and reports anything still missing.

The SQL files under __installation/ (roadphone-esx.sql, roadphone-qb.sql) are only a fallback — import one by hand if your database user is not allowed to create tables, or if you want to review the schema up front. On a normal install you never touch them.

Upgrading from an older version? Just start the new build. Migrations are part of the same pass — new columns, new indexes, widened enums. Take a database backup first anyway.

Step 3: Basic Configuration

Open config.lua and configure the essential settings:

Framework Detection

RoadPhone automatically detects your framework. No manual configuration needed.

Phone Item Requirement

config.lua

-- Set to true if players need a phone item to use the phone
Config.NeedItem = true

-- Regular phone items
Config.Items = {
    "phone",
    "purple_phone",
    "green_phone",
    "red_phone",
    "blue_phone",
    "black_phone"
}

If Config.NeedItem = false, all players can open the phone without needing an item.

Phone Keybind

config.lua

-- Command name for keybind
Config.PhoneCommand = "TogglePhone"

-- Enable custom keybind registration
Config.RegisterKeyMapping = true

-- Default key (players can rebind in FiveM settings)
Config.OpenKey = 'f1'

-- Used instead when RegisterKeyMapping = false (raw control id, 288 = F1)
Config.OpenKeyNumber = 288

Language

config.lua

-- Available: 'en', 'de', 'fr', 'es', 'it', 'pl', 'tr', 'cs', 'el', 'ru', 'zh'
-- (one file per language in lua-code/locales/, UI strings in public/static/locales/)
Config.Locale = 'en'

-- Temperature unit
Config.Fahrenheit = false

Step 4: Image Upload Setup

RoadPhone requires an image upload service for camera, profile pictures, and media sharing. Open API.lua and configure your upload service:

FiveManage (Recommended)
Custom Upload

API.lua

-- In config.lua
Config.uploadMethod = 'fivemanage'

-- In API.lua
API_KEY = "your-fivemanage-api-key"

Get your API key from fivemanage.com

API.lua

-- In config.lua
Config.uploadMethod = 'custom'

-- In uploader/upload-server.lua
-- Configure your presigned URL endpoint and API key

Configure your own upload endpoint in uploader/upload-server.lua. The endpoint should return a presigned URL for file uploads.

Without a valid API key, camera and image upload features will not work.

Step 5: Voice Integration

Configure voice chat integration for phone calls:

config.lua

-- Enable ONE of these based on your voice system
Config.UsePmaVoice = true      -- pma-voice
Config.UseMumbleVoip = false   -- mumble-voip
Config.UseSaltyChat = false    -- saltychat
Config.UseYacaVoice = false    -- yaca

If no voice system is enabled, phone calls will not work.

Step 6: Livestreams & Video Calls

Livestreams, Connect Live and video calls run through RoadShop’s streaming backend. Your Tebex transaction ID is what authorises your server against it:

API.lua

Cfg.TebexTransactionID = 'your-tebex-transaction-id'

Without it the backend answers 401 Unauthorized: video calls fail with a config-error notification, and livestreams cannot start. The server console prints Unauthorized: Check your TebexTransactionID in API.lua.

You find the transaction ID in your RoadPhone purchase confirmation. It is only sent server-to-server — never to the client.

The Music app does not need this key. It needs xsound running, and songs get into the library through player submissions plus approval (/music-verify) — or from your own source via the Custom Music API.

Step 7: Inventory Item Setup

If Config.NeedItem = true, you need to add phone items to your inventory system.

ox_inventory
QBCore
ESX
jaksam_inventory

Add to ox_inventory/data/items.lua:

['phone'] = {
label = 'Phone',
weight = 150,
stack = false,
close = true,
description = 'A smartphone'
},

Add to qb-core/shared/items.lua:

['phone'] = {
name = 'phone',
label = 'Phone',
weight = 150,
type = 'item',
image = 'phone.png',
unique = true,
useable = true,
shouldClose = true,
description = 'A smartphone'
},

Insert into your database:

INSERT INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`)
VALUES ('phone', 'Phone', 1, 0, 1);

RoadPhone registers configured phone items for use. Jaksam supports both the regular phone and the separate phone_fold item. Create or enable phone_fold in the inventory and list it in Config.FoldableItems; see Fold setup.

Step 8: Optional Features

Metadata System (Phone Stealing/Trading)

Enable item-based phone data for advanced features:

config.lua

Config.UseMetadata = true

-- 'auto' detects the running inventory. Force one only if detection picks wrong:
-- 'ox_inventory', 'one_inventory', 'jaksam', 'tgiann', 'qb-inventory', 'codem', 'core_inventory'
Config.InventorySystem = 'auto'

-- Metadata writes are coalesced instead of hitting the inventory on every change
Config.PhoneWriteBehind = true
Config.PhoneWriteBehindMs = 1000

Metadata System Guide

Learn how to set up and use the metadata system for phone stealing, trading, and multiple phones.

Target System

Enable target interaction for phone-related features:

config.lua

Config.UseTarget = true
Config.TargetSystem = "ox_target" -- or "qb-target"

SIM Cards

Numbers move onto SIM cards, calls and messages cost prepaid credits.

config.lua

Config.SimCardDLC = true   -- requires Config.UseMetadata = true

SIM Card System

Item setup, credits, shop NPCs and the exports for issuing SIMs.

Battery

The phone drains while it is used and has to be charged.

config.lua

Config.BatterySystem = true -- requires Config.UseMetadata = true

Find My

Location sharing between phone numbers, plus last-seen tracking for a lost phone.

config.lua

Config.FindMy = true

Housing

config.lua

Config.HousingEnabled = false
Config.HousingSystem = 'rtx_housing' -- esx_property, rtx_housing, ps_housing, rx_housing, LNS_Housing, vms_housing, custom
Config.HousingBillTypes = { 'electricity', 'water', 'gas' }

With HousingEnabled = false the housing scripts are not loaded at all — switching it on needs a resource restart, not just a config reload.

Loop

The short-video app comes with its own economy. These numbers decide how much money it removes from your server:

config.lua

Config.Loop = {
    CoinPrice = 10,           -- price per coin
    DiamondRatio = 0.5,       -- coins turned into diamonds for the receiver
    DiamondValue = 10,        -- payout per diamond
    MinPayout = 50,           -- diamonds needed before a payout
    PromotePricePerHour = 50,
    PromoteMaxHours = 24,
    InvestigatorJobs = { 'police' }, -- may trace a handle back to a phone number
    MaxClipSeconds = 60,
    PostRetentionDays = 0,    -- 0 = keep forever
}

Payout ratio = DiamondRatio * DiamondValue / CoinPrice. With the defaults, half of everything spent flows back into the economy and half is destroyed.

Audible Ringtones

config.lua

Config.HearableRingtone = true      -- bystanders hear a ringing phone (xsound, or mx-surround with Config.MXSurround)
Config.UnavailableRingSeconds = 6   -- how long an unreachable number keeps ringing
Config.Call = { RingTimeoutSec = 30 }
Config.FaceTime = { RingingTimeoutSec = 30 }

Use /ringtest in-game to hear how far a ringtone carries before enabling it server-wide.

Webhooks & Fees

API.lua also holds the optional Discord webhooks (crypto, messages, bank, calls, social apps, exploit detection) and the economy knobs:

API.lua

Cfg.YellowPageFee = 0
Cfg.BankPayTax = 0.05          -- 5%
Cfg.BankIBANPrefix = 'DE'      -- IBAN = prefix + 6 digits
Cfg.MinimumBankTransfer = 10000 -- transfers below this do not fire a webhook
Cfg.LivestreamPayTax = 0.05

Billing Integration

Connect with your billing system:

config.lua

-- Enable ONE of these
Config.myBilling = false
Config.okokBilling = false
Config.JaksamBilling = false
Config.bcsCompanyManager = false
Config.codemBilling = false      -- codem-billing v1
Config.codemBilling2 = false     -- codem-billing v2
Config.codemBilling2Folder = "codem-billing"
Config.rxBilling = false         -- rxscripts
Config.babloBilling = false      -- bablo scripts
Config.qfBilling = false         -- qfdevelopers (handles the money itself)

Banking Integration

config.lua

Config.okokBanking = false
Config.rxBanking = false

Step 9: Service & Emergency Numbers

Configure emergency services and dispatch:

config.lua

-- Emergency lines. A LIST of entries — players with a matching job can sign in
-- as dispatchers and take calls to that number.
Config.Leitstelle = {
    { number = 911, needjob = 'police' },
    { number = 112, needjob = 'ambulance' },
    -- one number shared by several jobs:
    -- { number = 555, needjob = { 'police', 'sheriff' } },
}

-- Jobs that can post news
Config.NewsAppAccess = {
    'police',
    'ambulance',
}

-- Service app: who may manage a business, which jobs are always open,
-- and which ones cannot receive dispatches at all
Config.ServiceMinGradeToManage = 0
Config.ServiceBusinessGrades = { ['police'] = 2, ['ambulance'] = 2 }
Config.ServiceAlwaysOpen = { 'police' }
Config.ServiceDispatchDisabled = {}

Config.Leitstelle must stay a list of { number, needjob } entries. The old map form (['police'] = 911) is not read any more — dispatch numbers would silently stop working.

Step 10: Final Steps

Restart your server

Restart your FiveM server to apply all changes.

Test the phone

Join your server and test the phone:

Press the configured key (default: F1) or use the phone item
Check that all apps load correctly
Test camera functionality
Make a test call

Give players phones

If Config.NeedItem = true, give players phone items:

-- ESX
xPlayer.addInventoryItem('phone', 1)

-- QBCore
Player.Functions.AddItem('phone', 1)

-- ox_inventory
exports.ox_inventory:AddItem(source, 'phone', 1)

Troubleshooting

Start with /rpselftest in-game. It prints framework, inventory, metadata support, the phone item it found and its metadata to the server console — that usually names the broken layer straight away.

Phone doesn't open

Check:

Resource is started (ensure roadphone in server.cfg)
Framework is loaded before roadphone
If NeedItem = true, player has a phone item
Keybind is correctly configured

Camera doesn't work

Check:

API key is set in API.lua
Config.uploadMethod matches your service
No firewall blocking outgoing requests

Calls don't work

Check:

Voice system is correctly configured
Both players have phone numbers assigned
xsound resource is running

Database errors

Check:

mysql-async or oxmysql starts before roadphone
Database credentials in server.cfg are correct
The database user may CREATE TABLE — otherwise the auto-installer cannot build the schema
The console on boot: it names every table it could not create

Framework not detected

Check:

Framework resource starts before roadphone
Framework is properly installed
Check server console for Bridge initialization messages

Next Steps

Metadata System

Enable phone stealing, trading, and multiple phones

Server Exports

Integrate RoadPhone with your other resources

Client Exports

Client-side integration options

Commands

Admin, repair and diagnostic commands

​Installation

​Requirements

Framework

Database

Dependencies

Optional

​Step 1: Download & Extract

​Step 2: Database Setup

​Step 3: Basic Configuration

​Framework Detection

​Phone Item Requirement

​Phone Keybind

​Language

​Step 4: Image Upload Setup

​Step 5: Voice Integration

​Step 6: Livestreams & Video Calls

​Step 7: Inventory Item Setup

​Step 8: Optional Features

​Metadata System (Phone Stealing/Trading)

Metadata System Guide

​Target System

​SIM Cards

SIM Card System

​Battery

​Find My

​Housing

​Loop

​Audible Ringtones

​Webhooks & Fees

​Billing Integration

​Banking Integration

​Step 9: Service & Emergency Numbers

​Step 10: Final Steps

​Troubleshooting

​Next Steps

Metadata System

Server Exports

Client Exports

Commands

Installation

Requirements

Step 1: Download & Extract

Step 2: Database Setup

Step 3: Basic Configuration

Framework Detection

Phone Item Requirement

Phone Keybind

Language

Step 4: Image Upload Setup

Step 5: Voice Integration

Step 6: Livestreams & Video Calls

Step 7: Inventory Item Setup

Step 8: Optional Features

Metadata System (Phone Stealing/Trading)

Target System

SIM Cards

Battery

Find My

Housing

Loop

Audible Ringtones

Webhooks & Fees

Billing Integration

Banking Integration

Step 9: Service & Emergency Numbers

Step 10: Final Steps

Troubleshooting

Next Steps