Add Atina 3D AI to your site in a few minutes

1. Configure your page

public_key is required. The SDK sends it with the browser origin to create a temporary session token after your domain is validated. You can also pass friendly defaults that shape the first visitor experience.

<script>
window.ATINA_CONTEXT = {
  public_key: "atina_pk_live_your_public_key",
  external_user_id: "optional-user-id-from-your-app",
  mode: "text"
};
</script>

Use window.AtinaSDK.configure() or new Atina() after the SDK loads to customize these runtime settings.

2. Load avatar mode

<div id="atina-root" style="height: 620px"></div>
<link rel="stylesheet" href="https://www.atina.comfylearnhub.com/atina-embed/assets/index-5b0ac9c0.css">
<script type="module" src="https://www.atina.comfylearnhub.com/atina-embed/assets/index-bc07bc84.js"></script>

3. Load text mode and callbacks

<div id="atina-text-root"></div>
<div class="my-atina-history"></div>
<link rel="stylesheet" href="https://www.atina.comfylearnhub.com/atina-embed-sdk/atina-sdk.css">
<script src="https://www.atina.comfylearnhub.com/atina-embed-sdk/atina-sdk.js"></script>
<script>
window.AtinaEvents.registerCallbacks([
  function (event) {
    console.log("Atina conversation updated", event.conversation_id);
  }
]);

window.AtinaSDK.mountChatHistory(".my-atina-history");
</script>

4. Toggle text and avatar mode

The SDK starts in window.ATINA_CONTEXT.mode when provided. You can also switch modes from your own button or menu.

<button id="atinaModeToggle">Toggle Atina Mode</button>
<button onclick="window.AtinaSDK.setMode('text')">Text</button>
<button onclick="window.AtinaSDK.setMode('avatar')">Avatar</button>

<script>
document.getElementById("atinaModeToggle").addEventListener("click", function () {
  window.AtinaSDK.toggleMode();
});
</script>

5. Latency debug mode

Latency debug mode displays a fixed TTFR (Time to First Response) badge on the host page and measures the time from stream connection to the first real assistant response. It ignores setup events like conversation.init and works for both avatar and text streams.

// Enable at startup
window.AtinaSDK.configure({
  mode: "text",
  latencyDebug: {
    enabled: true,
    label: "Atina TTFR"
  }
});

// Toggle later from your own QA/debug control
window.AtinaSDK.enableLatencyDebug();
window.AtinaSDK.disableLatencyDebug();
window.AtinaSDK.setLatencyDebug(true, { label: "Checkout assistant TTFR" });

// Listen for measured results
window.addEventListener("atina:latency-result", function (event) {
  console.log("Atina TTFR", event.detail.elapsedMs, event.detail.url);
});

window.AtinaEvents.on("latency-result", function (payload) {
  console.log("Atina TTFR", payload.elapsedMs);
});

You can also toggle the badge from the third-party website URL without changing code:

https://example.com/page?atina_latency_debug=1
https://example.com/page?latency=1

https://example.com/page?atina_latency_debug=0
https://example.com/page?latency=0

The enabled state is persisted in localStorage as atina_latency_debug so reloads keep the badge visible until it is disabled.

6. Configure Atina as an agent

After creating an embed app, open the Atina dashboard and add the capabilities this deployment needs. ICL-1 detects the universal Layer A capability, then Atina selects the Layer B instance you configured for that customer, domain, and use case.

7. Product feed format

Product feeds are best for anything that can be searched or compared without calling a live system every time. Use them for ecommerce catalogs, SaaS plan lists, service packages, booking packages, courses, or any public inventory-like data.

Feeds must be served over HTTPS and return JSON. Atina accepts a top-level array or an object containing products or items. Only title or name is required, but richer fields improve matching and answer quality.

When Atina answers with a product URL, the SDK turns the full https://... URL into a clickable link in text mode and conversation history.

