Subscribing to Oracle Radio WebSocket Presence Updates

Send a SUBSCRIBE_PRESENCE message to receive presence changes for Radio users in the connection's Identity Domain.

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	The current WebSocket message contract doesn't specify an operation-specific Radio permission.
Visibility	The service sends updates only for Radio users in the authenticated user's Identity Domain.
Session state	The WebSocket connection must be open and associated with an enabled Radio user. The subscription applies to that connection.

Request

Send the SUBSCRIBE_PRESENCE message as a JSON text message.

Name	Data type	Required	Default	Constraints	Description
`type`	string	Yes	None	Must be `SUBSCRIBE_PRESENCE`.	Identifies the presence-subscription operation.

{
  "type": "SUBSCRIBE_PRESENCE"
}

Responses

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

Message type	Kind	Description
`PRESENCE_SUBSCRIBED`	Direct response	Confirms that the connection will receive presence updates in its Identity Domain.
`PRESENCE_UPDATE`	Asynchronous event	Reports a presence change for a Radio user in the same Identity Domain.
`ERROR`	Error	Indicates that the request is invalid or couldn't be processed.

Note

Wait for PRESENCE_SUBSCRIBED before relying on PRESENCE_UPDATE events. Re-establish the subscription after opening a new WebSocket connection.

PRESENCE_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 `PRESENCE_SUBSCRIBED`.
`message`	string	No	Confirmation message.
`domain`	string	No	Identity Domain that scopes the subscription.
`timestamp`	string	No	Server date and time in ISO 8601 format.

{
  "type": "PRESENCE_SUBSCRIBED",
  "message": "You will receive PRESENCE_UPDATE messages for users in domain 'acme'",
  "domain": "acme",
  "timestamp": "2024-01-15T10:30:00Z"
}

PRESENCE_UPDATE 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 `PRESENCE_UPDATE`.
`userId`	string	Yes	Radio user identifier.
`status`	string	Yes	Presence status: `online`, `offline`, or `away`.
`username`	string	No	Username.
`domain`	string	No	Identity Domain.
`channel`	string	No	A representative current channel when the user is online. It isn't a list of all channels or the channel the user just left. Omitted when unavailable.
`affectedChannels`	array of strings	Yes	Channels whose live membership changed in this event. Can be empty when no channel membership changed.
`lastSeen`	string	No	ISO 8601 date and time value. Omitted when unavailable.

{
  "type": "PRESENCE_UPDATE",
  "userId": "u-12345",
  "username": "field-unit-5",
  "domain": "acme",
  "status": "online",
  "channel": "operations",
  "affectedChannels": ["operations"],
  "lastSeen": "2024-01-15T10:30:00Z"
}

A user can remain online through another session after leaving a channel. Use affectedChannels to refresh the relevant user lists; don't infer all memberships from channel alone. See presence monitoring.