The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
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.mdxindex 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/pYou 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>+<Tabsscrollablesize="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>+<Tabsscrollablesize="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 */}```swiftlet 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.<Tabsscrollable@@ -457,19 +505,19 @@ You can send a Broadcast message by making an HTTP request to Realtime servers.{/* prettier-ignore */}```bash+ # JSON payloadcurl -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.1Host: {PROJECT_REF}.supabase.coContent-Type: application/jsonapikey: {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 optionsYou 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