Pulse Phone docs

Pulse Phone: exports, events and state bags

This is the whole surface other resources can use. The phone resource is named phone. phone_api in the server console prints the add-on (app) API as a short summary. To add your own app to the phone, see Custom Apps next to this file.

For Pulse Phone 1.5.239 min readUpdated

1. State bags

The server writes these to Player(src).state. They are replicated, so clients read them as LocalPlayer.state.<key>, or Player(serverId).state.<key> for other players. The names match the ones other popular phone resources use, so existing HUD, dispatch and evidence scripts read them unchanged.

Key Type Meaning Set from
phoneNumber string | false number of the phone in hand (turn off with Config.Public.numberState = false) device load, provisioning, unique-phone switch
phoneOpen boolean phone out, screen shown client open/close, throttled flag event
phoneDisabled boolean disabled by SetPhoneDisabled server export
flashlight boolean torch on client torch toggle
airplaneMode boolean airplane mode client toggle
inCall boolean has a live call: dialling, ringing out or connected server call records
callAnswered boolean the call is connected server
onCallWith number | false server id of the other party (player-to-player) server
speakerphone boolean speaker on during a call server (phone:call:speaker)
mutedCall boolean this player muted their microphone on the call server (phone:call:signal)
otherMutedCall boolean the other party muted server
phoneItem boolean carries a phone item (Config.Item.required or unique phones) server inventory check
phoneBlocked boolean the player's state blocks the phone (dead, cuffed, escorted ... Config.Block) client state check, verified by the server
phoneEmergencyOnly boolean the phone opens on the emergency screen only (for example downed, Config.Block) client state check, verified by the server
phoneColour string | false unique phones only: finish id of the phone in hand item metadata / Config.Item.variants
phoneBattery number battery percent (0-100); other players' copies may lag (see below) server battery loop
phoneCharging boolean charging now server
phoneDead boolean battery empty: apps refused, calls ring out server
phone:anim, phone:anim:prop internal animation mirroring for other clients anim controller

Limits:

  • An incoming call sets inCall on the callee only once it is answered.
  • The three client flags (phoneOpen, flashlight, airplaneMode) are only accepted as booleans, through one rate-limited event. No other key can be set from a client.
  • phoneBattery is throttled for everyone except the phone's owner: it is written at once when charging starts or stops, when the phone dies, at 0, 20 and 100 %, and at every step below 20 %; otherwise it can lag up to 30 s. The owner's exports.phone:GetBattery() (client) and the server's GetBattery(src) are always exact.

2. Server events

Listen with AddEventHandler(name, fn) in a server script. Only the phone raises these. They are not net events, so a client cannot forge them.

Event Arguments
phone:numberChanged src, number \| nil, oldNumber \| nil
phone:toggled src, open
phone:callStarted callId, fromNumber, toNumber, fromSrc, toSrc (nil: not known yet), video
phone:callAnswered fromNumber, toNumber, fromSrc, toSrc, callId
phone:callEnded fromNumber, toNumber, reason, durationMs, fromSrc, toSrc, callId
phone:emergencyCall src, service ('police' \| 'ems' \| 'fire' \| ...), reason \| nil, coords (vector3) \| nil (Smart 911)
phone:emergencyText src, service, reason \| nil, body (Smart 911 emergency text)
phone:messageSent fromNumber, toNumber, body
phone:groupMessageSent fromNumber, groupId, body
phone:mailSent fromAddress, toAddress, subject
phone:wallet:transfer fromNumber, toNumber, amount, note
phone:photoSaved ownerNumber, url, kind ('photo' \| 'portrait' \| 'video')
phone:socialPost authorNumber, app, postId, caption, url
phone:mediaStored url, kind: a file the phone's upload stored
phone:mediaRefused src \| nil, url, where: a link the allow-list refused
phone:calendar:saved ownerNumber, event
phone:battery:died src
phone:notification:action src, app, notificationId, actionId: the player pressed a button your Notify offered (once per notification, within 30 minutes)

3. Client events

Listen with AddEventHandler in a client script. These are local and cannot be sent from the network.

Event Arguments
phone:toggled open, reason?
phone:openRefused reason: 'disabled', 'nui-focused' or 'check:<resource>'
phone:numberChanged number \| nil
phone:drive:carAudio resource, action, data: a button on Pulse Drive for the car stereo resource reported with SetCarAudio. action: 'play', 'pause', 'next', 'previous' or 'volume' (data.value, 0 to 1). Check resource == GetCurrentResourceName() and run your stereo's own controls; Pulse sends nothing while the state says canControl = false

4. Server exports (exports.phone:…)

