Introducing, 3Box Chatbox Plugin

Drop-in chatrooms for your decentralized app

Simple, Scalable, Decentralized Chatrooms

As part of our mission to help developers build better applications, 3Box is creating a rich plugin ecosystem that simplifies the web3 development experience.

Chatbox is a 3Box plugin which enables dapp developers to add chatrooms to their react Ethereum application with a few lines of code.

Getting Started with Chatbox

• Try the Demo 🎉
• Try it on 3Box Hub 3️⃣
• Read the Docs 📚

Why use Chatbox?

Deliver a more social, mainstream user experience.
After building and using dapps on Ethereum for 3+ years, we recognized that most have failed to extend functionality beyond the pseudonymous, financial, on-chain, buy/sell/transfer use cases; and this is a root cause of low engagement.

While these asset-driven use cases are a great start, and native to blockchains, most activity on mainstream applications today is more social and less financial in nature. With Chatbox, we wanted to provide simple social functionality that drives everyday engagement on dapps.

Think about how often you make trades in your brokerage account vs. how often you chat with others online. When designing Chatbox, we couldn’t help but think back to the volume of engagement that the Poloniex trollbox drove to their exchange.

Real-time decentralized messaging, no gas needed.
Chatbox is built using the 3Box Ghost Threads API (more on this below), which is a framework and system for performant, in-memory, decentralized messaging that does not use the blockchain. Instead Chatbox relies on IPFS and libp2p, which means that messages are real-time and there is no cost or wait times.

Build better apps, faster.
Chatbox, with its simple drop-in functionality, makes it easier than ever to experiment with social web3 development. And Chatbox isn’t just a toy; it’s fully-featured out-of-the-box and can scale with your application into production.

Customize your Chatbox

Our goal with Chatbox was to provide a simple, standard base react component that can be used out-of-the-box in your Ethereum application. However we realize that the standard implementation may not be completely sufficient for those looking for more control over their user experience.

For this reason, we designed the component to be customizable to your needs. Below are some available options. For more customization options, see the final section in this post on How to Build with Chatbox.

Decide on a pop-up or in-page component.
You can configure your Chatbox to be displayed as a pop-up modal (shown above), or as an embedded in-page element depending on the user experience you wish to provide.

Swap in your app’s name, image/logo, and color.
The standard component uses generic design, including a basic name “Chatbox”, chat bubble icon, and the color black. While this design can be sufficient, you may want to brand the component to better match your application. You can swap in your application’s name, image, and color scheme for a more personalized experience.

How did we build Chatbox?

3Box Chatbox is built using 3Box infrastructure, 3Box Ghost Threads (read our recent blog post), and handles all 3Box and web3 logic for creating a Chatbox.

Architecture

Chatbox is built using a standard implementation of 3Box Ghost Threads which are defined in the 3Box Threads API and made available via the 3Box.js SDK.

As with all Ghost Threads, Chatbox messages are sent from one peer to other peers presently connected to the network using IPFS/libp2p pubsub and are then stored in-memory by online peers. When new users come online, they request a message backlog from others. The message backlog is persisted as long as there is at least one user in the Chatbox, however if all users go offline then the history will disappear.

The Chatbox plugin includes UI for an embedded in-window or pop-up chatroom along with all relevant logic. The component is configurable to various authentication patterns, and can handle both Web3/3Box logged-in and logged-out states.

Authentication

Chatbox messages cannot be read until a user has authenticated their 3Box, authenticated the Space, and joined the Chatbox’s Ghost Thread. After authenticating and joining, a user can post and receive messages from other users in real-time.

How to Build with Chatbox

1. Install the Chatbox component
2. Choose your authentication pattern
3. Configure applications settings
4. Usage

1. Install the Chatbox component

npm i -S 3box-chatbox-react

2. Choose your authentication pattern

Depending on when and how your dapp handles authentication for web3 and 3Box, you will need to provide a different set of props to the Chatbox component.

Three acceptable authentication patterns and their respective props are discussed below in A-C:

A) Dapp handles web3 and 3Box logins, and they run before component is mounted. (recommended)

Dapp integrates with 3Box.js SDK and the 3box-chatbox-react component.

In this case, the box instance returned from calling the Box.openBox(ethAddr) method via 3Box.js should be passed to the box prop in the Chatbox component. The user's current Ethereum address should be passed to the currentUserAddr prop to determine which messages are their own.

B) Dapp handles web3 and 3Box logins, but they haven’t run before component is mounted. (recommended)

Dapp integrates with 3Box.js SDK and the 3box-chatbox-react component.

In this case, the login logic implemented in the dapp should be passed to the Chatbox component as the loginFunction prop, which is run when a user attempts to post a comment. The user's current Ethereum address should be passed to the currentUserAddr prop to determine which messages are their own.

C) Dapp has no web3 and 3Box login logic.

Dapp only integrates with the 3box-chatbox-react component, but not 3Box.js SDK.

All web3 and 3Box login logic will be handled within the Chatbox component, though it’s required that the ethereum object from your dapp's preferred web3 provider be passed to the ethereum prop in the component. In this instance, authentication will occur when a user attempts to join a chatroom.

Best Practice for Authentication

For the best UX, we recommend implementing one of the following authentication patterns: A; B; or B with A.

These patterns allow your application to make the box object available in the global application state where it can be used by all instances of the Chatbox component regardless of which page the user is on. This global pattern removes the need for users to authenticate on each chatbox component, should you decide to have more than one, which would be the case in C.

3. Configure application settings

First, choose a name for your application’s 3Box space.

Logically, 3Box threads exist and are accessed inside of 3Box spaces, and you will need to choose a name for the space to be used by your application’s threads. Although you are free to choose whichever name you’d like for your app’s space, we recommend using the name of your app. If your application already has a 3Box space, you are welcome to use that same one for the Chatbox.

Next, choose a naming convention for your application’s threads.

The Chatbox thread needs a name, and we recommend that your application creates threadNames according to a simple rule. We generally like using a natural identifier, such as community name, page URL, token ID, or other similar means.

4. Usage

import ChatBox from '3box-chatbox-react';

const MyComponent = ({ handleLogin, box, ethereum, myAddress, currentUser3BoxProfile, adminEthAddr }) => (
    <ChatBox 
        
        // required
        spaceName="mySpaceName"
        threadName="myThreadName"


        // Required props for context A) & B)
        box={box}
        currentUserAddr={myAddress}

        // Required prop for context B)
        loginFunction={handleLogin}

        // Required prop for context C)
        ethereum={ethereum}

        // optional
        mute={false}
        popupChat
        showEmoji
        colorTheme="#181F21"
        currentUser3BoxProfile={currentUser3BoxProfile}
        userProfileURL={address => `https://mywebsite.com/user/${address}`}
        spaceOpts={}
        threadOpts={}
        agentProfile={
            chatName: "3Box",
            imageUrl: "https://imgur.com/RXJO8FD"
        }
    />
);

Prop Types

Here’s a list of all the props used in the 3Box Chatbox component: spaceName, threadName, box, currentUserAddr, loginFunction, ethereum,popupChat, agentProfile, spaceOpts, threadOpts, colorTheme, mute, showEmoji, currentUser3BoxProfile, userProfileURL.

For more information on any of the prop types, view our docs.

Explore our other plugins

We’re working towards creating an ecosystem of 3Box and third-party plugins that make using 3Box APIs (identity, profiles, storage, messaging) as simple and easy as possible.

Explore the Profile Hover plugin

Explore the Comments plugin

Questions? Reach out on Discord!

We’re always online and available to chat in Discord if you have any questions about using our plugins.