API Reference

Four surfaces: Lua exports server-side and client-side, a REST API, and a Socket.IO stream. The exports need nothing enabled; REST and Socket.IO need exposeWeb = true.

Server exports

Call these as exports['tRadio']:name(...), whatever you named the folder.

Channel information

local info = exports['tRadio']:getChannelInfo("154.755")
-- info = { speakers = {...}, listeners = {...}, activeTalkers = {...} }

getAllChannels returns one entry per channel:

{
    zoneId         = 1,            -- 1-based index into the configured zones
    zoneName       = "Statewide",
    channelId      = 1,            -- 1-based index within that zone
    name           = "C2C",
    frequency      = 856.1125,
    type           = "conventional" or "trunked",
    frequencyRange = { 856.0, 859.0 },  -- trunked channels only
    coverage       = 500.0,             -- nil where the channel sets none
}

zoneId and channelId are positions in the config, not the stable string IDs the admin panel stores — reordering a zone changes them.

Alerts and panic

setAlertOnChannel resolves its third argument as: omitted or nil → the first alert; a number → 1-based index; a string → case-insensitive name match. enabled = nil toggles.

exports['tRadio']:setAlertOnChannel("154.755", true)                -- first alert, activate
exports['tRadio']:setAlertOnChannel("154.755", true, "SIGNAL 100")  -- by name
exports['tRadio']:setAlertOnChannel("154.755", nil, 2)              -- toggle the second
exports['tRadio']:setChannelPanic("154.755", 5, true)

setChannelPanic is a remote emergency for CAD and MDT integrations. Where the codeplug programs an emergency profile for that channel, the profile's mode and Silent setting win over meta. An emergency raised this way never auto-clears.

In getChannelPanicMeta: mode is "alarm", "call" or "alarmCall"; phase is "alarm", "call", "acked" or "noAck"; source is "button", "manDown" or "export".

Users

connect, scan and gps are frequency arrays, zones is a 1-based index array, and dispatch is a boolean (supervisor privileges).

Codeplugs and subscribers

-- getSubscriberInfo
{
    codeplugId     = "leo",
    unitId         = "1041",
    nac            = "141",
    allowedModels  = { "QRX-720", "HLX-120" },
    defaultLayouts = { Handheld = "QRX-720", Vehicle = "HLX-120" },
    features       = { gps = true, scan = true, emergencyButton = true, manDown = false },
    tones          = { ... },
    emergency      = {
        activateHoldMs = 1000,
        profiles       = { { id = "default", name = "Default", mode = "alarmCall",
                             revert = "tactical", hotMicSeconds = 5 } },
        assignments    = { default = "default" },   -- "" = no emergency
        -- legacy fields (emergencyChannelId, autoTransmit, autoTransmitDuration,
        -- panicRepeatInterval) are still present, mirrored from the default profile
    },
    announcementVolume = 0.8,
}

A player on the same codeplug keeps the same P25 unit ID across sessions and restarts.

AI dispatcher

A status is whatever a unit said — there is no allow-list. setUnitStatus trims whitespace and drops trailing punctuation, so "10-8." and "10-8" are the same. Every change fires tradio:ai:unitStatusChanged(serverId, value) as a normal server event.

refreshAiDispatchTools is needed only if you change what Config.aiDispatchTools returns after startup.

Callsigns and audio

Callsign exports require Enable Callsigns in the admin panel.

Tone keys come from the tone catalog. Both tone exports return true as soon as the request is dispatched, so a typo returns true and plays nothing. Check the key against the catalog, not the return value.

Client exports

Radio control

Scan exports. A radio scans the scan list of the channel it is on (see Scanning), and these edit that list.

• addListeningChannel adds the channel (or restores a nuisance-deleted one) and turns scanning on. For a channel already scanned it does nothing, so it is safe to repeat. Nothing is added if the current channel has no scan list, or the frequency is the channel you are on
• removeListeningChannel removes the channel and never turns scanning off
• getListeningChannels is empty while scan is off, even with entries in the list

tradio:client:openRadio also fires as a client event when a player uses the radio item — handle it yourself only if Config.inventory.system = 'custom'.

Transmission and state

Volume, appearance and information

Alerts and panic

Web API

Requires Config.exposeWeb = true and confirmed publication through tLib. The public base is <your tLib URL>/dispatch; paths below are relative to it. Examples use http://203.0.113.10:7777/dispatch.

Authenticating

Protected endpoints need a per-session token obtained at runtime. This is not Config.authToken.

curl -X POST http://203.0.113.10:7777/dispatch/radio/dispatch/auth \
  -H "Content-Type: application/json" \
  -d '{"nacId": "4417", "callsign": "Dispatcher-01"}'

import requests

res = requests.post(
    "http://203.0.113.10:7777/dispatch/radio/dispatch/auth",
    json={"nacId": "4417", "callsign": "Dispatcher-01"},
).json()
auth_token, session_id = res["authToken"], res["sessionId"]

const res = await fetch("http://203.0.113.10:7777/dispatch/radio/dispatch/auth", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ nacId: "4417", callsign: "Dispatcher-01" }),
}).then((r) => r.json());
const { authToken, sessionId } = res;

