Metadata Exports

RoadPhone Pro’s metadata system stores phone data directly on inventory items, enabling features like phone stealing and trading. These exports allow external resources to interact with phone metadata.

These exports only work when Config.UseMetadata = true in the phone configuration. They will return nil or false when metadata mode is disabled.

Helper Functions

GetPhoneMetadataOnly

Get the complete metadata object for a player’s active phone.

local metadata = exports['roadphone']:GetPhoneMetadataOnly(source)

source

number

required

The player’s server ID.

returns

table | nil

The complete phone metadata table, or nil if not found.

This is a lightweight function that uses the active phone slot. Use this when you only need to read metadata without modifying it.

UpdatePhoneMetadataField

Update a single top-level field in phone metadata.

local success = exports['roadphone']:UpdatePhoneMetadataField(source, fieldName, value)

source

number

required

The player’s server ID.

fieldName

string

required

The metadata field name to update (e.g., 'phone_background').

value

any

required

The new value for the field. Use nil to remove the field.

returns

boolean

true if successful, false otherwise.

UpdatePhoneMetadataNested

Update a nested field within phone metadata.

local success = exports['roadphone']:UpdatePhoneMetadataNested(source, parentField, childField, value)

source

number

required

The player’s server ID.

parentField

string

required

The parent field name (e.g., 'phone_settings').

childField

string

required

The child field name (e.g., 'brightness').

value

any

required

The new value for the nested field.

-- Update brightness setting
exports['roadphone']:UpdatePhoneMetadataNested(source, 'phone_settings', 'brightness', 75)

UpdatePhoneMetadataArray

Perform array operations (add/update/delete) on metadata arrays.

local success = exports['roadphone']:UpdatePhoneMetadataArray(source, arrayField, operation, data, idField, limit)

source

number

required

The player’s server ID.

arrayField

string

required

The array field name (e.g., 'phone_contacts').

operation

string

required

The operation type: 'add', 'update', or 'delete'.

data

any

required

For 'add'/'update': the item object. For 'delete': the ID value.

idField

string

required

The field name used as identifier (e.g., 'id').

limit

number

Optional maximum array size (only for 'add' operations).

-- Add a contact
exports['roadphone']:UpdatePhoneMetadataArray(source, 'phone_contacts', 'add', {
    id = 123,
    name = "John Doe",
    number = "1234567"
}, 'id', 200)

-- Update a contact
exports['roadphone']:UpdatePhoneMetadataArray(source, 'phone_contacts', 'update', {
    id = 123,
    name = "John Smith",
    number = "1234567"
}, 'id')

-- Delete a contact
exports['roadphone']:UpdatePhoneMetadataArray(source, 'phone_contacts', 'delete', 123, 'id')

Phone Number & Setup

GetPhoneNumberFromItem

Get the phone number from a player’s phone item.

local phoneNumber, itemName, slot, metadata = exports['roadphone']:GetPhoneNumberFromItem(source, specificSlot)

source

number

required

The player’s server ID.

specificSlot

number

Optional specific inventory slot to check.

returns

string, string, number, table

Returns phone number, item name, slot number, and full metadata.

AssignPhoneNumberToItem

Assign a new phone number to a phone item.

local success, phoneNumber = exports['roadphone']:AssignPhoneNumberToItem(source, itemName, slot)

source

number

required

The player’s server ID.

itemName

string

required

The phone item name.

slot

number

required

The inventory slot number.

returns

boolean, string

Success status and the assigned phone number.

GetOrCreatePhoneNumber

Get the phone number for a player, creating one if necessary.

local phoneNumber, wasCreated = exports['roadphone']:GetOrCreatePhoneNumber(source)

source

number

required

The player’s server ID.

returns

string, boolean

The phone number and whether it was newly created.

GetPhoneSetupFromItem

Check if the phone has completed initial setup.

local setupStatus = exports['roadphone']:GetPhoneSetupFromItem(source)

returns

number

1 if setup is complete, 0 if setup is needed.

UpdatePhoneSetup

Update the phone setup status.

local success = exports['roadphone']:UpdatePhoneSetup(source, setupStatus)

setupStatus

number

required

1 for complete, 0 for needs setup.

Background & Settings

GetPhoneBackground

Get the phone’s wallpaper background.

local background = exports['roadphone']:GetPhoneBackground(source)

returns

string | nil

The background URL/path, or nil if using default.

UpdatePhoneBackground

Set the phone’s wallpaper background.

local success = exports['roadphone']:UpdatePhoneBackground(source, background)

background

string | nil

required

The background URL/path, or nil to reset to default.

GetPhoneSettingsFromMetadata

Get all phone settings.

local settings = exports['roadphone']:GetPhoneSettingsFromMetadata(source)

