Skip to main content

Client Events

This page documents every networked client event RoadPhone Pro 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.
data
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.
number
string
required
The number to call.
isAnonym
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.
dispatch
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:
EventArgsWhen
roadphone:islandActivityActionactivityId, buttonIdA Dynamic-Island live-activity button was tapped (pairs with StartIslandActivity export).
roadphone:client:call:eventnumbernumberA configured event number was dialed — add your own handler for custom behavior (template in clientAPI.lua).
roadphone:watch:notification / :callStateChanged / :incomingCall / :callAccepted / :callEnded / :newMessage / :newTransaction / :musicStateChangedvariesRoadWatch companion bus — mirrors phone state to the smartwatch.
roadpad:setWeather, roadcarplay:setWeather, roadwatch:setWeatherweatherWeather fan-out to companion resources.
roadphonebox:acceptcall, roadphonebox:endCallvariesPhonebox companion signaling.
roadtv:playVideoYTvideo dataRoadTV companion playback.

Core & Phone Lifecycle — client/client.lua

EventParamsDescription
roadphone:useOpens the phone.
roadphone:closePhoneCloses the phone if open.
roadphone:invalidatePhoneCacheClears the “has phone” cache.
roadphone:loadPlayerClientneedsetup, phone_number, contacts, messages, yellowpages, groupmessages, groups, notes, callhistory, transactions, news, newscategories, blockednumbers, newsappaccess, darkchat_rooms, charnameNon-metadata mode: full initial data load into NUI.
roadphone:loadGlobalDatayellowpages, groupmessages, groups, news, newscategories, blockednumbers, newsappaccessMetadata mode: per-join global data load.
roadphone:loadPhoneDataneedsetup, phone_number, contacts, messages, notes, callhistory, transactionsMetadata mode: per-phone data push.
roadphone:playerLoadedMetadataModeMarks the player loaded in metadata mode.
roadphone:loadPlayerJobjobPushes the player’s job to NUI (setJob).
roadphone:setBackgroundFromMetadatabackground or nilSets/resets the wallpaper.
roadphone:setPinFromMetadatapin, pinNeededSets PIN state.
roadphone:setSettingsFromMetadatasettingsApplies phone settings.
roadphone:setUpdateupdateAvailable, version, changelog, newVersionShows the update banner.
roadphone:client:leitstelle:syncdispatchersSyncs emergency dispatcher lines.
roadphone:backup:reloadDataLegacy backup restore: re-triggers a full reload.
roadphone:restoreCompletedata (latent)Metadata-mode backup restore payload.
roadphone:blocked:numberstype ('add'/'remove'), numberUpdates the local blocked-numbers list.

Alarms

EventParamsDescription
roadphone:loadAlarmsalarmsLoads all alarms into NUI.
roadphone:alarm:addedalarmConfirms a created alarm.
roadphone:alarm:updatedalarmId, updatedAlarmConfirms an updated alarm.
roadphone:alarm:deletedalarmIdConfirms a deleted alarm.
roadphone:alarm:toggledalarmId, enabledConfirms an alarm toggle.

Notifications

EventParamsDescription
roadphone:sendNotificationdataPhone notification (see Integration Events).
roadphone:sendOffNotificationtextFramework game notification.

Calls & FaceTime — client/client.lua

EventParamsDescription
roadphone:client:callnumber, isAnonymStarts an outgoing call.
roadphone:client:call:phoneboxnumber, isAnonymOutgoing call via phonebox flow.
roadphone:client:incomingcallnumber, isAnonym, targetNumber, isLeitstelleCallIncoming-call logic: blocked check, ring UI, multi-phone banner.
roadphone:client:acceptIncomingCallcallchannelTransitions to active call, joins the voice channel.
roadphone:client:endCallnumber, number2Tears down call state, animation, voice.
roadphone:client:addCallHistorycallAppends to the local call history.
roadphone:client:setLeitstelleCallsourceStores the dispatcher source for Leitstelle calls.
roadphone:call:videoUpgradeRequestcallerNumberVoice→FaceTime upgrade prompt.
roadphone:call:videoUpgradeResponseresponderNumber, acceptedUpgrade accept/decline.
roadphone:sendCall / roadphone:sendCall:calledid, cal (, targetnumber)Legacy FaceTime signaling.
roadphone:acceptVideoCallOpens the video-call camera.
roadphone:videocallacceptedcallchannelJoins the voice channel for a video call.
roadphone:client:incomingGroupCallgroupIncoming group call ring.
roadphone:client:newGroupChatMembergroupid, memberGroup-call member joined.
roadphone:client:groupChatMemberLeavedgroupid, memberGroup-call member left.
roadphone:client:leaveGroupCallgroupid, forceLeaves the group voice call.

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

