QBCore Frameworkqbcore.netCommunity docs
On this page

Updated 2026-10-11 · 4 min read

qb-phone: installation, applications and real APIs

qb-phone provides QBCore's in-game phone UI for calls, contacts, messaging, mail, garage information and optional applications. This reference uses upstream commit 333e813, not the interfaces published for a different phone script or fork.

Installation and dependencies

  1. Install qb-core, oxmysql and the resources used by your chosen phone apps. The upstream manifest imports @qb-apartments/config.lua and the oxmysql library; ensure those resources are present.
  2. Import the original qb-phone.sql into a backed-up staging database. Do not paste an unrelated phone_contacts or phone_calls schema from a community tutorial.
  3. Start qb-phone after its dependencies and ensure the whole html UI directory is deployed.
  4. Test with two online characters: opening the phone, contact/message delivery, calls, banking and offline mail, then reconnect.

Database schema

The upstream SQL file declares these tables:

TableResponsibility
player_contactsSaved contacts and phone numbers
phone_invoicesInvoices and payment state
phone_messagesSMS conversation storage
player_mailsMail inbox and message metadata
crypto_transactionsPhone-visible cryptocurrency history
player_vehiclesShared player vehicle data included in the upstream SQL
phone_galleryImages in the phone gallery
phone_tweetsSocial posts from the built-in app

Migration warning: player_vehicles is also used by vehicle ownership/garage/dealership resources. Compare the existing table before importing or modifying schema; do not delete or recreate it just to repair the phone.

Actual configuration

The config.lua has Config.OpenPhone = 'M', Config.MaxSlots = 20, Config.TweetDuration = 12, Config.RepeatTimeout = 2000, Config.CallRepeats = 10, Config.Fivemerr = false, Config.BillingCommissions, Config.PhoneApplications and Config.StoreApps.

-- Modify these existing values in the installed upstream configuration:
Config.OpenPhone = 'M'
Config.MaxSlots = 20
Config.TweetDuration = 12
Config.Fivemerr = false

Config.PhoneApplications contains UI entries with names, icons, slots and optional job restrictions. StoreApps defines downloadable apps. There is no built-in Config.BatteryDecay, Config.DefaultApps, Config.PhoneAsItem or Config.JobApps in this pinned source.

Supported external server export

The reviewed server.lua registers one named server export:

ExportArgumentsPurpose
sendNewMailToOfflinecitizenid, mailDataStores a message for an online or offline character and notifies them when connected

The source consumes mailData.sender, subject, message and optionally button. Call it from a trusted server-owned workflow only.

-- An example inside an authorized server workflow where the recipient citizen ID
-- was already verified. Do not accept an arbitrary sender/recipient from a client.
local recipientCitizenId = 'EXAMPLE123'
exports['qb-phone']:sendNewMailToOffline(recipientCitizenId, {
    sender = 'Service Desk',
    subject = 'Application received',
    message = 'Your application has been recorded.',
})

OpenPhone, SendMessage, StartCall, AddTweet and SendBankingNotification are not registered exports of this upstream resource. Use its actual UI and internally registered event flows, or write a separately maintained integration instead of copying those names.

Events and integration boundaries

The source registers many qb-phone:server:* callback/event handlers for calls, SMS, invoicing, contacts, mail, transfers and social posts. Examples include qb-phone:server:GetPhoneData, GetInvoices, TransferMoney, sendNewMail and qb-phone:client:UpdateMessages. These are internal phone flows, not universally supported public exports. Never publish a client-triggerable money-transfer or mail-writing wrapper without server-side identity, amount and target checks.

External integrations may require pma-voice for calls, banking for payments, or screenshot/media services for attachments. Check installed revisions rather than assuming all applications work with every replacement phone.

Troubleshooting

SymptomCheck first
Phone UI does not openConfig.OpenPhone, qb-phone startup, console and NUI assets
Contacts, tweets or messages disappearCorrect SQL tables, active database and citizen ID
Phone's garage app is emptyplayer_vehicles schema and server-side ownership queries
Voice calls failpma-voice, voice configuration and local/remote call state
Offline mail is missingActual sendNewMailToOffline export, recipient citizen ID and player_mails
No such export OpenPhoneThe export is not present; do not copy a different phone's API
Updates break player phone dataCompare qb-phone.sql against existing tables on staging; back up first

Update checklist

  1. Pin qb-phone plus qb-core, qb-apartments, SQL, voice and banking dependencies.
  2. Test fresh phone creation, existing inboxes, offline mail, calls, invoices and reconnects.
  3. Confirm app-specific services are enabled only when their real dependencies exist.
  4. Audit internal finance/mail events and avoid trusting client-chosen prices or identifiers.

If you replace qb-phone instead of maintaining it, compare phone scripts on RPScripts by declared QBCore version, database tables and the exports your other resources call. RPScripts and qbcore.net are operated by the same owner.

Sources

Repository · Manifest · Config · Server export/events · SQL

Related: qb-banking, voice-chat troubleshooting.

Found an issue in this guide?

Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.

On this page

Leonida RP server website built with RPWebsite
RPWebsite

Advertisement · RPWebsite

Want a website for your server?

Launch a site with live player status, rules, and a join button in minutes.

Build your website