Chat example

Need a chat box for your website? Want something more independent and affordable than Firebase? In this super simple tutorial, I’ll show you how to build a chat using Iris.

The chat is offline-first and end-to-end encrypted. It is stored and propagated using the distributed database gun.

No signup of any kind required: just generate a key pair for the chat recipient. Optionally spin up your own free heroku instance to relay messages. Cost $0.

1. Include gun, sea and iris

  • Gun: a decentralized database
  • Sea: gun’s cryptography library
  • Iris: a library for decentralized social networking
<script src=""></script>
<script src=""></script>
<script src=""></script>

Note: at the time of writing this, sea.js sha-256 is broken on Safari, so you’ll need the patched version from the script tag above.

2. Initialize gun

var gun = new Gun({peers: ['']})

You can connect to someone else’s gun node, or you can easily deploy your own.

3. Create a key for the user (chat initiator)

Generate a new key:

var key = await iris.Key.generate()

Or generate a key and store it in localStorage:

var key = await iris.Key.getDefault()

4. Get the chat recipient’s chat link

  1. Go to (Github mirror).
  2. Click “Copy your chat link”
  3. Paste:
var chatLink = [chat link here]

5. Add chat button to document

Iris library comes with an embeddable chat button & UI.

iris.Chat.addChatButton({label: 'Live Chat', chatOptions: {gun, key, chatLink}});

It’s as simple as that! Chats opened by users will now show up for the key / account you created at

Feel free to inspect the element and override the stylesheet to match your site’s look and feel.

Full example

    <title>Live Chat Example</title>
    <meta name="viewport" content="width=device-width, user-scalable=no">
    <script src=""></script>
    <script src=""></script>
    <script src=""></script>
  <body style="background: #c5c7f7">
    <script type="text/javascript">
      iris.Key.getDefault().then(key => {
        var gun = new Gun({peers: ['']});
        // replace chatLink with your own chat link from
        var chatLink = '';
        iris.Chat.addChatButton({label: 'Live Chat', chatOptions: {gun, key, chatLink}});

Check it out on Codepen or Github

If you want to improve or customize the functionality, addChatButton() source code can be found here.


Chats are persisted in users’ browsers. Heroku nodes are ephemeral: their filesystem is reset once in a while. If you want to persist the chats on a server, you can add S3 storage to your heroku gun instance, or run a docker gun node.

Disclaimer: Messages are e2e encrypted, but message timestamps currently aren’t. In a decentralized network the timestamp and message author are visible to anyone. The library has not been security audited, so don’t use it for security critical purposes.