> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roadshop.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata Exports

> Server-side exports for phone item metadata manipulation

# 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.

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

## Helper Functions

### GetPhoneMetadataOnly

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

```lua theme={null}
local metadata = exports['roadphone']:GetPhoneMetadataOnly(source)
```

<ParamField path="source" type="number" required>
  The player's server ID.
</ParamField>

<ResponseField name="returns" type="table | nil">
  The complete phone metadata table, or `nil` if not found.
</ResponseField>

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

***

### UpdatePhoneMetadataField

Update a single top-level field in phone metadata.

```lua theme={null}
local success = exports['roadphone']:UpdatePhoneMetadataField(source, fieldName, value)
```

<ParamField path="source" type="number" required>
  The player's server ID.
</ParamField>

<ParamField path="fieldName" type="string" required>
  The metadata field name to update (e.g., `'phone_background'`).
</ParamField>

<ParamField path="value" type="any" required>
  The new value for the field. Use `nil` to remove the field.
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if successful, `false` otherwise.
</ResponseField>

***

### UpdatePhoneMetadataNested

Update a nested field within phone metadata.

```lua theme={null}
local success = exports['roadphone']:UpdatePhoneMetadataNested(source, parentField, childField, value)
```

<ParamField path="source" type="number" required>
  The player's server ID.
</ParamField>

<ParamField path="parentField" type="string" required>
  The parent field name (e.g., `'phone_settings'`).
</ParamField>

<ParamField path="childField" type="string" required>
  The child field name (e.g., `'brightness'`).
</ParamField>

<ParamField path="value" type="any" required>
  The new value for the nested field.
</ParamField>

<CodeGroup>
  ```lua Example theme={null}
  -- Update brightness setting
  exports['roadphone']:UpdatePhoneMetadataNested(source, 'phone_settings', 'brightness', 75)
  ```
</CodeGroup>

***

### UpdatePhoneMetadataArray

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

```lua theme={null}
local success = exports['roadphone']:UpdatePhoneMetadataArray(source, arrayField, operation, data, idField, limit)
```

<ParamField path="source" type="number" required>
  The player's server ID.
</ParamField>

<ParamField path="arrayField" type="string" required>
  The array field name (e.g., `'phone_contacts'`).
</ParamField>

<ParamField path="operation" type="string" required>
  The operation type: `'add'`, `'update'`, or `'delete'`.
</ParamField>

<ParamField path="data" type="any" required>
  For `'add'`/`'update'`: the item object. For `'delete'`: the ID value.
</ParamField>

<ParamField path="idField" type="string" required>
  The field name used as identifier (e.g., `'id'`).
</ParamField>

<ParamField path="limit" type="number">
  Optional maximum array size (only for `'add'` operations).
</ParamField>

<CodeGroup>
  ```lua Example theme={null}
  -- 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')
  ```
</CodeGroup>

***

## Phone Number & Setup

### GetPhoneNumberFromItem

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

```lua theme={null}
local phoneNumber, itemName, slot, metadata = exports['roadphone']:GetPhoneNumberFromItem(source, specificSlot)
```

<ParamField path="source" type="number" required>
  The player's server ID.
</ParamField>

<ParamField path="specificSlot" type="number">
  Optional specific inventory slot to check.
</ParamField>

<ResponseField name="returns" type="string, string, number, table">
  Returns phone number, item name, slot number, and full metadata.
</ResponseField>

***

### AssignPhoneNumberToItem

Assign a new phone number to a phone item.

```lua theme={null}
local success, phoneNumber = exports['roadphone']:AssignPhoneNumberToItem(source, itemName, slot)
```

<ParamField path="source" type="number" required>
  The player's server ID.
</ParamField>

<ParamField path="itemName" type="string" required>
  The phone item name.
</ParamField>

<ParamField path="slot" type="number" required>
  The inventory slot number.
</ParamField>

<ResponseField name="returns" type="boolean, string">
  Success status and the assigned phone number.
</ResponseField>

***

### GetOrCreatePhoneNumber

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

```lua theme={null}
local phoneNumber, wasCreated = exports['roadphone']:GetOrCreatePhoneNumber(source)
```

