API Reference

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

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 second alert
exports['tRadio']:setChannelPanic("154.755", 5, true)

local ok = exports['tRadio']:setUserChannel(5, "460.125")
exports['tRadio']:disconnectUser(5)

local perms = exports['tRadio']:getAcePermissions(5)
-- { connect = true, scan = true, gps = false, zones = true, dispatch = false }

{
    codeplugId         = "leo",
    unitId             = "141",
    nac                = 0x293,
    radioModel         = "APX8000",
    features           = { ... },
    tones              = { ... },
    emergency          = { ... },
    announcementVolume = 0.8,
}

exports['tRadio']:setCallsign(5, "L-141")
local cs = exports['tRadio']:getCallsign(5)  -- "L-141"

exports['tRadio']:playToneOnChannel("154.755", "ALERT")
exports['tRadio']:playToneOnSource(5, "BEEP")

exports['tRadio']:openRadio()          -- open with NUI focus
exports['tRadio']:openRadio(false)     -- open without focus
local ok = exports['tRadio']:connectToFrequency("154.755")

exports['tRadio']:startTransmitting()
local talker = exports['tRadio']:getActiveTalker()
-- { serverId = 5, name = "John Smith", frequency = "154.755" }

exports['tRadio']:setVolume(0.75)
exports['tRadio']:playTone("ALERT")
exports['tRadio']:NotifySirenChanged()

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

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

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

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

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

# Create patch
curl -X POST http://192.0.2.100:7777/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.125"]}'

# Play tone
curl -X POST http://192.0.2.100:7777/radio/dispatch/tone \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "x-session-id: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"frequency": "154.755", "tone": "ALERT"}'

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

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

const s = dispatch.getState();

{
  id: string, name: string,
  channels: [{
    id: string, frequency: string, name: string,
    type: string,           // "conventional" | "trunked" | "digital"
    canTransmit: boolean,
    listeners: number,
    users: [{
      id: string, name: string,
      nacId: string | null, unitId: string | null,
      transmitting: boolean, panic: boolean
    }]
  }]
}

{
  callsign: string,
  voiceVolume: number,   // 0–1
  sfxVolume: number,     // 0–1
  globalPTT: { pttKey, pttType, pttMouseButton },
  channelPTT: { [frequency]: PTTSettings },
  announcementGroupPTT: { [groupId]: PTTSettings }
}

dispatch.on('dispatch:zones', ({ zones }) => render(zones));

// Unsubscribe
const handler = ({ active }) => { /* ... */ };
dispatch.on('dispatch:ptt', handler);
onUnmount(() => dispatch.off('dispatch:ptt', handler));

dispatch.joinChannel('460.0625')
dispatch.leaveChannel()
dispatch.addScan('154.755')
dispatch.removeScan('154.755')

dispatch.startPTT()                    // global PTT — requires microphone + active channel
dispatch.stopPTT()
dispatch.startChannelPTT('460.0625')   // per-channel PTT
dispatch.stopChannelPTT()

dispatch.activateAnnouncementGroup('group-id')  // arm
dispatch.activateAnnouncementGroup(null)         // disarm

dispatch.triggerAlert('460.0625', 'SIGNAL 100')

dispatch.sendBroadcastAlert({
  frequency: '460.0625',
  type: 'Priority Alert',   // "General Alert" | "Information Alert" | "Priority Alert" | "Emergency Alert"
  message: 'All units respond to 123 Main St',
  tone: 'PRIORITY'
})

dispatch.acknowledgePanic(serverId, unitId)  // unitId optional

const patchId = await dispatch.createPatch(['460.0625', '154.755'])
await dispatch.removePatch(patchId)

dispatch.updateSettings({ voiceVolume: 0.8 })
dispatch.updateSettings({ callsign: 'DISP-1' })
dispatch.openSettings()
dispatch.closeSettings()

// All return Promise<boolean>
dispatch.kickUser(serverId)
dispatch.alertUser(serverId, 'Message text', frequency)
dispatch.setUserCallsign(serverId, 'UNIT-5')
dispatch.switchUserChannel(serverId, '462.000', '460.000')  // (id, newFreq, oldFreq)

