WebSocket.md: Tweaks to some names and add links

gtjoseph · gtjoseph · commit b4362ec0dafd · 2025-06-11T09:46:49.000-06:00
diff --git a/docs/Configuration/Channel-Drivers/WebSocket.md b/docs/Configuration/Channel-Drivers/WebSocket.md
@@ -29,7 +29,7 @@ Outgoing connections require you to pre-configure a websocket client in the `web
 exten = _x.,1,Dial(WebSocket/connection1/c(ulaw))
 ```
 
-This would connect to your application's websocket server using the client named `connection1` and using the `ulaw` codec.  Right after your server accepts the connection, you'll get a TEXT websocket message `MEDIA_START connection_id:<connection_id> channel:<channel_name> optimal_frame_size:<optimal_frame_size>`. This will allow you to correlate the incoming connection to the specific channel. The `a` dialstring options tells the channel driver to auto-answer the channel on successful connection.  If you omit the `a`, you can send an `ANSWER` TEXT message to answer the channel yourself.
+This would connect to your application's websocket server using the client named `connection1` and using the `ulaw` codec.  Right after your server accepts the connection, you'll get a TEXT websocket message `MEDIA_START connection_id:<connection_id> channel:<channel_name> optimal_frame_size:<optimal_frame_size>`. This will allow you to correlate the incoming connection to the specific channel.
 
 ### Incoming Connections
 
@@ -40,9 +40,9 @@ Incoming connections must be made to the global Asterisk HTTP server using the `
 exten = _x.,1,Dial(WebSocket/INCOMING/c(ulaw)n)
 ```
 
-The websocket channel will be created immediately and the `MEDIA_WEBSOCKET_CONNECTION_ID` channel variable will be set to an ephemeral connection id which must be used in the URI your application will connect to Asterisk with.  For example `/media/32966726-4388-456b-a333-fdf5dbecc60d`.  When Asterisk accepts the connection, you'll see the same `MEDIA_START` message as above.  You can also omit the `a` option and send an `ANSWER` TEXT message as above.
+The websocket channel will be created immediately and the `MEDIA_WEBSOCKET_CONNECTION_ID` channel variable will be set to an ephemeral connection id which must be used in the URI your application will connect to Asterisk with.  For example `/media/32966726-4388-456b-a333-fdf5dbecc60d`.  When Asterisk accepts the connection, you'll see the same `MEDIA_START` message as above.
 
-The default behavior is to automatically answer the channel when the websocket has connected successfully.  If for some reason you want to answer the channel yourself, you can add the `n` parameter to the dialstring and make a REST `channels/<id>/answer` call or send the `ANSWER` command (mentioned below) over the media websocket.
+Whether inbound or outbound, the default behavior is to automatically answer the channel when the websocket has connected successfully.  If for some reason you want to answer the channel yourself, you can add the `n` parameter to the dialstring and make a REST `channels/<id>/answer` call or send the `ANSWER` command (mentioned below) over the media websocket.
 
 ## Protocol
 
@@ -54,13 +54,13 @@ Media sent _to_ Asterisk _from_ your app is a bit trickier because chances are t
 
 When the websocket channel is created, a `MEDIA_WEBSOCKET_OPTIMAL_FRAME_SIZE` channel variable will be set that tells you the amount of data Asterisk needs to create a good 20ms frame using the codec you specified in the dialstring.  This is also reported in the `MEDIA_START` TEXT message. If you send a websocket message with a length that's exactly that size or some even multiple of that size, the channel driver will happily break that message up into the correctly sized frames and send one frame to the Asterisk core every 20ms with no leftover data.  If you send an oddly sized message though, the extra data that won't fill a frame will be dropped.  However...
 
