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)

number

required

The player’s server ID.

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)

number

required

The player’s server ID.

string

required

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

any

required

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

boolean

true if successful, false otherwise.

UpdatePhoneMetadataNested

Update a nested field within phone metadata.

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

number

required

The player’s server ID.

string

required

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

string

required

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

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)

number

required

The player’s server ID.

string

required

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

string

required

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

any

required

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

string

required

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

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)

number

required

The player’s server ID.

number

Optional specific inventory slot to check.

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)

number

required

The player’s server ID.

string

required

The phone item name.

number

required

The inventory slot number.

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)

number

required

The player’s server ID.

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)

number

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

UpdatePhoneSetup

Update the phone setup status.

local success = exports['roadphone']:UpdatePhoneSetup(source, 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)

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)

string | nil

required

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

GetPhoneSettingsFromMetadata

Get all phone settings.

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

table | nil

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

UpdatePhoneSettings

Update phone settings.

local success = exports['roadphone']:UpdatePhoneSettings(source, 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)

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.

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)

table

Array of contact objects.

AddContactToMetadata

Add a new contact.

local success = exports['roadphone']:AddContactToMetadata(source, 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)

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)

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)

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)

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)

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)

number

required

The player’s server ID.

table

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

AddAlbumToPhoneMetadata

Create a new album.

local success = exports['roadphone']:AddAlbumToPhoneMetadata(source, 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)

any

required

The album’s identifier.

table

required

Key/value pairs to merge into the album.

DeleteAlbumFromMetadata

Delete an album.

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

any

required

The album’s identifier.

AddPhotoToAlbumMetadata

Add a photo to an album. Skips duplicates.

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

any

required

The album’s identifier.

any

required

The photo’s identifier to add.

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)

any

required

The album’s identifier.

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)

any

required

The album’s identifier.

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)

number

required

The player’s server ID.

table

required

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

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)

number

required

The player’s server ID.

table

required

Array of message objects to set.

number

Number of unread messages. Defaults to 0.

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)

number

required

The player’s server ID.

table

required

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

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)

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)

number

required

The player’s server ID.

table

required

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

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)

string

Optional custom name for the backup. Defaults to timestamp.

string

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

GetPhoneBackups

Get all backups for the player.

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

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)

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)

​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

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