SDK Overview

npm install @vocantly/sdk

import { Vocantly } from '@vocantly/sdk';

// Token from your backend (POST /apps/:id/tokens)—never keys
const client = new Vocantly({
  wsUrl: 'wss://ws.dev.vocantly.com/ws',
  token,
  debug: true
});

// Connect to WebSocket
await client.connect();

// Join a conversation
await client.conversations.join('conversation-id');

// Get the conversation instance
const conversation = client.conversations.get('conversation-id');

// Listen for messages
conversation.on('message', (message) => {
  console.log('New message:', message.content);
});

// Send a message
conversation.sendMessage('Hello, world!');

Vocantly (Main Client)
├── conversations
│   ├── get(id) → Conversation
│   ├── has(id) → boolean
│   ├── join(id) → Promise
│   └── leave(id) → Promise
├── support
│   ├── get(id, role?) → SupportSession
│   └── has(id) → boolean
└── Events: connected, disconnected, error, presence

Conversation
├── id: string
├── isJoined: boolean
├── sendMessage(content, type?, metadata?)
├── startTyping()
├── stopTyping()
└── Events: message, typing, receipt, presence, joined, left

interface ClientConfig {
  wsUrl: string;   // Required. e.g. 'wss://ws.dev.vocantly.com/ws'
  token: string;   // Required. From your backend (POST /apps/:id/tokens)

  apiUrl?: string; // Optional. Needed for client.conversations.list() and conversation.fetchMessages()

  apiKey?: string;     // Dev only; do not use in production frontend
  apiSecret?: string;  // Dev only; do not use in production frontend
  getRestHeaders?: () => Promise<Record<string, string>>; // Alternative: backend returns REST headers

  debug?: boolean;
  autoReconnect?: boolean;    // default true
  maxReconnectAttempts?: number;
  reconnectDelay?: number;
}

import { Vocantly } from '@vocantly/sdk';

const client = new Vocantly({
  wsUrl: 'wss://ws.dev.vocantly.com/ws',
  token // from your backend
});

// Connection
await client.connect();
await client.disconnect();
client.isConnected(); // boolean
client.getState(); // ConnectionState

// Token management
client.updateToken(newToken);

// Events
client.on('connected', () => { /* ... */ });
client.on('disconnected', (data) => { /* ... */ });
client.on('error', (error) => { /* ... */ });
client.on('presence', (event) => { /* ... */ });

// Join a conversation
await client.conversations.join('conversation-id');

// Get conversation instance
const conversation = client.conversations.get('conversation-id');

// Check if exists
client.conversations.has('conversation-id'); // boolean

// Leave conversation
await client.conversations.leave('conversation-id');

const conversation = client.conversations.get('conversation-id');

// Properties
conversation.id;        // string
conversation.isJoined;  // boolean

// Send message
conversation.sendMessage('Hello!');
conversation.sendMessage('Hello!', 'text', { customField: 'value' });

// Typing indicators
conversation.startTyping();
conversation.stopTyping();

// Events
conversation.on('message', (message) => {
  console.log(message.id, message.content, message.senderId);
});

conversation.on('typing', (event) => {
  console.log(event.userId, event.state); // 'start' | 'stop'
});

conversation.on('receipt', (event) => {
  console.log(event.messageId, event.state); // 'delivered' | 'read'
});

conversation.on('joined', () => { /* ... */ });
conversation.on('left', () => { /* ... */ });

// Get support session for a conversation
const support = client.support.get('conversation-id', 'customer');

// Check if exists
client.support.has('conversation-id'); // boolean

const conversation = client.conversations.get('conv-id');

// Send message (optimistic update happens immediately)
conversation.sendMessage('Hello!');

// Listen for receipt updates
conversation.on('receipt', (event) => {
  console.log(`Message ${event.messageId}: ${event.state}`);
  // 'delivered' or 'read'
});

// Connection errors
client.on('error', (error) => {
  console.error('SDK error:', error.message);
});

// Conversation errors
const conversation = client.conversations.get('conv-id');
conversation.on('error', (error) => {
  console.error('Conversation error:', error.message);
});

// Try-catch for async operations
try {
  await client.connect();
} catch (error) {
  console.error('Connection failed:', error);
}

import { 
  Vocantly, 
  Conversation,
  Message,
  ConnectionState 
} from '@vocantly/sdk';

const client: Vocantly = new Vocantly({ /* config */ });
const conversation: Conversation = client.conversations.get('id');