Export Returns Notes
IsReady() boolean true once the phone takes requests: the database connection proved and the schema built, or the file store in use. A script that starts next to the phone waits on this instead of a guessed delay; false again while the database is down
GetPhoneNumber(src) number | nil from cache; nil until the player has loaded
SourceOfNumber(number) src | nil online players only
FormatNumber(number) string in Config.Numbers.format
GetEmail(src) address | nil
GetEmailOfNumber(number, cb) cb(address \| nil) works for offline players too
HasPhoneItem(src, number?) boolean always true when Config.Item.required is off; with unique phones number asks for that phone
Notify(src, { app?, title, body, sound?, actions?, deepLink?, thread? }) boolean actions: up to 3 { id, title, destructive?, deepLink? }; a press raises phone:notification:action. sound: a tone name, or false for silent
SetBadge(src, appId, count) boolean registered add-ons only
SendMessage(src, number, text) none as that player
SendMail(address, sender, subject, body) none
AddContact(ownerNumber, { name, number, avatar? }) boolean owner must be online
Call(src, number, video?) none places a call
IsInCall(src) boolean, callId
EndCall(src) boolean
SetPhoneDisabled(src, bool) / IsPhoneDisabled(src) boolean closes the phone if it is open
RecordTransaction(number, 'sent' \| 'received', amount, party, note?) boolean statement line only; does not move money
GetWalletBalance(number, cb) cb(balance \| nil)
UploadMedia(dataUrl, kind, cb) cb(url, reason) through the configured provider
IsMediaAllowed(url) boolean the server allow-list (Config.Media.allow)
Log(action, title, fields, src?) none writes to the phone's Discord/Fivemanage log
GetBattery(src) / SetBattery(src, percent) number server-authoritative level
IsCharging(src) / IsPhoneDead(src) boolean
ToggleCharging(src, on?, ratePerMin?) boolean an external charger (a cable item, a station script)
UsePowerbank(src) boolean single-use (reusable = false, the default): removes one Config.Battery.powerbank.item and charges amount % over time; reusable bank (reusable = true): plugs the phone in or out, charging to 100%
SaveBattery(src) / SaveAllBatteries() none levels also save every minute and on leave
RegisterApp / UnregisterApp / EmitApp / BroadcastApp / GetApps / Set / Get add-on apps (phone_api, CUSTOM_APPS.md): SDK v3 declarations add names and icons per language and OS, job grades, item gating, the web / media capabilities the owner reviews (Config.AppStore.capabilities), defaultInstalled and a dev-server devUrl (used only with set pulse_dev_apps true). An app id belongs to the resource that registered it while that resource runs. GetApps(src) is the list this player is offered
HasAppPermission(src, appId, perm) / GetAppContacts / GetAppPhotos / GetAppLocation(src, appId, cb) / GetAppRating(appId, cb) true / false / nil; cb(data, reason) creator apps (SDK v2): what the player allowed an app, the data it opens, the App Hub rating (CUSTOM_APPS.md sections 3 and 5)
RegisterProvider / UnregisterProvider / GetProvider / HasCapability / BridgeReport / GetCharacterId providers (custom_provider_template.lua in this folder)
RegisterFrameworkBridge, RegisterSite, RegisterMarketsEconomy, AddDirectoryEntry server exports, documented in the sections below
PhoneTaken / PhoneReturned / PhoneLocked / PhoneBypass / PhoneCustody / PhoneImei stolen phones
DropPhone / DroppedPhones, PairAccessory / UnpairAccessory / SetAccessoryBattery / RegisterAccessoryKind, IsBlocked, MarketsQuotes / MarketsShock as named
ClearNotifications(src, app?) boolean empties the notification list on that player's phone (all, or one app id)
StartActivity(src, def) id | false, reason an Island activity on the Island and Lock Screen (section 14)
UpdateActivity(src, id, patch) / EndActivity(src, id) / EndAllActivities(src?) boolean / count your own resource's activities only (section 14)
PlaceScriptCall(target, opts) callId | false, reason ring a player from a script identity: "Unknown", "Dispatch" (section 15)
EndScriptCall(callId) / GetScriptCallState(callId) boolean / 'ringing' | 'connected' | nil your own script calls only (section 15)
PlayerCall(src, number, video?, cb?) boolean the player places the call themselves, through every check the dialler makes (their own phone, Config.Block, the app being allowed, battery, carrier, rate limits). false only for a missing or over-long number. cb(result): the call's answer, or { ok = false, reason } when refused
PlayerSaveContact(src, { name?, number, avatar?, firstname?, lastname? }, cb?) boolean the player saves a contact into their own phone, checked as the Contacts app's save is. name falls back to firstname lastname, then to the number. false for a missing table or number. cb(contact) once saved, cb(nil) when the number is not valid, or cb({ ok = false, reason }) when refused
UnregisterSite(id) boolean removes a Browser site added with RegisterSite (section 9). Sites are removed by themselves when the resource that registered them stops
MapsAddPin(id, { label, x, y, category?, description?, colour? }) boolean a public Maps pin while the server runs (a business opening, an event venue). id: letters, digits and _, up to 32. coords = { x, y } works in place of x, y. category: hospital, police, garage, store, airport, bank, dealership, clothing, food, gas, job or other (the default). colour: '#RRGGBB'. Adding an id again replaces that pin; an id Config.Maps.locations already uses is refused, as is a 501st pin. Phones see the change within a few seconds
MapsRemovePin(id) boolean removes a pin added with MapsAddPin; false when there is none
MapsReportIncident(kind, x, y) id | nil a Maps report from your script (a crash your dispatch knows about). kind: a type in Config.Maps.incidents.types (crash, police, roadworks, hazard by default). A report of the same kind within mergeRadius keeps that one up instead and returns its id. nil when reports are off, the kind is unknown, the position is not usable or max reports are up

5. Client exports (exports.phone:…)

