Exports

Put the player's phone away. Returns false, 'invalid_source' when the player is not connected. Never yields.

exports.nx_phone:ClosePhone(source, 'cuffed')

Put the phone away and end its unlock, so the next open asks for the passcode even when Config.Auth.LockOnClose is false. Errors: invalid_source, failed. Awaits.

exports.nx_phone:LockPhone(source)

Stop the player from using the phone. Each calling resource holds its own disable, and the phone stays disabled while any resource holds one, so handcuffs and jail are two separate holds. Your hold is released when your resource stops. Calls still ring a disabled phone. Never yields.

exports.nx_phone:SetPhoneDisabled(source, true, 'You are in handcuffs.')
-- later
exports.nx_phone:SetPhoneDisabled(source, false)

Whether any server-side hold disables this player's phone, and one hold's reason. Holds set with the client export are not included. Never yields.

Whether the player has the phone open right now. Reads a replicated state, so it costs no round trip to the client.

if exports.nx_phone:IsPhoneOpen(source) then
    return -- refuse the action while the player is on the phone
end

Whether the player has an unlocked phone session.

Open the player's phone and call the number, as the client export StartCall does. Errors: invalid_source, invalid_number. Whether the call goes through is up to the player's phone (a passcode, no SIM). Never yields.

exports.nx_phone:StartCall(source, '555-0142')

The connected player holding the handset this number's active SIM is in, or nil. Awaits.

local target = exports.nx_phone:GetSourceFromNumber('555-4821')

The number the player is using: the handset they unlocked, if they still carry it and it has an active SIM, otherwise the first handset they carry (lowest inventory slot) with an active SIM. Awaits.

local number = exports.nx_phone:GetNumberFromSource(source)

The number a character uses, whether they are online or not. Use it to keep a customer's number on an order made while they are offline. Awaits.

local number = exports.nx_phone:GetNumberFromIdentifier(order.customerIdentifier)

Whether the player is a party of a voice call (dialling, ringing out or connected) or is in a FaceTime call. A call that only rings them does not count. Never yields.

Every active SIM the character owns, online or offline, as a list of { number, device_phone_id, carrier, primary }. device_phone_id is set while the SIM is in a phone. The main number comes first, with primary = true.

The same list for the character that owns the account.

The phone id of the handset the number's active SIM is in, or nil.

The number of the SIM in that handset, or nil.

The player's unlocked phone session, or nil when the phone is locked. Fields include phoneId, accountId, number, actorIdentifier, username, displayName and allowedApps (the app ids this player may open).

local ctx = exports.nx_phone:GetSessionContext(source)
if ctx and ctx.number then
    -- the player has an unlocked phone with a number
end

The account acting for this player: the phone session's account, else the laptop session's (with nx_computer), else the character's primary account.

Send a text message. Awaits.

local id, convOrErr = exports.nx_phone:SendMessage({
    from = '555-0190',
    to = '555-4821',
    text = 'Your order is ready for pickup.',
})
if not id then print('send failed: ' .. convOrErr) end

-- A quest offer with a meeting point and two answers.
exports.nx_phone:SendMessage({
    from = '555-0420',
    to = playerNumber,
    text = 'Got a job for you. Meet me here.',
    location = { x = 215.4, y = -810.2, name = 'Legion Square' },
    choices = { { id = 'accept', label = "I'm in" }, { id = 'decline', label = 'Not now' } },
})

Show a notification on a player's phone and store it on the handset. Returns the notification id. Awaits.

exports.nx_phone:Notify({
    source = playerId,
    appId = 'x.my_shop.orders',
    title = 'Order ready',
    message = 'Pick it up at the counter.',
})

Deliver a mail to a player's Mail inbox. With nx_computer running it goes through the laptop's mail system. Awaits.

exports.nx_phone:SendMail({
    to = '555-4821',
    fromName = 'Pacific Standard',
    subject = 'Statement ready',
    body = 'Your monthly statement is available at any branch.',
})

Claim a number for your resource. Registering the same number again from your resource updates it. Awaits.

exports.nx_phone:RegisterHotline('555-0190', {
    label = 'Downtown Cab Co.',
    onCall = function(src, info)
        return { ring = GetOnDutyDrivers() }   -- your own function
    end,
    onMessage = function(src, msg)
        exports.nx_phone:SendMessage({ from = '555-0190', to = msg.from, text = 'A driver is on the way.' })
    end,
})

Release a hotline. Errors: not_found, not_owner. Never yields.

An NPC calls a player. Awaits.

