📞 Calls

CallContact

Initiates a phone call from one player to another.

lua
---@param targetNumber string The phone number to call
---@param targetPlayerId number|nil Optional: Target player's source ID (auto-resolves if nil)
---@param callerNumber string The caller's phone number (can be payphone number)
---@param callerPlayerId number The caller's player source ID
---@param anonymousCall boolean|nil Optional: Whether to hide caller ID (default: false)
---@return table|nil Call data object with CallId, CallType, TargetData, etc. Returns nil if call fails
local callData = exports.yseries:CallContact(
    "0882222",      -- targetNumber
    nil,            -- targetPlayerId (nil will auto-resolve)
    "0889999",      -- callerNumber (can be non-existent number or even a string)
    source,         -- callerPlayerId (crucial to connect both players)
    false          -- anonymousCall (default: false)
)

Validation Checks:

Validates caller player ID
Checks if caller has airplane mode enabled
Checks if caller is already in a call (allows loudspeaker participants)
Checks if target can receive calls (dead, phone disabled, no phone item, etc.)
Automatically removes target from loudspeaker if they're a participant

Returns:

lua
{
    CallType = "outgoing",
    InCall = true,
    TargetData = {
        number = "0882222"
    },
    CallId = 17634,
    AnsweredCall = false,
    RecentCallId = nil  -- Will be created when call is answered
}

EndCall

Ends an active phone call by call ID.

lua
---@param callId number The call ID to end
---@return boolean True if call was ended successfully, false otherwise
local success = exports.yseries:EndCall(callId)

if success then
    print("Call ended successfully")
else
    print("Failed to end call - call not found")
end

Note: This will end the call for all participants and trigger cleanup events.

IsInCall

Checks if a player is currently in a phone call and returns the call ID if they are.

lua
---@param playerId number Player's source ID
---@return boolean True if player is in a call, false otherwise
---@return number|nil CallId if player is in a call, nil otherwise
local inCall, callId = exports.yseries:IsInCall(source)

if inCall then
    print("Player is currently in a call with CallId: " .. tostring(callId))
else
    print("Player is not in a call")
end

CanReceiveCalls

Checks if a player can receive incoming calls. Returns true if player is not in a call, or if they're a loudspeaker participant.

lua
---@param playerId number Player's source ID
---@return boolean True if player can receive calls, false otherwise
local canReceive = exports.yseries:CanReceiveCalls(source)

if canReceive then
    print("Player can receive calls")
else
    print("Player is busy and cannot receive calls")
end

Use Case: Check before initiating a call to ensure the target is available.

GetCallData

Retrieves call data for a specific call ID. Returns an array of call data objects (one for each participant).

lua
---@param callId number The call ID to retrieve data for
---@return table Array of call data objects
local callData = exports.yseries:GetCallData(17634)

if callData and #callData > 0 then
    for _, data in ipairs(callData) do
        print("Call Type: " .. data.CallType)
        print("Answered: " .. tostring(data.AnsweredCall))
        print("Call Start Time: " .. tostring(data.CallStartTime))
    end
end

Returns:

lua
{
    {
        CallType = "outgoing",
        InCall = true,
        TargetData = {
            number = "0882222"
        },
        CallId = 17634,
        AnsweredCall = true,
        CallStartTime = 1763542085,
        RecentCallId = 1896
    },
    {
        CallType = "ongoing",
        InCall = true,
        TargetData = {
            number = "0889999",
            anonymous = false,
            isCompany = false
        },
        CallId = 17634,
        AnsweredCall = true,
        CallStartTime = 1763542085,
        RecentCallId = 1895
    }
}

RemovePlayerFromServerCall

Removes a player from a call and cleans up their call state. Useful for handling disconnections or forced call termination.

lua
---@param playerSourceId number Player's source ID to remove from call
exports.yseries:RemovePlayerFromServerCall(source)

-- This will:
-- 1. Clean up loudspeaker state
-- 2. Remove player from any loudspeaker they're participating in
-- 3. Clear their call data

Note: This is typically called automatically on player disconnect, but can be used manually if needed.

BlockContact

Blocks or unblocks a phone number for a specific phone IMEI.

lua
---@param contactData table Contact data with phoneNumber and isBlocked flag
---@param contactData.phoneNumber string Phone number to block/unblock
---@param contactData.isBlocked boolean True to block, false to unblock
---@param phoneImei string Phone IMEI to block the number for
---@return boolean True if operation was successful, false otherwise
local success = exports.yseries:BlockContact({
    phoneNumber = "0882222",
    isBlocked = true
}, phoneImei)

if success then
    print("Number blocked successfully")
end

GetBlockedNumbers

Retrieves all blocked phone numbers for a specific phone IMEI.

lua
---@param phoneImei string Phone IMEI to get blocked numbers for
---@return table Array of blocked phone numbers
local blockedNumbers = exports.yseries:GetBlockedNumbers(phoneImei)

for _, number in ipairs(blockedNumbers) do
    print("Blocked number: " .. number)
end

Returns:

lua
{
    "0882222",
    "0883333",
    "0884444"
}

AddContact

Adds a new contact to a player's phone. The contact will be automatically synced to the player's cached contacts if they are online, and a UI notification will be sent to update the state.

lua
---@class ContactData
---@field number string The contact's phone number
---@field name string The contact's full name

---@param phoneNumber string The phone number to add the contact to
---@param data ContactData The contact data
---@return boolean success Whether the contact was added successfully
local success = exports.yseries:AddContact("01234567890", {
    number = "09876543210",
    name = "John Doe"
})

if success then
    print("Contact added successfully")
else
    print("Failed to add contact")
end

Parameters:

phoneNumber (string) - The phone number of the player whose contact list the new contact will be added to
data (ContactData) - The contact data object:
- number (string, required) - The contact's phone number
- name (string, required) - The contact's full name

Behavior:

Stores the name field directly in the database
If the player is online, their cached contacts (PhoneData.Contacts) will be automatically updated
A UI notification will be sent to update the phone's UI state with the new contact
Returns true if the contact was added successfully, false otherwise

Validation:

Validates that phoneNumber is a valid string
Validates that data.number and data.name are provided
Checks if the phone IMEI exists for the given phone number
Returns false if any validation fails or if the database insert fails

Example:

lua
-- Add a contact with full name
exports.yseries:AddContact("01234567890", {
    number = "09876543210",
    name = "John Doe"
})

-- Add a contact with single name
exports.yseries:AddContact("01234567890", {
    number = "09876543210",
    name = "Jane"
})

AddRecentCall

Adds a call to the recent calls list. This export should be used server-side only for security reasons, as it's vulnerable to manipulation if exposed to clients.

lua
---@param toNumber string The phone number that was called
---@param phoneImei string The phone IMEI
---@param callType string Call type: "outgoing", "incoming", or "missed"
---@param anonymousCall boolean Whether the call was anonymous
---@return number|nil The insert ID of the recent call, or nil if failed
local insertId = exports.yseries:AddRecentCall("0882222", phoneImei, "outgoing", false)

if insertId then
    print("Recent call added with ID: " .. tostring(insertId))
else
    print("Failed to add recent call")
end

Parameters:

toNumber (string, required) - The phone number that was called
phoneImei (string, required) - The phone IMEI
callType (string, required) - Call type: "outgoing", "incoming", or "missed"
anonymousCall (boolean, optional) - Whether the call was anonymous (default: false)

Returns:

number|nil - The insert ID of the recent call if successful, or nil if failed