Server exports
Telegram administration
Server exports and console commands for a government or admin resource: official telegrams to every mailbox, reading a mailbox, changing an address and closing a mailbox.
These exports are for a trusted server resource, such as a government or admin script. No client event can reach them. They are in apps/telegram/server/administration.lua.
#Settings
apps/telegram/config_server.lua > PocketServerConfig.Apps.telegram.Administration:
| Key | Default | What it does |
|---|---|---|
Enabled |
true |
Administration exports and commands on or off |
AllowedResources |
{} |
Resources that may call the exports, for example { ['my-government'] = true }. Empty: none. |
SenderAddress |
'SYSTEM' |
Address official telegrams come from |
SenderName |
'Resmî Telgraf Dairesi' |
Sender name on official telegrams |
MaxActiveBroadcasts |
3 |
Official telegrams that may be waiting at the same time |
MaxBroadcastRecipients |
10000 |
An official telegram is refused when there are more mailboxes than this |
BroadcastBatchSize |
25 |
Mailboxes filled per pass (1 to 100) |
ForcedClosure |
{ Enabled = true, RefundPercent = 0, CooldownSeconds = 86400 } |
Closing a mailbox: on or off, the part of the address fee paid back, and how long before the player may open one again |
BroadcastTemplates |
{} |
The official telegrams that may be sent, by key: ['notice'] = { subject = '...', body = '...' } |
- Every export returns a table with
ok. On failure it haserror. - A call from a resource that is not on
AllowedResources, or whileEnabledisfalse, returnsok = false. - Every call is written to the server log with the calling resource.
- Only one administration operation runs at a time. A second call meanwhile returns
ok = false; try again. - Operations that take a
nonce(16 to 64 letters, numbers or-) return the first result again for the same nonce.
#SendGovernmentTelegram
Queues an official telegram from a template to every personal and company mailbox that has an address.
lua---@param templateKey string key in BroadcastTemplates
---@param nonce string
---@return table result { ok, id, state, recipients } or { ok, id, state, queued, skipped, duplicate = true }
exports['fx-pocketbook']:SendGovernmentTelegram(templateKey, nonce)
lua-- config_server.lua: BroadcastTemplates = { tax = { subject = 'Land tax', body = 'Land tax is due on Friday.' } }
local result = exports['fx-pocketbook']:SendGovernmentTelegram('tax', 'tax-notice-1899-05-01')
- The subject and body must fit
Config.Telegram.MaxSubjectandMaxBody. - Delivery runs in the background every 10 seconds while players are online,
BroadcastBatchSizemailboxes per pass. A full mailbox is skipped and counted.
#GetGovernmentTelegramStatus
lua---@param id integer
---@return table result { ok, broadcast }
exports['fx-pocketbook']:GetGovernmentTelegramStatus(id)
lualocal status = exports['fx-pocketbook']:GetGovernmentTelegramStatus(4)
print(status.broadcast.state, status.broadcast.queued_count)
broadcast has id, state ('queued', 'completed' or 'cancelled'), template_key, queued_count, skipped_count, cursor_id, max_recipient_id, created_at and completed_at.
#CancelGovernmentTelegram
Stops the rest of an official telegram that is still queued. Telegrams already delivered stay.
lua---@param id integer
---@return table result { ok }
exports['fx-pocketbook']:CancelGovernmentTelegram(id)
luaexports['fx-pocketbook']:CancelGovernmentTelegram(4)
#InspectTelegramMailbox
Returns a mailbox and its telegrams, sent and received, 25 per page, newest first.
lua---@param address string
---@param page? integer default 1
---@return table result { ok, mailbox, messages, page }
exports['fx-pocketbook']:InspectTelegramMailbox(address, page)
lualocal result = exports['fx-pocketbook']:InspectTelegramMailbox('JMARSTON', 1)
addressis not case sensitive.
#ReassignTelegramAddress
Gives a personal mailbox a new address.
lua---@param address string current address
---@param newAddress string
---@param mailboxId integer the mailbox id, from InspectTelegramMailbox
---@return table result { ok, id, address }
exports['fx-pocketbook']:ReassignTelegramAddress(address, newAddress, mailboxId)
luaexports['fx-pocketbook']:ReassignTelegramAddress('JMARSTON', 'JOHNM', 118)
mailboxIdmust match the mailbox that hasaddressnow, so a changed mailbox is never touched by mistake.newAddressmust be free, may not start withPB-, may not be one ofConfig.Telegram.ReservedAddressesorSenderAddress, and may not be reserved for a company mailbox.- Company and system mailboxes cannot be changed.
#ForceCloseTelegramMailbox
Closes a personal mailbox. Its telegrams are kept. Needs ForcedClosure.Enabled = true.
lua---@param address string
---@param mailboxId integer
---@param nonce string
---@param reason string 8 to 240 characters
---@return table result { ok, closed, duplicate, refund, reopenAt }
exports['fx-pocketbook']:ForceCloseTelegramMailbox(address, mailboxId, nonce, reason)
luaexports['fx-pocketbook']:ForceCloseTelegramMailbox('JMARSTON', 118, 'close-118-1899-05-01', 'Court order 14/1899')
refundis in dollars (RefundPercentof the address fee).reopenAtis the unix time the player may open a mailbox again.- It works when the player is offline.
- It is refused while the player has a money operation waiting for review or a registration waiting.
#Console commands
The same operations are available as restricted commands, for the server console or players with the ACE permission command.<name>:
| Command | Arguments |
|---|---|
pocketbook_broadcast |
<template> <nonce> |
pocketbook_broadcast_status |
<id> |
pocketbook_broadcast_cancel |
<id> |
pocketbook_close_mailbox |
<address> <mailboxId> <nonce> <reason...> |
pocketbook_broadcast tax tax-notice-1899-05-01