Developer Documentation

Integrate Naoma AI demo sessions into your website with the SDK, or access session data programmatically via the REST API.

SDK

Embed AI-powered demo sessions with the JavaScript SDK.

Installation

Add this snippet to every page where you want to start a demo session. Replace YOUR_CLIENT_ID with your unique client identifier.

<script>
  window.NaomaConfig = {
    clientId: 'YOUR_CLIENT_ID',
    // recordingNotice: 'This session is being recorded' // optional
  };
  (function(d,s,id){
    var js,fjs=d.getElementsByTagName(s)[0];
    if(d.getElementById(id))return;
    js=d.createElement(s);js.id=id;
    js.src='https://demo.naoma.dev/sdk/sdk.js';
    fjs.parentNode.insertBefore(js,fjs);
  })(document,'script','naoma-sdk');
</script>

Configuration Options

Parameter	Type	Description
`clientId`required	string	Your unique client identifier.
`recordingNotice`	string	Custom recording notice text to display in the demo session.

API Reference

Naoma.startDemo(config)

Opens the demo agent in a modal overlay.

Parameter	Type	Description
`config.sessionData`	object	Data from the user session to pass to the demo (e.g., user ID, name, email, plan).
`config.language`	string	Language code for the demo session (e.g., "en", "es", "de"). Defaults to the agent's default language.

// Start demo with default settings
Naoma.startDemo();

// Start demo in Spanish
Naoma.startDemo({ language: 'es' });

// Start demo with session data
Naoma.startDemo({
  sessionData: {
    userId: '12345',
    name: 'John Doe',
    email: 'john@example.com',
    plan: 'premium'
  }
});

// Start demo with session data and language
Naoma.startDemo({
  sessionData: { userId: '12345', name: 'John Doe' },
  language: 'de'
});

Naoma.trackButtonView(element)

Tracks when a button becomes visible in the viewport.

Parameter	Type	Description
`element`required	HTMLElement	The button element to track.

const btn = document.getElementById("start-demo-btn");
Naoma.trackButtonView(btn);

Naoma.getLanguages()

Returns the list of languages supported by the agent, sorted by the user's browser language preferences. Languages matching the user's preferences appear first.

Returns: Promise<string[]> — Array of language codes

const languages = await Naoma.getLanguages();
console.log(languages); // ["en", "es", "de"]

// Build a language selector
if (languages.length > 1) {
  const select = document.createElement('select');
  languages.forEach(lang => {
    const option = document.createElement('option');
    option.value = lang;
    option.textContent = lang.toUpperCase();
    select.appendChild(option);
  });

  select.onchange = () => Naoma.startDemo({ language: select.value });
}

Naoma.checkClient()

Performs pre-flight checks to determine if the client is eligible to run demo sessions. Use this to conditionally show or hide demo UI elements.

Returns: Promise<{allowed: boolean, reason: string|null}>

const { allowed, reason } = await Naoma.checkClient();

if (allowed) {
  document.getElementById('demo-button').style.display = 'block';
} else {
  console.log('Demo not available:', reason);
}

The widget provides an interactive UI element that can be embedded on your site to offer demo experiences.

Configures the widget's position and data collection behavior.

Parameter	Type	Description
`config.position`	string	Widget position. Options: "top-left", "top-right", "bottom-left", "bottom-right", "top-center", "bottom-center", "left-center", "right-center". Default: "bottom-right".
`config.ctaText`	string	Custom text for the CTA button. Default: "Talk to an agent".
`config.primaryColor`	string	Primary color for buttons and input focus border. Replaces the default gradient with a solid color. e.g., "#0066FF".
`config.textColor`	string	Text color for buttons. Default: "white". e.g., "#FFFFFF".
`config.collectData`	object	Configuration for collecting additional user data before starting the demo.
`collectData.dataKey`required	string	The key to use when adding collected data to sessionData.
`collectData.placeholder`	string	Placeholder text for the input field. Default: "Enter your email".
`collectData.formTitle`	string	Title text displayed above the input field. Default: "Start your demo".
`collectData.validator`	function	Validation function that receives the input value and returns true if valid, or an error message string if invalid.

Widget state persistence: The widget remembers if the user collapsed it. On subsequent page loads, it remains collapsed until the user expands it again (stored in localStorage).

