Client Events
This page documents every networked client event RoadPhone registers, plus the client-side hooks it emits for other resources.Most events below are internal: the server pushes data to the phone NUI through them and you should not fire them yourself. The Integration Events section lists the entry points designed for external resources; everything else is reference material for understanding data flow.
Integration Events
roadphone:sendNotification
The main phone-notification API (also available as thesendNotification export). Shows a banner and/or lockscreen notification; routes to RoadWatch when the watch is open.
table
required
apptitle, title, message, img?, path?, user?, banner?, lockscreen?, app?, isMessageNotify?roadphone:sendOffNotification
Simple framework game notification (outside the phone UI) viaBridge.Notification.Show.
roadphone:use
The canonical “player used the phone item” hook — opens the phone. Fired by the server on item use; inventory scripts can fire it too.roadphone:closePhone
Closes the phone if it is open (fired when the phone item leaves the inventory).roadphone:client:call
Starts an outgoing call from the local player: plays the call animation, opens the call UI and triggers the server-side call flow.string
required
The number to call.
boolean
Make the call anonymous.
roadphone:client:call:phonebox (number, isAnonym) — same flow for phonebox resources, and roadphone:client:endCall — tears down the current call state.
roadphone:client:addContact
Adds a contact to the local player’s phone (relays to the server contact handler).roadphone:client:GiveContactDetails
Shares the local player’s name + number with the closest player within 2.5m (they receive an “add contact” prompt). Bind it to a key or a target interaction.roadphone:client:joinradio / roadphone:client:leaveradio
Joins/leaves a radio frequency through the phone’s radio system (radio-item and access checks included).roadphone:service:newDispatch
Pushes a new dispatch into the Service app UI. This is the client-side end of the dispatch flow — external job/dispatch resources normally go through the serverroadphone:sendDispatch event or the sendDispatch export instead, which handles job targeting for you.
table
required
The dispatch object (id, message, coords, sender, …).
roadphone:health:stressUpdate
Injects a stress value into the phone’s health simulation — designed as an entry point for other resources (e.g. drug or combat scripts).roadphone:setWeather / roadphone:checkWeather
setWeather pushes weather data ({ temp, type }) into the phone (and forwards to RoadPad/CarPlay/RoadWatch). checkWeather forces a refresh from the current game weather.
roadphone:nui
Generic passthrough: forwards any well-formed table straight to the phone NUI viaSendNUIMessage.
camera:phone / camera:facetime:menu
Opens the phone photo camera / the FaceTime selfie camera. Used by the livestream integration (roadphone:livestream:camera) and NUI callbacks; can be fired by external camera integrations.
roadphone:invalidatePhoneCache
Clears the client-side “has phone” cache. Fire it after adding/removing phone items outside normal inventory flows.Hooks emitted by RoadPhone (listen with AddEventHandler)
These events are fired by RoadPhone on the client for other resources to consume:Core & Phone Lifecycle — client/client.lua
Alarms
Notifications
Calls & FaceTime — client/client.lua
FaceTime (LiveKit)
All forward their payload to the FaceTime NUI layer:roadphone:facetime:incoming, :callerReady, :calleeReady, :callAccepted, :declined, :ended, :participantJoined, :participantLeft, :participantInvited, :participantDeclined, :participantUnreachable, :incomingTimeout, :callState, :reaction — each takes a single data table. :declined and :ended have a second handler in camera.lua that cleans up the selfie camera.
Radio — client/client.lua
Messages & Groups — client/client.lua
Bank, Crypto & Account — client/client.lua
Gallery & Weather — client/client.lua
Camera — client/camera.lua
Admin / Billing / Jobs / Taxi / RoadDrop / Yellow Pages
Service (Dispatch & Business) — client/service.lua
Music — client/music.lua
Mail / Notes / Calendar / Voice Memos / News
Health — client/health.lua
Connect (Instagram) — client/connect.lua
Connect DMs & Live — client/connect.lua, client/connectlive.lua
DM pushes (connect_dm_newMessage, connect_dm_read, connect_dm_reaction, typing) arrive via the generic roadphone:nui passthrough. Connect Live registers:
TweetWave — client/tweetwave.lua
Snapy — client/snapy.lua
DarkChat — client/darkchat.lua
Each forwards its payload table to the DarkChat NUI layer:
roadphone:darkchat:messagePushed, :messageDeleted, :roomUpdated, :memberJoined, :memberLeft, :memberKicked, :memberUpdated, :youWereKicked, :resyncRooms.
Dating (DateMe) — client/dating.lua
Livestream — client/livestream.lua
Addons
Battery events only register withConfig.BatterySystem + Config.UseMetadata; SIM card events with Config.SimCardDLC + Config.UseMetadata.
clientAPI.lua and island.lua register no networked events — their surfaces are exports and NUI callbacks. The Dynamic-Island Lua API is documented under Client Exports.