Asterisk media over WebSocket: channel, control and flow boundaries

Name the WebSocket role before configuring it

Asterisk can use WebSockets for several independent jobs. SIP over WebSocket carries SIP endpoint signaling. An ARI WebSocket carries events and, in newer arrangements, control requests. chan_websocket carries application media in binary frames and its own control events or commands in text frames. A successful connection in one role does not prove that either of the other sockets exists or works.

Draw the call leg and name the owning module, URI, subprotocol, authentication, direction and expected lifetime for every socket. The official examples explicitly allow ARI and media client/server choices to be mixed independently. Never reuse one WebSocket connection for both ARI and media; Asterisk documents them as separate connections even though both can draw client settings from websocket_client.conf.

Respect the release and module boundary

Asterisk documents the initial chan_websocket driver from 20.16.0, 21.11.0, 22.6.0 and 23.0.0. JSON control messages and chan_websocket.conf arrive later at 20.18.0, 22.8.0 and 23.2.0. Confirm the running binary, loaded module and available parameters before copying a current example into an older maintenance release.

On October 9, 2026 the official archive lists 22.11.0 as the latest final Asterisk 22 release and 22.12.0-rc2 as pre-release material. Branch documentation can contain options intended for the pending maintenance release. Do not represent a branch-generated option such as the newer write timeout as available on stable 22.11.0 without checking the installed version and its generated help.

Choose incoming or outgoing per-call media

For an outbound media connection, define a websocket_client.conf object and reference its connection name from Dial(WebSocket/...), the channel API or ARI External Media. For an incoming connection, create the channel with the literal INCOMING, retain MEDIA_WEBSOCKET_CONNECTION_ID, and connect the application to the corresponding /media/<id> URI. Media connections use the per-call configuration type; a persistent ARI connection is not a persistent media pipe.

By default Asterisk answers the WebSocket channel when the connection succeeds. The n dial-string option defers answer until the application sends the control command or answers through ARI. Keep socket establishment, channel creation, answer, bridge and media as separate timestamped states.

Keep raw media and control frames distinct

Asterisk sends application media in binary WebSocket frames without RTP headers. Text frames carry case-sensitive control commands and events such as MEDIA_START, MEDIA_XOFF and MEDIA_XON. Sending a control string as binary makes it media rather than a command. Capture WebSocket opcode, length and timestamp in addition to payload metadata.

For codecs Asterisk can reframe, MEDIA_START and MEDIA_WEBSOCKET_OPTIMAL_FRAME_SIZE expose the expected 20 ms size. Exact-size blocks or multiples can be split and timed by the driver; odd residual data can be dropped unless the documented buffering commands bracket a bulk transfer. Codecs with packet headers or non-divisible streams, including the documented Opus, Speex and G.729 cases, use passthrough behavior and leave framing and timing with the application.

Treat flow control as call state

The documented maximum WebSocket message is 65,500 bytes; a larger message closes the socket and hangs up the call. The driver holds roughly 1,000 frames, signals MEDIA_XOFF around 900 and MEDIA_XON below about 800. Media sent after XOFF is likely to be dropped. Backpressure is therefore part of the call protocol, not an optional performance hint.

Correlate MEDIA_START, channel ID, selected format, optimal frame size, queue events, application send rate and the final hangup. Do not convert a queue threshold into supported concurrency, throughput or latency. One quiet interval can produce generated silence and is not proof that the application sent valid audio.

Secure and prove each boundary

Use WSS where the deployment requires confidentiality and authenticate the intended application, verify the server certificate and hostname, restrict the listener, protect connection credentials and apply least privilege to any associated ARI user. TLS acceptance proves the adjacent WebSocket peer only; it does not authorize dialplan access or prove that media reached the far caller.

Pilot one bounded echo or known-file path using the official example concepts, then verify the socket, MEDIA_START, channel answer, binary media in both directions, queue state, bridge, far-leg media and hangup separately. Preserve a rollback for dialplan, client configuration and application version. No host, socket, media stream or call was tested for this guide.

Place WebSocket inside the External Media driver choice

The current ARI External Media guide compares WebSocket with the RTP/UDP and AudioSocket/TCP driver pairs. WebSocket release floors, transport_data, MEDIA_START and flow control remain specific to chan_websocket; they are not generic properties of every External Media channel.

Separate WebSocket upgrade from media flow

Use the Asterisk HTTP endpoint diagnostic to prove name, TCP, TLS, prefix, URI and upgrade before investigating later WebSocket media frames.