Skip to main content

REFERENCE

SDK Demos

How to use @asgard-js/core and @asgard-js/react, with demos you can try on the page.

Quick Start

This page walks you from zero to a working <Chatbot>.

Don't have a Bot Provider yet?

This page assumes you already have a Bot Provider endpoint. If you don't, start with the Integration Overview: the full development flow, how to build a bot in Odin, and which integration pattern to choose (Direct Connect / Backend Relay / Hosted Embed).

  1. Install​

    npm install @asgard-js/core @asgard-js/react

    Both packages are required:

    • @asgard-js/core — low-level SSE client, channel, and conversation model
    • @asgard-js/react — React components, hooks, and the built-in chat UI

  2. Get a Bot Provider Endpoint​

    The endpoint URL has a fixed format:

    https://api.asgard-ai.com/ns/{namespace}/bot-provider/{botProviderId}

    Create and publish a Bot Provider in Odin Studio to obtain the endpoint and credentials. Further reading:

    The SDK automatically derives the SSE endpoint (${botProviderEndpoint}/message/sse) and the blob upload endpoint from this base URL.

  3. Import the Stylesheet​

    import "@asgard-js/react/style";

    Run this once — otherwise the chatbot will render unstyled. The path resolves to @asgard-js/react/dist/index.css.

  4. Render <Chatbot>​

    import { Chatbot } from "@asgard-js/react";
    import "@asgard-js/react/style";
     
    export function App() {
      return (
        <Chatbot
          title="My Chatbot"
          customChannelId="user-123"
          config={{
            botProviderEndpoint:
              "https://api.asgard-ai.com/ns/{namespace}/bot-provider/{botProviderId}",
          }}
        />
      );
    }

    Two required props, plus a commonly-used one:

    PropRequiredDescription
    config.botProviderEndpoint✓The URL from step 2
    customChannelId✓Unique identifier for a conversation on your side (user id etc.)
    titleTitle shown in the header

    See Chatbot Props for the full list.

  5. SSR / Next.js / Docusaurus Caveats​

    @asgard-js/react depends on window, MediaRecorder, ResizeObserver and other browser-only APIs — it cannot run on the server. Every SSR framework needs a client-only wrapper:

    Next.js (App Router)​

    "use client";
     
    import dynamic from "next/dynamic";
     
    const Chatbot = dynamic(
      () => import("@asgard-js/react").then((m) => m.Chatbot),
      { ssr: false },
    );

    Next.js (Pages Router)​

    import dynamic from "next/dynamic";
     
    const Chatbot = dynamic(
      () => import("@asgard-js/react").then((m) => m.Chatbot),
      { ssr: false },
    );

    Docusaurus / Gatsby​

    import BrowserOnly from "@docusaurus/BrowserOnly";
     
    export default function MyPage() {
      return (
        <BrowserOnly>
          {() => {
            const { Chatbot } = require("@asgard-js/react");
            require("@asgard-js/react/style");
            return <Chatbot title="..." customChannelId="..." config={{ botProviderEndpoint: "..." }} />;
          }}
        </BrowserOnly>
      );
    }

    Vite / CRA​

    Pure SPAs have no SSR, so top-level imports work directly — no extra handling needed.

  6. Next Steps​

Ready to get started?

Want to see how Asgard fits your team? Talk to us.

Contact us