Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs: document binary broadcast messages (#46668)

Eduardo Gurgel8af2bb0cda6f
diff --git a/apps/docs/content/guides/realtime/broadcast.mdx b/apps/docs/content/guides/realtime/broadcast.mdx
index a6f73498569..6714da11eca 100644
--- a/apps/docs/content/guides/realtime/broadcast.mdx
+++ b/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