EventParamsDescription
roadphone:client:joinradiofrzJoins a radio frequency (item + access checks).
roadphone:client:leaveradioLeaves the radio channel.

Messages & Groups — client/client.lua

EventParamsDescription
roadphone:receiveMessagemessage, isOwner (0/1), phoneNumber, targetPhoneNumberNew SMS: blocked/multi-phone checks, NUI push, sound, RoadWatch mirror.
roadphone:messages:setAllMessagesallmessagesReplaces the local message cache.
roadphone:messagesReadreaderNumberMarks own sent messages as read (read receipts).
roadphone:messages:group:receivemessageNew group message.
roadphone:messages:groupCreatedgroup, nameAdded to a new group.
roadphone:messages:groupCreated:ownergroupConfirms own group creation.
roadphone:messages:groupOwnerChangedgroupid, newOwnerOwnership transfer.
roadphone:messages:groupDeletedgroupidGroup removed.
roadphone:messages:groupSettingsChangedgroupid, name, pictureGroup renamed/re-imaged.
roadphone:messages:groupMembersChangedgroupid, membersMember list updated.

Bank, Crypto & Account — client/client.lua

EventParamsDescription
roadphone:bank:addTransactiontransactionAppends a bank transaction (NUI + RoadWatch).
roadphone:bank:requestUpdatepayloadPayment-request update.
roadphone:crypto:setdataCrypto market data.
roadphone:client:crypto:setcryptocryptoThe player’s crypto holdings.
roadphone:loginAccountid, firstname, lastname, mail, profile, birthCloud/RoadID account login push.
EventParamsDescription
roadphone:addPicturepictureAdds a photo to the gallery UI.
roadphone:albumCreatedalbumConfirms a created album.
roadphone:checkWeatherRefreshes weather from game state.
roadphone:setWeatherweatherPushes weather data (fans out to companions).

Camera — client/camera.lua

EventParamsDescription
camera:phoneOpens the photo camera (prop + cell cam).
camera:facetime:menuOpens the FaceTime selfie camera.
camera:videophoneSets up the live video-call camera.
roadphone:livestream:cameraOpens the camera in livestream mode (registered in both client.lua and camera.lua).

Admin / Billing / Jobs / Taxi / RoadDrop / Yellow Pages

EventFileParamsDescription
roadphone:admin:openadmin.luaOpens the admin config panel (server ACE-gates recipients).
roadphone:admin:chunkResultadmin.luatransferId, resultResolves a pending chunked admin save.
roadphone:updatebillingbilling.luaRefreshes the invoice list.
roadphone:jobs:gigAddedjobs.luagigNew gig on the gig board.
roadphone:jobs:gigRemovedjobs.luaidGig removed.
roadphone:taxi:updatetaxi.luataxijobDriver-side job list update.
roadphone:taxi:update:customertaxi.luataxijobCustomer-side job update.
roadphone:taxi:pickedup:check:clienttaxi.luaphone, gpstogo, vehicle2, sourceReads the driver’s plate and confirms pickup with the server.
roadphone:taxi:setWaypointtaxi.luaGPStogoSets a map waypoint.
roadphone:taxi:showRatingtaxi.luatripDataShows the post-ride rating UI.
roadphone:roaddrop:receive:pictureroaddrop.luapicturelink, senderIncoming RoadDrop image.
roadphone:roaddrop:receive:contactroaddrop.luacontact, senderIncoming RoadDrop contact.
roadphone:roaddrop:receive:playlistroaddrop.luaplaylist, senderIncoming RoadDrop playlist.
roadphone:yellowpages:newpostadvertising.luapostNew yellow-pages ad (+ optional notification).
roadphone:yellowpages:deleteadvertising.luaidAd removed.

Service (Dispatch & Business) — client/service.lua