{
  "success": true,
  "sessionId": "dispatch_abc123",
  "authToken": "550e8400-e29b-41d4-a716-446655440000"
}

Send both headers on every protected request:

Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000
x-session-id: dispatch_abc123

• nacId must match dispatchNacId in config.lua
• Sessions last 24 hours; at most 100 exist at once, oldest evicted first
• Authentication is rate-limited to 15 attempts per 15 minutes per IP
• With Discord auth enabled the same endpoint returns 202 and a redirectUri
• After a server restart, re-issue a session with POST /radio/dispatch/reauth, sending only the Authorization header

Endpoint prefixes

Endpoints

Public, no auth:

Status and config:

Broadcasts, tones and alerts:

Channels, units and patches:

SESSION_TOKEN="550e8400-e29b-41d4-a716-446655440000"
SESSION_ID="dispatch_abc123"

curl http://203.0.113.10:7777/dispatch/radio/dispatch/status \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "x-session-id: $SESSION_ID"

curl -X POST http://203.0.113.10:7777/dispatch/api/patch/create \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "x-session-id: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"label": "TAC1-FIRE", "frequencies": ["154.755", "460.25"]}'

import requests

headers = {"Authorization": f"Bearer {auth_token}", "x-session-id": session_id}

status = requests.get(
    "http://203.0.113.10:7777/dispatch/radio/dispatch/status", headers=headers
).json()

requests.post(
    "http://203.0.113.10:7777/dispatch/api/patch/create",
    headers=headers,
    json={"label": "TAC1-FIRE", "frequencies": ["154.755", "460.25"]},
)

Error responses

All errors are application/json.

Frequencies accept strings ("154.755") or numbers (154.755) everywhere. Dispatcher serverId values must be negative; in-game player IDs are positive. CORS is enabled for all origins.

Socket.IO

Connect to appear as a dispatcher and receive real-time events.

const res = await fetch("http://203.0.113.10:7777/dispatch/radio/dispatch/auth", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ nacId: "4417", callsign: "Bot-01" }),
}).then((r) => r.json());

const socket = io("http://203.0.113.10:7777", {
  path: "/dispatch/socket.io",
  auth: {
    authToken: res.authToken, // per-session UUID — not Config.authToken
    sessionId: res.sessionId,
    serverId: -(1000 + Math.floor(Math.random() * 10000)), // must be negative
  },
});

Emit — client to server

Listen — server to client

Transmitting voice

The ordering, pacing and size rules a client must keep to be heard. A client that breaks them is usually dropped silently — most of these limits have no refusal event.

Send heartbeat every 5 seconds for the whole session.

The voice payload

Each non-IMBE packet must be a complete, independently decodable container — a WebM/Opus chunk, not a slice of one continuous stream.

Pacing and limits

A receiving radio queues at most 0.5 seconds of audio per talker and discards from the front beyond that, with no event, so a whole reply sent in one burst is mostly thrown away before it plays. Send about 300 ms of audio every 300 ms.

A transmission ends on the receiving end 450 ms after its queue runs dry, or 600 ms for encoding: "imbe". A longer gap splits one transmission into two for every listener.

setTalking with state: false and heartbeat are exempt from the control-event limit, so an unkey is never throttled.

Events you must handle

Five things get dropped silently: voice sent without a granted setTalking(true); voice sent after a force-stop; a packet over the size cap; a burst over 100/second; and a setSpeakerChannel changed mid-transmission, which clears your talk state. Unkey before you retune.

A minimal send loop

const CHUNK_MS = 300;
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

// `chunks` is an array of base64 WebM/Opus containers, each ~300 ms of audio,
// each independently decodable.
async function transmit(socket, frequency, chunks) {
  let halted = null;
  const onDenied = (d) => { halted = d; };
  const onForced = () => { halted = { reason: "forced-stop" }; };
  socket.on("ptt:denied", onDenied);
  socket.on("radio:forcedStopTalking", onForced);

  try {
    socket.emit("setTalking", { state: true, frequency });
    await sleep(50); // let a denial land before the first packet
    if (halted) return halted;

    const started = Date.now();
    for (let i = 0; i < chunks.length; i++) {
      if (halted) break;
      socket.emit("voice", { data: chunks[i], encoding: "opus", frequency });
      // Pace to real time. Never run ahead of the audio you are sending —
      // the receiver only queues 0.5 s and drops the oldest beyond that.
      await sleep(Math.max(0, started + (i + 1) * CHUNK_MS - Date.now()));
    }
  } finally {
    socket.emit("setTalking", { state: false, frequency });
    socket.off("ptt:denied", onDenied);
    socket.off("radio:forcedStopTalking", onForced);
  }
  return halted;
}

The finally block matters: an unkey that never goes out leaves the channel held until the liveness sweep clears it, and half-duplex blocks every other unit on that channel meanwhile.

Next steps

• Restyling or replacing the dispatch panel: Dispatch panel theming
• Config keys and admin-panel settings: Configuration
• Something not behaving: Troubleshooting