Mobile responsiveness: On viewports ≤ 480px, the data collection form automatically switches to a vertical layout.

// Position widget with email collection
Naoma.widget.configure({
  position: 'bottom-left',
  collectData: {
    dataKey: 'email',
    formTitle: 'Get started today',
    placeholder: 'Enter your email',
    validator: (value) => value && value.includes('@') || 'Valid email required'
  }
});

// Position widget with custom colors
Naoma.widget.configure({
  position: 'top-right',
  ctaText: 'Start a demo',
  primaryColor: '#0066FF',
  textColor: '#FFFFFF'
});

Display or hide the widget on the page.

Naoma.widget.show();
Naoma.widget.hide();

Expand the widget to show the full interface, or collapse it to its minimal state.

Naoma.widget.expand();
Naoma.widget.collapse();

Hero API

The hero block embeds a large animated avatar directly into your page — ideal for landing page hero sections. A placeholder image is shown instantly while the animation loads.

Naoma.hero.mount(container, config)

Mounts the hero block into the given container element.

Parameter	Type	Description
`container`required	HTMLElement	The DOM element to mount the hero into.
`config.width`	number	Width of the avatar area in pixels. Default: fills the container.
`config.height`	number	Height of the avatar area in pixels. Default: fills the container.
`config.ctaText`	string	Custom text for the CTA button. Default: "Start demo now".
`config.primaryColor`	string	Primary color for buttons and form elements. e.g., "#7C3AED".
`config.textColor`	string	Text color for buttons. Default: "white".
`config.collectData`	object	Configuration for collecting user data before starting the demo (same shape as widget’s collectData).
`collectData.dataKey`required	string	The key to use when adding collected data to sessionData.
`collectData.placeholder`	string	Placeholder text for the input field. Default: "Enter your email".
`collectData.formTitle`	string	Title text displayed above the input field.
`collectData.validator`	function	Validation function that returns true if valid, or an error message string if invalid.

Session data: The hero automatically merges data from Naoma.setSessionData() with any data collected via the form. You can pre-set known user data (name, phone, etc.) and the hero will include it when starting the demo.

Styling: All hero elements use .naoma-hero-* CSS classes that you can override with your own styles.

// Simple hero — click CTA to start demo immediately
Naoma.hero.mount(document.getElementById('hero-container'), {
  width: 500,
  height: 500,
  ctaText: 'Start demo now',
  primaryColor: '#7C3AED'
});

// Hero with email collection
Naoma.hero.mount(document.getElementById('hero-container'), {
  ctaText: 'Try it now',
  primaryColor: '#4f46e5',
  collectData: {
    dataKey: 'email',
    placeholder: 'Enter your work email',
    formTitle: 'Get a personalized demo',
    validator: (value) => {
      if (!value || !value.includes('@')) return 'Please enter a valid email';
      return true;
    }
  }
});

// Pre-set session data, then mount hero
Naoma.setSessionData({ username: 'John', phone: '+1234567890' });
Naoma.hero.mount(document.getElementById('hero-container'));

Naoma.hero.unmount()

Removes the hero block from the page and cleans up resources.

Naoma.hero.unmount();

Complete Example

A full page example using the demo button, hero block, and widget.

<!doctype html>
<html>
<head>
  <script>
    window.NaomaConfig = {
      clientId: 'YOUR_CLIENT_ID'
    };
    (function(d,s,id){
      var js,fjs=d.getElementsByTagName(s)[0];
      if(d.getElementById(id))return;
      js=d.createElement(s);js.id=id;
      js.src='https://demo.naoma.dev/sdk/sdk.js';
      fjs.parentNode.insertBefore(js,fjs);
    })(document,'script','naoma-sdk');
  </script>