returns

table | nil

Settings object with: brightness, flightmode, large_app_icons, iconcolor, darkmode, timeCustomization.

UpdatePhoneSettings

Update phone settings.

local success = exports['roadphone']:UpdatePhoneSettings(source, settings)

settings

table

required

Table with settings to update. Only provided keys will be changed.

Show Valid settings keys

brightness (number): 10-100
flightmode (number): 0 or 1
large_app_icons (number): 0 or 1
iconcolor (string): “light” or “dark”
darkmode (number): 0 or 1
timeCustomization (table | nil): Custom time display settings

exports['roadphone']:UpdatePhoneSettings(source, {
    brightness = 80,
    darkmode = 1
})

PIN/Passcode

GetPhonePin

Get the phone’s PIN configuration.

local pinData = exports['roadphone']:GetPhonePin(source)

returns

table | nil

Table with pin (string, 6 digits) and pin_needed (0 or 1).

UpdatePhonePin

Update the phone’s PIN.

local success = exports['roadphone']:UpdatePhonePin(source, pin, pinNeeded)

string

required

The 6-digit PIN code, or nil to remove.

pinNeeded

number

required

1 to require PIN on unlock, 0 to disable.

-- Set a PIN
exports['roadphone']:UpdatePhonePin(source, "123456", 1)

-- Remove PIN requirement but keep PIN stored
exports['roadphone']:UpdatePhonePin(source, "123456", 0)

-- Clear PIN completely
exports['roadphone']:UpdatePhonePin(source, nil, 0)

Contacts

GetPhoneContacts

Get all contacts from the phone.

local contacts = exports['roadphone']:GetPhoneContacts(source)

returns

table

Array of contact objects.

AddContactToMetadata

Add a new contact.

local success = exports['roadphone']:AddContactToMetadata(source, contact)

contact

table

required

Contact object with id, name, number, and optional avatar.

UpdateContactInMetadata

Update an existing contact.

local success = exports['roadphone']:UpdateContactInMetadata(source, contactId, updatedContact)

DeleteContactFromMetadata

Delete a contact.

local success = exports['roadphone']:DeleteContactFromMetadata(source, contactId)

Notes

GetPhoneNotes

Get all notes from the phone.

local notes = exports['roadphone']:GetPhoneNotes(source)

AddNoteToMetadata

Add a new note.

local success = exports['roadphone']:AddNoteToMetadata(source, note)

note

table

required

Note object with id, title, content, created_at.

UpdateNoteInMetadata

Update an existing note.

local success = exports['roadphone']:UpdateNoteInMetadata(source, noteId, updatedNote)

DeleteNoteFromMetadata

Delete a note.

local success = exports['roadphone']:DeleteNoteFromMetadata(source, noteId)

Photos

GetPhonePhotos

Get all photos from the phone.

local photos = exports['roadphone']:GetPhonePhotos(source)

AddPhotoToMetadata

Add a new photo.

local success = exports['roadphone']:AddPhotoToMetadata(source, photo)

photo

table

required

Photo object with id, url, created_at, and optional favorite.

UpdatePhotoInMetadata

Update photo properties (e.g., favorite status).

local success = exports['roadphone']:UpdatePhotoInMetadata(source, photoId, updates)

DeletePhotoFromMetadata

Delete a photo.

local success = exports['roadphone']:DeletePhotoFromMetadata(source, photoId)

Alarms

GetPhoneAlarms

Get all alarms from the phone.

local alarms = exports['roadphone']:GetPhoneAlarms(source)

AddAlarmToMetadata

Add a new alarm.

local success = exports['roadphone']:AddAlarmToMetadata(source, alarm)

UpdateAlarmInMetadata

Update an existing alarm.

local success = exports['roadphone']:UpdateAlarmInMetadata(source, alarmId, updatedAlarm)

DeleteAlarmFromMetadata

Delete an alarm.

local success = exports['roadphone']:DeleteAlarmFromMetadata(source, alarmId)

Messages

GetPhoneMessages

Get all messages from the phone.

local messages = exports['roadphone']:GetPhoneMessages(source)

AddMessageToMetadata

Add a new message to the phone.

local success = exports['roadphone']:AddMessageToMetadata(source, message)

MarkMessagesReadInMetadata

Mark messages from a specific number as read.

local success = exports['roadphone']:MarkMessagesReadInMetadata(source, phoneNumber)

Radio Channels

GetRadioChannelsFromMetadata

Get saved radio channels.

local channels = exports['roadphone']:GetRadioChannelsFromMetadata(source)

AddRadioChannelToMetadata

Add a saved radio channel.

local success = exports['roadphone']:AddRadioChannelToMetadata(source, channel)