8. Live API tool format

Live tools are read-only HTTPS GET endpoints for data that changes per visitor or cannot be safely stored in a feed. You can attach multiple tools. Name each tool by its purpose and add optional schema/keywords JSON so Atina can select the right one, such as order_tracking, account_status, transaction_lookup, shipment_status, or appointment_check.

In the dashboard, submit only the clean endpoint URL, for example https://example.com/api/atina/order-tracking. Atina adds q and keyword query parameters at request time. Optional JSON headers can be configured in the dashboard for server-to-server authorization.

This JSON is not sent to your endpoint. It helps Atina choose the right tool when you configure multiple APIs for the same app.

{
  "type": "order_tracking",
  "keywords": ["order", "delivery", "tracking", "where is my order"],
  "returns": ["status", "estimated_delivery", "tracking_url"],
  "references": ["order_id", "email", "phone"]
}

Return only data Atina is allowed to use. Do not expose private database credentials, admin endpoints, write actions, or private records unrelated to the current visitor request.

9. Escalation webhook format

If escalation mode is set to support ticket, Atina sends a POST request to your HTTPS webhook when ICL-1 routes the message to ESCALATION. Escalation policies can be configured for all domains or for a specific authorized domain; domain-specific policies override the default. The request includes the current message and recent conversation history so your system can create a ticket, notify a human, or route the issue to the right team.

POST https://example.com/api/atina/support-ticket
Content-Type: application/json
X-Atina-Webhook-Secret: your-shared-secret

{
  "source": "atina_embed",
  "app_id": 12,
  "session_id": 441,
  "conversation_id": 909,
  "domain_id": 3,
  "domain": "shop.example.com",
  "origin_domain": "shop.example.com",
  "external_user_id": "customer-123",
  "message": "I need to speak to someone about a failed payment.",
  "priority": "high",
  "routing": {
    "intent": "escalation",
    "capabilities": ["ESCALATION"],
    "source": "icl",
    "confidence": {
      "ESCALATION": 0.9412
    },
    "model_version": "icl-1-v1.0.0"
  },
  "customer_context": {
    "origin_domain": "shop.example.com",
    "external_user_id": "customer-123"
  },
  "recent_history": [
    {
      "role": "user",
      "message": "My payment failed but money left my account.",
      "created_at": "2026-07-11T13:24:00+01:00"
    },
    {
      "role": "assistant",
      "message": "I can help check the status or route this to support.",
      "created_at": "2026-07-11T13:24:08+01:00"
    }
  ]
}

Recommended response:

{
  "ok": true,
  "ticket_id": "SUP-10482",
  "status": "created",
  "message": "A support agent will follow up shortly.",
  "support_url": "https://example.com/support/tickets/SUP-10482"
}

This format is intentionally generic for SaaS, ecommerce, fintech, and logistics. Your webhook can map priority, routing.capabilities, origin_domain, and external_user_id into the correct queue, team, or ticket category. If you do not use a ticket webhook, choose phone, WhatsApp, or contact-detail collection in the dashboard. WhatsApp handoff uses the configured number to create a https://wa.me/... link.

Security model

• Never expose secret API keys in the browser. Embed uses only atina_pk_live_ public keys.
• Every request is checked against the submitted browser origin and your authorized domains.
• Validated embeds receive short-lived session tokens for history, uploads, rating, and streaming.
• Uploads are extracted as temporary context and expire through the existing cleanup workflow.
• Product feeds and live tools must use HTTPS. Live tools should be read-only and scoped to the minimum data needed for the visitor request.
• Use server-side headers for tool authentication. Do not place private tool tokens in frontend code or public product-feed URLs.
• Escalation webhooks should verify the source using a secret header configured in the dashboard when possible.

Drop-in starter snippets

Choose your frontend, copy or download the starter, then replace atina_pk_live_your_public_key with your own public key and the sample recommendation prompts with content that matches your page.