docs: document binary broadcast messages (#46668)

## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES

## What kind of change does this PR introduce?

Document Realtime broadcast of binary payloads

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Clarified binary payload behavior across SDKs and runtimes, including
version-gated support and which clients silently drop binaries.
* Added examples for sending binary messages via JavaScript, Swift, REST
(including file upload), and database broadcasts.
* Clarified REST payload handling (Content-Type selects JSON vs binary),
private messaging flag, and that batch endpoints accept JSON-only.
* Noted that channel.httpSend() uses REST starting in supabase-js
2.107.0.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>

apps/docs/content/guides/realtime/broadcast.mdx

@@ -128,6 +128,12 @@ Get the Project URL and key from [the project's **Connect** dialog](/dashboard/p
 
 You can receive Broadcast messages by providing a callback to the channel.
 
+<Admonition type="note">
+
+Binary payloads (`ArrayBuffer` / `ArrayBufferView`) are received automatically from **supabase-js 2.91.0** and **supabase-swift 2.44.0**. On older SDK versions, binary messages are silently dropped and never reach the callback.
+
+</Admonition>
+
 <Tabs
   scrollable
   size="small"
@@ -255,6 +261,12 @@ You can receive Broadcast messages by providing a callback to the channel.
 
 You can use the Supabase client libraries to send Broadcast messages.
 
+<Admonition type="note">
+
+Broadcast payloads can be binary (`ArrayBuffer` or `ArrayBufferView`, e.g. `Uint8Array`) over WebSocket from **supabase-js 2.91.0** and **supabase-swift 2.44.0**. Binary payloads sent to clients running older SDK versions are **silently dropped** and never arrive over the WebSocket. The Dart, Kotlin, and Python clients don't support binary payloads yet.
+
+</Admonition>
+
 <Tabs
   scrollable
   size="small"
@@ -298,6 +310,16 @@ You can use the Supabase client libraries to send Broadcast messages.
         payload: { message: 'Hi' },
       })
     })