Export Notes
Open() / Close() / IsOpen() Open respects every veto below
AddOpenCheck(fn) → id / RemoveOpenCheck(id) fn() returning false refuses the open. Checks are removed when their resource stops
SetDisabled(bool) / ToggleDisabled() / IsDisabled() a local switch; the server's SetPhoneDisabled drives the same one
GetPhoneNumber() from the state bag
FormatNumber(number)
IsInCall()
Notify({ app?, title, body, icon?, colour?, sticky? }) shown by this player's phone only
SetFlashlight(bool) / GetFlashlight() / GetAirplaneMode()
GetSignalBars() / SetAirplaneMode(bool)
RegisterCaptureProvider(p) / CaptureAvailable() camera capture backends: { name, Available, Take, Video = { Start(opts, cb), Stop(cb), Available?, Modes? } }. The Camera's Slo-mo and Time-lapse tabs appear only when Video.Modes lists them ({ 'SLO-MO', 'TIME-LAPSE' }, or Video.Supports(mode) answers true); Start then gets opts.mode and must record at that speed
Rpc(name, data) the phone's own request channel; internal
useItem(data, slot) ox_inventory item hook for unique phones (client = { export = 'phone.useItem' })
usePowerbank() ox_inventory item hook for the power bank (client = { export = 'phone.usePowerbank' })
GetBattery() / IsCharging() / IsPhoneDead() this player's own level, exact; setting the level is server-only
SetRestriction(key, mode \| nil) a player state of your own for Config.Block (a jail, a cutscene, surgery): 'block', 'emergency-only' or nil to clear it. Kept per calling resource and cleared when that resource stops. Add key to Config.Block.calls to choose what happens to a live call (unlisted: the call is kept)
StartActivity(def) / UpdateActivity(id, patch) / EndActivity(id) / EndAllActivities() an Island activity on this player's phone, from a client script (section 14)
SetCarAudio(state \| nil) → boolean a car audio script's stereo on Pulse Drive, the car screen: its Home card and Music view show it before the phone's music, labelled "Car stereo · label". state: { title?, artist?, art?, label?, colour?, playing, position, duration?, volume?, canControl, app?, vehicle? }; position and duration in seconds (no duration = a live stream), volume 0 to 1 (shows a volume slider), art an https:// or nui:// image, colour '#RRGGBB', app the id of your registered phone app (an Open button), vehicle the car's entity handle (shown only while the player sits in it). No title = the stereo is on but idle. Send it on every change and about once a second while playing; nil clears it. One state per calling resource, forgotten when that resource stops. false when Config.Drive.enabled = false. Buttons arrive as the client event phone:drive:carAudio (section 3)
PhoneAudioRoute() where this player's call audio goes: 'speaker' (the default), 'earpiece' or 'bluetooth'
NearestDroppedPhone() the id of the dropped handset within reach (Config.Dropped.pickupRange), or nil. For a server with its own interaction system
IsTabletOpen() true while this player has the Pulse Tablet open
LocaleStrings(prefix) → { code, strings } text in the language this player picked on the phone (the server's Config.Locale until the phone has booted): every key starting with prefix, with English where that language lacks one. Add your own keys in a config/locales/<name>_<code>.lua file per language (Locale.Register('<code>', { ['myscript.key'] = '...' }))
OpenDeptStore(storeId?) opens a department store (Config.DeptStores) when the player stands at one of its locations, as the prompt there does; without storeId, whichever store they are at. Returns false anywhere else. The server checks access and distance again
AppCompatAdd / AppCompatRemove / AppCompatMessage / AppCompatPopUp / AppCompatContextMenu / AppCompatComponent / AppCompatOpenApp / AppCompatCloseApp / AppCompatIsOpen / AppCompatIdOf used by the app compatibility resource (pulse-phone-app-compat, CUSTOM_APPS.md section 11); not an API of their own

Open vetoes, in order: disabled, then another resource holding NUI focus (Config.Open.blockWhenNuiFocused), then each AddOpenCheck. A refusal raises phone:openRefused with the reason. Checks made before this one still apply: the player's state (Config.Block: dead, downed, cuffed, escorted, carried, jailed, under water, in the pause menu, or a SetRestriction of another script) and the phone item.

6. Compatibility with other phones

Many scripts (police, ambulance, boss menus, garages, deliveries) send mail, texts, notifications and job alerts using the event names other phone resources use. The phone answers those events itself (mail, texts, notifications and job alerts), so those scripts work without edits.

A script that calls another phone's exports by that phone's resource name needs one change: call exports.phone instead. These seven server exports cover what such scripts do, and any script may use them directly:

Export What it does
ResolvePhone(target[, cb]) target is { source }, { number }, { email }, { identifier } or { imei }. Returns { number, email, name, identifier, imei, source }: with cb, online or offline; without it, online only, immediately.
DeliverMailTo(target, mail[, cb]) mail = { sender, subject, body, attachments? }. Calls cb(true, mailId) or cb(false, reason).
SendText(from, to, body[, opts][, cb]) From an online phone, a stored message. From anything else, a live service message named opts.name.
DispatchAlert(jobs, { title, body, coords? }) Notifies every on-duty member of the jobs; tapping the alert opens Maps at coords. Returns how many it reached.
CompanyMessage(src \| nil, jobOrCompany, body[, opts][, cb]) From a player, a message to the company's Services inbox, or an alert when anonymous. From a script, an alert.
PayBill(src, billId[, cb]) Pays one of the player's bills, as the Wallet does.
IsOnDuty(src[, job]) Whether the player is on duty in job, or in their own job when job is omitted.

7. Housing providers (Home app)

These are built in and chosen automatically when one of the scripts is running.

  • Scripts: qb-houses, qbx_properties, qs-housing, loaf_housing, vms_housing, rtx_housing, ps-housing, bcs_housing, nolag_properties, esx_property (bridge/server/housing.lua + bridge/client/housing.lua).
  • Priority: 6, so a provider you register at 10 wins.
  • Pinning: Config.Providers.housing = '<name>' pins one; 'none' turns housing off.
  • Client relay: some scripts only expose client exports, or only accept their own menu's net events. For those, the phone asks the owner's client to call that export or fire that event, and the housing script's server validates it as usual. The relay (phone:housing:ask / phone:housing:answer) is token-bound to the player it asked.

Vendor API each adapter uses (from each script's published source or documentation, cited in the adapter). "Owner's client" means the phone asks the owner's client to fire the event the housing script's own menu fires.

Script List Lock Keys
qb-houses its tables player_houses, houselocations (read only) its own lock event, from the owner's client its own give/remove events, from the owner's client
qbx_properties its properties table (read only) none (shells) list only (its key events need the owner inside)
qs-housing server export GetPlayerHouses none exposed none exposed
loaf_housing client export GetOwnedHouses server exports IsDoorLocked / SetDoorLocked client exports GiveKey, RemoveKeyHolder, GetKeyHolders
vms_housing server exports GetPlayerProperties / GetProperty none exposed its give/remove key events, from the owner's client
rtx_housing client export GetPlayerOwnedProperties its lock event + GlobalState its permission events, from the owner's client
ps-housing its properties table (read only) none (door lock script) its addAccess / removeAccess events, from the owner's client
bcs_housing server export GetOwnedHomeKeys server exports isLocked / LockHome (toggle) server exports GetKeyHolders, RemoveKeyHolder (giving a key stays in its menu)
nolag_properties server export GetAllProperties server export ToggleDoorlock (sets the state) server exports GetKeyHolders, AddKey, RemoveKey, as the player
esx_property server export GetProperties (with lock state) none exposed list from GetProperties

The loaf_housing calls could not be re-checked: its current version publishes no exports page.

CurrentHome(src[, cb]) (optional). Pulse Home Wi-Fi asks a housing provider which home the player is standing in when they place a router (Config.Wifi.placement 'housing', or 'auto' with a housing script). Return the home's id - one of the ids your ListOwned gives that player - or nil, or answer through cb(id) when your script has to look it up. Without it the phone goes by the homes' positions (within Config.Wifi.homeRadius) and by instanced homes (a routing bucket other than 0). None of the built-in adapters above has it: none of those scripts publishes such a call. Add it to your own provider (custom_provider_template.lua in this folder).

8. Unique phones

Set Config.Item.unique = true. The number lives in the item's metadata:

Key Meaning
phoneNumber the number
phoneColour the finish
description tooltip text

Device rows for item phones are keyed item:<id>. Face Unlock enrols the character, not the handset. The item's finish reaches the interface as bootstrap.device.colour and the phoneColour state bag, and the handset in the player's hand is drawn in that finish.

9. Browser sites (RegisterSite)

The Browser app cannot reach the internet. A site is registered by a resource on the server, and a page is data (a title and a list of blocks) that the phone draws in its own style. A site cannot carry script, a stylesheet or a URL outside the game. The add-on page kinds (list, detail, board, form) are accepted too and converted.

Lua
exports.phone:RegisterSite({
    id       = 'pdm',                       -- [a-z0-9_], also the event namespace
    name     = 'Premium Deluxe',            -- shown on the start page tile
    host     = 'pdm.ls',                    -- optional; default '<id>.<Config.Browser.tld>'
    colour   = '#B8322F', glyph = 'car',    -- tile art (built-in glyph set)
    keywords = { 'cars', 'dealer' },        -- optional, for the search box
    pages    = { ['/'] = { title = 'Showroom', blocks = { ... } } },
    resolve  = function(src, path, cb) cb(page) end,              -- optional, dynamic pages
    submit   = function(src, path, form, values, reply) end,      -- optional, forms
})

Blocks: heading, text, stats, list, cards, links, form, directory, hero (a branded banner with an optional picture), posts (short posts with author and time) and empty (a designed "nothing here" panel). A list row, card or post may carry app + route to open a phone app (Services, Wallet, Echo...) instead of a page.

Built-in sites. Eight ship by default, each drawn from data the server really has or labelled as a brochure. Three are generated: the server's front page (name, players online, phones issued, the apps on the phone), the phone directory, and a help site built from Config. Five are in-world (<tld> is Config.Browser.tld):

Site Host Content
City Services city.<tld> Config.Services, live: who is on duty, call the line, message the company (opens Services)
City Wire citywire.<tld> public Echo posts and LS Pages adverts from the server's own tables; a designed empty page otherwise
Harbor Trust harbortrust.<tld> the caller's real balance from the bank provider, and the way into Wallet
Redline Motors redline.<tld> a showroom brochure (Config.Browser.showroom): class, seats and list price per model, a page per car
Chromeworks chromeworks.<tld> a customs price list (Config.Browser.customs) and the mechanic's line from Config.Services

Replace the brochure data in config, or turn a site off with Config.Browser.builtin = { redline = false, ... }.

10. Player data controls (requests for the interface)

Server requests the interface calls through the normal request bridge (fetchNui('phone:<name>', data) on the page, phone:rpc on the wire). Each acts on the caller's own phone only, is rate limited by the security layer, and answers { ok, reason? }.

Request Data Effect
calls:history:delete { id } (a Recents row's id from bootstrap) hides that call from this phone's Recents; the other party keeps theirs. reason = 'not-found' for an id that is not this phone's
calls:history:clear {} hides every call from this phone's Recents
messages:thread:delete { number } or { group } "Delete Conversation" for this phone only (same as messages:conversation:delete)
messages:threads:delete { threads = [ { number } \| { group }, ... ] } (at most 50) the same for several at once; answers { ok, deleted, failed }
notifications:clear { app? } empties the notification list (all, or one app id); the server relays it to the page as the NUI message notifications:clear { app? }, which the page must handle by calling clearNotifications(app)

A call row stays in the database until both sides have deleted it. Recents from bootstrap no longer include deleted calls.

11. Owner tools (console, or ace phone.admin)

<id|number> is an online server id (up to five digits) or any phone number, online or offline. Every command writes a security-log row and an activity-log entry.

Command Does
phone:resetpin <id\|number> removes the passcode and Face Unlock; the lockout clears
phone:wipe <id\|number> confirm erases the phone's own data (contacts, photos, notes, reminders, calendar, voicemail, memos, saved places, playlists, albums, blocks, mail) and hides its calls and conversations for that phone, then factory resets it. Without confirm it only says what it would erase
phone:number <id\|number> <newnumber> a new number: must fit Config.Numbers.format and be unused; the phone's own data, conversations and call history move to the new number. phone:number with no arguments shows your own number. Refused with unique phones on (the number is on the item)
phone:inspect <id\|number> a summary: number, mail, IMEI, created, online, setup, power, passcode, counts
phone:retention [now] runs Config.Retention pruning now (now is required while retention is off)
phone:health prints the start-up panel again, including voice conflicts and config problems

12. Clock and retention settings

Config.Clock.mode = 'server' (the default) publishes the server's clock in the global state bag phone:clock ({ hour, minute }), so every phone shows the same time; utcOffset pins a zone. 'game' follows the game's time of day (and so any weather/time sync script), 'real' is each player's own computer clock, 'custom' a function in config.

Config.Retention (off by default) prunes messages, social DMs, Dark Chat, call history, social activity and optionally mail older than the configured days, once a day at hour, in batches.

13. Bills, carrier, charging, store, Home Wi-Fi, burners, taps and payphones

All server side unless marked.

Server exports

Export Returns Notes
SendBill(sender, targetSrc, amount, reason, society?, cb?) id | false, reason sender: a player's server id, or a name for a script ('police', 'city_hall'). targetSrc must be online. society: optional job name ('police' or 'society_police'); payment then goes to that company's account. A script name with no society bills for the account of that name. cb(ok, idOrReason) runs once the bill is stored. Reasons: disabled, target, amount (not a whole number from 1 to Config.Bills.maxAmount), society, sender, self, rate (Config.Bills.perMinute), no-device
GetBills(src, cb?) { unpaid = {...}, paid = {...} } the phone's own bills plus esx_billing / okokBilling / qb-core phone_invoices rows, newest first; the paid list is capped at Config.Bills.paidHistory. Without cb it waits for the answer, so call it from a thread. Each bill: { id, source, from, company, number, reason, amount, at, status, paidAt }
IsWalletCardLocked(src) boolean true while that player has locked their phone's card in Wallet > Cards. A script that charges "the phone" (a shop's tap to pay) should refuse while it is locked, as the phone's own payments do
CreateInvoice(fromSrc, toSrc, { amount, reason?, kind?, job?, due? }) id | nil, reason an invoice, fine or medical bill (Config.Invoices). fromSrc: the issuing player's server id, or a name for a script ('city'). toSrc must be online. kind: 'invoice' (default), 'fine' (needs job) or 'medical'. job: the company the money goes to; a player must hold that job. due: epoch ms or seconds, or a number of days from now; left out, Config.Invoices.dueDays; 0, no due date. Called from a thread it waits until the invoice is stored; outside one it returns the id at once, or nil, 'pending' while it is being forwarded (issueTo = 'forward'). Reasons: disabled, data, kind, amount, job, not-employee, sender, target, self, due, rate, plus SendBill's
PayInvoice(src, id, cb?) ok, reason pays the invoice from that player's bank, as the Wallet's Pay does. id: 'bill:phone:<id>' (or the bare id) or another billing resource's 'bill:<source>:<id>'. Without cb it waits, so call it from a thread
GetInvoices(src \| { job }, cb?) { unpaid, paid } | { invoices, totals } a player's bills, as GetBills; or with { job = 'mechanic' } that company's phone invoices, newest first (up to 100), with totals = { paid, unpaid, unpaidCount, overdue, overdueCount }. Each invoice: { id, to, number, from, reason, amount, kind, status, at, due?, paidAt?, dispute?, disputedAt? }. Without cb it waits
CancelInvoice(id, cb?) ok voids an unpaid phone invoice; the payer is told. cb(ok, row \| reason), reasons id and gone (paid, cancelled or unknown). Without cb, from a thread it waits for the answer; outside one it returns true once the request is made
HasService(src, service?) boolean may this phone make a call / send a text / use data now ('call' default, 'text', 'data'). Always true while Config.Carrier.enabled is false
GetCarrierStatus(src) table | nil nil while the carrier is off or the line is not loaded. { service ('ok' \| 'no-plan' \| 'suspended' \| 'no-service'), bars, roaming, carrier, plan, job, line = { number, iccid, eid, status, autorenew, renewsAt, graceUntil, ... }, usage = { talkSeconds, texts, dataKB } }
UseMagPack(src, slot?, name?) boolean as if the player used a Reserve item (ak47_inventory's onUse); name is the item name used (pulse_magpack or pulse_magpack_max)
UseChargingCable(src, slot?) boolean as if the player used the cable item
DetachChargers(src) takes the Reserve and cable off the phone
GetChargingState(src) { pack, cable, source?, mode?, packLevel? } what is attached, and where the cable is plugged in
SetPowerSource(src, name \| false) boolean a power source your script provides (a house, a charging station): while set, the cable can be plugged in anywhere. false clears it and unplugs a cable using it
UseBox(src, slot?, name?) boolean as if the player used the sealed phone box (Config.Store.boxItem, or a per-finish box name)
IsOnWifi(src) boolean true while that player's phone is online over Pulse Home Wi-Fi: a router, or a Personal Hotspot whose own phone has service. Decided on the server from where the character stands; false while Config.Wifi.enabled is false
SetRouterPlacementCheck(fn \| nil) boolean your own rule for where a router may go, replacing Config.Wifi.placement: fn(src, coords, bucket) -> ok, reason. coords is { x, y, z } of the spot, bucket the player's routing bucket. A false answer refuses, and reason (a string) is what the player is told. maxPerPlayer and minSpacing still apply. nil goes back to the config rule. A function that errors refuses
UseRouter(src) boolean as if the player used the router item (Config.Wifi.item): starts placing it (ak47_inventory's onUse)
UseBurner(src, slot?) boolean as if the player used the burner item (Config.Burner.item): the burner comes out (ak47_inventory's onUse)
IsBurnerNumber(number) boolean true for a Pulse Burner's number, live or destroyed
TapNumber(number, reason, hours, officerSrc?) id | nil, reason a police tap from an MDT (Config.Taps). With officerSrc that player must be allowed (job, grade, duty) and their maxActive applies; without it the tap is placed by your resource. Call it from a thread or an event handler: it waits for the number's database lookup. Reasons: disabled, number, emergency, reason (8-200 characters), hours (1 to maxHours, whole), unknown-number, exists, untappable (a burner with Config.Burner.allowTaps = false), not-in-service, limit-officer, limit-server, not-police, grade, off-duty, busy
EndTap(id) boolean ends an active tap
UseBudsItem(src) boolean as if the player used the Pulse Buds item (Config.Accessories.buds.item): the case comes up in their hand to pick Left, Right or Both (ak47_inventory's onUse). With Config.Accessories.buds.caseInHand = false it is UseBuds
UseBuds(src) boolean the Pulse Buds straight in if they are out, out if they are in, without the case
AreBudsIn(src) boolean true while that player's Pulse Buds are in: their calls are private and their phone's sounds stay in their ears
UseRingLight(src) boolean as if the player used the Pulse Ring Light item: starts placing it (ak47_inventory's onUse)
UseCardWallet(src) boolean as if the player used the Pulse Card Wallet item: on the phone if it is off, off if it is on (ak47_inventory's onUse)
IsCardWalletOn(src) boolean true while the card wallet is on that player's phone

Client exports (ox_inventory item hooks)

Export Item entry
usePack client = { export = 'phone.usePack' } on pulse_magpack
useCable client = { export = 'phone.useCable' } on pulse_cable
useBox client = { export = 'phone.useBox' } on pulse_phone_box (and the per-finish boxes)
useRouter client = { export = 'phone.useRouter' } on pulse_router (Pulse Home Wi-Fi)
useBurner client = { export = 'phone.useBurner' } on pulse_burner (the Pulse Burner)
useBuds client = { export = 'phone.useBuds' } on pulse_buds
useRingLight client = { export = 'phone.useRingLight' } on pulse_ringlight
useCardWallet client = { export = 'phone.useCardWallet' } on pulse_wallet

The server re-reads the slot and the item for each of these; nothing the client sends is trusted. Ready-made item entries are in config/items/.

Client export: opening the store from your own script

Export Returns Notes
OpenStore() boolean opens the store counter when the player stands at a store (Config.Store.locations, within Config.Store.range), exactly as pressing E there does; with no counter there, the Pulse machine they stand at (as OpenVendingMachine()). false anywhere else. For a server with its own menu, NPC or target script. The server still checks the distance at checkout

Server events

Event Arguments
phone:bills:sent billId, ownerNumber, amount, reason, job \| nil
phone:bills:paid fullId ('bill:<source>:<id>'), payerNumber, amount, job \| nil
phone:tap:intercept { id, tap, number, at, kind ('sms' \| 'group' \| 'call'), from, to, body, duration (s), status }: one intercepted event on a tapped number. Never call audio

State bags

Key Type Meaning
phoneCharger 'pack' | 'cable' | 'both' | nil the accessories on the phone in this player's hand; written only by the server
phone:unbox internal the unboxing scene other players see; written only by the server

Payphone calls

A payphone call is an ordinary call of the phone's call system, so phone:callStarted, phone:callAnswered and phone:callEnded fire for it. The caller's "number" is what Config.Payphone.callerId shows: Config.Payphone.callerLabel (default Payphone), Unknown, or the booth's own number. The payphone itself has no exports.

14. Island activities (Island and Lock Screen)

Another resource can show an Island activity on a player's phone: the same Island and Lock Screen card the phone's own timers and calls use, drawn by the same code. A delivery route, a heist countdown, a tow truck on its way.

Server (exports.phone:…)

Lua
local id, why = exports.phone:StartActivity(src, {
    id        = 'delivery',            -- optional, your own key (1-32 of A-Z a-z 0-9 _ -); starting it again replaces it
    title     = 'Delivery route',      -- required, 1-40 characters
    detail    = '3 stops left',        -- optional, up to 60
    compact   = '1/4',                 -- optional, up to 12: the short text beside the camera
    progress  = 0.25,                  -- optional, 0 to 1: a bar
    -- or a countdown the phone runs itself (no update per second needed):
    -- countdown = 90,                 -- seconds (1 s to 24 h), or endsAt = os.time() + 90
    -- endOnZero = true,               -- remove it when it reaches zero (else it stays at 0:00)
    glyph     = 'truck',               -- a glyph (list below), or appIcon = 'my_app' (an app's icon)
    colour    = '#FF9F0A',             -- #rrggbb, must reach 3:1 contrast on black
    link      = 'my_app/route/42',     -- optional: where a tap goes ('messages', 'my_app', 'my_app/<route>')
})
if not id then print('not shown: ' .. why) end

exports.phone:UpdateActivity(src, id, { detail = '2 stops left', progress = 0.5 })
exports.phone:UpdateActivity(src, id, { detail = false })   -- false (or '') clears a field
exports.phone:EndActivity(src, id)
exports.phone:EndAllActivities(src)     -- every activity YOUR resource shows on that player (nil = on everyone)

UpdateActivity takes any of the same fields except id; countdown = false stops a countdown, link = false removes the link. It returns true, or false, reason.

Client (exports.phone:…, this player's phone only)

Lua
local id = exports.phone:StartActivity({ title = 'Fuel', glyph = 'fuel', progress = 0.6 })
exports.phone:UpdateActivity(id, { progress = 0.55, compact = '55%' })
exports.phone:EndActivity(id)

Same definition and limits. endsAt is read against GetCloudTimeAsInt() on the client. A link or appIcon naming an add-on works once the phone has received this player's add-on list.

What the player sees

Where What
Island, one activity the glyph or app icon leading; compact trailing (else the countdown, else detail)
Island, two or three small pills either side of the camera. The phone's own call, timer and music always stay in front of yours
Island, held title, detail and the progress bar
Lock Screen the card: title, detail, progress bar and a stripe in your colour
Tap opens link (an app of the phone, or a registered add-on at the route). No link: the tap expands it

A countdown shows as m:ss (h:mm:ss over an hour) after your detail ("Drill running · 1:24") and fills the bar as it runs.

Glyphs: the Island's call, music, timer, navigation, record, camera, download, job, delivery, event, emergency, and the add-on set shield, cross, wrench, cart, bank, key, car, house, briefcase, radio, pin, bolt, book, chart, dice, fuel, gavel, heart, lock, note, plane, tag, truck. Default: event.

Limits (config/apps.lua, Config.Api.activities)

Setting Default Meaning
perResource 2 activities one resource may show on one phone at once ('limit-resource')
perPlayer 4 from every script together ('limit-player'); the interface also never holds more than 6
updateMs 500 one activity updates at most this often. Faster updates are merged and the newest state is sent when the interval ends, so the last one always arrives
startsPerMinute 20 starts per resource per player per minute ('rate-limited')
enabled true false refuses every start ('disabled')

Text lengths are fixed by the screen: title 40, detail 60, compact 12 characters. Longer text is refused, not cut, with a reason such as 'title is longer than 40 characters'; an unknown field (detial = …) is refused too. Each refusal also prints one console line naming your resource (at most once a minute per reason).

Other reasons: 'player-offline', 'no-phone' (the player's phone has not loaded), 'unknown-activity' (not yours, or already ended), 'id cannot change'.

Cleanup

Your activities end when you end them, when your resource stops (the server and client halves each clear their own), when the player leaves, and - with endOnZero - when the countdown runs out. One resource can never update or end another's: activities are keyed by the calling resource.

15. Script calls (a custom or hidden caller id)

A server script can ring a player from an identity that is not a phone - a mission's "Unknown" caller, a dispatcher - through the phone's own call system: the ringtone, the call screen, answer and decline, call waiting when they are already talking, Recents, and the public call events (phone:callStarted, phone:callAnswered, phone:callEnded).

Lua
local callId, why = exports.phone:PlaceScriptCall(target, {   -- target: server id, or a phone number held by someone online
    label       = 'Unknown',           -- required, 1-32 characters: what the call screen and Recents show
    number      = '555-0142',          -- optional, 3-15 digits (+ - ( ) and spaces allowed)
    hidden      = false,               -- default: true without a number, false with one
    speaker     = dispatcherSrc,       -- optional: a player whose voice carries the call
    ringSeconds = 30,                  -- 5 to 60 (default Config.Api.scriptCalls.ringSeconds)
    onAnswer    = function(callId, src) end,
    onDigit     = function(callId, src, digit) end,            -- a key on the in-call keypad: '0'-'9', '*', '#'
    onEnd       = function(callId, reason, durationMs) end,   -- 'ended' | 'missed' | 'declined' | 'dropped' | 'busy'
})
exports.phone:EndScriptCall(callId)          -- hang up from your side
exports.phone:GetScriptCallState(callId)     -- 'ringing' | 'connected' | nil

Audio. With speaker, that player is the calling end - their own phone shows the call - and the phone's existing voice routing puts both in one call channel (pma-voice, mumble-voip, SaltyChat, TokoVOIP, YACA), exactly as for a phone-to-phone call. Without speaker nobody is on the far end: the line connects and is silent, and your script supplies what the player hears or reads (onAnswer is where to start it).

Phone menus. The in-call keypad sends each digit the player presses: onDigit gets it on a script call, so a script can run a menu ("press 1 for parts, 2 for service"). On any call, every other player listening hears the touch tone, and the server event phone:callDigit (callId, src, digit) fires for scripts. Digits come only from a connected, unheld call and are rate-limited.

Security

Server only. These are server exports and no net event leads to them, so a client can never place a script call. EndScriptCall and GetScriptCallState only answer the resource that placed the call, and a player's own call can never be ended through them.

Logged. Every script call writes Script call placed and Script call ended to the phone's activity log (calls: the resource, the label, the number or withheld, the callee, the reason) and a call-history row, whose caller column is the number shown, or the label when the number is withheld. A script call never offers voicemail (there is no one to offer it to).

Refusals (false, reason): 'unavailable' (target offline, phone not loaded, dead battery or no service), 'busy' (already ringing or dialling), 'speaker-busy', 'speaker-is-target', 'limit-resource' (Config.Api.scriptCalls.perResource, default 8 at once), 'disabled', and a sentence for a bad option ('label is required', 'number must have 3 to 15 digits', 'unknown field "video"'). Your resource stopping hangs up its calls; the callbacks are not called then, because the resource is gone.

A working example of sections 14 and 15: pulse-phone-devapi-demo/ (in this folder) (/devkit_delivery, /devkit_heist, /devkit_call, /devkit_dispatch <id>, /devkit_fuel).

16. Phone damage, protection and repairs (Config.Damage, config/apps.lua)

The server decides every crack and every drop of water (server/damage.lua); the condition belongs to the handset (the phone item with unique phones, otherwise the character's phone).

Server exports

Export Returns Notes
GetPhoneDamage(src) table | nil the handset in that player's hand: { screen ('intact' \| 'cracked' \| 'badly'), water (nil \| 'flicker' \| 'dead'), case (protection id \| nil), protector, pouch }. nil while its record is not loaded yet
RepairPhone(src, what?, cb?) true repairs the handset in that player's hand for free - for a mechanic or electronics job that charges in its own way. what: 'screen', 'water' or 'all' (default). cb(changed): false when there was nothing to repair. A screen repair takes a screen protector with the old glass
DamagePhone(src, what) boolean 'crack', 'shatter' (badly cracked) or 'water' from your own script. A screen protector still takes a crack, and the waterproof pouch still keeps water out
FitPhoneProtection(src, item) boolean as if the player used that protection item (pulse_case, pulse_case_clear, pulse_pouch, pulse_protector): the item is taken from their inventory

A job script repairing phones:

Lua
RegisterNetEvent('myjob:repairPhone', function(target)
    local src = source
    -- your own checks: job, distance, the price
    exports.phone:RepairPhone(target, 'all', function(changed)
        if changed then --[[ charge, log, notify ]] end
    end)
end)

Client export (ox_inventory item hook)

Export Item entry
useProtection client = { export = 'phone.useProtection' } on pulse_case, pulse_case_clear, pulse_pouch, pulse_protector

Inventories that cannot make items usable fit protection with /phoneprotect <id> (Config.Damage.protection.command) or at the Pulse Store's Repairs counter.

State bags

Key Type Meaning
phone:damage { s, k, x, y, w, c, t } | nil the handset in this player's hand: screen 0-2, the crack's seed and impact point, water 0-2, the case style ('rugged' | 'clear') and its tint row. Written only by the server; the screen on the prop and the case on the handset are drawn from it

Owner tool

phone:damage <playerId> <crack|shatter|water|repair|clear> from the console, or a player with the phone.admin ACE. clear also takes off everything fitted.

17. Groups and group jobs (Config.Groups)

Players make groups in the Groups app (create, invite a contact, join with a code). A job script reads and drives the group through these server exports. Group ids are numbers; an unknown or disbanded group answers nil, false, 0 or {} - never an error.

The names and argument order are the ones group-job scripts are commonly written against, so a script that calls these functions on another resource needs one change: call exports.phone.

Export Returns Notes
GetGroupByMembers(src) id | nil the player's group
FindGroupByMember(src) id | 0 the same, 0 when none
GetPlayerGroup(src) id | nil
getGroupMembers(id) { src, ... } in join order
GetGroupMembers(id) { { source, name }, ... } with character names
getGroupSize(id) / GetGroupMembersCount(id) number
GetGroupLeader(id) src | nil
isGroupLeader(src, id) / IsGroupLeader(id, src) boolean both argument orders exist
GetGroup(id) { id, name, leader, members, status, stages, temp } | nil
CreateGroup(src, name?) id | nil a group made by a script (isGroupTemp is true)
AddGroupMember(id, src) / RemoveGroupMember(id, src) boolean
DestroyGroup(id) boolean members are told it was disbanded
isGroupTemp(id) boolean
setJobStatus(id, status, stages?) / SetJobStatus(id, status, stages?) boolean stages = { { name, isDone }, ... }; 'WAITING' with no stages takes the job card down
getJobStatus(id) / GetJobStatus(id) string
resetJobStatus(id) boolean back to 'WAITING', card removed
SetGroupJob(id, { label, stage?, stages?, countdown? \| endsAt? }) boolean the job card with a timer (countdown seconds, or a UNIX endsAt)
SetGroupStage(id, index) boolean stages before index are done
SetGroupWaypoint(id, coords, label?) / ClearGroupWaypoint(id) boolean sets every member's GPS waypoint; the app offers Route to it
pNotifyGroup(id, title, body) / NotifyGroup(id, body) boolean a phone notification to every member
CreateBlipForGroup(id, name, data) boolean data = { label, coords, sprite, colour \| color, scale, alpha, route, routeColour \| routeColor, radius?, netId? \| entity? }
CreateBlipForGroup(id, name, label, coords, sprite, colour, scale, route) boolean the same, positional
RemoveBlipForGroup(id, name) boolean
GroupEvent(id, event, args) / SendGroupEvent(id, event, args) boolean TriggerClientEvent(event, member, args) for each member
SetGroupData(id, key, value) / GetGroupData(id, key) / DestroyGroupData(id, key) script data kept with the group

Client exports: GetGroupID() (0 when none), IsGroupLeader(), GetJobStage() (the status), GetGroup() (the group as the app sees it).

The job card. While a group has a job (a status other than 'WAITING', stages, or SetGroupJob), every member's Island and Lock Screen show it: the job, the current stage, done/total and the timer. Tapping it opens Groups. It is the phone's own activity, so it never counts against your resource's activity limit (section 14).

Server events (AddEventHandler): phone:groups:created (id, src), phone:groups:joined (id, src), phone:groups:left (id, src, reason: 'left', 'kicked', 'dropped', 'unloaded', 'script'), phone:groups:disbanded (id, members).

Members leave a group when they leave the server or log out of the character; a leader who leaves hands it to the longest-standing member.

18. Dispatch lines, online status, Jobs and the trap phone

  • Dispatch lines (config/apps.lua). A company line with a dispatcher on duty queues its callers for the dispatcher, with hold music and the caller's place in line; the dispatcher works the line from Services > My Work > Dispatch Console and can transfer a caller to a unit. With nobody dispatching, the line rings everyone on duty exactly as before. The public call events fire for every leg; a transferred call ends the dispatcher's leg with reason 'transferred', and a transfer nobody answered with 'transfer-failed'.
  • Online status (config/apps.lua). The dot on a contact; each player chooses who sees it in Settings > Privacy & Security. Nothing is exported.
  • Jobs (config/apps.lua). The job board and business directory. Admins remove reviews and postings with phone:jobs (ace phone.admin).
  • Trap phone (Config.Burner.trap in config/apps.lua, off by default). Buyers text a carried Pulse Burner; the hand-off pays through the framework's money functions and can raise a police alert through the dispatch script.

19. Hail: trip offers from your own job script

An NPC taxi job (or any job that needs a driver) can send a trip to Hail drivers who are online. The driver sees it on the normal request card with its countdown and taps Accept or Decline. Hail only shows the offer and tells you the answer. Your script does everything after that: the NPC, the pickup, the destination, the fare, the payment and any XP. Hail moves no money for these offers and does not list them in the driver's Hail earnings.

Once a driver accepts, Hail holds them for your job. They get no Hail trips and the app shows "On a job". The hold ends when you call EndHailJob, when the driver goes offline or leaves the server, or after holdMinutes.

Server exports (exports.phone:…)

Export Returns Notes
GetHailDrivers(coords?, radius?) array of drivers Every online driver, nearest first when coords is given. Each entry has source, number, name, state ('free', 'offer', 'trip', 'job'), free, coords, distance and vehicle (label, plate, net, model).
IsHailDriverFree(source) free, state false, 'offline' when the player is not online in Hail.
SendHailOffer(source, offer, cb?) offerId or nil, reason Offers to one driver. Reasons: 'not-online', 'busy', 'bad-offer', 'bad-coords'.
SendHailOfferNear(offer, cb?) offerId, driverSource or nil, reason Offers to the nearest free driver in the service area within offer.radius (default Config.Rides.trip.offerRadius) of the pickup. Skips the sources in offer.exclude. Adds the reason 'no-driver'.
CancelHailOffer(offerId) boolean Withdraws an offer your resource sent that is still waiting.
EndHailJob(source) boolean Releases a driver from your job so Hail offers them trips again. Only the resource that sent the offer can release it.

The offer table:

Field Required Meaning
pickup yes vector3 or { x, y, z }
dest yes vector3 or { x, y, z }
pickupLabel, destLabel no Place names shown on the card (up to 60 characters)
riderName no Shown on the card. Default "Local passenger".
label no A tag on the card, for example 'NPC fare' (up to 24 characters)
fare no The amount shown to the driver. Display only: your script pays it.
pay no 'cash' (default) or 'bank', the chip on the card
seconds no Time to answer, 5 to 120. Default Config.Rides.trip.offerSeconds.
holdMinutes no How long an accepted job holds the driver, 1 to 240. Default 30.
radius, exclude no SendHailOfferNear only

cb(accepted, reason, offerId) is called once. reason is 'accepted', 'declined', 'expired' or 'offline'. To accept, the driver must still be in the driver seat of the car they went online with.

Server events (listen with AddEventHandler)

  • phone:hail:offerAnswered (offerId, driverSource, accepted, reason, resourceName)
  • phone:hail:jobEnded (offerId, driverSource, reason, resourceName). Reasons: 'ended' (you called EndHailJob), 'offline' and 'timeout'.
  • phone:hail:driverOnline (source, number)
  • phone:hail:driverOffline (source, number, reason)

If your resource stops, its waiting offers and held jobs are cleared. Nothing is called back into it.

Example: an NPC fare

Lua
local function offerNpcFare(pickup, dest, fare)
    local exclude = {}
    local function try()
        local id, driver = exports.phone:SendHailOfferNear({
            pickup = pickup, dest = dest, fare = fare, label = 'NPC fare',
            pickupLabel = 'Legion Square', destLabel = 'Vespucci Beach', exclude = exclude,
        }, function(accepted, reason)
            if accepted then
                StartNpcFare(driver, pickup, dest, fare)   -- your job: spawn the NPC, pay at drop-off
            elseif reason == 'declined' or reason == 'expired' then
                exclude[#exclude + 1] = driver
                try()                                      -- offer it to the next nearest driver
            end
        end)
        if not id then print('no Hail driver for this fare: ' .. tostring(driver)) end
    end
    try()
end

-- When your fare is finished or cancelled:
exports.phone:EndHailJob(driverSource)