Documentation

Learn how to integrate Echoes into your application and start collecting feedback in minutes.

Quick Start

Create a Project

Get Your API Key

Generate an API key from your project settings.

Send Feedback

Use the API or SDK to send feedback from your app.

Authentication

All API requests require authentication using an API key. Include your API key in the x-api-key header.

API keys are project-specific and can be generated from your project settings. Keys start with ek_live_ for production or ek_test_ for testing.

Keep your API keys secure! Never expose them in client-side code or commit them to version control. Use environment variables instead.

API Reference

POST/api/v1/feedback

Submit feedback from your application

Headers

Header	Value	Required
x-api-key	Your API key	Yes
Content-Type	application/json	Yes

Request Body

Field	Type	Description
category	string	One of: `bug`, `feature`, `question`, `praise`
message	string	The feedback message (max 10,000 chars)
userIdentifier	string?	Optional user identifier (email, ID, etc.)
metadata	object?	Optional JSON metadata (max 10KB)

Code Examples

import { Echoes } from "@echoessh/sdk";

const echoes = new Echoes({
  apiKey: process.env.ECHOES_API_KEY!,
});

// Send feedback
await echoes.send({
  category: "bug",
  message: "Button doesn't work on mobile",
  userIdentifier: "user@example.com",
  metadata: { browser: "Chrome", page: "/settings" },
});

// Or use convenience methods
await echoes.bug("Login button not responding");
await echoes.feature("Add dark mode support");
await echoes.question("How do I reset my password?");
await echoes.praise("Love the new design!");

Response Codes

Code	Description
201	Feedback created successfully
400	Invalid request body
401	Missing or invalid API key
403	API key is disabled
429	Rate limit exceeded

Success Response

{
  "success": true,
  "feedbackId": "550e8400-e29b-41d4-a716-446655440000"
}

Error Response

{
  "success": false,
  "error": "Invalid category"
}

Rate Limiting

The API is rate limited to 100 requests per minute per API key. Rate limit information is included in response headers:

Header	Description
X-RateLimit-Limit	Maximum requests per window (100)
X-RateLimit-Remaining	Remaining requests in current window
X-RateLimit-Reset	Unix timestamp when the window resets

SDK

The official Echoes SDK provides a type-safe, convenient way to integrate feedback collection into your JavaScript/TypeScript applications.

Installation

bun add @echoessh/sdk

Basic Usage

Initialize the client and send feedback with full type safety.

import { Echoes } from "@echoessh/sdk";

const echoes = new Echoes({
  apiKey: process.env.ECHOES_API_KEY!,
  // Optional configuration
  baseUrl: "https://echoes.sh",
  timeout: 10000,
  debug: false,
});

// Full control
await echoes.send({
  category: "bug",
  message: "Button doesn't work",
  userIdentifier: "user@example.com",
  metadata: { page: "/settings" },
});

// Convenience methods
await echoes.bug("Something broke");
await echoes.feature("Add dark mode");
await echoes.question("How do I...?");
await echoes.praise("Love it!");

// Chain user context
const userEchoes = echoes.withUser("user@example.com");
await userEchoes.bug("Error on my account");

React Integration

Provider & Widget

Use the built-in provider and feedback widget component.

import { EchoesProvider, FeedbackWidget } from "@echoessh/sdk/react";

function App() {
  return (
    <EchoesProvider config={{ apiKey: process.env.NEXT_PUBLIC_ECHOES_API_KEY! }}>
      <YourApp />
      <FeedbackWidget
        userIdentifier="user@example.com"
        onSuccess={(id) => console.log("Feedback submitted:", id)}
        showCategories={true}
        theme="dark"
      />
    </EchoesProvider>
  );
}

React Hooks

Use hooks for custom feedback UI.

import { useEchoes, useFeedback } from "@echoessh/sdk/react";

function FeedbackButton() {
  const echoes = useEchoes();
  const { send, isLoading, isSuccess } = useFeedback();

  const handleClick = async () => {
    await send({
      category: "bug",
      message: "Something went wrong",
    });
  };

  if (isSuccess) return <p>Thanks for your feedback!</p>;

  return (
    <button onClick={handleClick} disabled={isLoading}>
      {isLoading ? "Sending..." : "Report Bug"}
    </button>
  );
}

Analytics

Echoes Analytics provides comprehensive user behavior tracking including page views, clicks, scroll depth, errors, and session recordings. Understand how users interact with your application in real-time.

Page Views

Automatic tracking of page navigation and route changes

Click Tracking

Capture clicks with coordinates and element context

Scroll Depth

Track how far users scroll on each page

Session Replay

Watch recordings of user sessions (Pro+)

Quick Setup

Add the Analytics Provider to your app layout to start tracking automatically.

import { EchoesAnalyticsProvider } from "@echoessh/sdk/analytics";

// In your app layout (e.g., layout.tsx)
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <EchoesAnalyticsProvider
          config={{
            apiKey: process.env.NEXT_PUBLIC_ECHOES_API_KEY!,
            // Automatic tracking (all enabled by default)
            trackPageViews: true,
            trackClicks: true,
            trackScroll: true,
            trackErrors: true,
            // Session recording (Pro+ plans)
            enableRecording: true,
            // Privacy settings
            maskInputs: true,
            sessionTimeout: 30 * 60 * 1000, // 30 minutes
          }}
        >
          {children}
        </EchoesAnalyticsProvider>
      </body>
    </html>
  );
}