<ParamField path="source" type="number" required>
  The player's server ID.
</ParamField>

<ResponseField name="returns" type="string, boolean">
  The phone number and whether it was newly created.
</ResponseField>

***

### GetPhoneSetupFromItem

Check if the phone has completed initial setup.

```lua theme={null}
local setupStatus = exports['roadphone']:GetPhoneSetupFromItem(source)
```

<ResponseField name="returns" type="number">
  `1` if setup is complete, `0` if setup is needed.
</ResponseField>

***

### UpdatePhoneSetup

Update the phone setup status.

```lua theme={null}
local success = exports['roadphone']:UpdatePhoneSetup(source, setupStatus)
```

<ParamField path="setupStatus" type="number" required>
  `1` for complete, `0` for needs setup.
</ParamField>

***

## Background & Settings

### GetPhoneBackground

Get the phone's wallpaper background.

```lua theme={null}
local background = exports['roadphone']:GetPhoneBackground(source)
```

<ResponseField name="returns" type="string | nil">
  The background URL/path, or `nil` if using default.
</ResponseField>

***

### UpdatePhoneBackground

Set the phone's wallpaper background.

```lua theme={null}
local success = exports['roadphone']:UpdatePhoneBackground(source, background)
```

<ParamField path="background" type="string | nil" required>
  The background URL/path, or `nil` to reset to default.
</ParamField>

***

### GetPhoneSettingsFromMetadata

Get all phone settings.

```lua theme={null}
local settings = exports['roadphone']:GetPhoneSettingsFromMetadata(source)
```

<ResponseField name="returns" type="table | nil">
  Settings object with: `brightness`, `flightmode`, `large_app_icons`, `iconcolor`, `darkmode`, `timeCustomization`.
</ResponseField>

***

### UpdatePhoneSettings

Update phone settings.

```lua theme={null}
local success = exports['roadphone']:UpdatePhoneSettings(source, settings)
```

<ParamField path="settings" type="table" required>
  Table with settings to update. Only provided keys will be changed.
</ParamField>

<Expandable title="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
</Expandable>

<CodeGroup>
  ```lua Example theme={null}
  exports['roadphone']:UpdatePhoneSettings(source, {
      brightness = 80,
      darkmode = 1
  })
  ```
</CodeGroup>

***

## PIN/Passcode

### GetPhonePin

Get the phone's PIN configuration.

```lua theme={null}
local pinData = exports['roadphone']:GetPhonePin(source)
```

<ResponseField name="returns" type="table | nil">
  Table with `pin` (string, 6 digits) and `pin_needed` (0 or 1).
</ResponseField>

***

### UpdatePhonePin

Update the phone's PIN.

```lua theme={null}
local success = exports['roadphone']:UpdatePhonePin(source, pin, pinNeeded)
```

<ParamField path="pin" type="string" required>
  The 6-digit PIN code, or `nil` to remove.
</ParamField>

<ParamField path="pinNeeded" type="number" required>
  `1` to require PIN on unlock, `0` to disable.
</ParamField>

<CodeGroup>
  ```lua Example theme={null}
  -- 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)
  ```
</CodeGroup>

***

## Contacts

### GetPhoneContacts

Get all contacts from the phone.

```lua theme={null}
local contacts = exports['roadphone']:GetPhoneContacts(source)
```

<ResponseField name="returns" type="table">
  Array of contact objects.
</ResponseField>

***

### AddContactToMetadata

Add a new contact.

```lua theme={null}
local success = exports['roadphone']:AddContactToMetadata(source, contact)
```

<ParamField path="contact" type="table" required>
  Contact object with `id`, `name`, `number`, and optional `avatar`.
</ParamField>

***

### UpdateContactInMetadata

Update an existing contact.

```lua theme={null}
local success = exports['roadphone']:UpdateContactInMetadata(source, contactId, updatedContact)
```

***

### DeleteContactFromMetadata

Delete a contact.

```lua theme={null}
local success = exports['roadphone']:DeleteContactFromMetadata(source, contactId)
```

***

### UpdatePhoneContacts

Replace the entire contacts array in metadata.

