@viam/sdk

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

Installation

``bash
npm install @viam/sdk
`

Quick Start

$3

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

function App() {
return (
config={{
guiderId: 'your-guider-id',
apiUrl: 'https://api.viam.io/api/v1', // optional
}}
>



);
}

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

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

return (
<>
setIsOpen(true)}>Contact Us
{isOpen && setIsOpen(false)} />}

);
}
`

$3

Wrap elements to auto-highlight and scroll when triggered:

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

function PricingSection() {
return (
actionKey="act_pricing_abc123"
onTrigger={() => console.log('User was directed to pricing!')}
>




);
}
`

$3

`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

$3

| 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 |

$3

| 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 |

$3

#### 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.

$3

| 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