Plan Limits

Free

1,000 sessions/mo

7-day retention

Pro

50,000 sessions/mo

30-day retention + recordings

Ultra

Unlimited sessions

90-day retention + recordings

Event Tracking

The SDK automatically tracks common events. You can also send custom events using the track() function.

Automatic Events

Event Type	Trigger	Data Captured
pageview	Route change	URL, title, referrer
click	Mouse click	Coordinates, element selector, text
scroll	Scroll milestones	Depth %, page height
error	JS error	Message, stack trace, source
form_submit	Form submission	Form ID, field count

Custom Events & User Identification

Use hooks to track custom events and identify users.

import { useEchoesAnalytics } from "@echoessh/sdk/analytics";

function CheckoutButton() {
  const { track, identify } = useEchoesAnalytics();

  const handlePurchase = async () => {
    // Track custom events
    track("purchase_completed", {
      productId: "prod_123",
      amount: 99.99,
      currency: "USD",
    });
  };

  // Identify logged-in users
  const handleLogin = (user) => {
    identify(user.id, {
      email: user.email,
      plan: user.plan,
    });
  };

  return <button onClick={handlePurchase}>Complete Purchase</button>;
}

Events API

Events are batched and sent to the API automatically. Here's the payload format:

// Events API - POST /api/v1/analytics/events
{
  "sessionId": "sess_abc123",
  "visitorId": "vis_xyz789",
  "userIdentifier": "user@example.com", // optional
  "events": [
    {
      "type": "pageview",
      "timestamp": 1705312200000,
      "url": "https://example.com/dashboard",
      "properties": { "title": "Dashboard" }
    },
    {
      "type": "click",
      "timestamp": 1705312205000,
      "url": "https://example.com/dashboard",
      "x": 150,
      "y": 300,
      "selector": "button.action"
    },
    {
      "type": "custom",
      "timestamp": 1705312210000,
      "url": "https://example.com/dashboard",
      "name": "feature_used",
      "properties": { "feature": "export" }
    }
  ],
  "session": {
    "userAgent": "Mozilla/5.0...",
    "screenWidth": 1920,
    "screenHeight": 1080,
    "referrer": "https://google.com",
    "utmSource": "google",
    "utmMedium": "cpc"
  }
}

Session Recording

Session recordings let you watch exactly how users interact with your application. Powered by rrweb, recordings capture DOM mutations efficiently without affecting performance.

Privacy First: Session recordings automatically mask input values by default. Sensitive content can be excluded using CSS classes.

Configuration

Enable recording and configure privacy settings:

<EchoesAnalyticsProvider
  config={{
    apiKey: process.env.NEXT_PUBLIC_ECHOES_API_KEY!,
    enableRecording: true,
    // Recording options
    recordingConfig: {
      // Mask all input values (recommended)
      maskInputs: true,
      // Block specific elements from recording
      blockClass: "echoes-block",
      // Mask specific elements (show as ****)
      maskClass: "echoes-mask",
      // Ignore specific elements from mouse tracking
      ignoreClass: "echoes-ignore",
      // Sample rate (1 = 100%, 0.5 = 50%)
      sampling: {
        canvas: 15, // Canvas snapshot interval (fps)
        scroll: 150, // Scroll event throttle (ms)
        input: "last", // Input recording: "all" | "last"
      },
    },
  }}
>
  {children}
</EchoesAnalyticsProvider>

{/* In your components */}
<input type="password" className="echoes-mask" />
<div className="echoes-block">Sensitive content not recorded</div>

Privacy Controls

Class	Effect
echoes-block	Element and children are not recorded (shows placeholder)
echoes-mask	Text content is replaced with asterisks (*****)
echoes-ignore	Mouse interactions on element are not tracked

Viewing Recordings

Access session recordings from your project dashboard under Sessions. Use the built-in player to:

Play, pause, and scrub through recordings
Adjust playback speed (0.5x to 4x)
Skip inactive periods automatically
View event timeline alongside the recording
Filter sessions by device, country, or duration

Note: Session recording is available on Pro and Ultra plans. Free tier users can still access page views, clicks, and scroll tracking.

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your Echoes project. Configure webhooks in your project settings.

Available Events

Event	Description
feedback.created	New feedback received
feedback.updated	Feedback status or priority changed
feedback.deleted	Feedback was deleted

Webhook Payload

{
  "event": "feedback.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "category": "bug",
    "status": "new",
    "priority": "medium",
    "message": "Login button not working",
    "userIdentifier": "user@example.com",
    "metadata": {
      "browser": "Chrome",
      "page": "/login"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Tip: Webhooks include a X-Echoes-Signature header for verifying the payload authenticity.

CLI

The Echoes CLI lets you manage projects, send feedback, and view data directly from your terminal.

# Install the CLI
npm install -g @echoes/cli

# Login to your account
echoes login

# List your projects
echoes projects list

# Send feedback from terminal
echoes send --project my-app --category bug --message "CLI test"

# View recent feedback
echoes feedback list --project my-app --limit 10

Ready to get started?

Create your free account and start collecting feedback today.

Get Started Free