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
- Install
qb-core,oxmysqland the resources used by your chosen phone apps. The upstream manifest imports@qb-apartments/config.luaand the oxmysql library; ensure those resources are present. - Import the original
qb-phone.sqlinto a backed-up staging database. Do not paste an unrelatedphone_contactsorphone_callsschema from a community tutorial. - Start
qb-phoneafter its dependencies and ensure the wholehtmlUI directory is deployed. - 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:
| Table | Responsibility |
|---|---|
player_contacts | Saved contacts and phone numbers |
phone_invoices | Invoices and payment state |
phone_messages | SMS conversation storage |
player_mails | Mail inbox and message metadata |
crypto_transactions | Phone-visible cryptocurrency history |
player_vehicles | Shared player vehicle data included in the upstream SQL |
phone_gallery | Images in the phone gallery |
phone_tweets | Social 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 = falseConfig.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:
| Export | Arguments | Purpose |
|---|---|---|
sendNewMailToOffline | citizenid, mailData | Stores 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
| Symptom | Check first |
|---|---|
| Phone UI does not open | Config.OpenPhone, qb-phone startup, console and NUI assets |
| Contacts, tweets or messages disappear | Correct SQL tables, active database and citizen ID |
| Phone's garage app is empty | player_vehicles schema and server-side ownership queries |
| Voice calls fail | pma-voice, voice configuration and local/remote call state |
| Offline mail is missing | Actual sendNewMailToOffline export, recipient citizen ID and player_mails |
No such export OpenPhone | The export is not present; do not copy a different phone's API |
| Updates break player phone data | Compare qb-phone.sql against existing tables on staging; back up first |
Update checklist
- Pin
qb-phoneplusqb-core,qb-apartments, SQL, voice and banking dependencies. - Test fresh phone creation, existing inboxes, offline mail, calls, invoices and reconnects.
- Confirm app-specific services are enabled only when their real dependencies exist.
- 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.
