Subscribing to an Oracle Radio WebSocket Channel
Send a SUBSCRIBE message to join the current Radio WebSocket connection to one or more channels.
Permissions and Prerequisites
The following permissions and prerequisites apply to this operation.
| Requirement | Value |
|---|---|
| Authentication | Complete the supported authentication path for the client before sending this operation. See authentication. |
| Radio permission | radio.channel.subscribe |
| Channel access | The user must have subscribe access to each channel. Nonadministrators can subscribe only to channels in their domain. When ACL enforcement applies, the user must have explicit access to a restricted or hidden channel. |
| Session state | The WebSocket connection must be open. This operation creates live membership for the current connection; it doesn't grant channel access. |
Note
The contract doesn't define whether this subscription survives a reconnect or how it relates to a separately saved subscription.
The contract doesn't define whether this subscription survives a reconnect or how it relates to a separately saved subscription.
Request
Send the SUBSCRIBE message as a JSON text message. Use channels for one or more channel names. The singular channel property is retained for compatibility.
| Name | Data type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
type | string | Yes | None | Must be SUBSCRIBE. | Identifies the channel-subscribe operation. |
channel | string | No | None | Single channel name. | Compatibility property for requesting one channel. |
channels | array of strings | No | None | Channel names. | Channels to join. |
user | string | No | None | Display name. | Display name for the user. |
Note
The contract defines both
The contract defines both
channel and channels as optional and doesn't define behavior when both or neither property is supplied. For a portable preview request, supply exactly one of these properties. Prefer channels.{
"type": "SUBSCRIBE",
"channels": ["operations", "dispatch"],
"user": "operator1"
}Responses
The following table lists the messages the client can receive and explains their purpose.
| Message type | Kind | Description |
|---|---|---|
SUBSCRIBED | Direct response | Reports the result for each requested channel. A batch response can contain both successful and denied results. |
SUBSCRIBE_DENIED | Denial | Reports that a single-channel request was denied, including the channel and reason. |
ERROR | Error | Indicates that the request message is invalid or couldn't be processed. |
SUBSCRIBED Response
The following table describes the response properties, their data types, and whether they are required.
| Name | Data type | Required | Description |
|---|---|---|---|
type | string | Yes | Response type. The value is SUBSCRIBED. |
channel | string | No | Channel for a single-channel response. |
channels | object | No | Result keyed by requested channel name. |
channels.*.subscribed | boolean | No | Whether the connection joined the channel. |
channels.*.mode | string | No | Channel mode. |
channels.*.owner | string | No | Channel owner. |
channels.*.busy | boolean | No | Whether the channel is busy. |
channels.*.busyBy | string | No | Username of the current talk-token holder. |
channels.*.busyByDisplayName | string | No | Display name of the current talk-token holder. |
channels.*.priority | integer | No | Priority of the current talk token. |
channels.*.expiresAt | string | No | Talk-token expiration date and time in ISO 8601 format. |
channels.*.denied | boolean | No | Whether the channel request was denied. |
channels.*.error | string | No | Error for the channel request. |
channels.*.reason | string | No | Reason for a denial. |
channels.*.code | string | No | Code for a denial. |
user | string | No | User display name returned with the result. |
subscribed | boolean | No | Result for a single-channel request. |
busy | boolean | No | Whether a single requested channel is busy. |
busyBy | string | No | Talk-token holder for a single requested channel. |
{
"type": "SUBSCRIBED",
"channels": {
"operations": {
"subscribed": true,
"mode": "normal",
"busy": true,
"busyBy": "dispatcher1",
"priority": 50
},
"dispatch": {
"subscribed": true,
"mode": "normal",
"busy": false
}
},
"user": "operator1"
}