# 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](https://github.com/qbcore-fivem/qb-phone/tree/333e8132359b1c50c31c2bc6db8e8a64db6c93f6), 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](https://github.com/qbcore-fivem/qb-phone/blob/333e8132359b1c50c31c2bc6db8e8a64db6c93f6/fxmanifest.lua) imports `@qb-apartments/config.lua` and the oxmysql library; ensure those resources are present.
2. Import the **original** [`qb-phone.sql`](https://github.com/qbcore-fivem/qb-phone/blob/333e8132359b1c50c31c2bc6db8e8a64db6c93f6/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:

| 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`](https://github.com/qbcore-fivem/qb-phone/blob/333e8132359b1c50c31c2bc6db8e8a64db6c93f6/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`.

~~~lua filename="config.lua"
-- 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`](https://github.com/qbcore-fivem/qb-phone/blob/333e8132359b1c50c31c2bc6db8e8a64db6c93f6/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.

~~~lua filename="server.lua"
-- 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

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](https://rpscripts.net/product-category/phone-scripts/) 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](https://github.com/qbcore-fivem/qb-phone/tree/333e8132359b1c50c31c2bc6db8e8a64db6c93f6) · [Manifest](https://github.com/qbcore-fivem/qb-phone/blob/333e8132359b1c50c31c2bc6db8e8a64db6c93f6/fxmanifest.lua) · [Config](https://github.com/qbcore-fivem/qb-phone/blob/333e8132359b1c50c31c2bc6db8e8a64db6c93f6/config.lua) · [Server export/events](https://github.com/qbcore-fivem/qb-phone/blob/333e8132359b1c50c31c2bc6db8e8a64db6c93f6/server.lua) · [SQL](https://github.com/qbcore-fivem/qb-phone/blob/333e8132359b1c50c31c2bc6db8e8a64db6c93f6/qb-phone.sql)

Related: [qb-banking](/docs/resources/qb-banking), [voice-chat troubleshooting](/docs/troubleshooting/voice-chat).
