> For the complete documentation index, see [llms.txt](https://dnotifier.gitbook.io/product-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dnotifier.gitbook.io/product-docs/realtime-communication/binary-messaging.md).

# Binary messaging

Send **raw byte buffers** without JSON structure using `sendBinary()`. Use this for custom protocols, efficient op streams, or payloads that do not fit the structured `send()` model.

{% hint style="info" %}
For images, audio, and documents in chat apps, prefer [**Structured payloads**](https://github.com/smartguy6666/dnotifier-sdk/blob/main/docs/realtime-communication/binary-messaging/structured-payloads/README.md) via `send()` — your `onMessage` handler gets a typed JSON body. Use `sendBinary()` when you control both ends of a custom binary format.
{% endhint %}

***

## `sendBinary()` contract

| Field         | Required | Description                                         |
| ------------- | -------- | --------------------------------------------------- |
| `senderId`    | Yes      | Must match the connecting user's `userId`           |
| `receiverIds` | Yes      | Array of target user IDs                            |
| `buffer`      | Yes      | Raw bytes (`Uint8Array` in JS, `List<int>` in Dart) |
| `type`        | No       | Frame type hint (default `"binary"`)                |

Unlike `send()`, `sendBinary()` always requires `receiverIds` (array form).

***

## When to use `sendBinary` vs `send`

| Use `send()`                              | Use `sendBinary()`                        |
| ----------------------------------------- | ----------------------------------------- |
| Chat text, images, audio, docs            | Custom binary protocol                    |
| JSON-serializable data                    | Game state, CRDT ops, compressed streams  |
| Automatic chunking of structured payloads | Low-level framed bytes you parse yourself |

Both methods chunk large buffers automatically.

***

## Receiving binary

Binary frames arrive in `onMessage`. Inspect `metadata.type` and use `payload.raw()` when the body is not JSON:

```js
onMessage: (msg) => {
  if (msg.metadata.type === "binary") {
    const bytes = msg.payload.raw();
    handleCustomBinary(bytes);
    return;
  }
  const body = msg.payload.toJSON();
  // structured send() payloads
},
```

***

## Language guides

| Language                | Guide                                                                                                      |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
| JavaScript / TypeScript | [javascript-typescript.md](/product-docs/realtime-communication/binary-messaging/javascript-typescript.md) |
| Dart / Flutter          | [dart-flutter.md](/product-docs/realtime-communication/binary-messaging/dart-flutter.md)                   |

***

## Related topics

* [Structured payloads](https://github.com/smartguy6666/dnotifier-sdk/blob/main/docs/realtime-communication/binary-messaging/structured-payloads/README.md)
* [Large messages & chunking](https://github.com/smartguy6666/dnotifier-sdk/blob/main/docs/realtime-communication/binary-messaging/chunking.md)
* [Multiple receivers](https://github.com/smartguy6666/dnotifier-sdk/blob/main/docs/realtime-communication/binary-messaging/multiple-receivers/README.md)