UpdateRadioChannelInMetadata

Update a saved radio channel.

local success = exports['roadphone']:UpdateRadioChannelInMetadata(source, channelId, updatedChannel)

DeleteRadioChannelFromMetadata

Delete a saved radio channel.

local success = exports['roadphone']:DeleteRadioChannelFromMetadata(source, channelId)

GetRadioRecentFromMetadata

Get recent radio frequencies.

local recent = exports['roadphone']:GetRadioRecentFromMetadata(source)

AddRadioRecentToMetadata

Add a frequency to recent list.

local success = exports['roadphone']:AddRadioRecentToMetadata(source, frequency)

ClearRadioRecentFromMetadata

Clear all recent frequencies.

local success = exports['roadphone']:ClearRadioRecentFromMetadata(source)

TweetWave

-- Get account
local account = exports['roadphone']:GetTweetWaveAccountFromMetadata(source)

-- Set account (on login)
exports['roadphone']:SetTweetWaveAccountInMetadata(source, {
    id = 1,
    username = "johndoe",
    avatar_url = "/img/user.png",
    bio = "Hello world",
    verify = 0
})

-- Update account fields
exports['roadphone']:UpdateTweetWaveAccountInMetadata(source, {
    avatar_url = "/img/newavatar.png",
    bio = "Updated bio"
})

-- Clear account (on logout)
exports['roadphone']:ClearTweetWaveAccountFromMetadata(source)

Backwards Compatibility: The old *TwitterAccount* export names still work but are deprecated.

Connect

-- Get account
local account = exports['roadphone']:GetConnectAccountFromMetadata(source)

-- Set account (on login)
exports['roadphone']:SetConnectAccountInMetadata(source, {
    id = 1,
    username = "johndoe",
    firstname = "John",
    lastname = "Doe",
    avatar_url = "/img/user.png",
    verify = 0
})

-- Update account fields
exports['roadphone']:UpdateConnectAccountInMetadata(source, {
    avatar_url = "/img/newavatar.png"
})

-- Clear account (on logout)
exports['roadphone']:ClearConnectAccountFromMetadata(source)

RoadID Account

-- Get account
local account = exports['roadphone']:GetPhoneAccountFromMetadata(source)

-- Set account
exports['roadphone']:SetPhoneAccountInMetadata(source, {
    firstname = "John",
    lastname = "Doe",
    mail = "[email protected]",
    birth = "01.01.1990",
    profile = "/img/user.png"
})

-- Update profile picture
exports['roadphone']:UpdatePhoneAccountInMetadata(source, {
    profile = "/img/newprofile.png"
})

-- Clear account (on logout)
exports['roadphone']:ClearPhoneAccountFromMetadata(source)

App Layout

GetPhoneAppsFromMetadata

Get installed apps and homescreen layout.

local apps = exports['roadphone']:GetPhoneAppsFromMetadata(source)

returns

table | nil

Object with installed (array of app IDs) and homescreen (layout data).

UpdateInstalledApps

Update the list of installed apps.

local success = exports['roadphone']:UpdateInstalledApps(source, installedApps)

UpdateHomescreenLayout

Update the homescreen layout (pages and dock).

local success = exports['roadphone']:UpdateHomescreenLayout(source, homescreenData)

Backup System

Backup functions require Config.BackupEnabled = true in the configuration.

CreatePhoneBackup

Create a backup of all phone data.

local success, result = exports['roadphone']:CreatePhoneBackup(source, backupName, backupType)

backupName

string

Optional custom name for the backup. Defaults to timestamp.

backupType

string

'manual' or 'auto'. Defaults to 'manual'.

GetPhoneBackups

Get all backups for the player.

local backups = exports['roadphone']:GetPhoneBackups(source)

returns

table

Array of backup objects with backup_id, backup_name, created_at, backup_type.

RestorePhoneBackup

Restore phone data from a backup.

local success, message = exports['roadphone']:RestorePhoneBackup(source, backupId)

backupId

string

required

The UUID of the backup to restore.

DeletePhoneBackup

Delete a backup.

local success, message = exports['roadphone']:DeletePhoneBackup(source, backupId)

Metadata Limits

Phone metadata has built-in limits to prevent inventory bloat:

Data Type	Limit
Messages	300
Contacts	200
Notes	150
Photos	150
Alarms	30
Radio Channels	30

When limits are exceeded, the oldest items are automatically removed.

Complete Example