-If you need to send a file or a buffer received from an external source like an AI agent, it's quite possible that the buffer size won't be an even multiple of the optimal size.  In this case, the app can send Asterisk a `START_BULK_MEDIA` TEXT websocket message before sending the media. This tells the channel driver to buffer the data received so it can make full frames even across multiple received BINARY messages.  That process will continue until the app sends Asterisk a `END_BULK_MEDIA` TEXT message. When the channel driver receives that, it'll take whatever data is left in the buffer that couldn't make a full frame and append silence to it to make up a full frame and send that to the core.
+If you need to send a file or a buffer received from an external source like an AI agent or a file, it's quite possible that the buffer size won't be an even multiple of the optimal size.  In this case, the app can send Asterisk a `START_MEDIA_BUFFERING` TEXT websocket message before sending the media. This tells the channel driver to buffer the data received so it can make full frames even across multiple received BINARY messages.  That process will continue until the app sends Asterisk a `STOP_MEDIA_BUFFERING` TEXT message. When the channel driver receives that, it'll take whatever data is left in the buffer that couldn't make a full frame with, append silence to it to make up a full frame and send that to the core.
 
 So why can't Asterisk just do that process all the time and dispense with the TEXT messages?  Well, let's say the app sends a message with an odd amount of data and the channel driver saves off the odd bit.  What happens if you don't send any data for a while?  If 20ms goes by and the channel driver doesn't get any more data what is it supposed to do with the leftover?  If it appends silence to make a full frame and sends it to the core, then the app sends more data after 30ms, the caller will hear a gap in the audio.  If the app does that a lot, it'll be a bad experience for ther caller.
 
 ### Max Message Size and Flow Control
 
-Chances are that your app will be sending data faster to Asterisk than Asterisk will be sending out to a caller so there are some rules you need to follow to prevent the channel driver from consuming excessive memory...
+Chances are that your app will be sending data faster to Asterisk than Asterisk will be sending out to a caller so there are some rules you need to follow to prevent the channel driver from consuming excessive memory.  First...
 
 /// warning
 The maximum websocket message size the underlying websocket code can handle is 65500 bytes.  Attempting to send a message greater than that length will result in the websocket being closed and the call hungup!
@@ -74,50 +74,48 @@ See the next section for more commands the app can send.
 
 /// warning
 You must ensure that the control messages are sent as TEXT messages.  Sending them as BINARY messages will cause them to be treated as media.
+
+All commands are case-sensitive.
 ///
 
 Some of the control TEXT messages you can send the driver have already been mentioned but here's the full list:
 
 #### Commands
 
-/// note
-All commands are case-sensitive.
-///
-
 /// define
-`ANSWER`: Answer the WebSocket channel
+`ANSWER`
 
 - This will cause the WebSocket channel to be answered.
 
-`HANGUP`: Hangup the WebSocket channel
+`HANGUP`
 
 - This will cause the WebSocket channel to be hung up and the websocket to be closed.
 
-`START_BULK_MEDIA`: Start buffering media
+`START_MEDIA_BUFFERING`
 
 - Indicates to the channel driver that the following media should be buffered to create properly sized and timed frames.
 
-`END_BULK_MEDIA <optional_id>`: Stop buffering media
+`STOP_MEDIA_BUFFERING <optional_id>`
 
-- Indicates to the channel driver that buffering is no longer needed and anything remaining in the buffer should have silence appended before sending to the Asterisk core.  When the last frame of this bulk transfer has been sent to the core, the app will receive a `BULK_MEDIA_END` notification.  If the optional id was specified in this command, it'll be returned in the notification.  If you send multiple files in quick succession, the id can help you correlate the `BULK_MEDIA_END` notification to the `END_BULK_MEDIA` command that trigfgered it.
+- Indicates to the channel driver that buffering is no longer needed and anything remaining in the buffer should have silence appended before sending to the Asterisk core.  When the last frame of this bulk transfer has been sent to the core, the app will receive a `MEDIA_BUFFERING_COMPLETED` notification.  If the optional id was specified in this command, it'll be returned in the notification.  If you send multiple files in quick succession, the id can help you correlate the `MEDIA_BUFFERING_COMPLETED` notification to the `STOP_MEDIA_BUFFERING` command that triggered it.
 
