Server Events
The phone announces its lifecycle moments as plain server-local events. Listen with a standard handler:
AddEventHandler('sd-phone:server:messages:sent', function(message)
-- react to the send
end)All events fire via TriggerEvent, which is synchronous: handlers run inline inside the phone's own action, so keep them cheap and never let them error. Payloads carry citizenids where noted; they are for trusted server resources and must not be forwarded to clients unfiltered.
Phone Numbers
sd-phone:server:number:assigned
Fires exactly once per character, when their phone number is first minted.
AddEventHandler('sd-phone:server:number:assigned', function(citizenid, number)
print(citizenid .. ' was assigned ' .. number)
end)| Parameter | Type | Description |
|---|---|---|
citizenid | string | The character the number was minted for |
number | string | The raw-digit number |
INFO
No source argument: minting can happen with the owner offline (the getPhoneNumberByIdentifier export with ensure = true). Resolve a server id yourself when you need one, and expect nil.
Messages
sd-phone:server:messages:sent
Fires once per logical SMS send, on all three delivery paths: a player's 1:1 send, a player's group send, and a system text.
AddEventHandler('sd-phone:server:messages:sent', function(m)
if not m.system and not m.group then
print(m.senderNumber .. ' texted ' .. m.targetNumber)
end
end)| Parameter | Type | Description |
|---|---|---|
system | boolean | true for sendSystemMessage-style service texts |
group | boolean | true for group-thread sends |
source | number|nil | Sending player's server id (absent on system texts) |
citizenid | string|nil | Sending character (absent on system texts) |
senderNumber | string | Sending number |
senderName | string|nil | Display name (system texts only) |
targetNumber | string|nil | Recipient number (1:1 and system) |
targetCitizenid | string|nil | Recipient character, nil when the number is not in service |
targetSource | number|nil | Recipient's server id when online and delivered live |
groupId | number|nil | Group thread id (group sends) |
members | table|nil | Group roster of { citizenid, number, name } (group sends); treat as read-only |
kind | string | Message kind (text, image, gif, location, ...) |
body | string | Message text |
meta | table|nil | Sanitized kind metadata |
mid | string | Shared logical id correlating the per-mailbox copies |
messageId | number | Stored row id (sender copy for player sends, recipient copy for system texts) |
recipientId | number|nil | Recipient copy row id, nil when no copy was stored |
withheld | boolean|nil | true when airplane mode is holding the delivery |
timestamp | number | Unix seconds |
INFO
On a 1:1 send, targetCitizenid can be set while recipientId and targetSource are nil: the number is in service but the sender is blocked, and the block is deliberately indistinguishable from offline.
Mail
sd-phone:server:mail:sent
Fires once per mail send, both player composes and system mail.
AddEventHandler('sd-phone:server:mail:sent', function(mail)
print(('%s mailed %d recipient(s): %s'):format(mail.from.email, #mail.to, mail.subject))
end)| Parameter | Type | Description |
|---|---|---|
system | boolean | true for sendMail-style system senders |
id | string|nil | Stored message id (absent on a system send that reached nobody) |
citizenid | string|nil | Sending character (player composes only) |
from | table | { name, email } |
to | string[] | Normalized recipient addresses |
subject | string | Subject line |
body | string | Body text |
sentAt | number | Unix seconds |
delivered | number|nil | Recipient accounts that existed (system sends only) |
Calls
All call events share one call table:
| Field | Type | Description |
|---|---|---|
channel | number | The pma-voice call channel, doubling as the call id |
company | string|nil | Display name for company/group rings, nil for 1:1 calls |
caller | table | { source, citizenid, name, number } |
callee | table|nil | Same shape; nil on group rings before an answer |
targets | table|nil | Group rings only: everyone rung, same party shape |
sd-phone:server:call:started
Fires when a 1:1 call starts ringing, and once per company/group ring (with targets populated and callee nil).
AddEventHandler('sd-phone:server:call:started', function(call)
print(call.caller.number .. ' is calling ' .. (call.callee and call.callee.number or call.company))
end)sd-phone:server:call:answered
Fires when a call is answered, including a group ring being promoted to a live call (the answering employee becomes callee; company keeps the display name). The payload adds startedAt (unix seconds at answer).
sd-phone:server:call:ended
Fires on every teardown, answered or not, with endedBy as a second argument.
AddEventHandler('sd-phone:server:call:ended', function(call, endedBy)
if call.answered then
print(('call on channel %d lasted %ds'):format(call.channel, call.duration))
end
end)Extra payload fields on this event:
| Field | Type | Description |
|---|---|---|
answered | boolean | Whether the call was ever active |
duration | number | Seconds, 0 when never answered |
reason | string | 'declined', 'hangup', 'disconnected', or 'unavailable' |
| Parameter | Type | Description |
|---|---|---|
call | table | The call table above |
endedBy | number|nil | Server id that caused the teardown, nil on disconnects |
INFO
Cancelled group rings that nobody answered also fire this event (answered = false, callee = nil), so a dispatch script can observe missed company calls. Payloads are built from stored session state, so a disconnecting player still appears with the data they rang with.
Services
sd-phone:server:services:message
Fires when a citizen messages a company through the Services app (or the messageCompany export).
AddEventHandler('sd-phone:server:services:message', function(e)
if e.job == 'police' then
print(('911 text from %s (%s): %s'):format(e.name, e.number, e.body))
end
end)| Parameter | Type | Description |
|---|---|---|
source | number | Sending player's server id |
citizenid | string | Sending character |
job | string | Company job name |
label | string | Company display label |
number | string | Sender's phone number |
name | string | Sender's display name |
kind | string | Composer kind |
body | string | Message text |
meta | table|nil | Kind metadata |
Banking
sd-phone:server:banking:transaction
Fires when an externally-logged Wallet row is appended (the addBankTransaction export or the internal event that backs it).
| Parameter | Type | Description |
|---|---|---|
citizenid | string | Row owner |
source | number|nil | Owner's server id when online |
amount | number | Signed amount, positive = money in |
label | string | Row label |
category | string|nil | Category tag |
counterparty | string|nil | Who the money moved to or from |
timestamp | number | Unix seconds |
sd-phone:server:banking:transfer
Fires once per player-to-player Wallet transfer made in the phone.
| Parameter | Type | Description |
|---|---|---|
fromCitizenid | string | Sender |
fromNumber | string | Sender's number |
fromSource | number | Sender's server id |
toCitizenid | string | Recipient |
toNumber | string | Recipient's number |
toSource | number|nil | Recipient's server id when online |
amount | number | Amount moved |
note | string|nil | Transfer note |
timestamp | number | Unix seconds |
Photos
sd-phone:server:photos:added
Fires when a photo lands in a gallery, on every add path: camera captures, saved URLs, and the addPhoto export.
| Parameter | Type | Description |
|---|---|---|
source | number | Owner's server id |
citizenid | string | Owner |
id | number | Gallery row id |
url | string | Hosted media URL |
sd-phone:server:photos:deleted
Fires when a player deletes media from their own gallery. Retention pruning and admin wipes bypass it deliberately.
| Parameter | Type | Description |
|---|---|---|
source | number | Owner's server id |
citizenid | string | Owner |
id | number | Deleted row id |
url | string | The deleted media URL |
Social
sd-phone:server:birdy:post
Fires when a new Birdy post is created.
| Parameter | Type | Description |
|---|---|---|
id | number | Post id |
source | number | Author's server id |
citizenid | string | Author |
username | string | Author's handle |
displayName | string | Author's display name |
body | string | Post text |
images | string[]|nil | Attached image URLs, nil for text-only posts |
sd-phone:server:photogram:post
Fires when a new Photogram post is created.
| Parameter | Type | Description |
|---|---|---|
id | number | Post id |
source | number | Author's server id |
citizenid | string | Author |
username | string | Author's handle |
images | string[] | Post media URLs |
caption | string | Caption (may be empty) |
location | string|nil | Location tag |
private | boolean | Whether the author's account is private |
INFO
Private authors' posts are scoped to approved followers inside the app. This payload is server-local and trusted; never forward it to clients unfiltered.
Classifieds
sd-phone:server:pages:post
Fires when a new Pages listing is posted. Payload fields come from the stored row: { id, source, citizenid, number, title, body, price, image, images } (images is the stored JSON string).
sd-phone:server:marketplace:post
Fires when a new Marketplace listing is posted. Same shape as the Pages event.
Contacts
sd-phone:server:contacts:added
Fires when a contact lands in a player's phone book, from the app, the addContact export, or an accepted AirShare.
| Parameter | Type | Description |
|---|---|---|
source | number | Owner's server id |
citizenid | string | Owner |
id | number | Contact row id |
name | string | Contact name |
phone | string | Contact number, digit-normalized |
shared | boolean | true when it arrived via AirShare |
sd-phone:server:contacts:removed
Fires when contacts are removed, from the app delete or the removeContactByNumber export.
| Parameter | Type | Description |
|---|---|---|
source | number | Owner's server id |
citizenid | string | Owner |
id | number|nil | Row id (app deletes) |
phone | string | Removed number, digit-normalized |
removed | number | Rows removed |
Wi-Fi
sd-phone:server:wifi:connected
Fires when a player joins a Wi-Fi network, once the join has been recorded. The password has already been checked and the server has already placed the player inside the network's radius, so this is a connection that genuinely happened.
AddEventHandler('sd-phone:server:wifi:connected', function(source, networkId)
if networkId == 'mazebank' then
print(GetPlayerName(source) .. ' is on the bank router')
end
end)| Parameter | Type | Description |
|---|---|---|
source | number | The player's server id |
networkId | string | Network id from configs/wifi.lua |
sd-phone:server:wifi:disconnected
Fires when a connection ends, once per ending.
| Parameter | Type | Description |
|---|---|---|
source | number | The player's server id |
networkId | string | The network they were on, read before the connection was cleared |
Every path that ends a connection fires it: an explicit disconnect, walking out of range, the network being edited out of the config under a live connection, and the player dropping from the server. A listener gating a door or a terminal on a network has to hear the ending rather than merely stop being told about the id, so none of those four is allowed to end a connection silently.
Bluetooth
A device's own onConnect and onDisconnect callbacks only reach the resource that registered it. These events are how everything else watches: a logging script, an admin tool, or a resource that cares whether a player has any audio device at all without owning one.
sd-phone:server:bluetooth:connected
Fires when a player connects to a device, after the owning script's onConnect has run, so a listener always sees a settled connection.
AddEventHandler('sd-phone:server:bluetooth:connected', function(source, deviceId, device)
print(('%s connected to %s (%s)'):format(GetPlayerName(source), device.name, device.owner))
end)| Parameter | Type | Description |
|---|---|---|
source | number | The player's server id |
deviceId | string | Device id as its owning resource registered it |
device | table | { id, name, kind, owner }, identity only |
Both the pairing a player taps in Settings and the reconnect sweep that picks a device back up when they walk into range come through here. There is no separate "paired" event, because pairing always ends in a connection.
sd-phone:server:bluetooth:disconnected
Fires when a connection ends, once per ending.
AddEventHandler('sd-phone:server:bluetooth:disconnected', function(source, deviceId, reason)
if reason == 'range' then
print(GetPlayerName(source) .. ' walked away from ' .. deviceId)
end
end)| Parameter | Type | Description |
|---|---|---|
source | number | The player's server id |
deviceId | string | The device they were on, read before the connection was cleared |
reason | string | Why it ended, from the table below |
| Reason | Meaning |
|---|---|
manual | The player disconnected or forgot the device in Settings |
range | They walked out of the device's reach |
disabled | They switched their Bluetooth radio off |
dropped | They left the server |
unregistered | The device was removed, or the resource owning it stopped |
kicked | A script called disconnectBluetooth |
Every path that ends a connection fires it, including the two that no client ever reports: the owning resource stopping, and the player dropping. A listener holding state against a connection has to hear the ending rather than merely stop being told about it, so none of the six is allowed to end a connection silently.
Cell service
sd-phone:server:service:lost
Fires when a player loses cell service.
| Parameter | Type | Description |
|---|---|---|
source | number | The player's server id |
INFO
A client only reports which edge it crossed. The level is re-derived from the server's own coords before anything fires, so a forged report cannot announce a loss that did not happen. A repeat loss announces nothing.
sd-phone:server:service:regained
Fires when a player comes back into coverage.
| Parameter | Type | Description |
|---|---|---|
source | number | The player's server id |
Pre-existing rather than new: this is the event that drains texts withheld while the player was out of coverage.
Settings
sd-phone:server✈️released
Fires when a player switches airplane mode off, releasing withheld messages.
| Parameter | Type | Description |
|---|---|---|
source | number | The player's server id |
sd-phone:server:documents:created
Fires once per document created through the Documents exports — player-created documents do not fire it.
AddEventHandler('sd-phone:server:documents:created', function(data)
print(('%s issued "%s" (%s) as %s'):format(data.resource or '?', data.name, data.kind, data.docId))
end)| Field | Type | Description |
|---|---|---|
citizenid | string | The owning identity (the acting phone profile under unique phones) |
docId | string | The new document's id |
name | string | Document display name |
kind | string | 'text', 'image', or 'file' |
resource | string? | The resource that invoked the export |
TIP
Client-local events (phone opened, camera mode, flashlight) live on the Client Events page. Third-party scripts written against lb-phone's events keep working through the lb-phone compatibility layer.