Requesting the Oracle Radio WebSocket Talk Floor
Send a REQUEST_TALK message to request a talk token for transmitting on a Radio channel.
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.talk.request |
| Channel access | The user must have talk access to the requested channel. A request can be denied by the channel access control list. |
| Session state | The WebSocket connection must be open. Only one talk token can control the talk floor for a channel at a time. |
Request
Send the REQUEST_TALK message as a JSON text message.
| Name | Data type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
type | string | Yes | None | Must be REQUEST_TALK. | Identifies the talk-floor request. |
channel | string | No | default | Channel name. | Channel for which to request the talk floor. |
user | string | No | None | Display name. | Display name supplied with the request. |
priority | integer | No | 0 | From 0 through 1000. Values over 100 require radio.talk.priority.high; without that permission, the effective priority is limited to 100. | Request priority. A higher priority can preempt a lower priority. |
Note
First send
First send
SUBSCRIBE. In the SUBSCRIBED response, confirm that the target channel's result has subscribed set to true. If the service returns SUBSCRIBE_DENIED, or the target channel's result has denied set to true, resolve the denial and subscribe again before sending REQUEST_TALK. Note
The current WebSocket talk-token lifetime is 30 seconds;
The current WebSocket talk-token lifetime is 30 seconds;
REQUEST_TALK doesn't accept a requested duration. Use the expiresAt value returned with GRANTED to track token validity. Stop transmitting when the service sends TOKEN_EXPIRED.{
"type": "REQUEST_TALK",
"channel": "operations",
"user": "dispatcher1",
"priority": 50
}Responses
The following table lists the messages the client can receive and explains their purpose.
| Message type | Kind | Description |
|---|---|---|
GRANTED | Direct response or queued grant | Returns a talk token. A later grant for a queued request has fromQueue set to true. |
DENIED | Direct response | Reports that the channel is busy or the request was otherwise denied. |
QUEUED | Direct response | Reports the request's position behind the current token holder. |
TALK_DENIED | Denial | Reports a Radio permission or channel access denial, with a reason and code. |
CHANNEL_BUSY | Asynchronous event | Notifies channel subscribers that a user holds the talk floor. |
INTERRUPTED | Asynchronous event | Notifies the token holder that a higher-priority user took the talk floor. Stop transmitting. |
TOKEN_EXPIRED | Asynchronous event | Notifies the token holder that the talk token expired. Stop transmitting and request another token if needed. |
ERROR | Error | Indicates that the request is invalid or couldn't be processed. |
GRANTED 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 GRANTED. |
token | string | Yes | UUID talk token to use for the transmission. |
channel | string | Yes | Channel controlled by the talk token. |
userDisplayName | string | No | Display name of the token holder. |
priorityWarning | string | No | Warning about the requested priority. |
fromQueue | boolean | No | Whether the server granted a previously queued request. |
expiresAt | string | Yes | Talk-token expiration date and time in ISO 8601 format. |
{
"type": "GRANTED",
"token": "550e8400-e29b-41d4-a716-446655440000",
"channel": "operations",
"userDisplayName": "Dispatcher One",
"expiresAt": "2024-01-15T10:35:00Z"
}