Sending Messages

Send any JSON-serializable value with .send(). Messages are relayed to all other connected clients.

Note: The server never stores or logs message content.

Basics

Strings, objects, arrays — anything that survives JSON.stringify:

// send anything JSON-serializable
channel.send('hello world')
channel.send([1, 2, 3])
channel.send({ x: 100, y: 200 })

Typed Messages

Include a type field in your message to enable type-based routing on the receiving end:

// send a typed message — the `type` field is used for routing
channel.send({ type: 'chat', text: 'hello!' })
channel.send({ type: 'move', x: 100, y: 200 })
channel.send({ type: 'reaction', emoji: '🔥', targetId: 42 })

Receivers can then listen for specific types with .on('chat', ...) or .on('move', ...) instead of handling everything in a single 'message' listener.

Direct Messages

Send a private message to a specific user by passing their uid as the second argument. Only that user receives it — it is not broadcast to the channel.

// send a private message to a specific user
channel.send('hey, just between us', 'abc123')

// works with objects too
channel.send({ type: 'invite', room: 'vip' }, 'abc123')

You can get a user's uid from join events (with announce: true) or from any message they send.

Push (Send & Close)

Use .push() to send a message and immediately disconnect — useful for fire-and-forget patterns:

// send a message, then immediately disconnect
channel.push('goodbye!')

// useful for fire-and-forget patterns
connect('analytics:events')
  .push({ event: 'signup', userId: 123 })

HTTP Push

Send a message to a channel via HTTP — no WebSocket connection needed. This is ideal for server-to-server messaging, webhooks, or any backend that needs to push updates to connected clients.

Requires a namespace with a sendKey. Pass the key in the x-send-key header.

The request body is the message — send any valid JSON value (string, object, array, number, etc.) directly as the body.

await fetch('https://itty.ws/push/myapp:alerts', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'x-send-key': 'your-send-key',
  },
  body: JSON.stringify({ type: 'alert', text: 'Server restarted' }),
})

curl -X POST https://itty.ws/push/myapp:alerts \
  -H "x-send-key: your-send-key" \
  -d '{"type":"alert","text":"Server restarted"}'

The message is broadcast to all connected clients on the channel, formatted identically to WebSocket messages (but without a uid or alias).

Next: Receiving Messages — listen for messages with type routing and filter functions.