```lua theme={null}
local success = exports['roadphone']:UpdatePhoneContacts(source, contacts)
```

<ParamField path="contacts" type="table" required>
  Array of contact objects to replace all existing contacts.
</ParamField>

***

## Notes

### GetPhoneNotes

Get all notes from the phone.

```lua theme={null}
local notes = exports['roadphone']:GetPhoneNotes(source)
```

***

### AddNoteToMetadata

Add a new note.

```lua theme={null}
local success = exports['roadphone']:AddNoteToMetadata(source, note)
```

<ParamField path="note" type="table" required>
  Note object with `id`, `title`, `content`, `created_at`.
</ParamField>

***

### UpdateNoteInMetadata

Update an existing note.

```lua theme={null}
local success = exports['roadphone']:UpdateNoteInMetadata(source, noteId, updatedNote)
```

***

### DeleteNoteFromMetadata

Delete a note.

```lua theme={null}
local success = exports['roadphone']:DeleteNoteFromMetadata(source, noteId)
```

***

### UpdatePhoneNotes

Replace the entire notes array in metadata.

```lua theme={null}
local success = exports['roadphone']:UpdatePhoneNotes(source, notes)
```

<ParamField path="notes" type="table" required>
  Array of note objects to replace all existing notes.
</ParamField>

***

## Photos

### GetPhonePhotos

Get all photos from the phone.

```lua theme={null}
local photos = exports['roadphone']:GetPhonePhotos(source)
```

***

### AddPhotoToMetadata

Add a new photo.

```lua theme={null}
local success = exports['roadphone']:AddPhotoToMetadata(source, photo)
```

<ParamField path="photo" type="table" required>
  Photo object with `id`, `url`, `created_at`, and optional `favorite`.
</ParamField>

***

### UpdatePhotoInMetadata

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

```lua theme={null}
local success = exports['roadphone']:UpdatePhotoInMetadata(source, photoId, updates)
```

***

### DeletePhotoFromMetadata

Delete a photo.

```lua theme={null}
local success = exports['roadphone']:DeletePhotoFromMetadata(source, photoId)
```

***

### UpdatePhonePhotos

Replace the entire photos array in metadata.

```lua theme={null}
local success = exports['roadphone']:UpdatePhonePhotos(source, photos)
```

<ParamField path="photos" type="table" required>
  Array of photo objects to replace all existing photos.
</ParamField>

***

## Albums

### GetPhoneAlbumsFromMetadata

Get all photo albums from the phone.

```lua theme={null}
local albums = exports['roadphone']:GetPhoneAlbumsFromMetadata(source)
```

<ParamField path="source" type="number" required>
  The player's server ID.
</ParamField>

<ResponseField name="returns" type="table">
  Array of album objects, or empty table if none exist.
</ResponseField>

***

### AddAlbumToPhoneMetadata

Create a new album.

```lua theme={null}
local success = exports['roadphone']:AddAlbumToPhoneMetadata(source, album)
```

<ParamField path="album" type="table" required>
  Album object with `id`, `name`, `photoIds` fields.
</ParamField>

***

### UpdateAlbumInMetadata

Update specific fields of an existing album.

```lua theme={null}
local success = exports['roadphone']:UpdateAlbumInMetadata(source, albumId, updates)
```

<ParamField path="albumId" type="any" required>
  The album's identifier.
</ParamField>

<ParamField path="updates" type="table" required>
  Key/value pairs to merge into the album.
</ParamField>

***

### DeleteAlbumFromMetadata

Delete an album.

```lua theme={null}
local success = exports['roadphone']:DeleteAlbumFromMetadata(source, albumId)
```

<ParamField path="albumId" type="any" required>
  The album's identifier.
</ParamField>

***

### AddPhotoToAlbumMetadata

Add a photo to an album. Skips duplicates.

```lua theme={null}
local success = exports['roadphone']:AddPhotoToAlbumMetadata(source, albumId, photoId)
```

<ParamField path="albumId" type="any" required>
  The album's identifier.
</ParamField>