theme.setVar('--accent-raw', '#ff6600')   // set a CSS variable on <html>
theme.removeVar('--accent-raw')

// Adds "tj-ptt-active" to <html> (auto-prefixed)
theme.addClass('ptt-active')
theme.removeClass('ptt-active')

theme.hideDefaultUI()    // hides Header, ZoneList, and announcement bar
theme.showDefaultUI()    // restores them

// Persistent <div> inside .dispatch-app — mount custom HTML here
const root = theme.getContainer()

theme.hideDefaultUI();
const root = theme.getContainer();
root.style.cssText = 'flex:1;overflow:auto;display:flex;flex-direction:column';

function renderChannel(c, activeFreq) {
  const panicking = c.users.filter(u => u.panic).length;
  const active = c.frequency === activeFreq;
  return `
    <div data-freq="${c.frequency}" style="
      padding:10px 14px; border-bottom:1px solid var(--border); cursor:pointer;
      background:${active ? 'var(--my-dispatch-bg)' : 'transparent'};
      border-left:3px solid ${active ? 'var(--accent-raw)' : 'transparent'}">
      <div style="display:flex;align-items:center;gap:8px">
        <span style="font-weight:600;color:var(--text-primary)">${c.name}</span>
        <span style="font-size:11px;color:var(--text-secondary)">${c.frequency}</span>
        ${panicking ? `<span style="color:var(--danger);font-size:11px;font-weight:700">⚠ PANIC</span>` : ''}
        ${c.users.some(u=>u.transmitting) ? `<span style="color:var(--accent-raw);font-size:11px">● TX</span>` : ''}
      </div>
      <div style="font-size:11px;color:var(--text-secondary);margin-top:2px">
        ${c.users.map(u =>
          `<span style="color:${u.transmitting ? 'var(--accent-raw)' : u.panic ? 'var(--danger)' : 'var(--text-secondary)'}">${u.name}</span>`
        ).join(', ') || 'No users'}
      </div>
    </div>`;
}

function render() {
  const s = dispatch.getState();
  const channels = s.zones.flatMap(z => z.channels);
  root.innerHTML = `
    <div style="padding:10px 14px;border-bottom:1px solid var(--border);
                display:flex;align-items:center;gap:12px;background:var(--bg-secondary)">
      <span style="font-weight:700;color:var(--text-primary)">${s.serverName || 'Dispatch'}</span>
      <span style="font-size:11px;color:${s.connected ? 'var(--success)' : 'var(--danger)'}">● ${s.health}</span>
      <span style="font-size:11px;color:var(--text-secondary);margin-left:auto">${s.callsign}</span>
    </div>
    <div style="flex:1;overflow-y:auto">
      ${channels.map(c => renderChannel(c, s.channel)).join('')}
    </div>
    <div style="padding:10px 14px;border-top:1px solid var(--border);
                display:flex;gap:8px;background:var(--bg-secondary)">
      <button id="ptt-btn" style="flex:1;padding:8px;border-radius:6px;border:none;cursor:pointer;
        font-weight:700;color:var(--text-primary);
        background:${s.pttActive ? 'var(--accent-raw)' : 'var(--bg-hover)'}">
        ${s.pttActive ? '● TRANSMITTING' : 'PTT'}
      </button>
      <button onclick="dispatch.openSettings()" style="padding:8px 12px;border-radius:6px;
        border:1px solid var(--border);background:transparent;color:var(--text-secondary);cursor:pointer">⚙</button>
    </div>`;

  root.querySelectorAll('[data-freq]').forEach(el => {
    el.onclick = () => dispatch.joinChannel(el.dataset.freq);
  });

  const pttBtn = root.querySelector('#ptt-btn');
  if (pttBtn) {
    pttBtn.onmousedown = () => dispatch.startPTT();
    pttBtn.onmouseup   = () => dispatch.stopPTT();
    pttBtn.onmouseleave = () => dispatch.stopPTT();
  }
}

dispatch.on('dispatch:zones', render);
dispatch.on('dispatch:channel', render);
dispatch.on('dispatch:ptt', render);
dispatch.on('dispatch:connection', render);
dispatch.on('dispatch:callsign', render);