exports.nx_phone:CallPlayer(playerId, {
    from = '555-0420',
    script = {
        text = 'Vlad here. Still want that job?',
        choices = { { id = 'yes', label = 'Yes' }, { id = 'no', label = 'No' } },
        onChoice = function(src, info)
            if info.choice == 'yes' then
                StartQuest(src)   -- your own function
                return { text = 'Good. Pier, midnight. Come alone.', hangup = true }
            end
            return { text = 'Your loss.', hangup = true }
        end,
    },
})

exports.nx_phone:RegisterHotline('555-0420', {
    label = 'Vlad',
    onCall = function(src, info)
        return { bot = {
            text = 'Vlad. What do you need?',
            choices = { 'Work', 'Nothing' },
            onChoice = function(src2, pick)
                if pick.choice == 'c1' then
                    OfferJob(src2)  -- your own function
                    return { text = 'Check your messages.', hangup = true }
                end
            end,
        } }
    end,
})

Every live call as a list of { id, state, service, callerNumber, calleeNumber, startedAt }. A hidden caller's number is included, since server code is trusted.

for _, call in ipairs(exports.nx_phone:GetActiveCalls()) do
    print(call.id, call.state, call.callerNumber)
end

One live call, or nil. Fields: callId, state, from?, to?, hidden, service?, hotline?, video (always false), fromSource?, answeredBy?, answeredSource?, startedAt, answeredAt?. Never yields.

End a live call. Errors: not_found, invalid. Never yields.

Force-drop a live call for staff tools, the same way airplane mode drops one. The phone has no admin concept, so check permissions before you call it. Errors: invalid, unavailable, not_found, no_handset, still_active.

Decide who rings for a service line. info is { callId, number, label, emergency, from, source, hidden }. When fn returns nil, the line falls back to its jobs, minGrade and requireDuty. One resource owns a line's router at a time. Errors: not_a_service, router_taken, invalid_handler. Never yields.

exports.nx_phone:SetServiceRouter('911', function(info)
    return GetDispatchersNear(info.source)   -- your own function; nil = default rule
end)

Create a SIM owned by the player's character and put the SIM item in their inventory. Returns the number. Awaits.

local number, err = exports.nx_phone:GiveSim(source, { number = '555-7777' })

Create a SIM record with a random number without giving an item. Most resources want GiveSim instead. Errors: schema_not_ready, pool_exhausted, insert_failed.

Start the reclaim clock (Config.Sim.ReclaimDays). The number stops working at once and a call on it drops. Errors: sim_not_found, sim_reclaimed. Awaits.

Take the number from its owner for good. It is never issued again. Awaits.

Give an unused SIM a different number. The old number is retired for good. Awaits.

Put a SIM the player carries into a phone they carry, exactly as using the SIM item does. Returns the inserted number and the number of the SIM it replaced, if any. Awaits.

local number, replaced = exports.nx_phone:InsertSim(source, { number = '555-7777' })

Take the SIM out of a phone the player carries and give it back as an item. Returns its number. Awaits.

One SIM, whatever its status. Awaits.

Every SIM a player carries: SIM items in their inventory (with slot) and the SIMs inside the phones they carry (with phoneId). Each entry has the same fields as GetSim. Awaits.

The character's main number, online or offline, or nil when they have none. A suspended main number is still returned; a reclaimed one is not. Awaits.

local main = exports.nx_phone:GetPrimaryNumber(xPlayer.identifier)

The main numbers of many characters in one lookup, as { [identifier] = number }, for a list such as a dispatch roster. Characters without a main number are left out. Awaits.

local numbers = exports.nx_phone:GetPrimaryNumbers({ 'char1:abc', 'char1:def' })
for identifier, number in pairs(numbers) do
    print(identifier, number)
end

Whether the number is someone's main number. Awaits.

Give the player a replacement SIM for their main number, the same replacement the carrier counter sells, with no counter and no charge. Use it from your own shop. Returns the number. Awaits.

local number, err = exports.nx_phone:ReplaceMainSim(source)
if not number then
    return TriggerClientEvent('ox_lib:notify', source, { type = 'error', description = err })
end

The handset record: phone_id, imei, owner_identifier, model, lock_state, last known position and more. nil when it does not exist.

Lock, set Lost Mode on, or erase a handset. byActor must be the handset's owner unless opts.adminOverride is true. message and contact are shown in Lost Mode. 'wiped' erases the phone's data. Returns how many unlock sessions were ended. Errors: invalid_device, invalid_state, device_not_found, not_your_device, invalid_contact.

Whether the player carries that handset.