<ParamField path="photoId" type="any" required>
  The photo's identifier to add.
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` on success (or if already exists), `false` if album not found.
</ResponseField>

***

### RemovePhotoFromAlbumMetadata

Remove a photo from an album.

```lua theme={null}
local success = exports['roadphone']:RemovePhotoFromAlbumMetadata(source, albumId, photoId)
```

<ParamField path="albumId" type="any" required>
  The album's identifier.
</ParamField>

<ParamField path="photoId" type="any" required>
  The photo's identifier to remove.
</ParamField>

***

### AddMultiplePhotosToAlbumMetadata

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

```lua theme={null}
local success = exports['roadphone']:AddMultiplePhotosToAlbumMetadata(source, albumId, photoIds)
```

<ParamField path="albumId" type="any" required>
  The album's identifier.
</ParamField>

<ParamField path="photoIds" type="table" required>
  Array of photo identifiers to add.
</ParamField>

<CodeGroup>
  ```lua Example theme={null}
  -- Add multiple photos to an album
  exports['roadphone']:AddMultiplePhotosToAlbumMetadata(source, "album-001", {
      "photo-001", "photo-002", "photo-003"
  })
  ```
</CodeGroup>

***

## Alarms

### GetPhoneAlarms

Get all alarms from the phone.

```lua theme={null}
local alarms = exports['roadphone']:GetPhoneAlarms(source)
```

***

### AddAlarmToMetadata

Add a new alarm.

```lua theme={null}
local success = exports['roadphone']:AddAlarmToMetadata(source, alarm)
```

***

### UpdateAlarmInMetadata

Update an existing alarm.

```lua theme={null}
local success = exports['roadphone']:UpdateAlarmInMetadata(source, alarmId, updatedAlarm)
```

***

### DeleteAlarmFromMetadata

Delete an alarm.

```lua theme={null}
local success = exports['roadphone']:DeleteAlarmFromMetadata(source, alarmId)
```

***

### UpdatePhoneAlarms

Replace all alarms on the phone at once.

```lua theme={null}
local success = exports['roadphone']:UpdatePhoneAlarms(source, alarms)
```

<ParamField path="source" type="number" required>
  The player's server ID.
</ParamField>

<ParamField path="alarms" type="table" required>
  Array of alarm objects to set. Pass `{}` to clear all alarms.
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if the metadata was updated successfully, `false` otherwise.
</ResponseField>

<CodeGroup>
  ```lua Example theme={null}
  -- 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, {})
  ```
</CodeGroup>

***

## Messages

### GetPhoneMessages

Get all messages from the phone.

```lua theme={null}
local messages = exports['roadphone']:GetPhoneMessages(source)
```

***

### AddMessageToMetadata

Add a new message to the phone.

```lua theme={null}
local success = exports['roadphone']:AddMessageToMetadata(source, message)
```

***

### MarkMessagesReadInMetadata

Mark messages from a specific number as read.

```lua theme={null}
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).

```lua theme={null}
local success = exports['roadphone']:UpdatePhoneMessages(source, messages, unreadCount)
```

<ParamField path="source" type="number" required>
  The player's server ID.
</ParamField>

<ParamField path="messages" type="table" required>
  Array of message objects to set.
</ParamField>

<ParamField path="unreadCount" type="number">
  Number of unread messages. Defaults to `0`.
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if the metadata was updated successfully, `false` otherwise.
</ResponseField>

<CodeGroup>
  ```lua Example theme={null}
  -- 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)
  ```
</CodeGroup>

***

## Radio Channels

### GetRadioChannelsFromMetadata

Get saved radio channels.

```lua theme={null}
local channels = exports['roadphone']:GetRadioChannelsFromMetadata(source)
```

***

### AddRadioChannelToMetadata

Add a saved radio channel.

```lua theme={null}
local success = exports['roadphone']:AddRadioChannelToMetadata(source, channel)
```

***

### UpdateRadioChannelInMetadata

Update a saved radio channel.

```lua theme={null}
local success = exports['roadphone']:UpdateRadioChannelInMetadata(source, channelId, updatedChannel)
```

***

### DeleteRadioChannelFromMetadata

Delete a saved radio channel.