+
+    /**
+     * The payload can be binary (ArrayBuffer / ArrayBufferView) from supabase-js 2.91.0.
+     * Receivers on older SDK versions will not get the message.
+     */
+    myChannel.send({
+      type: 'broadcast',
+      event: 'cursor-pos',
+      payload: new Uint8Array([1, 2, 3]).buffer,
+    })
     ```
 
   </TabPanel>
@@ -335,6 +357,12 @@ You can use the Supabase client libraries to send Broadcast messages.
   <$Show if="sdk:swift">
   <TabPanel id="swift" label="Swift">
 
+    <Admonition type="note">
+
+    Binary payloads over WebSocket are supported from supabase-swift 2.44.0. Receivers on older SDK versions will not get binary messages.
+
+    </Admonition>
+
     {/* prettier-ignore */}
     ```swift
     let myChannel = await supabase.channel("test-channel") {
@@ -440,11 +468,31 @@ By default, all database broadcasts are private, meaning clients must authentica
 
 </Admonition>
 
+To broadcast a binary payload from your database, use the `realtime.send_binary()` function with a `bytea` payload:
+
+{/* prettier-ignore */}
+```sql
+select
+  realtime.send_binary(
+    '\x012345'::bytea, -- bytea payload
+    'event',           -- Event name
+    'topic',           -- Topic
+    true               -- Private / Public flag (defaults to true)
+  );
+```
+
+The same public/private matching rule applies: a binary broadcast only reaches channels with the same private setting. Binary messages only reach clients on **supabase-js 2.91.0** and **supabase-swift 2.44.0** or later; older clients silently drop them.
+
 You can use the `realtime.broadcast_changes()` helper function to broadcast messages when a record is created, updated, or deleted. For more details, read [Subscribing to Database Changes](/docs/guides/realtime/subscribing-to-database-changes).
 
 ### Broadcast using the REST API
 
-You can send a Broadcast message by making an HTTP request to Realtime servers.
+You can send a single Broadcast message by making an HTTP request to Realtime servers. The endpoint embeds the topic and event in the path, and the `Content-Type` header determines the payload type:
+
+- `application/json` — JSON payload
+- `application/octet-stream` — binary payload
+
+Add `?private=true` to broadcast to a private channel.
 
 <Tabs
   scrollable
@@ -457,19 +505,19 @@ You can send a Broadcast message by making an HTTP request to Realtime servers.
 
     {/* prettier-ignore */}
     ```bash
+    # JSON payload
     curl -v \
     -H 'apikey: <SUPABASE_TOKEN>' \
     -H 'Content-Type: application/json' \
-    --data-raw '{
-      "messages": [
-        {
-          "topic": "test",
-          "event": "event",
-          "payload": { "test": "test" }
-        }
-      ]
-    }' \
-    'https://<PROJECT_REF>.supabase.co/realtime/v1/api/broadcast'
+    --data-raw '{ "test": "test" }' \
+    'https://<PROJECT_REF>.supabase.co/realtime/v1/api/broadcast/test/events/event'
+
+    # Binary payload
+    curl -v \
+    -H 'apikey: <SUPABASE_TOKEN>' \
+    -H 'Content-Type: application/octet-stream' \
+    --data-binary @payload.bin \
+    'https://<PROJECT_REF>.supabase.co/realtime/v1/api/broadcast/test/events/event?private=true'
     ```
 
   </TabPanel>
@@ -477,26 +525,39 @@ You can send a Broadcast message by making an HTTP request to Realtime servers.
 
     {/* prettier-ignore */}
     ```bash
-    POST /realtime/v1/api/broadcast HTTP/1.1
+    POST /realtime/v1/api/broadcast/test/events/event HTTP/1.1
     Host: {PROJECT_REF}.supabase.co
     Content-Type: application/json
     apikey: {SUPABASE_TOKEN}
-    {
-      "messages": [
-        {
-          "topic": "test",
-          "event": "event",
-          "payload": {
-            "test": "test"
-          }
-        }
-      ]
-    }
+    { "test": "test" }
     ```
 
   </TabPanel>
 </Tabs>
 
+<Admonition type="note">
+
+To send multiple messages in a single request, the batch endpoint `POST /realtime/v1/api/broadcast` is still available. It accepts a JSON body with a `messages` array (JSON payloads only):
+
+{/* prettier-ignore */}
+```bash
+curl -v \
+-H 'apikey: <SUPABASE_TOKEN>' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+  "messages": [
+    {
+      "topic": "test",
+      "event": "event",
+      "payload": { "test": "test" }
+    }
+  ]
+}' \
+'https://<PROJECT_REF>.supabase.co/realtime/v1/api/broadcast'
+```
+
+</Admonition>
+
 ## Broadcast options
 
 You can pass configuration options while initializing the Supabase Client.
@@ -783,7 +844,7 @@ You can also send a Broadcast message by making an HTTP request to Realtime serv
   <TabPanel id="js" label="JavaScript">
     <Admonition type="note">
 
-    This is currently available only in the Supabase JavaScript client version 2.37.0 and later.
+    `channel.httpSend()` always uses the REST API regardless of WebSocket connection state, and is available from the Supabase JavaScript client version 2.107.0 and later. `ArrayBuffer` and `ArrayBufferView` (e.g. `Uint8Array`) payloads are sent as `application/octet-stream`; all other payloads are JSON-encoded.
 
     </Admonition>
 
@@ -792,13 +853,11 @@ You can also send a Broadcast message by making an HTTP request to Realtime serv
 
     // No need to subscribe to channel
 
-    channel
-      .send({
-        type: 'broadcast',
-        event: 'test',
-        payload: { message: 'Hi' },
-      })
-      .then((resp) => console.log(resp))
+    // JSON payload
+    await channel.httpSend('cursor-pos', { x: Math.random(), y: Math.random() })
+
+    // Binary payload (ArrayBuffer / ArrayBufferView) — sent as application/octet-stream
+    await channel.httpSend('cursor-pos', new Uint8Array([1, 2, 3]).buffer)
 
     // Remember to clean up the channel