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. + + +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. + + + + +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. + + + @@ -335,6 +357,12 @@ You can use the Supabase client libraries to send Broadcast messages. <$Show if="sdk:swift"> + + + Binary payloads over WebSocket are supported from supabase-swift 2.44.0. Receivers on older SDK versions will not get binary messages. + + + {/* 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 +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. ' \ -H 'Content-Type: application/json' \ - --data-raw '{ - "messages": [ - { - "topic": "test", - "event": "event", - "payload": { "test": "test" } - } - ] - }' \ - 'https://.supabase.co/realtime/v1/api/broadcast' + --data-raw '{ "test": "test" }' \ + 'https://.supabase.co/realtime/v1/api/broadcast/test/events/event' + + # Binary payload + curl -v \ + -H 'apikey: ' \ + -H 'Content-Type: application/octet-stream' \ + --data-binary @payload.bin \ + 'https://.supabase.co/realtime/v1/api/broadcast/test/events/event?private=true' ``` @@ -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" } ``` + + +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: ' \ +-H 'Content-Type: application/json' \ +--data-raw '{ + "messages": [ + { + "topic": "test", + "event": "event", + "payload": { "test": "test" } + } + ] +}' \ +'https://.supabase.co/realtime/v1/api/broadcast' +``` + + + ## 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 - 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. @@ -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