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)

UpdatePhoneContacts

Replace the entire contacts array in metadata.

local success = exports['roadphone']:UpdatePhoneContacts(source, contacts)

contacts

table

required

Array of contact objects to replace all existing contacts.

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)

UpdatePhoneNotes

Replace the entire notes array in metadata.

local success = exports['roadphone']:UpdatePhoneNotes(source, notes)

notes

table

required

Array of note objects to replace all existing notes.

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)

UpdatePhonePhotos

Replace the entire photos array in metadata.

local success = exports['roadphone']:UpdatePhonePhotos(source, photos)

photos

table

required

Array of photo objects to replace all existing photos.

Albums

GetPhoneAlbumsFromMetadata

Get all photo albums from the phone.

local albums = exports['roadphone']:GetPhoneAlbumsFromMetadata(source)

source

number

required

The player’s server ID.

returns

table

Array of album objects, or empty table if none exist.

AddAlbumToPhoneMetadata

Create a new album.

local success = exports['roadphone']:AddAlbumToPhoneMetadata(source, album)

album

table

required

Album object with id, name, photoIds fields.

UpdateAlbumInMetadata

Update specific fields of an existing album.

local success = exports['roadphone']:UpdateAlbumInMetadata(source, albumId, updates)

albumId

any

required

The album’s identifier.

updates

table

required

Key/value pairs to merge into the album.

DeleteAlbumFromMetadata

Delete an album.

local success = exports['roadphone']:DeleteAlbumFromMetadata(source, albumId)

albumId

any

required

The album’s identifier.

AddPhotoToAlbumMetadata

Add a photo to an album. Skips duplicates.

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

albumId

any

required

The album’s identifier.

photoId

any

required

The photo’s identifier to add.

returns

boolean

true on success (or if already exists), false if album not found.

RemovePhotoFromAlbumMetadata

Remove a photo from an album.

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

albumId

any

required

The album’s identifier.

photoId

any

required

The photo’s identifier to remove.

AddMultiplePhotosToAlbumMetadata

Add multiple photos to an album at once. Skips duplicates.

local success = exports['roadphone']:AddMultiplePhotosToAlbumMetadata(source, albumId, photoIds)

albumId

any

required

The album’s identifier.

photoIds

table

required

Array of photo identifiers to add.

-- Add multiple photos to an album
exports['roadphone']:AddMultiplePhotosToAlbumMetadata(source, "album-001", {
    "photo-001", "photo-002", "photo-003"
})

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)

UpdatePhoneAlarms

Replace all alarms on the phone at once.

local success = exports['roadphone']:UpdatePhoneAlarms(source, alarms)

source

number

required

The player’s server ID.

alarms

table

required

Array of alarm objects to set. Pass {} to clear all alarms.

returns

boolean

true if the metadata was updated successfully, false otherwise.

-- Replace all alarms
exports['roadphone']:UpdatePhoneAlarms(source, {
    { id = 1, time = "07:00", label = "Morning", enabled = true, days = {1,2,3,4,5} },
    { id = 2, time = "12:00", label = "Lunch", enabled = true, days = {1,2,3,4,5,6,7} }
})

-- Clear all alarms
exports['roadphone']:UpdatePhoneAlarms(source, {})

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)

UpdatePhoneMessages

Replace all messages on the phone at once. Messages are automatically limited to the configured maximum (default 300).

local success = exports['roadphone']:UpdatePhoneMessages(source, messages, unreadCount)

source

number

required

The player’s server ID.

messages

table

required

Array of message objects to set.

unreadCount

number

Number of unread messages. Defaults to 0.

returns

boolean

true if the metadata was updated successfully, false otherwise.

-- Replace all messages
exports['roadphone']:UpdatePhoneMessages(source, {
    { id = 1, sender = "1234567", message = "Hello!", time = 1710000000, read = true },
    { id = 2, sender = "7654321", message = "Hey there", time = 1710001000, read = false }
}, 1)

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)

UpdateRadioChannels

Replace all saved radio channels on the phone at once.

local success = exports['roadphone']:UpdateRadioChannels(source, channels)

source

number

required

The player’s server ID.

channels

table

required