</head>
<body>
  <div id="demo-section">
    <button onclick="startDemo()" id="startDemoButton">Get a demo now!</button>
  </div>

  <script>
    // === OPTION 1: Demo Button ===
    // Track button view (optional)
    Naoma.trackButtonView(document.querySelector("#startDemoButton"));

    // Start demo on button click with session data
    function startDemo() {
      Naoma.startDemo({
        sessionData: {
          name: "John Doe",
          company: "Acme Inc",
          userId: "12345"
        }
      });
    }

    // === OPTION 2: Hero Block ===
    // Mount an animated avatar hero with email collection
    Naoma.hero.mount(document.getElementById('demo-section'), {
      width: 400,
      height: 400,
      ctaText: 'Start demo now',
      primaryColor: '#7C3AED',
      collectData: {
        dataKey: 'email',
        placeholder: 'Enter your work email',
        validator: (value) => value && value.includes('@') || 'Valid email required'
      }
    });

    // === OPTION 3: Widget ===
    // Configure widget position and email collection
    Naoma.widget.configure({
      position: 'bottom-right',
      ctaText: 'Start a demo',
      primaryColor: '#7C3AED',
      collectData: {
        dataKey: 'email',
        formTitle: 'Get started today',
        placeholder: 'Enter your email',
        validator: (value) => value && value.includes('@') || 'Valid email required'
      }
    });
  </script>
</body>
</html>

TypeScript Support

TypeScript definitions are available for the SDK. Download the types file and add it to your project.

1. Download the types file

Save https://demo.naoma.dev/sdk/sdk.d.ts to your project (e.g. src/types/naoma-sdk.d.ts).

2. Use in your TypeScript code

/// <reference path="./types/naoma-sdk.d.ts" />

Naoma.startDemo({
  sessionData: { userId: "123", name: "John Doe" }
});

Or import types directly:

import type { NaomaSDK, SessionData } from './types/naoma-sdk.d.ts';

const sessionData: SessionData = {
  userId: "123",
  name: "John Doe"
};

Naoma.startDemo({ sessionData });

Public API

Access session data and receive real-time event notifications via the REST API.

Base URL: https://api.naoma.app

Authentication

All API requests require authentication via one of two methods. To obtain your credentials, contact the Naoma team.

Bearer Token

Authorization: Bearer <token>

HTTP Basic Auth

Where client_id is your account's client ID and token is your API token.

Authorization: Basic <base64(client_id:token)>

Tip: Basic Auth is useful for manual exports — you can open a download link directly in your browser and enter your client_id and token when prompted. For example: https://api.naoma.app/v1/sessions.csv

List Sessions

Returns completed sessions for your account.

GET /v1/sessions.json

Returns sessions as a JSON array.

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "metadata": {},
      "transcript": [],
      "summary": "Customer asked about billing.",
      "evaluation": {"qualified": true, "company_size": 50, "urgency": "high"},
      "duration_secs": 120,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

GET /v1/sessions.csv

Returns a CSV file with a header row followed by data rows for the selected fields.

Query Parameters

Parameter	Type	Description
`since`	int64	Unix timestamp. Returns only sessions created after this time. Default: 0.
`limit`	int	Max number of sessions to return (1–100). Default: 100.
`fields`	string	Comma-separated list of fields to include. Available: id, metadata, transcript, summary, evaluation, duration_secs, created_at. Default: all.

Example:

GET /v1/sessions.json?since=1700000000&limit=50&fields=id,summary,created_at

Pagination

Results are ordered by created_at ascending. To paginate, use the created_at of the last returned item (as a unix timestamp) as the since value in the next request.

Errors

Status	Description
`400`	Invalid query parameter.
`401`	Missing or invalid credentials.

Webhooks

Webhooks allow you to receive real-time notifications when events occur. To register a webhook, contact the Naoma team with the URL you'd like to receive events at. You will receive a webhook secret for signature verification.

Events

Status	Description
`session.evaluated`	Fired when a session has been evaluated.

Payload

Webhook events are delivered as POST requests with a JSON body:

{
  "event_type": "session.evaluated",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "metadata": {},
    "transcript": [],
    "summary": "Customer asked about billing.",
    "evaluation": {"qualified": true, "company_size": 50, "urgency": "high"},
    "duration_secs": 120,
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Signature Verification

Each request includes an X-Webhook-Signature header containing an HMAC-SHA256 hex digest of the request body, signed with your webhook secret. Verification is optional but recommended.

Compute HMAC-SHA256 of the raw request body using your secret as the key.
Hex-encode the result.
Compare it to the X-Webhook-Signature header value.

const crypto = require('crypto');

function verifyWebhookSignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return signature === expected;
}

Need Help?

Our team can help you integrate Naoma into your website and get the most out of AI-powered demos.

Talk to Sales Team