Battery level from 0 to 100.

Set the battery level, for example from a charger item.

Whether airplane mode is on.

Whether ownerNumber has blocked otherNumber.

Whether either number has blocked the other.

The name ownerNumber saved for otherNumber, or nil.

A map of number to saved name, for the numbers that have a contact.

Save a contact in a player's phonebook, for example an NPC. Awaits.

exports.nx_phone:AddContact(playerId, { number = '555-0420', name = 'Vlad', note = 'Knows people.' })

Remove a contact from a player's phonebook. Errors: invalid_target, invalid_number, not_found. Awaits.

Start an activity on a player's phone. Returns its id. Errors: disabled, invalid_content:field, too_big, too_many, owner_cap, rate_limited.

local id = exports.nx_phone:StartLiveActivity(customer, {
    title = 'Repair order',
    subtitle = 'Los Santos Customs',
    glyph = 'wrench',
    steps = { labels = { 'Placed', 'In progress', 'Ready' }, current = 1 },
    actions = { { id = 'cancel', label = 'Cancel', style = 'destructive' } },
})

Update one of your activities. Errors: not_found, not_owner, rate_limited, invalid_content:field.

exports.nx_phone:UpdateLiveActivity(id, { steps = { labels = { 'Placed', 'In progress', 'Ready' }, current = 3 }, alert = true })

End one of your activities.

Your own activities on that player as a list of { id, owner, title, startedAt, updatedAt }.

Add your resource's web page to the phone as an app. Returns the app id, x.your_resource.name. The SDK page lists every field.

local id, err = exports.nx_phone:RegisterApp({
    name = 'dice',
    label = 'Dice',
    page = 'web/index.html',
    icon = 'web/icon.webp',
})

Remove one of your apps. Errors: invalid_name, not_found.

Whether the app is installed on that handset. Always true when Depot is turned off.

Add an .lc website to the phone's Browser. Your sites are removed when your resource stops.

exports.nx_phone:RegisterSite({
    domain = 'pizza.lc',            -- lowercase letters, digits and dashes, ending in .lc
    title = 'Pizza Planet',         -- up to 80 characters
    description = 'Hot pizza, fast', -- optional, up to 200
    keywords = { 'pizza', 'food' },  -- optional, used by search.lc
    pages = {
        ['/'] = {
            title = 'Pizza Planet',
            theme = { accent = '#e23b3b', bg = '#1a1a1a' },
            blocks = {
                { type = 'hero', title = 'Pizza Planet', subtitle = 'Open late' },
                { type = 'button', label = 'Call us', href = 'app:calls' },
            },
        },
    },
    -- or: handler = function(src, path, query, form) return page end
})

Remove one of your sites.

Send an alert to the Shift inbox of every on-duty holder of the job, with a phone notification. Returns the first alert id and the list of ids. Awaits.

exports.nx_phone:SendDispatch({
    job = 'police',
    code = '10-90',
    title = 'Store alarm',
    body = '24/7 on Innocence Blvd',
    coords = GetEntityCoords(GetPlayerPed(source)),
    priority = 'high',
})

Add a job to the character's held jobs, or change its grade. A new grade for the job they work reaches the framework too. Errors: forbidden, disabled, schema_not_ready, invalid_request, unknown_job, max_jobs.

Remove a held job, online or offline. 'left' means it was the worked job and the character is now on Config.Shift.MultiJob.Fallback; do not set a job yourself in that case. Errors: forbidden, disabled, invalid_request, not_held, unavailable.

The character's held jobs as a list of { job, grade, removable }.

Everyone holding the job as a list of { identifier, grade, removable }.

A list of every job name that has members.

Whether the company is open right now. false for a company that is not listed. Never yields.

if not exports.nx_phone:GetCompanyOpen('mechanic') then
    return -- nobody is working at LS Customs
end

Every open company as a set, { [id] = true }. Never yields.

Every company in the directory, sorted by name. Never yields.

for _, company in ipairs(exports.nx_phone:GetCompanies()) do
    print(company.label, company.number, company.open)
end

Add a company to the directory from your own resource, or update one you added. The directory picks it up within a moment. Never yields.

local function register()
    if GetResourceState('nx_phone') ~= 'started' then return end
    exports.nx_phone:RegisterCompany('burgershot', {
        label = 'Burger Shot',
        coords = vector3(-1183.5, -884.2, 13.8),
        icon = 'nui://my_assets/burgershot.png',
        description = 'Burgers, fries and shakes.',
    })
end

