Documentation

Introduction

EchoSDK is a headless, developer-centric support platform designed to replace expensive, "seat-based" support platforms. By leveraging RAG (Retrieval-Augmented Generation) and a pay-as-you-go model, we enable developers to build high-performance support directly into their own UI.

Key Features

Headless SDK

A "drop-in" React component that lives in your codebase. It supports adaptive theming to match your brand and is context-aware to provide smarter AI resolutions.

Ingestion & RAG Pipeline

Point the SDK at any documentation URL to train the AI instantly. It uses Firestore Vector Search and Gemini 2.5 Flash Lite for high-accuracy, low-latency responses.

Smart Human Handover

Notifications are sent directly to your Slack channel with contextual handoff, including the user's question and failed AI sources.

Getting Started

1. CLI Setup (Recommended)

The fastest way to connect your app to EchoSDK:

# Authenticate once — opens a browser window
npx echosdk login

# Link or create a Chat App in your project directory
npx echosdk init

# Install the SDK
npm install @echosdk/react

init writes echo.config.json with your appId and appends NEXT_PUBLIC_ECHOSDK_APP_ID to .env.local if it exists.

CLI Commands

npx echosdk loginAuthenticate via browser (one-time)

npx echosdk initGenerate echo.config.json for this project

npx echosdk whoamiShow the logged-in account

npx echosdk logoutRemove stored credentials

2. React Usage

import { EchoChat } from '@echosdk/react';
import '@echosdk/react/dist/style.css';

function App() {
  return (
    <div>
      <YourApp />
      <EchoChat appId="your-app-id" />
    </div>
  );
}

3. Next.js Usage

// app/layout.tsx
import { EchoChat } from '@echosdk/react';
import '@echosdk/react/dist/style.css';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <EchoChat appId={process.env.NEXT_PUBLIC_ECHOSDK_APP_ID!} />
      </body>
    </html>
  );
}

Props

Prop	Type	Default	Description
appId	string	required	Your EchoSDK application ID
apiUrl	string	https://echosdk.com	Custom API endpoint
theme	'light' \| 'dark' \| 'auto'	'auto'	Color theme
position	'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'	'bottom-right'	Chat bubble position
primaryColor	string	#3B82F6	Primary brand color
placeholder	string	'Type your message...'	Input placeholder text
greeting	string	'Chat with us'	Chat window title
userName	string	-	User's name
userEmail	string	-	User's email
metadata	object	-	Additional context data
onMessage	(message: Message) => void	-	Message callback
onError	(error: Error) => void	-	Error callback

Security

Credential	What it is	Safe in client bundle?	Recommended env var
appId	Public app identifier	Yes	NEXT_PUBLIC_ECHOSDK_APP_ID
apiKey	Secret Bearer token	No	ECHOSDK_API_KEY

apiKey is used with EchoSDKClient for server-side proxy patterns (e.g. a Next.js Route Handler). Never place it in a NEXT_PUBLIC_ variable or any client-side bundle.

Server-side Usage

// app/api/echo/route.ts — server-side only
import { EchoSDKClient } from '@echosdk/react';

const client = new EchoSDKClient({
  appId: process.env.NEXT_PUBLIC_ECHOSDK_APP_ID!,  // public — NEXT_PUBLIC_ is fine
  apiKey: process.env.ECHOSDK_API_KEY,              // secret — no NEXT_PUBLIC_ prefix
});

Theming

Customize the appearance using props and CSS variables:

<EchoChat
  appId="your-app-id"
  theme="dark"
  primaryColor="#8B5CF6"
  style={{
    '--echo-border-radius': '8px',
    '--echo-font-family': 'Inter, sans-serif',
  } as React.CSSProperties}
/>

Available CSS Variables

--echo-primary-color
--echo-background
--echo-surface
--echo-text-primary
--echo-text-secondary
--echo-border
--echo-border-radius
--echo-font-family

Advanced Usage

Using Hooks

import { useChat } from '@echosdk/react';

function CustomChat() {
  const [state, actions] = useChat('your-app-id');

  return (
    <div>
      <button onClick={actions.toggleChat}>Toggle Chat</button>
      <div>Messages: {state.messages.length}</div>
    </div>
  );
}

Event Callbacks

<EchoChat
  appId="your-app-id"
  onMessage={(message) => {
    console.log('New message:', message);
  }}
  onError={(error) => {
    console.error('Chat error:', error);
  }}
/>

TypeScript

import type { Message, ChatState, EchoChatProps } from '@echosdk/react';