Developer Documentation

Naoma.startDemo(config)

Opens the demo agent in a modal overlay.

// 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.

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);
}

Naoma.widget.configure(config)

Configures the widget's position and data collection behavior.

// 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'
});

Naoma.widget.show() / Naoma.widget.hide()

Display or hide the widget on the page.

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

Naoma.widget.expand() / Naoma.widget.collapse()

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

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

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)>

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

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.

Events

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.

1. Compute HMAC-SHA256 of the raw request body using your secret as the key.
2. Hex-encode the result.
3. 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;
}