Adding Ethora SDK to Your Node.js Backend

This guide will walk you through integrating the Ethora SDK into your existing Node.js backend application.

Table of Contents

• Prerequisites
• Installation
• Environment Configuration
• Basic Integration
• Integration Patterns
• Common Use Cases
• Error Handling
• Best Practices
• Troubleshooting

Prerequisites

• Node.js 18+ or higher
• TypeScript 5.0+ (for TypeScript projects)
• An existing Node.js backend application (Express, Fastify, NestJS, etc.)
• Ethora API credentials:
  • ETHORA_CHAT_API_URL
  • ETHORA_CHAT_APP_ID
  • ETHORA_CHAT_APP_SECRET
  • ETHORA_CHAT_BOT_JID (optional, for chatbot features)

API Documentation (Swagger)

Ethora exposes Swagger UI from every running backend instance at:

• Hosted (Ethora main): https://api.ethoradev.com/api-docs/
• Enterprise/self-hosted: https://api.<your-domain>/api-docs/

If you are running a separate staging instance, the same pattern applies (e.g. https://api.asterotoken.com/api-docs/).

Installation

Step 1: Install the Package

npm install @ethora/sdk-backend
# or
yarn add @ethora/sdk-backend
# or
pnpm add @ethora/sdk-backend

Step 2: Install Type Definitions (if using TypeScript)

The package includes TypeScript definitions, so no additional @types package is needed.

Environment Configuration

Step 1: Add Environment Variables

Add the following environment variables to your .env file or your environment configuration:

# Required
ETHORA_CHAT_API_URL=https://api.ethoradev.com
ETHORA_CHAT_APP_ID=your_app_id_here
ETHORA_CHAT_APP_SECRET=your_app_secret_here

# Optional (for chatbot features)
[email protected]

Step 2: Load Environment Variables

If you're using a .env file, ensure you have dotenv installed and configured:

npm install dotenv

In your main application file (e.g., app.js, server.js, or index.ts):

import dotenv from "dotenv";

// Load environment variables
dotenv.config();

Basic Integration

Step 1: Import the SDK

import { getEthoraSDKService } from "@ethora/sdk-backend";

Step 2: Initialize the Service

You can initialize the service in several ways:

Option A: Singleton Pattern (Recommended)

// services/chatService.ts
import { getEthoraSDKService } from "@ethora/sdk-backend";

// Get the singleton instance
const chatService = getEthoraSDKService();

export default chatService;

Option B: Direct Initialization

// In your route handler or service
import { getEthoraSDKService } from "@ethora/sdk-backend";

const chatService = getEthoraSDKService();

Option C: Dependency Injection (for frameworks like NestJS)

// chat.service.ts
import { Injectable } from "@nestjs/common";
import { getEthoraSDKService } from "@ethora/sdk-backend";

@Injectable()
export class ChatService {
  private readonly ethoraService = getEthoraSDKService();

  // Your methods here
}

Integration Patterns

Pattern 1: Express.js Integration

// routes/chat.ts
import express, { Request, Response } from "express";
import { getEthoraSDKService } from "@ethora/sdk-backend";
import axios from "axios";

const router = express.Router();
const chatService = getEthoraSDKService();

// Create a chat room for a workspace
router.post(
  "/workspaces/:workspaceId/chat",
  async (req: Request, res: Response) => {
    try {
      const { workspaceId } = req.params;
      const roomData = req.body;

      const response = await chatService.createChatRoom(workspaceId, {
        title: roomData.title || `Chat Room ${workspaceId}`,
        uuid: workspaceId,
        type: roomData.type || "group",
        ...roomData,
      });

      res.json({ success: true, data: response });
    } catch (error) {
      if (axios.isAxiosError(error)) {
        res.status(error.response?.status || 500).json({
          error: "Failed to create chat room",
          details: error.response?.data,
        });
      } else {
        res.status(500).json({ error: "Internal server error" });
      }
    }
  }
);

// Create a user
router.post("/users/:userId", async (req: Request, res: Response) => {
  try {
    const { userId } = req.params;
    const userData = req.body;

    const response = await chatService.createUser(userId, userData);
    res.json({ success: true, data: response });
  } catch (error) {
    if (axios.isAxiosError(error)) {
      res.status(error.response?.status || 500).json({
        error: "Failed to create user",
        details: error.response?.data,
      });
    } else {
      res.status(500).json({ error: "Internal server error" });
    }
  }
});

// Grant user access to chat room
router.post(
  "/workspaces/:workspaceId/chat/users/:userId",
  async (req: Request, res: Response) => {
    try {
      const { workspaceId, userId } = req.params;

      await chatService.grantUserAccessToChatRoom(workspaceId, userId);
      res.json({ success: true, message: "Access granted" });
    } catch (error) {
      if (axios.isAxiosError(error)) {
        res.status(error.response?.status || 500).json({
          error: "Failed to grant access",
          details: error.response?.data,
        });
      } else {
        res.status(500).json({ error: "Internal server error" });
      }
    }
  }
);

// Generate client JWT token
router.get("/users/:userId/chat-token", (req: Request, res: Response) => {
  try {
    const { userId } = req.params;
    const token = chatService.createChatUserJwtToken(userId);
    res.json({ token });
  } catch (error) {
    res.status(500).json({ error: "Failed to generate token" });
  }
});

// Get users
router.get("/users", async (req: Request, res: Response) => {
  try {
    const { chatName, xmppUsername } = req.query;
    const params: any = {};
    if (chatName) params.chatName = String(chatName);
    if (xmppUsername) params.xmppUsername = String(xmppUsername);

    const response = await chatService.getUsers(
      Object.keys(params).length > 0 ? params : undefined
    );
    res.json({ success: true, data: response });
  } catch (error) {
    if (axios.isAxiosError(error)) {
      res.status(error.response?.status || 500).json({
        error: "Failed to get users",
        details: error.response?.data,
      });
    } else {
      res.status(500).json({ error: "Internal server error" });
    }
  }
});

// Update users (batch)
router.patch("/users", async (req: Request, res: Response) => {
  try {
    const { users } = req.body;
    if (!Array.isArray(users) || users.length === 0) {
      return res.status(400).json({ error: "users must be a non-empty array" });
    }
    if (users.length > 100) {
      return res
        .status(400)
        .json({ error: "Maximum 100 users allowed per request" });
    }

    const response = await chatService.updateUsers(users);
    res.json({ success: true, data: response });
  } catch (error) {
    if (axios.isAxiosError(error)) {
      res.status(error.response?.status || 500).json({
        error: "Failed to update users",
        details: error.response?.data,
      });
    } else {
      res.status(500).json({ error: "Internal server error" });
    }
  }
});

export default router;

Pattern 2: NestJS Integration

// chat/chat.service.ts
import { Injectable, HttpException, HttpStatus } from "@nestjs/common";
import { getEthoraSDKService } from "@ethora/sdk-backend";
import axios from "axios";

@Injectable()
export class ChatService {
  private readonly ethoraService = getEthoraSDKService();

  async createChatRoom(workspaceId: string, roomData?: any) {
    try {
      return await this.ethoraService.createChatRoom(workspaceId, roomData);
    } catch (error) {
      if (axios.isAxiosError(error)) {
        throw new HttpException(
          {
            message: "Failed to create chat room",
            details: error.response?.data,
          },
          error.response?.status || HttpStatus.INTERNAL_SERVER_ERROR
        );
      }
      throw error;
    }
  }

  async createUser(userId: string, userData?: any) {
    try {
      return await this.ethoraService.createUser(userId, userData);
    } catch (error) {
      if (axios.isAxiosError(error)) {
        throw new HttpException(
          {
            message: "Failed to create user",
            details: error.response?.data,
          },
          error.response?.status || HttpStatus.INTERNAL_SERVER_ERROR
        );
      }
      throw error;
    }
  }

  generateClientToken(userId: string): string {
    return this.ethoraService.createChatUserJwtToken(userId);
  }
}

// chat/chat.controller.ts
import { Controller, Post, Get, Param, Body } from "@nestjs/common";
import { ChatService } from "./chat.service";

@Controller("chat")
export class ChatController {
  constructor(private readonly chatService: ChatService) {}

  @Post("workspaces/:workspaceId/rooms")
  async createChatRoom(
    @Param("workspaceId") workspaceId: string,
    @Body() roomData: any
  ) {
    return this.chatService.createChatRoom(workspaceId, roomData);
  }

  @Post("users/:userId")
  async createUser(@Param("userId") userId: string, @Body() userData: any) {
    return this.chatService.createUser(userId, userData);
  }

  @Get("users/:userId/token")
  getClientToken(@Param("userId") userId: string) {
    return { token: this.chatService.generateClientToken(userId) };
  }
}

Pattern 3: Fastify Integration

// routes/chat.ts
import { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
import { getEthoraSDKService } from "@ethora/sdk-backend";

const chatService = getEthoraSDKService();

export async function chatRoutes(fastify: FastifyInstance) {
  // Create chat room
  fastify.post(
    "/workspaces/:workspaceId/chat",
    async (request: FastifyRequest, reply: FastifyReply) => {
      const { workspaceId } = request.params as { workspaceId: string };
      const roomData = request.body as any;

      try {
        const response = await chatService.createChatRoom(
          workspaceId,
          roomData
        );
        return { success: true, data: response };
      } catch (error) {
        reply.code(500).send({ error: "Failed to create chat room" });
      }
    }
  );

  // Generate client token
  fastify.get(
    "/users/:userId/chat-token",
    async (request: FastifyRequest, reply: FastifyReply) => {
      const { userId } = request.params as { userId: string };
      const token = chatService.createChatUserJwtToken(userId);
      return { token };
    }
  );
}

Common Use Cases

Use Case 1: Workspace Setup Flow

When creating a new workspace, set up the chat room and initial users:

async function setupWorkspaceChat(
  workspaceId: string,
  userIds: string[],
  adminUserId: string
) {
  const chatService = getEthoraSDKService();

  try {
    // 1. Create chat room
    await chatService.createChatRoom(workspaceId, {
      title: `Workspace ${workspaceId}`,
      uuid: workspaceId,
      type: "group",
    });

    // 2. Create users (if they don't exist)
    for (const userId of userIds) {
      try {
        await chatService.createUser(userId, {
          firstName: "User",
          lastName: "Name",
        });
      } catch (error) {
        // User might already exist, continue
        console.warn(`User ${userId} might already exist`);
      }
    }

    // 3. Grant access to all users
    await chatService.grantUserAccessToChatRoom(workspaceId, userIds);

    // 4. Grant chatbot access (if configured)
    try {
      await chatService.grantChatbotAccessToChatRoom(workspaceId);
    } catch (error) {
      console.warn("Chatbot access not configured or failed");
    }

    return { success: true };
  } catch (error) {
    console.error("Failed to setup workspace chat:", error);
    throw error;
  }
}

Use Case 2: User Onboarding

When a new user joins your platform:

async function onboardNewUser(
  userId: string,
  userData: { firstName: string; lastName: string; email: string }
) {
  const chatService = getEthoraSDKService();

  try {
    // Create user in chat service
    await chatService.createUser(userId, {
      firstName: userData.firstName,
      lastName: userData.lastName,
      email: userData.email,
      displayName: `${userData.firstName} ${userData.lastName}`,
    });

    // Generate client token for frontend
    const clientToken = chatService.createChatUserJwtToken(userId);

    return {
      success: true,
      chatToken: clientToken,
    };
  } catch (error) {
    console.error("Failed to onboard user:", error);
    throw error;
  }
}

Use Case 3: Adding User to Existing Workspace

When adding a user to an existing workspace:

async function addUserToWorkspace(workspaceId: string, userId: string) {
  const chatService = getEthoraSDKService();

  try {
    // Ensure user exists
    try {
      await chatService.createUser(userId);
    } catch (error) {
      // User might already exist, continue
    }

    // Grant access to workspace chat room
    await chatService.grantUserAccessToChatRoom(workspaceId, userId);

    return { success: true };
  } catch (error) {
    console.error("Failed to add user to workspace:", error);
    throw error;
  }
}

Use Case 4: Cleanup on Workspace Deletion

When deleting a workspace:

async function cleanupWorkspaceChat(workspaceId: string, userIds: string[]) {
  const chatService = getEthoraSDKService();

  try {
    // Delete chat room (handles non-existent gracefully)
    await chatService.deleteChatRoom(workspaceId);

    // Optionally delete users (if they're no longer needed)
    if (userIds.length > 0) {
      try {
        await chatService.deleteUsers(userIds);
      } catch (error) {
        console.warn("Some users might not exist:", error);
      }
    }

    return { success: true };
  } catch (error) {
    console.error("Failed to cleanup workspace chat:", error);
    throw error;
  }
}

Use Case 5: Getting Users

Retrieve users from the chat service:

async function getUsersExample() {
  const chatService = getEthoraSDKService();

  try {
    // Get all users
    const allUsers = await chatService.getUsers();
    console.log(`Total users: ${allUsers.results?.length || 0}`);

    // Get users by chat name (group chat)
    const groupChatUsers = await chatService.getUsers({
      chatName: "appId_workspaceId",
    });

    // Get users by chat name (1-on-1 chat)
    const oneOnOneUsers = await chatService.getUsers({
      chatName: "userA-userB",
    });

    return { allUsers, groupChatUsers, oneOnOneUsers };
  } catch (error) {
    console.error("Failed to get users:", error);
    throw error;
  }
}

Use Case 6: Updating Users (Batch)

Update multiple users at once:

async function updateUsersExample() {
  const chatService = getEthoraSDKService();

  try {
    // Update multiple users (1-100 users per request)
    const response = await chatService.updateUsers([
      {
        xmppUsername: "appId_user1",
        firstName: "John",
        lastName: "Doe",
        username: "johndoe",
        profileImage: "https://example.com/avatar1.jpg",
      },
      {
        xmppUsername: "appId_user2",
        firstName: "Jane",
        lastName: "Smith",
        username: "janesmith",
      },
    ]);

    // Check results
    response.results?.forEach((result: any) => {
      if (result.status === "updated") {
        console.log(`User ${result.xmppUsername} updated successfully`);
      } else if (result.status === "not-found") {
        console.warn(`User ${result.xmppUsername} not found`);
      } else if (result.status === "skipped") {
        console.log(`User ${result.xmppUsername} update skipped`);
      }
    });

    return response;
  } catch (error) {
    console.error("Failed to update users:", error);
    throw error;
  }
}

Error Handling

Handling API Errors

The SDK uses Axios for HTTP requests, so errors are AxiosError instances:

import axios from "axios";
import { getEthoraSDKService } from "@ethora/sdk-backend";

const chatService = getEthoraSDKService();

async function createChatRoomSafely(workspaceId: string) {
  try {
    return await chatService.createChatRoom(workspaceId);
  } catch (error) {
    if (axios.isAxiosError(error)) {
      const status = error.response?.status;
      const errorData = error.response?.data;

      // Handle specific error cases
      if (status === 422) {
        // Validation error
        console.error("Validation error:", errorData);
      } else if (status === 401) {
        // Authentication error
        console.error("Authentication failed - check your credentials");
      } else if (status === 404) {
        // Resource not found
        console.error("Resource not found");
      } else {
        // Other HTTP errors
        console.error(`HTTP error ${status}:`, errorData);
      }
    } else {
      // Non-HTTP errors
      console.error("Unexpected error:", error);
    }
    throw error;
  }
}

Graceful Error Handling for Idempotent Operations

Some operations are idempotent and can be safely retried:

async function ensureChatRoomExists(workspaceId: string) {
  const chatService = getEthoraSDKService();

  try {
    await chatService.createChatRoom(workspaceId);
  } catch (error) {
    if (axios.isAxiosError(error)) {
      const errorData = error.response?.data;
      const errorMessage =
        typeof errorData === "object" && errorData !== null
          ? (errorData as { error?: string }).error || ""
          : String(errorData || "");

      // If room already exists, that's okay
      if (
        error.response?.status === 422 &&
        (errorMessage.includes("already exist") ||
          errorMessage.includes("already exists"))
      ) {
        console.log("Chat room already exists, continuing...");
        return; // Success - room exists
      }
    }
    // Re-throw if it's a different error
    throw error;
  }
}

Best Practices

1. Use Singleton Pattern

The SDK provides a singleton instance. Reuse it rather than creating multiple instances:

// Good
const chatService = getEthoraSDKService();

// Avoid
const chatService1 = getEthoraSDKService();
const chatService2 = getEthoraSDKService(); // Unnecessary

2. Centralize Chat Service

Create a service wrapper in your application:

// services/chatService.ts
import { getEthoraSDKService } from "@ethora/sdk-backend";
import type { ChatRepository } from "@ethora/sdk-backend";

class ChatServiceWrapper {
  private service: ChatRepository;

  constructor() {
    this.service = getEthoraSDKService();
  }

  async setupWorkspace(workspaceId: string, userIds: string[]) {
    // Your custom logic here
    await this.service.createChatRoom(workspaceId);
    // ... more setup logic
  }

  // Expose other methods as needed
  getService() {
    return this.service;
  }
}

export default new ChatServiceWrapper();

3. Environment Variable Validation

Validate environment variables on application startup:

// config/validateEnv.ts
function validateEthoraConfig() {
  const required = [
    "ETHORA_CHAT_API_URL",
    "ETHORA_CHAT_APP_ID",
    "ETHORA_CHAT_APP_SECRET",
  ];

  const missing = required.filter((key) => !process.env[key]);

  if (missing.length > 0) {
    throw new Error(
      `Missing required Ethora environment variables: ${missing.join(", ")}`
    );
  }
}

// Call on startup
validateEthoraConfig();

4. Logging Integration

Integrate with your existing logging system:

import { getEthoraSDKService } from "@ethora/sdk-backend";
import { logger } from "./utils/logger"; // Your logger

const chatService = getEthoraSDKService();

async function createChatRoomWithLogging(workspaceId: string) {
  logger.info(`Creating chat room for workspace: ${workspaceId}`);
  try {
    const result = await chatService.createChatRoom(workspaceId);
    logger.info(`Chat room created successfully: ${workspaceId}`);
    return result;
  } catch (error) {
    logger.error(`Failed to create chat room: ${workspaceId}`, error);
    throw error;
  }
}

5. Type Safety

Use TypeScript types from the SDK:

import type { UUID, ApiResponse } from "@ethora/sdk-backend";

async function createUserTyped(
  userId: UUID,
  userData: {
    firstName: string;
    lastName: string;
    email: string;
  }
): Promise<ApiResponse> {
  const chatService = getEthoraSDKService();
  return await chatService.createUser(userId, userData);
}

Troubleshooting

Issue: "Missing required environment variables"

Solution: Ensure all required environment variables are set:

ETHORA_CHAT_API_URL=https://api.ethoradev.com
ETHORA_CHAT_APP_ID=your_app_id
ETHORA_CHAT_APP_SECRET=your_app_secret

Issue: "Authentication failed" (401 errors)

Solution: Verify your ETHORA_CHAT_APP_SECRET is correct and matches your app ID.

Issue: "User already exists" errors

Solution: Handle idempotent operations gracefully:

try {
  await chatService.createUser(userId);
} catch (error) {
  if (axios.isAxiosError(error) && error.response?.status === 422) {
    // User already exists, continue
    console.log("User already exists");
  } else {
    throw error;
  }
}

Issue: "Chat room not found" during deletion

Solution: The SDK handles this gracefully. The deleteChatRoom method returns { ok: false, reason: "Chat room not found" } if the room doesn't exist, which is safe to ignore.

Issue: TypeScript compilation errors

Solution: Ensure you're using TypeScript 5.0+ and have proper type definitions:

npm install --save-dev typescript@^5.0.0

Next Steps

• Review the API Reference for detailed method documentation
• Check out the Examples directory for complete integration examples
• See the Healthcare Insurance Demo for a real-world use case

Support

For issues, questions, or contributions, please refer to the main README.md file.

TypeScript Configuration

The project uses strict TypeScript settings. See tsconfig.json for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

Apache 2.0

Support

For issues and questions, please open an issue on the GitHub repository.