Skip to main content

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 the sendNotification 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) via Bridge.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.
Related: 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 server roadphone: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 via SendNUIMessage.
Advanced use only — you are talking directly to the phone UI event system. Prefer the SendMessageNUI export.

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

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 with Config.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.