-`PAUSE_MEDIA`: Pause media being sent to the Asterisk core
+`FLUSH_MEDIA`
 
-- If you've sent a large amount of media but need to pause it playing to a caller while you decide if you need to flush it or not, you can send a `PAUSE_MEDIA` command.  The channel driver will then start playing silence to the caller but keep the data you've already sent in the queue.  You can still send media to the channel driver while it's paused; it just will get queued behind whatever was already in the queue.
+- Send this command to the channel driver if you've sent a large amount of media but want to discard any queued but not sent. Flushing the buffer automatically ends any bulk transfer in progress and also resets the paused state so there's no need to send `STOP_MEDIA_BUFFERING` or `CONTINUE_MEDIA` commands. No `MEDIA_BUFFERING_COMPLETED` notification will be sent in this case.  This command could be useful if an automated agent detects the caller is speaking and wants to interrupt a prompt it already replied with.
 
-`CONTINUE_MEDIA`: Continue media being sent to the Asterisk core
+`PAUSE_MEDIA`
 
-- If you've previously paused the media, this will cause the channel driver to stop playing silence and resume playing media from the queue from the point you paused it.
+- If you've sent a large amount of media but need to pause it playing to a caller while you decide if you need to flush it or not, you can send a `PAUSE_MEDIA` command.  The channel driver will then start playing silence to the caller but keep the data you've already sent in the queue.  You can still send media to the channel driver while it's paused; it'll just get queued behind whatever was already in the queue.
 
-`FLUSH_MEDIA`: Flush the buffer
+`CONTINUE_MEDIA`
 
-- Send this command to the channel driver if you've sent a large amount of media but want to discard any queued but not sent. Flushing the buffer automatically ends any bulk transfer in progress and also resets the paused state so there's no need to send `END_BULK_MEDIA` or `CONTINUE_MEDIA` commands. No `BULK_MEDIA_END` notification will be sent in this case.  This command could be useful if an automated agent detects the caller is speaking and wants to interrupt a prompt it already replied with.
+- If you've previously paused the media, this will cause the channel driver to stop playing silence and resume playing media from the queue from the point you paused it.
 
-`GET_STATUS`: Get the current queue status
+`GET_STATUS`
 
 - This will cause the channel driver to send back a `STATUS` message (described below).
 
-`REPORT_QUEUE_DRAINED`: Request a notification when the frame queue is empty
+`REPORT_QUEUE_DRAINED`
 
 - This will cause the channel driver to send back a one-time `QUEUE_DRAINED` notification the next time it detects that there are no more frames to process in the queue.
 
@@ -127,23 +125,23 @@ All commands are case-sensitive.
 
 /// define
 
-`MEDIA_XOFF`: Stop sending media
+`MEDIA_XOFF`
 
-- The channel driver will send this notification to the app when the frame queue length reaches the high water mark.  The app should then pause sending media.  Any media sent after this has a high probability of being dropped.
+- The channel driver will send this notification to the app when the frame queue length reaches the high water (XOFF) level.  The app should then pause sending media.  Any media sent after this has a high probability of being dropped.
 
-`MEDIA_XON`: Start sending media again
+`MEDIA_XON`
 
-- The channel driver will send this notification when the frame queue length drops below the low water mark.  This indicates that it's safe for the app to start sending media again.
+- The channel driver will send this notification when the frame queue length drops below the low water (XON) level.  This indicates that it's safe for the app to start sending media again.
 
-`STATUS`: Response from the `GET_STATUS` command
+`STATUS`
 
 - The channel driver will send this notification in response to a `GET_STATUS` command.<br>Example: `STATUS queue_length:43 xon_level:800 xoff_level:900 queue_full:false bulk_media:true media_paused:false`
 