```lua theme={null}
local success = exports['roadphone']:DeleteRadioChannelFromMetadata(source, channelId)
```

***

### GetRadioRecentFromMetadata

Get recent radio frequencies.

```lua theme={null}
local recent = exports['roadphone']:GetRadioRecentFromMetadata(source)
```

***

### AddRadioRecentToMetadata

Add a frequency to recent list.

```lua theme={null}
local success = exports['roadphone']:AddRadioRecentToMetadata(source, frequency)
```

***

### ClearRadioRecentFromMetadata

Clear all recent frequencies.

```lua theme={null}
local success = exports['roadphone']:ClearRadioRecentFromMetadata(source)
```

***

### UpdateRadioChannels

Replace all saved radio channels on the phone at once.

```lua theme={null}
local success = exports['roadphone']:UpdateRadioChannels(source, channels)
```

<ParamField path="source" type="number" required>
  The player's server ID.
</ParamField>

<ParamField path="channels" type="table" required>
  Array of radio channel objects to set. Pass `{}` to clear all channels.
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if the metadata was updated successfully, `false` otherwise.
</ResponseField>

<CodeGroup>
  ```lua Example theme={null}
  -- 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, {})
  ```
</CodeGroup>

***

## Social Media Accounts

### TweetWave

```lua theme={null}
-- 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)
```

<Note>
  **Backwards Compatibility:** The old `*TwitterAccount*` export names still work but are deprecated.
</Note>

***

### Connect

```lua theme={null}
-- 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

```lua theme={null}
-- 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.

```lua theme={null}
local apps = exports['roadphone']:GetPhoneAppsFromMetadata(source)
```

<ResponseField name="returns" type="table | nil">
  Object with `installed` (array of app IDs) and `homescreen` (layout data).
</ResponseField>

***

### UpdateInstalledApps

Update the list of installed apps.

```lua theme={null}
local success = exports['roadphone']:UpdateInstalledApps(source, installedApps)
```

***

### UpdateHomescreenLayout

Update the homescreen layout (pages and dock).

```lua theme={null}
local success = exports['roadphone']:UpdateHomescreenLayout(source, homescreenData)
```

***

### UpdatePhoneApps

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

```lua theme={null}
local success = exports['roadphone']:UpdatePhoneApps(source, appsData)
```

<ParamField path="source" type="number" required>
  The player's server ID.
</ParamField>

<ParamField path="appsData" type="table" required>
  Object with `installed` (array of app IDs) and `homescreen` (layout data).
</ParamField>

<ResponseField name="returns" type="boolean">
  `true` if the metadata was updated successfully, `false` otherwise.
</ResponseField>

<CodeGroup>
  ```lua Example theme={null}
  exports['roadphone']:UpdatePhoneApps(source, {
      installed = { "phone", "messages", "camera", "settings", "mail" },
      homescreen = {
          -- your layout structure
      }
  })
  ```
</CodeGroup>

***

## Backup System

<Note>
  Backup functions require `Config.BackupEnabled = true` in the configuration.
</Note>

### CreatePhoneBackup

Create a backup of all phone data.

```lua theme={null}
local success, result = exports['roadphone']:CreatePhoneBackup(source, backupName, backupType)
```

<ParamField path="backupName" type="string">
  Optional custom name for the backup. Defaults to timestamp.
</ParamField>

<ParamField path="backupType" type="string">
  `'manual'` or `'auto'`. Defaults to `'manual'`.
</ParamField>

***

### GetPhoneBackups

Get all backups for the player.

```lua theme={null}
local backups = exports['roadphone']:GetPhoneBackups(source)
```

<ResponseField name="returns" type="table">
  Array of backup objects with `backup_id`, `backup_name`, `created_at`, `backup_type`.
</ResponseField>

***

### RestorePhoneBackup

Restore phone data from a backup.

```lua theme={null}
local success, message = exports['roadphone']:RestorePhoneBackup(source, backupId)
```

<ParamField path="backupId" type="string" required>
  The UUID of the backup to restore.
</ParamField>

***

### DeletePhoneBackup

Delete a backup.

```lua theme={null}
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

```lua theme={null}
-- 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)
```