EventParamsDescription
roadphone:service:newDispatchdispatchNew dispatch: NUI push + dispatch sound.
roadphone:service:deleteDispatchidDispatch deleted.
roadphone:service:finishDispatchidDispatch finished.
roadphone:service:declineDispatchidDispatch declined.
roadphone:service:statusUpdatedata (id, status, assignedTo, assignedToName)Dispatch status change.
roadphone:service:dispatchForwardeddata (dispatchId, forwardedTo)Dispatch reassigned.
roadphone:service:locationRequestdata (dispatchId, dispatcherName)Live-location share offer.
roadphone:service:locationSharingAccepteddata (dispatchId)Share accepted.
roadphone:service:liveLocationUpdatedata (dispatchId, x, y, dispatcherName)Live coordinates.
roadphone:service:locationSharingStoppeddata (dispatchId)Share ended.
roadphone:businessStatusUpdatejob, statusBusiness open/closed state.
roadphone:newBusinessNewsnewsItemNew business news item.
roadphone:managementDataUpdatedata (balance, employees)Business management data.

Music — client/music.lua

EventParamsDescription
roadphone:server:musictype, sid, url, coords, volume, loop, timestampCore 3D-audio controller (xSound play/pause/volume/seek per nearby player).
roadphone:music:setPlaylistsplaylistsPlaylist list push.
roadphone:music:setAdminisAdminMusic-admin flag for the UI.

Mail / Notes / Calendar / Voice Memos / News

EventFileParamsDescription
roadphone:mail:updatemailsmail.luamails, sendermailsMailbox refresh.
roadphone:notes:newnotes.luanoteNew note push.
roadphone:notes:syncnotes.luaTriggers a notes refetch.
roadphone:calendar:newcalendar.luaeventNew calendar event push.
roadphone:calendar:synccalendar.luaTriggers a calendar refetch.
roadphone:voicemail:newpostvoicememos.luapostNew voice memo.
roadphone:voicemail:deletevoicememos.luaidVoice memo deleted.
roadphone:news:newpostnews.luapostNew article (+ optional notification).
roadphone:news:postUpdatednews.luapostDataArticle edited.
roadphone:news:deletenews.luaidArticle deleted.
roadphone:news:categoryCreatednews.luacategoryCategory created.
roadphone:news:categoryDeletednews.luaidCategory deleted.
roadphone:news:breakingTogglednews.luadata (id, is_breaking, breaking_until)Breaking flag toggled.
roadphone:news:breakingnews.luapostBreaking-news alert broadcast.

Health — client/health.lua

EventParamsDescription
roadphone:health:stressUpdatestressLevelInjects a stress value (see Integration Events).

Connect (Instagram) — client/connect.lua

EventParamsDescription
roadphone:instagram_setAccountid, firstname, lastname, username, password, avatarUrl, verifySession account push.
roadphone:instagram_setpostspostsFeed data.
roadphone:instagram_newpostinapNew post (+ optional notification).
roadphone:instagram_addAccountaccountNew account broadcast.
roadphone:insto_createAccountaccountAccount-created confirmation.
roadphone:instagram:logoutLogout push.
roadphone:insto_updateinapLikesinapId, likesPost like count.
roadphone:updatepostIsLikedinapId, isLikesOwn like state.
roadphone:instagram:addcommentcommentNew comment.
roadphone:connect:commentLikeUpdatedpayload (commentId, likes)Comment like count.
roadphone:connect:commentLikeSelfpayload (commentId, isLiked)Own comment-like state.
roadphone:connect:postUpdatedpostPost edited.
roadphone:connect_deletepostIdPost deleted.
roadphone:instagram:addstorystoryNew story.
roadshop:instagram:follow:clientselfUser, usernameFollow notification fired by the roadshop resource.

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:
EventParamsDescription
roadphone:setConnectLivestreamsstreamsActive Connect livestreams.
roadphone:connectLive:viewerUpdatedataViewer count update.
roadphone:connectLive:endeddata (streamId)Stream ended.
roadphone:nuidata (with .event)Generic NUI passthrough (see Integration Events).

TweetWave — client/tweetwave.lua