-- External script: Give player a phone with pre-configured data
RegisterCommand('givephone', function(source, args)
    local targetId = tonumber(args[1])
    if not targetId then return end

    -- Add phone item to player inventory (use your inventory system)
    -- exports['ox_inventory']:AddItem(targetId, 'phone', 1)

    -- Wait for inventory update
    Citizen.Wait(100)

    -- Assign phone number
    local success, phoneNumber = exports['roadphone']:AssignPhoneNumberToItem(targetId, 'phone', 1)

    if success then
        -- Pre-configure the phone
        exports['roadphone']:UpdatePhoneSetup(targetId, 1)
        exports['roadphone']:UpdatePhoneSettings(targetId, {
            brightness = 100,
            darkmode = 0
        })

        -- Add emergency contact
        exports['roadphone']:AddContactToMetadata(targetId, {
            id = os.time(),
            name = "Emergency Services",
            number = "911"
        })

        print("Phone given with number: " .. phoneNumber)
    end
end, true)

API documentation

RoadPhone-Pro

RoadPhone

RoadPad

RoadCarPlay

​Metadata Exports

​Helper Functions

​GetPhoneMetadataOnly

​UpdatePhoneMetadataField

​UpdatePhoneMetadataNested

​UpdatePhoneMetadataArray

​Phone Number & Setup

​GetPhoneNumberFromItem

​AssignPhoneNumberToItem

​GetOrCreatePhoneNumber

​GetPhoneSetupFromItem

​UpdatePhoneSetup

​Background & Settings

​GetPhoneBackground

​UpdatePhoneBackground

​GetPhoneSettingsFromMetadata

​UpdatePhoneSettings

​PIN/Passcode

​GetPhonePin

​UpdatePhonePin

​Contacts

​GetPhoneContacts

​AddContactToMetadata

​UpdateContactInMetadata

​DeleteContactFromMetadata

​Notes

​GetPhoneNotes

​AddNoteToMetadata

​UpdateNoteInMetadata

​DeleteNoteFromMetadata

​Photos

​GetPhonePhotos

​AddPhotoToMetadata

​UpdatePhotoInMetadata

​DeletePhotoFromMetadata

​Alarms

​GetPhoneAlarms

​AddAlarmToMetadata

​UpdateAlarmInMetadata

​DeleteAlarmFromMetadata

​Messages

​GetPhoneMessages

​AddMessageToMetadata

​MarkMessagesReadInMetadata

​Radio Channels

​GetRadioChannelsFromMetadata

​AddRadioChannelToMetadata

​UpdateRadioChannelInMetadata

​DeleteRadioChannelFromMetadata

​GetRadioRecentFromMetadata

​AddRadioRecentToMetadata

​ClearRadioRecentFromMetadata

​Social Media Accounts

​TweetWave

​Connect

​RoadID Account

​App Layout

​GetPhoneAppsFromMetadata

​UpdateInstalledApps

​UpdateHomescreenLayout

​Backup System

​CreatePhoneBackup

​GetPhoneBackups

​RestorePhoneBackup

​DeletePhoneBackup

​Metadata Limits

​Complete Example

Metadata Exports

Helper Functions

GetPhoneMetadataOnly

UpdatePhoneMetadataField

UpdatePhoneMetadataNested

UpdatePhoneMetadataArray

Phone Number & Setup

GetPhoneNumberFromItem

AssignPhoneNumberToItem

GetOrCreatePhoneNumber

GetPhoneSetupFromItem

UpdatePhoneSetup

Background & Settings

GetPhoneBackground

UpdatePhoneBackground

GetPhoneSettingsFromMetadata

UpdatePhoneSettings

PIN/Passcode

GetPhonePin

UpdatePhonePin

Contacts

GetPhoneContacts

AddContactToMetadata

UpdateContactInMetadata

DeleteContactFromMetadata

Notes

GetPhoneNotes

AddNoteToMetadata

UpdateNoteInMetadata

DeleteNoteFromMetadata

Photos

GetPhonePhotos

AddPhotoToMetadata

UpdatePhotoInMetadata

DeletePhotoFromMetadata

Alarms

GetPhoneAlarms

AddAlarmToMetadata

UpdateAlarmInMetadata

DeleteAlarmFromMetadata

Messages

GetPhoneMessages

AddMessageToMetadata

MarkMessagesReadInMetadata

Radio Channels

GetRadioChannelsFromMetadata

AddRadioChannelToMetadata

UpdateRadioChannelInMetadata

DeleteRadioChannelFromMetadata

GetRadioRecentFromMetadata

AddRadioRecentToMetadata

ClearRadioRecentFromMetadata

Social Media Accounts

TweetWave

Connect

RoadID Account

App Layout

GetPhoneAppsFromMetadata

UpdateInstalledApps

UpdateHomescreenLayout

Backup System

CreatePhoneBackup

GetPhoneBackups

RestorePhoneBackup

DeletePhoneBackup

Metadata Limits

Complete Example