Quick Start

npm install @vocantly/sdk

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

// Token from your backend—never use keys in the frontend
const client = new Vocantly({
  wsUrl: 'wss://ws.dev.vocantly.com/ws',
  token
});

await client.connect();

const client = new Vocantly({
  wsUrl: 'wss://ws.dev.vocantly.com/ws',
  apiUrl: 'https://dev.vocantly.com/api/v1',
  token
});
await client.connect();
const { conversations } = await client.conversations.list({ limit: 50 });

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

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

console.log('Joined conversation:', conversation.id);

// Get the conversation and send a message
const conversation = client.conversations.get('conversation-id');
conversation.sendMessage('Hello, world!');

// Or in one line:
client.conversations.get('conversation-id').sendMessage('Hello, world!');

// Get the conversation and listen for incoming messages
const conversation = client.conversations.get('conversation-id');

conversation.on('message', (message) => {
  console.log('New message:', message.content);
  console.log('From:', message.senderId);
  // Update your UI here
});

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

// Start typing indicator
conversation.startTyping();

// Stop typing indicator
conversation.stopTyping();

// Listen for typing events from others
conversation.on('typing', (event) => {
  if (event.state === 'start') {
    console.log(`${event.userId} is typing...`);
  } else {
    console.log(`${event.userId} stopped typing`);
  }
});

// Listen for presence updates at the SDK level
client.on('presence', (event) => {
  console.log(`${event.userId} is ${event.state}`);
  // event.state is 'online' or 'offline'
});

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

async function initializeChat() {
  // Token from your backend (POST /apps/:id/tokens)
  const token = await fetch('/api/sdk-token', { credentials: 'include' }).then(r => r.json()).then(d => d.token);

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

  // Handle connection events
  client.on('connected', () => console.log('Connected!'));
  client.on('disconnected', () => console.log('Disconnected'));
  client.on('error', (err) => console.error('Error:', err));

  // Connect to WebSocket
  await client.connect();
  console.log('Connected to Vocantly');

  // Join conversation
  const conversationId = 'your-conversation-id';
  await client.conversations.join(conversationId);

  // Get conversation instance
  const conversation = client.conversations.get(conversationId);

  // Listen for messages
  conversation.on('message', (message) => {
    console.log('Received:', message.content);
    // Display message in your UI
  });

  // Listen for typing
  conversation.on('typing', (event) => {
    if (event.state === 'start') {
      console.log(`${event.userId} is typing...`);
    }
  });

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

  // Send a message
  conversation.sendMessage('Hello from Vocantly!');

  return client;
}

// Initialize
initializeChat().catch(console.error);

curl -X POST https://dev.vocantly.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "password": "your-password"
  }'

# Get conversations
curl https://dev.vocantly.com/api/v1/conversations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get messages for a conversation
curl https://dev.vocantly.com/api/v1/conversations/{conversationId}/messages \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

// SDK (recommended)
await client.connect();

// Or manually (browsers: use Sec-WebSocket-Protocol)
const ws = new WebSocket('wss://ws.dev.vocantly.com/ws', [token]);
ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'join', conversation_id: 'conversation-id' }));
};
ws.onmessage = (e) => console.log(JSON.parse(e.data));