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 has error.
  • A call from a resource that is not on AllowedResources, or while Enabled is false, returns ok = 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.MaxSubject and MaxBody.
  • Delivery runs in the background every 10 seconds while players are online, BroadcastBatchSize mailboxes 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)
  • address is 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)
  • mailboxId must match the mailbox that has address now, so a changed mailbox is never touched by mistake.
  • newAddress must be free, may not start with PB-, may not be one of Config.Telegram.ReservedAddresses or SenderAddress, 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')
  • refund is in dollars (RefundPercent of the address fee). reopenAt is 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