Unsubscribing an Oracle Radio User from WebSocket Channels

Send an UNSUBSCRIBE_USER message to remove another connected Radio user from 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 UNSUBSCRIBE_USER message as a JSON text message.

Name	Data type	Required	Default	Constraints	Description
`type`	string	Yes	None	Must be `UNSUBSCRIBE_USER`.	Identifies the user-unsubscription operation.
`targetUser`	string	Conditional	None	At least one of `targetUser` or `user` is required.	Username of the user to unsubscribe. 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 unsubscribe the user from 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": "UNSUBSCRIBE_USER",
  "targetUser": "field-unit-5",
  "channels": [
    "emergency"
  ]
}

Responses

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

Message type	Kind	Description
`USER_UNSUBSCRIBED`	Direct response	Returns the unsubscription result for each requested channel.
`UNSUBSCRIBED_BY`	Asynchronous event	Notifies the target user's connection that another user unsubscribed it from 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_UNSUBSCRIBED 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_UNSUBSCRIBED`.
`targetUser`	string	Yes	Username of the target user.
`channels`	object	Yes	Map keyed by channel name. Each value describes the channel unsubscription result.
`channels.*.unsubscribed`	boolean	Yes	Whether the target user was unsubscribed from the channel.
`channels.*.clientsUnsubscribed`	integer	No	Number of the target user's connected clients unsubscribed from the channel.
`channels.*.reason`	string	No	Reason that a channel subscription wasn't removed.
`unsubscribedBy`	string	No	Username of the user who requested the unsubscription.

{
  "type": "USER_UNSUBSCRIBED",
  "targetUser": "field-unit-5",
  "channels": {
    "emergency": {
      "unsubscribed": true,
      "clientsUnsubscribed": 1
    }
  },
  "unsubscribedBy": "dispatcher1"
}

UNSUBSCRIBED_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 `UNSUBSCRIBED_BY`.
`channel`	string	Yes	Channel from which the target user's connection was unsubscribed.
`unsubscribedBy`	string	Yes	Username of the user who requested the unsubscription.
`message`	string	Yes	Notification message.

{
  "type": "UNSUBSCRIBED_BY",
  "channel": "emergency",
  "unsubscribedBy": "dispatcher1",
  "message": "You have been unsubscribed from channel 'emergency' by dispatcher1"
}