Full disclosure before we start: Ethora is our product. This site is run by the team that builds it, so treat this as the honest quick-start from the people who maintain the code, not an impartial review. We have written plenty of neutral roundups elsewhere on this site. This one is the tutorial for our own SDK, and we will tell you plainly where it fits and where it does not.
This post originally went up in early 2024 under the old “Ethora engine” branding, back when the pitch leaned heavily on digital wallets and web3. A lot has changed since then. Ethora today is an open source chat and AI SDK: real-time messaging, group chats, file sharing, and AI agents you can drop into your own product. The wallet and blockchain pieces still exist under the hood for teams that want them, but the front door is chat. So here is the rewritten, current version of the tutorial.
What we are building
The goal is the simplest useful thing: a React web app with a working chat room in it. Real users, real messages, message history, all backed by a real chat server rather than a mocked-in-memory array. You should be able to go from an empty folder to sending messages in well under an hour, most of which is npm doing its thing.
The building block is @ethora/chat-component, our React chat widget on npm. It is a prebuilt component: it renders the message list, the input, attachments, and the connection logic, and talks to an Ethora server instance behind the scenes. You point it at an app ID and it handles login, rooms, and message delivery. Under the hood the platform runs on XMPP (the same protocol family WhatsApp started from) with a REST API layer over it for user management, apps, and files. You do not need to know any XMPP to use the component, but it is nice to know the transport is a battle-tested standard rather than something invented last quarter.
Why an SDK instead of building it yourself
We keep a whole comparison of the options in our best chat SDK roundup, so we will not rehash the vendor landscape here. But the build-vs-buy question deserves a straight answer, because “just use socket.io” is the most common trap in this category.
A weekend prototype with WebSockets is genuinely easy. What is not easy is everything after the prototype: message history and pagination, delivery and read state, offline queueing, reconnection that does not drop messages, push notifications, file uploads with access control, moderation, multi-device sync, and the ops work of keeping a stateful real-time server healthy under load. Each of those is a small project. Together they are a team’s quarter, and none of them are your product. That is the case for using any mature SDK, ours or a competitor’s.
Where Ethora specifically fits: it is open source and self-hostable. If your objection to the usual commercial chat SDKs is per-user pricing that scales painfully, or a compliance requirement that says message data cannot live on a third-party cloud, that is exactly the gap we built for. You can start on the free cloud tier and later move the whole thing onto your own AWS account or Docker host without rewriting your frontend. If you just want a hosted API and do not care where data lives, the commercial vendors in our roundup are perfectly good choices too.
Step 1: Create a React project
Any modern React setup works. Vite is the least ceremony:
npm create vite@latest ethora-chat-app -- --template react-ts
cd ethora-chat-app
npm install
Next.js works as well; just remember the chat component is client-side, so render it in a client component.
Step 2: Install the chat component
npm install @ethora/chat-component
That is the entire dependency story for the frontend. No separate socket library, no state management addon for messages, no manual token juggling in your components.
Step 3: Get an app ID
The component needs to know which Ethora app (workspace) it belongs to. Sign up at ethora.com, create an app in the admin panel, and copy its app ID. Alternatively, run our setup CLI, which provisions credentials and drops them into a config file for you:
npx @ethora/setup
Either way you end up with an app ID string. Keep it in an environment variable rather than hardcoding it, out of habit if nothing else. The app ID is not a secret in the password sense, but config belongs in config.
Step 4: Render the chat
Minimal usage looks like this:
import { Chat } from "@ethora/chat-component";
function App() {
return (
<div style={{ height: "100vh" }}>
<Chat config={{ appId: import.meta.env.VITE_ETHORA_APP_ID }} />
</div>
);
}
export default App;
One honest caveat: the component evolves, and prop names have changed between versions before. Treat the snippet above as the shape of the integration, and check the README on the npm page or the GitHub repo for the current props before you copy-paste. The config object is where you control theming, which room to open, whether users log in with their own accounts or as guests, and similar behavior. The docs list the current surface; we would rather point you there than have this article confidently describe an API from two versions ago, which is exactly the failure mode the 2024 version of this post fell into.
Run npm run dev, open the app in two browser windows, and send yourself a message. That is the whole core loop working: the component connects to the Ethora cloud, authenticates, joins the room, and messages flow with history persisted server-side.
Step 5: Make it yours
From here the work is product work, not plumbing. The usual next moves:
- Wire in your own users. Instead of Ethora’s login screen, pass your existing authenticated user through so chat identity matches app identity. The REST API layer handles user creation and tokens.
- Theme it. Colors, layout, and branding are configurable so the widget stops looking like a demo and starts looking like your app.
- Control the rooms. Create rooms per project, per order, per patient, per whatever your domain object is, via the API, and point the component at the right one.
Where to go next
Self-hosting. Everything the cloud tier runs is open source. When you outgrow the hosted option, or your legal team asks where the messages live, you can deploy the server side yourself via Docker or AWS. Your React code keeps working; you change the endpoint config, not the frontend.
React Native. If you need the same chat in a mobile app, there is a React Native SDK that talks to the same backend, so web and mobile users share rooms and history. Start with the repo’s SDK section; the concepts carry over directly from what you built here.
AI agents. This is where Ethora has moved furthest since the 2024 version of this article. You can add LLM-powered bots to any room: support assistants, RAG bots answering from your docs, or automation that reacts to messages. The AI SDK covers this, including self-hosted LLM setups for teams that cannot send chat data to third-party model APIs.
If you build something with it, the GitHub repo is the right place for issues and questions. We read them. That is one of the quieter advantages of using an SDK from a team small enough to answer its own issue tracker.