Replacing qb-phone: Moving Your QBCore Server to a Modern Phone

qb-phone has carried a lot of QBCore servers. It is free, it ships with the QBCore ecosystem, and if your developers know it well, it can be extended in any direction. Still, many servers eventually want to replace qb-phone with a modern phone, usually when they want features they would otherwise have to build and maintain themselves.

This guide covers the honest version of that switch: why servers move, what to audit before you do, what will not carry over, and a cutover plan that does not break your jobs, items or player habits.

Why QBCore servers replace qb-phone

There is nothing wrong with running qb-phone. Servers that switch tend to have one of these reasons:

• Feature gaps they would have to build. Video calls, call recording, a ride-hailing app with server-checked pickups, delivery jobs, vehicle rentals, racing with buy-ins, device models such as fold or retro phones, or payphones.
• Developer time. Every hour spent maintaining phone UI is an hour not spent on the content that makes your server unique.
• Look and feel. Players compare the in-game phone to the one in their pocket. A phone with iOS-style motion, a lock screen, a control center and widgets changes how often they use it.
• Localization. If your community is multilingual, a phone with built-in languages saves translation work.

If none of these apply to you, staying on qb-phone is a reasonable decision. If they do, read on.

What to check before you replace qb-phone

Framework integration

A replacement should read QBCore the way QBCore stores things, not through a generic layer. Our QBCore adapter reads the core object directly: citizen IDs, charinfo names, PlayerData.money cash and bank via Functions.AddMoney and RemoveMoney, jobs from QBCore.Shared.Jobs with grades, boss flags and duty, and offline characters from the players table for company management. Details are on the QBCore page. If you are on Qbox rather than classic QBCore, use the native Qbox build instead of the bridge.

Inventory and the phone item

QBCore's shared items already define a phone item, which is also the default item name our phone looks for. Supported inventories for the physical phone include qb-inventory and ox_inventory (both tested), plus adapters for ps-inventory, qs-inventory, codem-inventory, core_inventory and origen_inventory. Those five are statically verified only, so test them on staging first.

One behavior change to communicate: in our phone, phone state belongs to the device, not the character. A device_id stored in the item's metadata carries the number, contacts, settings and app data. If a player loses or hands over the item, the data goes with it.

Voice

qb-phone servers typically run pma-voice, which our phone supports for calls (6.6.2 or newer). FiveM Enhanced Voice is the other option. Check that your pma-voice version is current before cutover.

Banking, bills and company accounts

• Wallet and transfers use QBCore's cash and bank directly.
• Bills can use the phone's own billing, or read esx_billing, okokBilling or qs-billing if one of those runs on your server (Config.Wallet.billing in config/wallet.lua).
• Company accounts in the Services app auto-detect Renewed-Banking, qb-banking or qb-management for deposits and withdrawals.

What does not carry over

Be clear with yourself and your players: qb-phone data does not migrate automatically. There is no importer for qb-phone messages, contacts, photos, mail or tweets. Plan for a clean start:

• Phone numbers change. Our phone generates its own numbers per device (configurable prefixes and length in config/system.lua), so a player's old qb-phone number, often stored in charinfo.phone, is not reused.
• Contacts and chats start empty. Players will rebuild them in the first days.
• Any script that reads charinfo.phone to find a player by number will now see a number that does not match the phone. Switch those lookups to the phone's exports (below).

Most servers handle this by announcing a "new phone network" date, framing it in roleplay as a carrier switch, and keeping the old database tables untouched in case you need to roll back.

Find everything that talks to qb-phone

This is the step that prevents broken jobs after cutover. Other resources often trigger qb-phone events or call its exports to send mail, notifications or messages. Search your resources folder:

grep -rn "qb-phone" resources/ --include=*.lua

Typical hits are job scripts sending mail, heist scripts sending texts, and dispatch or garage scripts sending notifications. Each one needs to point at the new phone. Our server exports cover the common cases:

-- text a player from a service name or number
exports.phone:SendMessage("LSPD", targetNumber, "Your vehicle has been impounded.")

-- mail with an optional action button that triggers a server event
exports.phone:SendMail({
  to = targetNumber,
  from = "[email protected]",
  subject = "Job offer",
  body = "Report to **Los Santos Customs** at 9:00.",
})

-- push notification that respects the player's per-app mute
exports.phone:SendNotification(source, { app = "mail", title = "New job", body = "Check your inbox." })

-- look players up by number instead of charinfo.phone
local number = exports.phone:GetEquippedNumber(source)
local target = exports.phone:GetSourceFromNumber(number)

Replace phone with your resource folder name. Mail action buttons can only trigger server events of the resource that sent the mail, and the handler receives (source, data, mailId), so always re-validate source server-side. On the client, exports.phone:SetDisabled(true) closes and blocks the phone, which is what you want for cuffed or dead players.

A cutover plan that does not break your server

1. Configure on paper first

Decide your edition and apps before you buy. Most QBCore roleplay servers land on Pro (Wallet, Garage, Jobs, Maps, video calls) or Ultimate if they want Ride, Delivery, Rentals, Racing and the social apps. In the configurator you can set app values such as wallet transfer limits, billing jobs and ride fares before checkout. Edition contents are on the pricing page.

2. Stand up a staging server

Copy your server with a fresh database, then use this order in server.cfg:

ensure oxmysql
ensure qb-core
ensure qb-inventory
ensure pma-voice
ensure screenshot-basic
ensure phone

Remove the ensure qb-phone line entirely; do not just leave it after the new phone. The schema applies itself on first start, no SQL import. The full walkthrough is in our installation guide.

3. Test the flows players actually use

• Two players call, text and mail each other.
• A job script that used to send qb-phone mail now sends it through the new exports.
• A boss hires, promotes and fires from the Services app, and the job changes in QBCore.
• A Wallet transfer moves real bank money.
• The phone item moves between players with its data.

4. Check keybinds

The default key is F1 (+phone). Many QBCore servers bind F1 to a radial menu. Either change Config.OpenKeybind or tell players they can rebind it under Settings, Key Bindings, FiveM.

5. Cut over and keep a rollback

Announce the date, deploy during low population, and keep the qb-phone folder and its tables untouched for a couple of weeks. If something critical breaks, you can switch the ensure lines back.

After the switch

Give players a few days to rebuild contacts. Watch your support channel for scripts you missed in the grep. If a technical defect on our side cannot be fixed, you can request a voluntary refund within seven days; your statutory rights are unaffected.

Next steps

Try the phone before you commit: the configurator runs the real interface in your browser, so you and your staff can click through the apps your players use. Pick QBCore as the framework and the preview shows your exact build. For a broader look at what to compare, read how to choose a FiveM phone script.