Skip to main content

Quick Start

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

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 a Bot Provider in the Asgard platform console to obtain one. The SDK automatically derives the SSE endpoint (${botProviderEndpoint}/message/sse) and the blob upload endpoint from this base URL.

warning

The endpoint field from earlier versions of @asgard-js/core is deprecated. Always use botProviderEndpoint. endpoint will be removed in the next major release.

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

Three required props:

PropDescription
config.botProviderEndpointThe URL from step 2
customChannelIdUnique 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.

Next Steps​