]> git.ipfire.org Git - thirdparty/asterisk.git/commit
chan_websocket: Add capability for JSON control messages and events. master
authorGeorge Joseph <gjoseph@sangoma.com>
Wed, 22 Oct 2025 12:23:31 +0000 (06:23 -0600)
committergithub-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Tue, 4 Nov 2025 19:27:56 +0000 (19:27 +0000)
commitf08020df80537b81e76f603afd6b6bc0deac6437
tree48161511a5be10ad37bfd3c21944a1b4e946ecfb
parenta9a1b976a7cbac855523996dbe4197caf014d99c
chan_websocket: Add capability for JSON control messages and events.

With recent enhancements to chan_websocket, the original plain-text
implementation of control messages and events is now too limiting.  We
probably should have used JSON initially but better late than never.  Going
forward, enhancements that require control message or event changes will
only be done to the JSON variants and the plain-text variants are now
deprecated but not yet removed.

* Added the chan_websocket.conf config file that allows setting which control
message format to use globally: "json" or "plain-text".  "plain-text" is the
default for now to preserve existing behavior.

* Added a dialstring option `f(json|plain-text)` to allow the format to be
overridden on a call-by-call basis.  Again, 'plain-text' is the default for
now to preserve existing behavior.

The JSON for commands sent by the app to Asterisk must be...
`{ "command": "<command>" ... }` where `<command>` is one of `ANSWER`, `HANGUP`,
`START_MEDIA_BUFFERING`, etc.  The `STOP_MEDIA_BUFFERING` command takes an
additional, optional parameter to be returned in the corresponding
`MEDIA_BUFFERING_COMPLETED` event:
`{ "command": "STOP_MEDIA_BUFFERING", "correlation_id": "<correlation id>" }`.

The JSON for events sent from Asterisk to the app will be...
`{ "event": "<event>", "channel_id": "<channel_id>" ... }`.
The `MEDIA_START` event will now look like...

```
{
  "event": "MEDIA_START",
  "connection_id": "media_connection1",
  "channel": "WebSocket/media_connection1/0x5140001a0040",
  "channel_id": "1761245643.1",
  "format": "ulaw",
  "optimal_frame_size": 160,
  "ptime": 20,
  "channel_variables": {
    "DIALEDPEERNUMBER": "media_connection1/c(ulaw)",
    "MEDIA_WEBSOCKET_CONNECTION_ID": "media_connection1",
    "MEDIA_WEBSOCKET_OPTIMAL_FRAME_SIZE": "160"
  }
}
```

Note the addition of the channel variables which can't be supported
with the plain-text formatting.

The documentation will be updated with the exact formats for all commands
and events.

Resolves: #1546
Resolves: #1563

DeveloperNote: The chan_websocket plain-text control and event messages are now
deprecated (but remain the default) in favor of JSON formatted messages.
See https://docs.asterisk.org/Configuration/Channel-Drivers/WebSocket for
more information.

DeveloperNote: A "transport_data" parameter has been added to the
channels/externalMedia ARI endpoint which, for websocket, allows the caller
to specify parameters to be added to the dialstring for the channel.  For
instance, `"transport_data": "f(json)"`.
channels/chan_websocket.c
channels/chan_websocket_doc.xml [new file with mode: 0644]
configs/samples/chan_websocket.conf.sample [new file with mode: 0644]
res/ari/resource_channels.c
res/ari/resource_channels.h
res/res_ari_channels.c
rest-api/api-docs/channels.json