SDK Documentation

Build with EchoAI

Integrate intelligent AI chat assistants into your website with just a few lines of code.

Quick Start

Get your EchoAI assistant running in under 2 minutes with these simple steps.

Add the SDK Script

Include the Echo SDK script in your HTML file before the closing </body> tag.

HTML

<script src="https://cdn.echoaichat.com/sdk/echo-sdk.js"></script>

Initialize the Widget

Create a new EchoSDK instance with your assistant identifier.

JavaScript

const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762'
});

You're all set!

Your EchoAI assistant is now ready. The widget will load in the element with ID #echo-chat.

Installation

Complete HTML example to get you started quickly.

HTML

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Website</title>
</head>
<body>
  <!-- Your website content -->

  <!-- Echo Chat Container -->
  <div id="echo-chat" style="height: 500px;"></div>

  <!-- Echo SDK -->
  <script src="https://cdn.echoaichat.com/sdk/echo-sdk.js"></script>
  <script>
    const echoWidget = new EchoSDK({
      container: '#echo-chat',
      assistantIdentifier: 'dovjmm372762',
      height: '100%'
    });
  </script>
</body>
</html>

Live Preview

Configure the widget options below and see changes in real time. The generated code updates automatically.

Height

Auto Focus

Input Placeholder

User Context

Display Text

Sources Label

Searching Text

Tools Text

Loading Text

Override Starter Questions

JavaScript

Live demo

This widget connects to a real EchoAI assistant. Change the options and click "Apply & Reload" to see the result.

Core Options

Essential configuration options for your Echo widget.

Option	Type	Description
`container` Required	string \| Element	CSS selector or DOM element where the chat will be mounted
`assistantIdentifier` Required	string	Your unique assistant identifier from the Echo dashboard
`height` Optional	string \| number	Widget height (e.g., "500px", "100%", 500)
`autoFocus` Optional	boolean	Auto-focus input field on load. Default: `false`
`userContext` Optional	string	Additional context about the user (max 1000 chars)
`starterQuestions` NEW	Array	Override default starter questions (max 5)
`onError` Optional	function	Error callback: `(error: Error) => void`

Text Customization

Customize UI text with the textConfig option.

JavaScript

const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  textConfig: {
    inputPlaceholder: 'Ask me anything...',
    sourcesLabel: 'Knowledge Sources',
    searchingText: 'Searching...',
    toolsText: 'Processing...',
    loadingText: 'Thinking...'
  }
});

Property	Type	Description
`inputPlaceholder`	string	Placeholder text for the input field
`sourcesLabel`	string	Label for knowledge sources section
`searchingText`	string	Text shown while searching
`toolsText`	string	Text shown while processing tools
`loadingText`	string	Text shown while loading response

Floating Button

Display the chat as a floating button that opens a popup.

JavaScript

const echoWidget = new EchoSDK({
  assistantIdentifier: 'dovjmm372762',
  floatingButton: {
    enabled: true,
    position: 'bottom_right',
    tooltip: 'Chat with us!',
    width: '400px',
    height: '600px'
  }
});

Property	Type	Description
`enabled`	boolean	Enable floating button mode
`position`	string	`bottom_right` \| `bottom_left` \| `top_right` \| `top_left`
`icon`	string	Custom icon URL
`tooltip`	string	Tooltip text on hover
`width` / `height`	string \| number	Popup dimensions

Starter Questions

Override default starter questions to customize the initial chat experience.

What are Starter Questions?

Starter questions appear when users first open the chat, providing quick conversation starters. Override them via the SDK for page-specific customization.

Basic Usage

JavaScript

const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  starterQuestions: [
    { question: 'What are your pricing plans?' },
    { question: 'How do I get started?' },
    { question: 'Can I see a demo?' }
  ]
});

Behavior

Maximum 5 questions — Additional questions are ignored
Max 200 characters — Longer text is truncated
Empty array [] — Hides all starter questions
Undefined — Uses default questions from dashboard

