Oracle Radio WebSocket API

Get the active Public Safety and Security instance's serviceEndpoint from the instance details. To construct its Radio WebSocket URL, change the scheme from https to wss, retain the same hostname and any explicitly supplied port, and replace the /api/ path with /ws/radio.

The WebSocket path starts at the managed instance origin. It is /ws/radio, not /api/ws/radio or /api/v1/ws/radio. Use the hostname supplied by Public Safety and Security; don't construct a hostname from a region, realm, or instance OCID, and don't add a port.

For a registered Radio mobile application, radioBaseUrl in the registration descriptor is already the managed origin. Change https to wss and set the path to /ws/radio.

This JavaScript example derives the URL from the actual serviceEndpoint value returned for the instance. URL parsing retains the supplied hostname and effective port.

const serviceUrl = new URL(serviceEndpoint);
const webSocketUrl = new URL("/ws/radio", serviceUrl);
webSocketUrl.protocol = "wss:";
// Pass webSocketUrl.href to the supported client's WebSocket connection API.

To use the registration descriptor instead, initialize serviceUrl with new URL(radioBaseUrl). URL construction doesn't authenticate the connection. Continue with the connection example for mobile authentication and the first request and response messages.

Use the WebSocket URL for the Public Safety and Security instance. Review the supported authentication paths before connecting. After the upgrade, clients exchange JSON control messages except when sending binary audio frames.

A Radio mobile application sends its registered Radio device ID in the X-Oracle-Radio-Device-Id header during the HTTP upgrade. After the connection opens, it sends its bearer access token in AUTH and waits for AUTH_SUCCESS. The device ID binds the connection to registered device inventory and renews its online state; it does not replace the bearer access token. Supply exactly one valid ID: a malformed, repeated, or unknown supplied ID causes authentication to fail. An omitted ID leaves the connection unbound and cannot establish mobile audio readiness.

The service accepts at most 1 MiB in one complete inbound WebSocket message, including a complete binary audio message. This is separate from the 50 MiB limit for one audio session; see audio limits.

Every JSON message has a type property. Server messages omit an optional property when no value is available; when an optional property is present, its value isn't JSON null. Clients should ignore additive properties they do not understand, handle documented error and denial messages, and treat an unknown required message type according to the contract-version policy.

Use REST for durable discovery and history when practical. Use WebSocket messages for current session subscriptions, floor control, live messages, presence, and audio.

• Workflows show how to combine stateful operations to complete a task.
• Sessions check connection health and return connection-local identity and state.
• Channels list, get, create, and delete channels.
• Channel Subscriptions list and manage the channels joined by the current connection.
• Channel Users list users connected to a channel.
• Channel Status gets current channel and talk-floor state.
• Message History gets recent channel messages.
• Talk Floor requests and releases permission to transmit.
• Audio Transmissions start, send, and end audio transmissions.
• Text Messages send channel text messages.
• User Subscriptions manage another connected user's channel subscriptions.
• Presence gets presence and subscribes to presence updates.

• Review message families before implementing client and server messages.
• Handle errors and operation-specific denials before changing client state or retrying.
• Check compatibility before upgrading a client or sending a changed message shape.

• Use the quick start to establish authenticated REST and WebSocket access.
• Follow session recovery when a connection closes.
• Use troubleshooting or the FAQ for additional help.