AddEventHandler('nx_phone:sdkReady', register)
AddEventHandler('onResourceStart', function(res)
    if res == GetCurrentResourceName() then register() end
end)

Remove a company your resource registered. Errors: not_found, not_owner. Never yields.

Ring every online owner and key holder of the property with a notification that opens the Home app's doorbell sheet. Returns how many phones were notified. Limited by Config.Home.Doorbell.Cooldown.

Post to Yapp as an existing profile, for example a city account. Returns the post id. Errors: disabled, not_found, and the post's own checks.

Set or remove a profile's verified badge. The same as the yapp_verify command. Errors: invalid_tier, not_found.

The public profile: id, handle, displayName, avatar, verified, bio, isPrivate, followers, following, posts and createdAt.

Open a charge on a merchant's phone, as if they keyed it in Wallet. The nearest customer with their phone out gets the Pay sheet. Returns the charge key. Errors: forbidden, invalid_request, rate_limited, unavailable, and the charge's own checks.

local key, err = exports.nx_phone:CreateTerminalCharge(source, { amount = 45, label = 'Burger meal' })

{ status, amount, total, payerIdentifier?, refId? }. status is, for example, waiting, paid, cancelled, expired or refunded. Listen to nx_phone:taptopay:paid instead of polling.

{ success, devices }: the character's phones and where each one is.

{ success, device, live, location? }, or { success = false, error }.

Make the phone ring for Config.Beacon.SoundSeconds. { success, where, seconds }, or { success = false, error }.

Turn Lost Mode on or off. { success, devices }, or { success = false, error }.

Robocall campaigns, newest first, for police tools. Each has id, ownerIdentifier, accountId, callerId, agentNumber, pitch, status, targets, placed, answered, screened, pressed and createdAt.

Open the phone. Returns true when it opened or was already open, false when it was refused (no phone, disabled, or a can-open hook said no).

exports.nx_phone:OpenPhone()

Put the phone away.

Close the phone if it is open (returns false), otherwise open it (returns true when it opened).

Whether the phone is open.

The client version of the server export. Each calling resource holds its own disable, an open phone closes, and a disabled phone does not rise for calls or notifications. Returns whether the phone is disabled after the call.

exports.nx_phone:SetPhoneDisabled(true, 'Not while swimming.')

Whether the phone is disabled, and a map of holder to reason. A holder is a resource name, or 'server' for a hold set with the server export.

Add a check that runs before the phone opens. Returns an id for RemoveCanOpen. The hook is removed when your resource stops.

exports.nx_phone:RegisterCanOpen(function(ctx)
    if IsPedSwimmingUnderWater(PlayerPedId()) then
        return false, 'Your phone would drown.'
    end
end)

Remove one of your can-open hooks. Only the resource that registered it can remove it.

Whether the player is in a connected call or an outgoing call that is ringing out, and the live call's state ('dialing', 'ringing', 'active' and so on) when there is one.

The id of the handset that is open, or nil when the phone is closed.

Whether the phone is unlocked.

Open the phone and call the number, for a button like Call customer in your own UI. The phone opens through the item as usual, a locked phone asks for the passcode first, and the call starts once it is unlocked. The call is dropped if the phone is put away first or is not unlocked within 60 seconds. Errors: invalid_number, disabled, in_call, cannot_open (no phone carried, or a can-open hook refused). A call the phone refuses (no SIM, airplane mode) shows its reason in the Phone app.

-- a "Call customer" button in your NUI
RegisterNUICallback('callCustomer', function(data, cb)
    local ok, err = exports.nx_phone:StartCall(data.phone)
    cb({ ok = ok, error = err })
end)

Start an activity on the local player's phone. Returns its id.

local id = exports.nx_phone:StartLiveActivity({
    title = 'Taxi fare',
    glyph = 'taxi',
    value = '$12',
    timer = { startedAt = GetCloudTimeAsInt() * 1000 },
})

Update one of your activities.

End one of your activities.

Your resource's activities on this client as a list of { id, owner, title, startedAt, updatedAt }.

Whether the company is open right now.

local label = exports.nx_phone:GetCompanyOpen('taxi') and 'Open' or 'Closed'

Every open company as a set, { [id] = true }.

Send data to your app's page (nxp.onMessage). Returns false and drops the message when the app is not on screen, the data is too large, or your resource passed 30 messages a second.

exports.nx_phone:SendAppMessage('dice', { kind = 'nearby', total = 7 })

Whether your app is on the phone's screen.

Play the phone's own sounds on this client only. 'ring' loops a ringtone until 'stop'; 'isRinging' reports whether one is playing.