Page-Specific Example

JavaScript

// Dynamic questions based on current page
function getStarterQuestions() {
  const path = window.location.pathname;

  if (path.includes('/pricing')) {
    return [
      { question: 'Compare pricing plans' },
      { question: 'Do you offer discounts?' },
      { question: 'Enterprise options?' }
    ];
  }

  if (path.includes('/docs')) {
    return [
      { question: 'How do I install the SDK?' },
      { question: 'Show me code examples' }
    ];
  }

  // Use dashboard defaults
  return undefined;
}

const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  starterQuestions: getStarterQuestions()
});

Note

SDK-provided questions override dashboard settings. Changes in your dashboard won't affect pages using overrides.

User Context

Pass metadata about the current user or session to the AI assistant. The context is injected into the AI's system prompt, enabling personalized responses without users repeating information.

How it works

The AI receives your context as known metadata and will use it to answer questions directly — without calling knowledge retrieval tools. For example, if you pass a user's plan tier, the AI can immediately answer "What plan am I on?" from context alone.

Plain Text

JavaScript

const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  userContext: 'Company size: 50-100 employees, Industry: Healthcare, Plan: Enterprise'
});

JSON Format (Recommended)

For structured data, use JSON.stringify(). This gives the AI clearly labeled fields to reference.

JavaScript

// Structured context with JSON (recommended)
const user = await fetchCurrentUser();

const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  userContext: JSON.stringify({
    userId: user.id,
    membershipTier: 'gold',
    companySize: '50-100 employees',
    accountAge: '2 years',
    cartItems: 3,
    rewardPoints: 1250
  })
});

Dynamic Context

Build context from your application state at initialization time.

JavaScript

// Dynamic context based on application state
function buildContext() {
  const user = getCurrentUser();
  const cart = getCartState();

  return JSON.stringify({
    name: user.firstName,
    plan: user.subscription.plan,
    cartTotal: cart.total,
    itemCount: cart.items.length,
    preferredLanguage: user.locale
  });
}

const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  userContext: buildContext()
});

Limits & Rules

Aspect	Detail
Max length	1000 characters — exceeding throws an error
Type	String only (plain text or JSON)
Scope	Per conversation thread — set at creation, cannot be updated mid-conversation
Validation	Enforced both client-side (SDK) and server-side (API)

Best Practices

Use identifiers instead of full names (userId: "user_123")
Include non-sensitive metadata: plan tier, company size, preferences
Use JSON format for structured data
Only include data that improves AI responses

Don't

Include passwords, SSN, or credit card numbers
Store highly sensitive PII
Include data users wouldn't want the AI to know
Pass API keys or credentials

Code Examples

Common integration patterns for different use cases.

Embedded Widget

JavaScript

const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  height: '600px',
  autoFocus: true,
  textConfig: {
    inputPlaceholder: 'Ask me anything...',
    sourcesLabel: 'References'
  }
});

With User Context

JavaScript

// Personalize based on logged-in user
const user = getCurrentUser();

const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  userContext: `Name: ${user.name}, Plan: ${user.plan}`,
  starterQuestions: [
    { question: 'How do I upgrade my plan?' },
    { question: "What's new in my account?" }
  ]
});

Full Configuration

JavaScript

const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  height: '100%',
  autoFocus: true,

  textConfig: {
    inputPlaceholder: 'How can I help you today?',
    sourcesLabel: 'Knowledge Sources',
    searchingText: 'Searching...',
    toolsText: 'Processing...',
    loadingText: 'Generating response...'
  },

  userContext: 'Premium user, prefers detailed answers',

  urlContextOptions: {
    autoDetect: true
  },

  starterQuestions: [
    { question: "What's new this week?" },
    { question: 'Show me advanced features' },
    { question: 'API integration guide' }
  ],

  onError: (error) => {
    console.error('Echo SDK error:', error);
  }
});