-`BULK_MEDIA_END [ <optional_id> ]`: Indicates that a bulk media transfer has finished.
+`MEDIA_BUFFERING_COMPLETED [ <optional_id> ]`
 
-- The channel driver will send this mesage when bulk media has finished being framed, timed and sent to the Asterisk core. If an optional id was supplied on the `END_BULK_XFER` command, it will be returned in this message.
+- The channel driver will send this mesage when bulk media has finished being framed, timed and sent to the Asterisk core. If an optional id was supplied on the `STOP_MEDIA_BUFFERING` command, it will be returned in this message.
 
-`QUEUE_DRAINED`: Response from `REPORT_QUEUE_DRAINED`
+`QUEUE_DRAINED`
 
 - The channel driver will send this when it's processed the last frame in the queue and you've asked to be notified with a `REPORT_QUEUE_DRAINED` command.  If no media is received within the next 20ms, a silence frame will be sent to the core.  This is a one-time notification.  You must send additional `REPORT_QUEUE_DRAINED` commands to get more notifications.
 
@@ -161,7 +159,7 @@ All configuration is done in the common [websocket_client.conf](/Latest_API/API_
 
 ## Creating the Channel
 
-### Using the Dial() Dialplan App
+### Using the [Dial() Dialplan App](/Latest_API/API_Documentation/Dialplan_Applications/Dial/)
 
 The full dial string is as follows:
 
@@ -173,7 +171,7 @@ Dial(WebSocket/<connection_id>/<options>[,<timeout>[,<dial_options>]])
 * **&lt;connection_id&gt;**: For outgoing connections, this is the name of the pre-defined client connection from websocket_client.conf.  For incoming connections, this must be the special `INCOMING` id.
 * **&lt;options&gt;**:
     * `c(<codec>)`: If not specified, the first codec from the caller's channel will be used.  Having said that, if your app is expecting a specific codec, you should specify it here or you may be getting audio in a format you don't expect.
-    * `n`: Don't auto-answer the WebSocket channel upon successful connection. Set this if you wish to answer the channel yourself. You can then send an `ANSWER` TEXT message on the websocket when you're ready to answer the channel.
+    * `n`: Don't auto-answer the WebSocket channel upon successful connection. Set this if you wish to answer the channel yourself. You can then send an `ANSWER` TEXT message on the websocket when you're ready to answer the channel or make a `/channels/<channel_id>/answer` REST call.
 
 Examples:
 
@@ -182,7 +180,7 @@ Dial(WebSocket/connection1/c(alaw)n)
 Dial(WebSocket/INCOMING/c(slin16))
 ```
 
-### Using the ARI `/channels`, `/channels/<id>` or `/channels/create` REST APIs
+### Using the [ARI `/channels`](/Latest_API/API_Documentation/Asterisk_REST_Interface/Channels_REST_API/) REST APIs
 
 You can also create a WebSocket channel using the normal channel API calls and setting the `endpoint` parameter to the same dial string syntax described in the previous section.
 
@@ -195,9 +193,9 @@ POST http://server:8088/ari/channels/create?endpoint="WebSocket/INCOMING/c(ulaw)
 
 The first example will create and dial the channel then connect to your app using the "media_connection1" websocket_client configuration. The channel will auto answer when the websocket connection is established.  The second example will create the channel but not dial or auto-answer it.  Instead the channel driver will wait for your app to connect to it.  You can then dial and answer it yourself when appropriate.  You can still omit the `n` to have incoming connections auto-answered.
 
-### Using ARI External Media (`/channels/externalMedia`)
+### Using [ARI External Media](/Development/Reference-Information/Asterisk-Framework-and-API-Examples/External-Media-and-ARI) (`/channels/externalMedia`)
 
-You can also create a channel using externalMedia with a transport of `websocket` and an encapsulation of `none`.
+You can also create a channel using external media with a transport of `websocket` and an encapsulation of `none`.
 
 Example:
 
