Phone - Exports

Phone component API for notifications, data management, and UI control

The Phone component provides server-side notification delivery and client-side UI control. Other resources interact with the phone primarily through notifications and data updates.

Overview

Access via Phone on both server and client.

Notifications

Push notifications to players

Phone Data

Manage app data

UI Control

Open, close, and manage phone state

Permissions

App-level permission checks

---

Server-Side Methods

Primary Server API: The main way other resources interact with the phone server-side is through Phone.Notification. Direct data manipulation should be rare.

Phone.Notification:Add

Send a notification to a player’s phone.

Phone.Notification:Add(source, title, description, time, duration, app, actions, notifData)

source · number · required

Player server ID

title · string · required

Notification title

description · string · required

Notification body text

time · number · required

Timestamp (use os.time())

duration · number · required

Display duration in milliseconds

app · string · required

App identifier (e.g., 'messages', 'email', 'bank')

actions · table

Action buttons on the notification

notifData · table

Additional data payload

Example:

-- Simple notification
Phone.Notification:Add(source, 'New Message', 'You have a new text message', os.time(), 5000, 'messages')

-- Notification with data
Phone.Notification:Add(source, 'Bank Alert', 'Deposit of $5,000 received', os.time(), 5000, 'bank', nil, {
    amount = 5000,
    account = accountNumber
})

-- 911 dispatch notification to police
local dutyData = Jobs.Duty:GetDutyData('police')

for _, policeSource in ipairs(dutyData.DutyPlayers) do
    Phone.Notification:Add(policeSource, '911 Call', 'Shots fired at Legion Square', os.time(), 10000, 'phone')
end

---

Phone.Notification:AddWithId

Send a notification with a specific ID for tracking and updating.

Phone.Notification:AddWithId(source, id, title, description, time, duration, app, actions, notifData)

id · string · required

Unique notification identifier for later updates/removal

All other parameters are the same as Notification:Add.

Example:

-- Trackable notification
Phone.Notification:AddWithId(source, 'delivery_123', 'Delivery Update', 'Your package is on the way', os.time(), 8000, 'email')

---

Phone.Notification:Update

Update an existing notification by ID.

Phone.Notification:Update(source, id, title, description)

source · number · required

Player server ID

id · string · required

Notification ID (from AddWithId)

title · string · required

New title

description · string · required

New description

Example:

-- Update delivery status
Phone.Notification:Update(source, 'delivery_123', 'Delivery Complete', 'Your package has been delivered')

---

Phone.Notification:RemoveById

Remove a notification by its ID.

Phone.Notification:RemoveById(source, id)

---

Phone:UpdateJobData

Update a player’s job data on their phone (permissions, apps, etc.).

Phone:UpdateJobData(source, returnValues)

source · number · required

Player server ID

returnValues · boolean

If true, returns the data instead of sending to client

data · table

When returnValues is true: {charJobPerms = table, jobData = table}

---

Client-Side Methods

Phone:Open

Opens the phone UI.

Phone:Open()

---

Phone:Close

Closes the phone UI.

Phone:Close(forced, doJankyStuff)

forced · boolean

Force close, skip route reset

doJankyStuff · boolean

Skip route reset behavior

---

Phone:IsOpen

Check if the phone UI is currently open.

Phone:IsOpen()

isOpen · boolean

true if phone is open

Example:

-- Close phone before starting an action
if Phone:IsOpen() then
    Phone:Close()
end

---

Phone:OpenLimited

Opens the phone in limited mode (e.g., for payphones).

Phone:OpenLimited()

---

Phone:OpenPayphone

Opens the phone specifically for payphone use.

Phone:OpenPayphone()

---

Phone:IsAppUsable

Check if a specific app is installed and usable by the current player.

Phone:IsAppUsable(app)

app · string|table · required

App identifier or table of app identifiers

usable · boolean

true if the app is accessible

---

Phone Data Methods (Client)

Phone.Data:Set

Set phone data by key.

Phone.Data:Set(key, data)

---

Phone.Data:Add

Add data to the phone store.

Phone.Data:Add(type, data, key)

---

Phone.Data:Update

Update existing phone data.

Phone.Data:Update(type, id, data)

---

Phone.Data:Remove

Remove phone data by key and ID.

Phone.Data:Remove(key, id)

---

Phone.Data:Reset

Clear all phone data.

Phone.Data:Reset()

---

Permissions (Client)

Phone.Permissions:HasPermission

Check if the current player has a specific app permission.

Phone.Permissions:HasPermission(app, permission)

app · string · required

App identifier

permission · string · required

Permission name

has · boolean

true if player has the permission

Example:

-- Check if player can create redline races
if Phone.Permissions:HasPermission('redline', 'create') then
    -- Allow race creation
end

---

Best Practices

Use Meaningful Notification Durations

-- ✅ Good: Important notifications stay longer
Phone.Notification:Add(source, '911 Call', 'Emergency at ...', os.time(), 10000, 'phone')

-- ✅ Good: Info notifications are shorter
Phone.Notification:Add(source, 'Bank', 'Deposit received', os.time(), 3000, 'bank')

Track Notifications When Needed

-- Use AddWithId when you need to update or remove later
Phone.Notification:AddWithId(source, 'taxi_' .. requestId, 'Taxi Request', 'Picking up...', os.time(), 0, 'phone')

-- Later, update it
Phone.Notification:Update(source, 'taxi_' .. requestId, 'Taxi', 'Arrived at pickup')

-- Or remove it
Phone.Notification:RemoveById(source, 'taxi_' .. requestId)

---

Next Steps

Phone - Events

Phone events and middleware

Phone - Apps

App configuration and restrictions

Characters API

Character data access