Array of radio channel objects to set. Pass {} to clear all channels.

returns

boolean

true if the metadata was updated successfully, false otherwise.

-- Replace all saved radio channels
exports['roadphone']:UpdateRadioChannels(source, {
    { id = 1, name = "Police", frequency = 150.0 },
    { id = 2, name = "EMS", frequency = 155.0 }
})

-- Clear all channels
exports['roadphone']:UpdateRadioChannels(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 = "john@example.com",
    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)

UpdatePhoneApps

Replace the entire apps data (installed apps and homescreen layout) at once.

local success = exports['roadphone']:UpdatePhoneApps(source, appsData)

source

number

required

The player’s server ID.

appsData

table

required

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

returns

boolean

true if the metadata was updated successfully, false otherwise.

exports['roadphone']:UpdatePhoneApps(source, {
    installed = { "phone", "messages", "camera", "settings", "mail" },
    homescreen = {
        -- your layout structure
    }
})

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

Documentation Index

​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

​UpdatePhoneContacts

​Notes

​GetPhoneNotes

​AddNoteToMetadata

​UpdateNoteInMetadata

​DeleteNoteFromMetadata

​UpdatePhoneNotes

​Photos

​GetPhonePhotos

​AddPhotoToMetadata

​UpdatePhotoInMetadata

​DeletePhotoFromMetadata

​UpdatePhonePhotos

​Albums

​GetPhoneAlbumsFromMetadata

​AddAlbumToPhoneMetadata

​UpdateAlbumInMetadata

​DeleteAlbumFromMetadata

​AddPhotoToAlbumMetadata

​RemovePhotoFromAlbumMetadata

​AddMultiplePhotosToAlbumMetadata

​Alarms

​GetPhoneAlarms

​AddAlarmToMetadata

​UpdateAlarmInMetadata

​DeleteAlarmFromMetadata

​UpdatePhoneAlarms

​Messages

​GetPhoneMessages

​AddMessageToMetadata

​MarkMessagesReadInMetadata

​UpdatePhoneMessages

​Radio Channels

​GetRadioChannelsFromMetadata

​AddRadioChannelToMetadata

​UpdateRadioChannelInMetadata

​DeleteRadioChannelFromMetadata

​GetRadioRecentFromMetadata

​AddRadioRecentToMetadata

​ClearRadioRecentFromMetadata

​UpdateRadioChannels

​Social Media Accounts

​TweetWave

​Connect

​RoadID Account

​App Layout

​GetPhoneAppsFromMetadata

​UpdateInstalledApps

​UpdateHomescreenLayout

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

UpdatePhoneContacts

Notes

GetPhoneNotes

AddNoteToMetadata

UpdateNoteInMetadata

DeleteNoteFromMetadata

UpdatePhoneNotes

Photos

GetPhonePhotos

AddPhotoToMetadata

UpdatePhotoInMetadata

DeletePhotoFromMetadata

UpdatePhonePhotos

Albums

GetPhoneAlbumsFromMetadata

AddAlbumToPhoneMetadata

UpdateAlbumInMetadata

DeleteAlbumFromMetadata

AddPhotoToAlbumMetadata

RemovePhotoFromAlbumMetadata

AddMultiplePhotosToAlbumMetadata

Alarms

GetPhoneAlarms

AddAlarmToMetadata

UpdateAlarmInMetadata

DeleteAlarmFromMetadata

UpdatePhoneAlarms

Messages

GetPhoneMessages

AddMessageToMetadata

MarkMessagesReadInMetadata

UpdatePhoneMessages

Radio Channels

GetRadioChannelsFromMetadata

AddRadioChannelToMetadata

UpdateRadioChannelInMetadata

DeleteRadioChannelFromMetadata

GetRadioRecentFromMetadata

AddRadioRecentToMetadata

ClearRadioRecentFromMetadata

UpdateRadioChannels

Social Media Accounts

TweetWave

Connect

RoadID Account

App Layout

GetPhoneAppsFromMetadata

UpdateInstalledApps

UpdateHomescreenLayout

UpdatePhoneApps

Backup System

CreatePhoneBackup

GetPhoneBackups

RestorePhoneBackup

DeletePhoneBackup