SDK Installation

npm install @vocantly/sdk

yarn add @vocantly/sdk

pnpm add @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
});

await client.connect();

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

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

await client.connect();

interface ClientConfig {
  // Required
  wsUrl: string;              // WebSocket server URL
  token: string;              // SDK authentication token

  // Optional: required for list() and fetchMessages() (inbox)
  apiUrl?: string;            // REST API base, e.g. 'https://dev.vocantly.com/api/v1'

  // REST auth: use ONE of (token), (apiKey + apiSecret), or getRestHeaders
  apiKey?: string;            // App public key (dev only; do not expose in production)
  apiSecret?: string;         // App secret (dev only; do not expose in production)
  getRestHeaders?: () => Promise<Record<string, string>>;  // Preferred: backend returns headers

  debug?: boolean;            // Enable debug logging (default: false)
  autoReconnect?: boolean;    // Auto-reconnect on disconnect (default: true)
  maxReconnectAttempts?: number; // Max reconnect attempts (default: 5)
  reconnectDelay?: number;    // Initial reconnect delay in ms (default: 1000)
}

const client = new Vocantly({
  wsUrl: 'wss://ws.dev.vocantly.com/ws',
  token, // from your backend
  debug: process.env.NODE_ENV === 'development',
});
await client.connect();
// join, sendMessage, etc. — list() and fetchMessages() will throw until apiUrl + auth are set

// Option A: Bearer token only (recommended for frontend)
const client = new Vocantly({
  wsUrl: 'wss://ws.dev.vocantly.com/ws',
  apiUrl: 'https://dev.vocantly.com/api/v1',
  token, // same token used for WebSocket; REST calls use Authorization: Bearer <token>
  debug: true,
});
// client.conversations.list() and conversation.fetchMessages() use the token

// Option B: Backend proxy (production — no keys in client)
const client = new Vocantly({
  wsUrl: 'wss://ws.dev.vocantly.com/ws',
  apiUrl: 'https://your-api.com/vocantly', // your backend
  token,
  getRestHeaders: async () => {
    const res = await fetch('/api/vocantly-headers', { credentials: 'include' });
    return res.json(); // { 'Authorization': 'Bearer ...', 'X-Api-Key': '...', etc. }
  },
});

curl -X POST https://dev.vocantly.com/api/v1/apps/YOUR_APP_ID/tokens \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: pk_xxxxx" \
  -H "X-Api-Secret: sk_xxxxx" \
  -d '{"external_user_id": "user_123", "name": "Jane", "email": "jane@example.com"}'

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

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

// Listen for connection state
client.on('connected', () => {
  console.log('✅ SDK connected successfully!');
  console.log('State:', client.getState()); // ConnectionState.CONNECTED
});

client.on('error', (error) => {
  console.error('❌ Connection error:', error);
});

// Connect
try {
  await client.connect();
} catch (error) {
  console.error('Failed to connect:', error);
}

import { useEffect, useState } from 'react';
import { Vocantly, ConnectionState } from '@vocantly/sdk';

function useVocantly(token: string) {
  const [client, setClient] = useState<Vocantly | null>(null);
  const [state, setState] = useState<ConnectionState>(ConnectionState.DISCONNECTED);

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

    chatClient.on('state', setState);
    chatClient.connect();

    setClient(chatClient);

    return () => {
      chatClient.disconnect();
    };
  }, [token]);

  return { client, state };
}

// Usage
function ChatComponent({ token }) {
  const { client, state } = useVocantly(token);

  if (state !== ConnectionState.CONNECTED) {
    return <div>Connecting...</div>;
  }

  return <div>Connected!</div>;
}

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { Vocantly, ConnectionState } from '@vocantly/sdk';

const props = defineProps<{ token: string }>();

const client = ref<Vocantly | null>(null);
const state = ref<ConnectionState>(ConnectionState.DISCONNECTED);

onMounted(async () => {
  client.value = new Vocantly({
    wsUrl: 'wss://ws.dev.vocantly.com/ws',
    token: props.token,
    debug: true
  });

  client.value.on('state', (newState) => {
    state.value = newState;
  });

  await client.value.connect();
});

onUnmounted(() => {
  client.value?.disconnect();
});
</script>

<template>
  <div v-if="state === ConnectionState.CONNECTED">Connected!</div>
  <div v-else>Connecting...</div>
</template>