Voice AI Avatar API
for Any Website

Quick Start (60 Seconds)

Adding Smara to your site requires no backend setup or complex npm builds. A single <script> tag initializes the voice widget, loads your active knowledge base, and binds page tool actions.

<!-- Smara Voice AI Avatar Widget -->
<script
  src="https://smara.space/embed.js"
  data-api-key="sk_live_smara2026"
  data-position="bottom-right"
  data-theme="dark"
></script>

Platform Embedding Guide

Smara embeds seamlessly into any CMS, website builder, or web application without plugins:

API Keys & Authentication

Smara uses API keys to authenticate requests and load your configured avatar persona. You can manage and regenerate your API keys anytime inside your Studio Dashboard.

Client Session Tokens (Production)

To prevent API key theft, generate a short-lived session token (valid for 1 hour) on your backend server and pass it to the frontend script using data-session-token:

// Server-side Session Token Generator (Node.js / Express)
const express = require('express');
const app = express();

app.post('/api/create-avatar-session', async (req, res) => {
  const response = await fetch('https://api.smara.space/v1/sessions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SMARA_SECRET_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      site_id: 'demo',
      user_id: req.user ? req.user.id : 'guest_anon',
      ttl: 3600 // 1 hour TTL
    })
  });

  const data = await response.json();
  res.json({ session_token: data.session_token });
});

Then initialize the widget on the frontend using the ephemeral session token:

<script
  src="https://smara.space/embed.js"
  data-session-token="st_live_9a87f2bc31a4"
  data-position="bottom-right"
></script>

Domain Security & CORS Restrictions

To prevent unauthorized sites from embedding your avatar widget or consuming your monthly quota, configure Allowed Origin Domains in your Studio Dashboard.

Content Security Policy (CSP) Directives

If your web application enforces a strict Content Security Policy, add the following CSP directives to allow Smara script execution and WebRTC audio streaming:

Content-Security-Policy: 
  script-src 'self' https://smara.space https://cdn.smara.space;
  connect-src 'self' wss://api.smara.space https://api.smara.space;
  media-src 'self' blob:;

Widget Configuration Attributes

Customize the floating widget appearance and behavior directly via HTML attributes:

Universal Web Tool Actions

Smara avatars are trained to execute real-time tool actions directly on your website via voice commands:

JavaScript Event Listener Callback

Listen for live tool actions executed by your avatar on your frontend using the native smara:tool_call event:

// Listen for avatar tool call actions on your page
window.addEventListener('smara:tool_call', (e) => {
  const { action, args } = e.detail;
  console.log('Avatar executed action:', action, args);

  if (action === 'navigate_page') {
    document.querySelector(args.target_section)?.scrollIntoView({ behavior: 'smooth' });
  }

  if (action === 'open_contact_modal') {
    openLeadForm();
  }

  if (action === 'add_to_cart') {
    myCart.add(args.product_key);
  }
});