EventParamsDescription
roadphone:twitter_setAccountusername, password, avatarUrl, verify, date, accountIdSession account push.
roadphone:twitter_createAccountaccountAccount-created confirmation.
roadphone:twitter_loggedOut / roadphone:twitter:logoutLogout pushes.
roadphone:twitter_deleteTwitterusername, passwordAccount deleted; refreshes users.
roadphone:twitter_newposttweetNew tweet notification.
roadphone:twitter_newTweettweetNew tweet data.
roadphone:twitter_getUserTweetstweetsOwn tweets push.
roadphone:twitter_updateTweetLikestweetId, likesLike count.
roadphone:twitter_setTweetLikestweetId, isLikesOwn like state.
roadphone:twitter_updateTweetRepoststweetId, countRepost count.
roadphone:twitter_setTweetReposttweetId, isRepostedOwn repost state.
roadphone:twitter_updateQuoteCounttweetId, countQuote count.
roadphone:twitter_setBookmarktweetId, isBookmarkedOwn bookmark state.
roadphone:twitter_setFollowtargetUserId, isFollowingOwn follow state.
roadphone:twitter:addcommentcommentNew comment.

Snapy — client/snapy.lua

EventParamsDescription
roadphone:snapy_setAccountaccountSession account push.
roadphone:snapy_loginError / roadphone:snapy_registerError— / reasonAuth errors.
roadphone:snapy_newSnapsnapDataIncoming snap (+ gated notification).
roadphone:snapy_newStorystoryDataNew story.
roadphone:snapy_newMessagemessageNew chat message (+ gated notification).
roadphone:snapy_newGroupgroupAdded to a group.
roadphone:snapy_friendRequestrequestIncoming friend request.
roadphone:snapy_friendAcceptedpayloadRequest accepted.
roadphone:snapy_friendIgnoredrequestIdRequest ignored.
roadphone:snapy_friendRemoveddataFriendship removed.
roadphone:snapy_typingpayload (from, name, group_id)Typing indicator.
roadphone:snapy_messageReadpayload (by)Read receipt.
roadphone:snapy_messageReactiondataMessage reaction.
roadphone:snapy_snapSaveddataSnap saved to chat.
roadphone:snapy_screenshotteddataScreenshot alert.
roadphone:snapy_profileUpdateddataProfile change.
roadphone:snapy_memoryAddedmemoryMemory saved.

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

EventParamsDescription
roadphone:dating_authCheckResultexists, profile, hasProfile, profileCompleteAuth check response.
roadphone:dating_loginResultsuccess, profile, hasProfile, profileCompleteLogin response.
roadphone:dating_registerResultsuccess, profileRegistration response.
roadphone:dating_setupCompletesuccessSetup finished.
roadphone:dating_profileDataprofileOwn profile push.
roadphone:dating_profileUpdatedsuccessProfile update confirmation.
roadphone:dating_swipeQueueprofilesSwipe queue.
roadphone:dating_newMatchmatchId, profileNew match (+ phone notification).
roadphone:dating_matchesListmatchesMatches list.
roadphone:dating_likesListprofilesWho liked you.
roadphone:dating_matchRemovedmatchIdUnmatched.
roadphone:dating_messageHistorymatchId, messagesChat history.
roadphone:dating_newMessagemessageNew chat message.
roadphone:dating_messagesReadmatchId, messageIdsRead receipts.

Livestream — client/livestream.lua

EventParamsDescription
roadphone:receiveActiveStreamsstreamsActive-streams list.
livestream:startStreamdata (streamId, …)Own stream started.
livestream:stopStreamOwn stream stopped.
livestream:streamEndedstreamIdWatched stream ended.
livestream:updateViewerCountstreamId, viewerCountViewer count.
roadphone:livestream:streamAddedstreamNew stream in the list.
roadphone:livestream:streamRemovedstreamIdStream removed.
roadphone:livestream:newStreamusername”X went live” notification.
roadphone:livestream:setaccountusername, password, avatarAccount push.
roadphone:livestream:profileUpdatedusername, avatarUrlProfile change.
roadphone:livestream:receiveMessagedataStream chat message.

Addons

Battery events only register with Config.BatterySystem + Config.UseMetadata; SIM card events with Config.SimCardDLC + Config.UseMetadata.
EventAddonParamsDescription
roadphone:battery:updateBatterylevelBattery level push.
roadphone:battery:chargedBatterylevelFully charged (+ notification).
roadphone:battery:chargingStateBatteryisChargingCharging state.
roadphone:battery:lowBatteryLow-battery notification.
roadphone:battery:criticalBatteryCritical-battery notification.
roadphone:battery:phoneDeadBatteryBattery empty: closes the phone.
roadphone:simcard:creditsUpdateSIM CardsimIndex, creditsSIM credit update.
roadpods:client:connectRoadPodsConnects RoadPods (ownership check, opens the phone).
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.