@viam/sdk

Interactive SDK for Viam - AI-powered UI interactions triggered by chat.

Installation

npm install @viam/sdk

Quick Start

React

import { ViamProvider, ViamChat, useViamAction } from '@viam/sdk/react';

function App() {
  return (
    <ViamProvider
      config={{
        guiderId: 'your-guider-id',
        apiUrl: 'https://api.viam.io/api/v1', // optional
      }}
    >
      <MyApp />
      <ViamChat position="bottom-right" />
    </ViamProvider>
  );
}

function ContactButton() {
  const [isOpen, setIsOpen] = useState(false);

  // Register action - when user asks "open contact modal", this triggers
  useViamAction('act_contact_xyz123', () => {
    setIsOpen(true);
  });

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Contact Us</button>
      {isOpen && <ContactModal onClose={() => setIsOpen(false)} />}
    </>
  );
}

Using ViamTarget

Wrap elements to auto-highlight and scroll when triggered:

import { ViamTarget } from '@viam/sdk/react';

function PricingSection() {
  return (
    <ViamTarget
      actionKey="act_pricing_abc123"
      onTrigger={() => console.log('User was directed to pricing!')}
    >
      <div className="pricing-section">
        <h2>Pricing</h2>
        {/* ... */}
      </div>
    </ViamTarget>
  );
}

Vanilla JavaScript

import { createViam } from '@viam/sdk';

const viam = createViam({
  guiderId: 'your-guider-id',
});

// Initialize
await viam.init();

// Register actions
viam.register('act_contact_xyz123', (payload) => {
  document.getElementById('contact-modal').classList.add('open');
});

// Send a message
const response = await viam.sendMessage('How do I contact support?');
// If message matches "contact" action, it will trigger automatically

API Reference

ViamProvider Props

| Prop | Type | Description | |------|------|-------------| | config.guiderId | string | Your Viam guider ID (required) | | config.apiUrl | string | API URL (default: http://localhost:4001/api/v1) | | onAction | (key, payload) => void | Called when any action is triggered | | onError | (error) => void | Called on errors |

ViamChat Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | position | 'bottom-right' \| 'bottom-left' \| 'inline' | 'bottom-right' | Chat widget position | | theme | 'light' \| 'dark' | 'light' | Color theme | | primaryColor | string | '#f97316' | Primary accent color | | title | string | 'Chat Assistant' | Chat header title | | placeholder | string | 'Ask a question...' | Input placeholder |

Hooks

useViam()

Returns the full Viam context with SDK instance, messages, and methods.

useViamAction(actionKey, handler, deps?)

Register an action handler that fires when the AI triggers this action.

useViamMessages()

Returns { messages, isLoading, sendMessage } for building custom chat UIs.

useViamReady()

Returns boolean indicating if SDK is initialized.

ViamTarget Props

| Prop | Type | Description | |------|------|-------------| | actionKey | string | The action key to respond to (required) | | onTrigger | (payload) => void | Called when action is triggered | | highlightStyle | CSSProperties | Custom highlight styles | | highlightDuration | number | How long to highlight (ms, default: 3000) | | scrollIntoView | boolean | Auto-scroll to element (default: true) |

Setting Up Actions

1. Go to your Viam dashboard
2. Navigate to your Guider → SDK tab
3. Enable SDK integration
4. Create actions with trigger prompts:
   • Name: "Open Contact Modal"
   • Prompts: "contact support", "get in touch", "talk to someone"
5. Copy the generated action key (e.g., act_contact_x7y8z9)
6. Use the key in your code with useViamAction or viam.register()

How It Works

1. User types a message in the chat
2. AI analyzes if message matches any configured SDK action
3. If matched, the registered handler is called
4. Chat displays a response confirming the action

License

MIT