Embed Config Reference | Cortexvia Docs

How to Pass Config

type ChatbotCdnOptions = {
  chatbotKey: string;
  config?: ChatbotConfig;
};

Use chatbotKey for the bot you want to show, then put every widget setting inside config. Keep display options grouped inside config as shown in the examples.

Required

{
  chatbotKey: string;
}

Documented Stable Props

type ChatbotConfig = {
  domId?: string;
  mode?: "chatbot" | "chat";
  defaultOpen?: boolean;
  labels?: {
    thinking?: string;
  };
  inputPlaceholder?: string;
  showPoweredBy?: boolean;
  poweredByText?: string;
  poweredByBrandText?: string;
  hideHeader?: boolean;
  showHeaderLogo?: boolean;
  showUserAvatar?: boolean;
  showAssistentAvatar?: boolean;
  userAvatarMode?: "badge" | "image";
  userAvatarUrl?: string;
  userAvatarLqipUrl?: string;
  assistentAvatarUrl?: string;
  assistentAvatarLqipUrl?: string;
  position?: "bottom-right" | "bottom-left";
  title?: string;
  titleImageUrl?: string;
  titleImageLqipUrl?: string;
  showIconTitle?: boolean;
  showTitleText?: boolean;
  iconTitleText?: string;
  titleText?: string;
  onReady?: (event: {
    chatbotKey: string;
    title: string;
    usedFallbackInit: boolean;
  }) => void;
  styleOverrides?: {
    layout?: {
      root?: CSSProperties;
      header?: CSSProperties;
      title?: CSSProperties;
      messagesContainer?: CSSProperties;
    };
    userMessage?: { bubble?: CSSProperties; text?: CSSProperties; avatar?: CSSProperties };
    assistantMessage?: { bubble?: CSSProperties; text?: CSSProperties; avatar?: CSSProperties };
    input?: {
      wrapper?: CSSProperties;
      container?: CSSProperties;
      textarea?: CSSProperties;
      sendButton?: CSSProperties;
      poweredBy?: CSSProperties;
      poweredByBrand?: CSSProperties;
    };
    widget?: {
      wrapper?: CSSProperties;
      window?: CSSProperties;
      launcher?: CSSProperties;
    };
  };
};

This list is the recommended setup surface for new embeds. If an option is not listed here, leave it out unless Cortexvia support specifically asks you to use it.

Reference Example

html

<script>
  window.cvChatHandle = window.ChatbotSDK.mount("#cv-chat", {
    chatbotKey: "ctx-cb-xxxxxxxxxxxxxxxx",
    config: {
      mode: "chatbot",
      title: "Support Assistant",
      titleImageUrl: "https://cdn.example.com/brand/logo.png",
      titleImageLqipUrl: "https://cdn.example.com/brand/logo-lqip.jpg",
      showHeaderLogo: true,
      showUserAvatar: true,
      showAssistentAvatar: true,
      showIconTitle: true,
      iconTitleText: "Ask about Cortexvia",
      inputPlaceholder: "Ask anything...",
      showPoweredBy: false,
      onReady: function (event) {
      },
      userAvatarMode: "badge",
      styleOverrides: {
        widget: {
          wrapper: { zIndex: 9999 }
        }
      }
    }
  });
</script>

titleImageUrl is optional. If you skip it, the widget uses the assistant or default chatbot avatar while showHeaderLogo stays enabled. Set showHeaderLogo: false when you want to hide the logo slot completely. Pair remote image URLs with their *LqipUrl preview fields for smoother slow-network loading.

Behavior Notes

domId: sets an id on the mounted chat shell so you can target it with your own CSS when needed.

labels.thinking: changes the assistant waiting label shown before the first token arrives.

showPoweredBy: set it to false when you want to remove the footer branding row. For free-tier bots, this is locked on and remains visible as Powered by cortexvia.in.

showHeaderLogo: set it to false to remove the header logo area entirely. If it is enabled, the header uses your logo first, then the assistant or default chatbot avatar.

userAvatarMode: use "badge" for the built-in user badge or "image" to render the configured user avatar image.

showIconTitle / showTitleText: controls whether the launcher tooltip pill next to the closed launcher icon is displayed. Defaults to true. Set to false to hide the tooltip pill completely.

iconTitleText / titleText: custom text string to display inside the launcher tooltip pill. Defaults to "Ask about [chatbotName]" (or "Ask about Cortexvia").

onReady: runs after widget init completes. Use it to hide your host-page loader or reveal the chat shell only after the SDK is ready.

Default behavior: new embeds should not pass language-switching keys. The widget and playground follow one default response flow.

Compatibility Note

Keep existing key spellings exactly: showAssistentAvatar and assistentAvatarUrl.

Related Embed References

Embed and Use

How to start, update, and remove widget.

Style Overrides

Detailed style customization examples.

Style Target Map

Where each style override key applies in UI.

Default Behavior

Current widget behavior.