MCPTT developer package

This folder is for developers who build software that talks to MCPTT: dispatcher consoles, CAD links, mapping, logging and reporting tools. Start here, then read the guide for what you are building.

README.md (this file): the system in one page, which interface to use, hostnames, access, glossary.
dispatcher-guide.md: building a dispatcher console (voice, floor, emergencies, calls, locations, monitoring, recordings).
events-websocket.md: the real-time event stream (who is talking, locations, presence, battery, signal, emergencies, monitoring) and its commands.
management-rest.md: the management REST API (orgs, callsigns, devices, talkgroups, memberships, remote monitoring).
openapi/management-v1.yaml: the OpenAPI 3.1 contract of the management REST API.
echocad-integration.md: moving a CAD (EchoCAD) from a WalkieFleet WebSocket client to the event stream: setup per agency, both sites, message and field mapping, gaps, adapter outline, acceptance tests.

These documents describe what the servers do today. Anything not described is not offered. Statements marked "unverified" could not be confirmed and may change.

1. The system in one page

MCPTT is a push-to-talk system for public safety. Radios and phones talk on talkgroups; the server forwards voice and never mixes or transcodes it.

Sites. Production runs two active sites, loc1 and loc2. Each site terminates radio connections, decides who may talk, forwards voice, records, stores locations, serves the admin portal and the management API, and hosts an event stream. The two sites are joined, so a radio at one site hears a talker at the other.
Clients. Android radios and Android and iOS phone apps. Each client keeps a connection to both sites at once, so losing one site causes no audible gap.
Dispatcher console. Not offered yet. The dispatcher guide says what a console can build on today.
Admin portal. Web pages on each site (https://loc1.server.mcptt.com, https://loc2.server.mcptt.com) for system and agency admins: users, devices, talkgroups, transmissions, map, event stream tokens, release notes.

The three integration surfaces

Surface	Transport	What it is for	State today
Client protocol (voice)	QUIC, TLS 1.3, one connection per client per site	Talking and listening: floor request, grant and release, audio, emergencies, private calls, call alerts, messaging	Running in production for radios and phones; used through the MCPTT client SDK
Event stream	WebSocket, JSON, `wss://events.loc<N>.server.mcptt.com/v1/stream`	Watching the system live: who is talking, locations, presence, battery, signal, emergencies, monitoring sessions. Commands: clear an emergency, request a location, send a call alert, start, stop and watch remote monitoring	Running at both sites
Management REST API	HTTPS, JSON, OAuth 2.0 client credentials, `https://loc<N>.server.mcptt.com/api/v1`	Reading and changing configuration: orgs, callsigns, persons, devices, talkgroups, memberships; starting, watching and stopping remote monitoring	Running at both sites; recordings, location history and webhooks are planned, not served

Which surface to use

You want to	Use
Talk or listen on a talkgroup, make a private call, send a call alert from a voice client	Client protocol, through the client SDK
Show who is talking on every talkgroup	Event stream, `floor.granted` / `floor.idle`
Show units on a map	Event stream, `location.position` (needs `events:location` and `locations:read`)
Ask a unit for its position now	Event stream command `location.request`
Show battery, accessory, signal	Event stream, `presence.*`, `network.signal`
See and clear emergencies	Event stream, `emergency.*` events and the `emergency.clear` command
Send a call alert from a console or CAD	Event stream command `call_alert.send`
Watch and listen to a radio remotely	Management REST API, `/monitoring/sessions` (or the event stream's monitoring commands), then the viewer WebSocket or the shareable viewer page
Create users, devices, talkgroups, memberships	Management REST API
Feed a CAD or logging system	Event stream (webhooks are planned, not offered)
Play or download a recording	The admin portal, or a client SDK session. Recording endpoints in the REST API are planned, not served

2. Hostnames

Name	Use
`loc1.server.mcptt.com`	Site 1: admin portal, management API (`/api/v1`, `/oauth/token`), voice client listener
`loc2.server.mcptt.com`	Site 2: same as site 1
`events.loc1.server.mcptt.com`, `events.loc2.server.mcptt.com`	Event stream per site (`/v1/stream`), TLS 1.3 only
`monitor.loc1.server.mcptt.com`, `monitor.loc2.server.mcptt.com`	Remote monitoring viewer socket and viewer page per site; you get these URLs from the API, do not build them

There is no public sandbox. Ask the operator for a test agency. Event numbering is per site: a client that moves between events.loc1 and events.loc2 must resync (see the event stream guide, section 4.4).

3. Getting access

Access is granted by an admin of your agency or by the system operator. No credentials are published in this package.

Event stream: an agency admin creates an event token in the admin portal of each site you connect to. Tokens are per site, expire after 7, 30 or 90 days (30 at most with locations:read), and carry scopes such as events:floor, events:presence, events:network, events:location, locations:read. Details: events-websocket.md, section 2.3.
Management API: an agency administrator or the operator creates an API client and gives you its client id and secret. You exchange them at /oauth/token for a bearer token with the scopes you need (15 minutes by default). Details: management-rest.md.
Voice (client protocol): a voice client is a device in the agency's inventory with a callsign. Today that means a device record plus an enrolled device key, and a callsign sign-in. Human console sign-in with OIDC and MFA is not offered yet. See the dispatcher guide, section 6.

Recordings, transcripts, locations and monitoring are criminal justice information (CJI). Every access is audited, and you must not log their content.

4. Glossary

Term	Meaning
Tenant, agency, org	The customer organisation that owns users, devices and talkgroups. The API says org and the event stream says tenant; people say agency. Each has an agency number.
Talkgroup, channel	A group voice channel. "Channel" is the radio user's word: a radio's channel list is the talkgroups it may use. Talkgroups have a number within the agency, shown as `1001-2` across agencies.
Callsign	The functional identity that talks, such as "Engine 5", with an optional unit number. A person signs in to a callsign; the callsign, not the device, holds the floor and the emergency. The event stream calls its id `alias_id`.
Person	A human, who may hold a callsign and sign in on shared radios.
UE, device	User equipment: one radio, phone or console instance. A callsign can be on several devices at once.
Burst, transmission	One press of PTT: from grant to release. Identified by `transmission_id` (a UUIDv7). Recordings, transcripts and the transmission log are per burst.
Floor	The right to talk on a talkgroup or in a private call. The site grants it to one talker at a time, queues or denies others, and tells everyone who is talking.
Site, home	A site is one server location. A client's homes are the two sites it is connected to.
Emergency	A state of a callsign (SOS, man-down, duress and others), raised from a device and cleared by a dispatcher, an admin or the user.
Private call	A one-to-one half-duplex call to a callsign, unconfirmed by default.
Call alert	A page to a callsign: "call me back", optional short text, live only.
Remote monitoring	Listening to, and optionally watching through the camera of, a radio without its user pressing PTT. Started for a reason, audited, and recorded.