SDK Reference

SDK Documentation

Official SDKs for React, vanilla JavaScript, and TypeScript to embed Runa in any web application.

Installation

npm install @useruna/client @useruna/ui

React SDK

RunaProvider

Wrap your app with RunaProvider to configure global settings:

import { RunaProvider } from '@useruna/client';

export default function App({ children }) {
  return (
    <RunaProvider
      productId="your-product-id"
      userId={currentUser.id}
      userEmail={currentUser.email}
    >
      {children}
    </RunaProvider>
  );
}

RunaWidget

Drop-in chat widget component:

import { RunaWidget } from '@useruna/ui';

export default function Dashboard() {
  return (
    <div>
      <h1>My App</h1>
      <RunaWidget
        productId="your-product-id"
        theme="light"
        position="bottom-right"
        initialMessage="Hi! How can I help you today?"
      />
    </div>
  );
}

useRuna hook

Access the agent programmatically inside your components:

import { useRuna } from '@useruna/client';

export function MyComponent() {
  const { sendMessage, messages, isLoading, openWidget } = useRuna();

  const handleAction = async () => {
    const reply = await sendMessage('Show me this user\'s recent activity');
    console.log(reply);
  };

  return (
    <button onClick={handleAction}>
      Ask Runa
    </button>
  );
}

Vanilla JavaScript SDK

Use the JavaScript client without any framework:

import { RunaClient } from '@useruna/client';

const runa = new RunaClient({
  productId: 'your-product-id',
  apiEndpoint: 'https://api.useruna.ai',
});

// Send a message
const response = await runa.chat({
  message: 'How many users signed up this week?',
  sessionId: 'user-session-123',
});

console.log(response.reply);

Configuration Options

Prop	Type	Required	Description
productId	string	Yes	Your Runa product ID from the dashboard.
apiEndpoint	string	No	API base URL. Defaults to https://api.useruna.ai
userId	string	No	Identify the current user for personalization.
userEmail	string	No	User email for context and analytics.
theme	"light" \| "dark"	No	Widget color theme. Defaults to "light".
position	"bottom-right" \| "bottom-left"	No	Widget button position. Defaults to "bottom-right".
initialMessage	string	No	Greeting message shown when the widget opens.
onMessage	(msg: Message) => void	No	Callback fired on each new message.

TypeScript Types

export interface RunaConfig {
  productId: string;
  apiEndpoint?: string;
  userId?: string;
  userEmail?: string;
  theme?: 'light' | 'dark';
  position?: 'bottom-right' | 'bottom-left';
  initialMessage?: string;
  onMessage?: (message: Message) => void;
}

export interface Message {
  id: string;
  role: 'user' | 'assistant';
  content: string;
  timestamp: string;
  toolCalls?: ToolCall[];
}

export interface ToolCall {
  id: string;
  name: string;
  arguments: Record<string, unknown>;
  result?: unknown;
}