Subscribing an Oracle Radio User to WebSocket Channels

Send a SUBSCRIBE_USER message to add another connected Radio user to one or more live channel subscriptions.

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.user.subscriptions.manage`
Channel access	This operation changes the target user's live channel subscription. It doesn't change the target user's channel access.
Session state	The requester's WebSocket connection must be open. The target username must identify a currently connected Radio user in the same Identity Domain.

Request

Send the SUBSCRIBE_USER message as a JSON text message.

Name	Data type	Required	Default	Constraints	Description
`type`	string	Yes	None	Must be `SUBSCRIBE_USER`.	Identifies the user-subscription operation.
`targetUser`	string	Conditional	None	At least one of `targetUser` or `user` is required.	Username of the user to subscribe. Use this property for new integrations.
`user`	string	Conditional	None	At least one of `targetUser` or `user` is required.	Legacy alias for `targetUser`.
`channel`	string	Conditional	None	At least one of `channel` or `channels` is required.	One channel name.
`channels`	array of strings	Conditional	None	At least one of `channel` or `channels` is required.	Channel names. Use this property to subscribe the user to one or more channels.

The request must include at least one target selector and at least one channel selector. Use targetUser instead of the legacy user alias. Specify channel for one channel or channels for one or more channels.

{
  "type": "SUBSCRIBE_USER",
  "targetUser": "field-unit-5",
  "channels": [
    "operations",
    "emergency"
  ]
}

Responses

The following table lists the messages the client can receive and explains their purpose.

Message type	Kind	Description
`USER_SUBSCRIBED`	Direct response	Returns the subscription result for each requested channel.
`SUBSCRIBED_BY`	Asynchronous event	Notifies the target user's connection that another user subscribed it to a channel.
`ERROR`	Denial or error	Indicates a missing target or channel selector, a missing management permission, a target user who isn't connected, or another processing failure.

USER_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 `USER_SUBSCRIBED`.
`targetUser`	string	Yes	Username of the target user.
`channels`	object	Yes	Map keyed by channel name. Each value describes the channel subscription result.
`channels.*.subscribed`	boolean	Yes	Whether the target user is subscribed to the channel.
`channels.*.mode`	string	Yes	Channel mode.
`channels.*.clientsSubscribed`	integer	Yes	Number of the target user's connected clients subscribed to the channel.
`channels.*.busy`	boolean	Yes	Whether the channel's talk floor 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.
`subscribedBy`	string	No	Username of the user who requested the subscription.

{
  "type": "USER_SUBSCRIBED",
  "targetUser": "field-unit-5",
  "channels": {
    "operations": {
      "subscribed": true,
      "mode": "normal",
      "clientsSubscribed": 1,
      "busy": false
    }
  },
  "subscribedBy": "dispatcher1"
}

SUBSCRIBED_BY Event

The following table describes the event properties, their data types, and whether they are required.

Name	Data type	Required	Description
`type`	string	Yes	Event type. The value is `SUBSCRIBED_BY`.
`channel`	string	Yes	Channel to which the target user's connection was subscribed.
`subscribedBy`	string	Yes	Username of the user who requested the subscription.
`message`	string	Yes	Notification message.

{
  "type": "SUBSCRIBED_BY",
  "channel": "operations",
  "subscribedBy": "dispatcher1",
  "message": "You have been subscribed to channel 'operations' by dispatcher1"
}