> 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/python.md).

# Python

Send raw bytes with `send_binary()`.

***

## Basic example

```python
import asyncio
from dnotifier import DNotifier

async def main():
    notifier = DNotifier(
        app_id="your-app-id",
        secret="your-app-secret",
        transport="ws",
        user_id="user-alice",
        on_connected=lambda: None,
        on_message=lambda msg: _handle_message(msg),
    )

    await notifier.connect()

    await notifier.send_binary(
        sender_id="user-alice",
        receiver_ids=["user-bob"],
        buffer=bytes([0x00, 0x01, 0x02, 0xFF]),
    )

    await asyncio.sleep(3600)

def _handle_message(msg):
    if msg.metadata.type == "binary":
        raw = msg.payload.raw()
        print(f"Binary frame: {len(raw)} bytes")
        return
    print(msg.payload.to_json())

asyncio.run(main())
```

***

## Multiple receivers

```python
await notifier.send_binary(
    sender_id="user-alice",
    receiver_ids=["user-bob", "user-carol"],
    buffer=compressed_state_bytes,
)
```

***

## Custom protocol example

```python
import struct

def encode_cursor_op(x: float, y: float) -> bytes:
    return struct.pack("ff", x, y)

await notifier.send_binary(
    sender_id=my_user_id,
    receiver_ids=[peer_user_id],
    buffer=encode_cursor_op(120.5, 340.0),
)
```

Receiver:

```python
def on_message(msg):
    raw = msg.payload.raw()
    x, y = struct.unpack("ff", raw)
    update_peer_cursor(x, y)
```

***

## Note

For chat images and files, prefer `send()` with structured `data` — it integrates better with history and UI rendering. Reserve `send_binary()` for custom sync protocols.

***

## Troubleshooting

| Issue                                | Check                                        |
| ------------------------------------ | -------------------------------------------- |
| Receiver gets JSON instead of binary | Confirm you called `send_binary`, not `send` |
| `ValueError` on receiver\_ids        | Pass a non-empty list                        |
| Garbled bytes on receive             | Use `payload.raw()`, not `to_json()`         |

***

## Learn more

* [Structured payloads](https://dnotifier.gitbook.io/product-docs/realtime-communication/structured-payloads/python.md)
* [Large messages & chunking](https://dnotifier.gitbook.io/product-docs/realtime-communication/chunking.md)
