Documentation / /
Web APIs

datPeers API

datPeers is an experimental API for sending and receiving messages between peers on a given dat:// website. It includes methods for attaching “session data” to your connection. This session data can be used to broadcast a username, profile URL, or other identifying information.

To use this API, include the following in your dat.json manifest file:

{
  "experimental": {
    "apis": ["datPeers"]
  }
}

Security and privacy

Users of the datPeers API should be conscious of its limited properties. This API is designed to be a minimal stopgap solution while better tools are developed. This “minimal design” is reflected by its limited privacy, security, and reliability.

With this API, you should expect:

  • No privacy. The messages and session data are not kept private on the network.
  • No security. The messages and session data could be modified by an intermediary.
  • No reliability. Messages may not reach their intended destination.

This API is experimental and temporary. We suggest you avoid any use-cases that depend on privacy or reliability.

Methods

experimental.datPeers.getSessionData()

Fetch the session data attached to your identity on the network. Will be undefined until a value is set using setSessionData().

  • returns Promise<Any>

Example:

var sessionData = await experimental.datPeers.getSessionData()

experimental.datPeers.setSessionData(sessionData)

Set the session data attached to your identity on the network.

  • sessionData Any. The data you wish to have attached to your identity. Must be no larger than 256 bytes when serialized to JSON.
  • returns Promise<void>

Example:

await experimental.datPeers.setSessionData({
  name: 'Bob',
  url: 'dat://bob.com'
})

Session data is not private, not guaranteed to be correct, and could be modified by an intermediary on the network. See Security and privacy for more information.

experimental.datPeers.list()

List the connected peers.

  • returns Promise<DatPeer>. See DatPeer for more information.

Example:

var peers = await experimental.datPeers.list()

experimental.datPeers.get(id)

Get a connected peer by their ID.

  • id String. The ID of the peer.
  • returns Promise<DatPeer>. See DatPeer for more information.

Example:

var peer = await experimental.datPeers.get(peerId)

experimental.datPeers.broadcast(message)

Broadcasts a message to all connected peers.

  • message Any. The message to broadcast.
  • returns Promise<void>

Example:

await experimental.datPeers.broadcast({hello: 'world!'})

Messages are not private and could be modified by an intermediary on the network. See Security and privacy for more information.

Events

Event: "connect"

A new peer has connected to the current site.

  • event.peer DatPeer. The connecting peer.

Example:

experimental.datPeers.addEventListener('connect', ({peer}) => {
  console.log(peer.id, 'has connected')
})

Event: "disconnect"

A peer has disconnected from the current site.

  • event.peer DatPeer. The disconnecting peer.

Example:

experimental.datPeers.addEventListener('disconnect', ({peer}) => {
  console.log(peer.id, 'has disconnected')
})

Event: "message"

A message has been received from a peer.

  • event.peer DatPeer. The messaging peer.
  • event.message Any. The message.

Example:

experimental.datPeers.addEventListener('message', ({peer, message}) => {
  console.log(peer.id, 'has sent the following message:', message)
})

Messages are not private and could be modified by an intermediary on the network. See Security and privacy for more information.

Event: "session-data"

A peer has updated their session data.

  • event.peer DatPeer. The disconnecting peer.

Example:

experimental.datPeers.addEventListener('session-data', ({peer}) => {
  console.log(peer.id, 'has set their session data to', peer.sessionData)
})

DatPeer

id

The ID of the peer. This ID is randomly generated and should not be saved.

sessionData

The session data set by the peer.

send(message)

Send a message to the peers.

  • message Any. The message to send.
  • returns Promise<void>

Example:

var peer = await experimental.datPeers.get(datPeerId)
await peer.send({hello: 'friend!'})

Messages are not private and could be modified by an intermediary on the network. See Security and privacy for more information.