Implementation Guide (Backend to Frontend)

┌─────────────┐     auth + /chat/start or /chat/token     ┌─────────────┐
│   Frontend  │ ◄─────────────────────────────────────── │   Backend   │
│  (React etc)│         returns token + conversation_id  │ (Node, etc) │
└──────┬──────┘                                          └──────┬──────┘
       │                                                         │
       │  WebSocket + REST (with token)                           │  REST (API keys)
       ▼                                                         ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                    Vocantly (WebSocket + API)                           │
└──────────────────────────────────────────────────────────────────────────┘

VOCANTLY_API_URL=https://dev.vocantly.com/api/v1
VOCANTLY_APP_ID=your-app-uuid
VOCANTLY_PK=your-public-key
VOCANTLY_SK=your-secret-key

// services/vocantly.js
import axios from 'axios';

const API_URL = process.env.VOCANTLY_API_URL || 'https://dev.vocantly.com/api/v1';
const APP_ID = process.env.VOCANTLY_APP_ID;
const PK = process.env.VOCANTLY_PK;
const SK = process.env.VOCANTLY_SK;

/**
 * Create an EXTERNAL conversation. Idempotent by external_id.
 * Use a stable external_id (e.g. sorted user ids) so the same conversation is reused.
 */
export async function createExternalConversation(externalId, participants) {
  if (!PK || !SK) throw new Error('VOCANTLY_PK and VOCANTLY_SK required');
  const { data } = await axios.post(
    `${API_URL}/conversations/external`,
    { external_id: externalId, participants },
    {
      headers: {
        'Content-Type': 'application/json',
        'X-Api-Key': PK,
        'X-Api-Secret': SK,
      },
    }
  );
  const conv = data?.data ?? data;
  return conv?.id ?? conv?.conversation_id ?? conv;
}

/**
 * Issue an SDK token for a user. The frontend will use this token to connect.
 */
export async function issueSdkToken(external_user_id, name, email) {
  if (!APP_ID || !PK || !SK) throw new Error('Vocantly app credentials missing');
  const { data } = await axios.post(
    `${API_URL}/apps/${APP_ID}/tokens`,
    { external_user_id, name, email: email || undefined },
    {
      headers: {
        'Content-Type': 'application/json',
        'X-Api-Key': PK,
        'X-Api-Secret': SK,
      },
    }
  );
  const payload = data?.data ?? data;
  const token = payload?.token;
  if (!token) throw new Error('No token in response');
  return { token, expires_in: payload.expires_in, user_id: payload.user_id ?? external_user_id };
}

// GET /api/chat/token – returns { token, expires_in }
// Requires: authenticated user (your auth middleware)
router.get('/token', authMiddleware, async (req, res) => {
  const currentId = req.user.userId;
  const currentUser = await User.findById(currentId).select('name email');
  if (!currentUser) return res.status(404).json({ error: 'User not found' });
  const { token, expires_in } = await issueSdkToken(
    currentId,
    currentUser.name,
    currentUser.email
  );
  return res.json({ token, expires_in });
});

// POST /api/chat/start – body: { otherUserId }
// Returns: { token, conversation_id, other_user: { id, name } }
router.post('/start', authMiddleware, async (req, res) => {
  const { otherUserId } = req.body;
  const currentId = req.user.userId;
  // Resolve currentUser, otherUser from your DB...

  const externalId = [currentId, otherUserId].sort().join('_');
  const participants = [
    { external_user_id: currentId, name: currentUser.name, email: currentUser.email },
    { external_user_id: otherUserId, name: otherUser.name, email: otherUser.email },
  ];

  const conversation = await createExternalConversation(externalId, participants);
  const conversationId = typeof conversation === 'string' ? conversation : conversation?.id;
  const { token } = await issueSdkToken(currentId, currentUser.name, currentUser.email);

  return res.json({
    token,
    conversation_id: conversationId,
    other_user: { id: otherUser._id, name: otherUser.name },
  });
});

npm install @vocantly/sdk

// config.js
const defaultWsUrl = 'wss://ws.dev.vocantly.com/ws';
const defaultApiUrl = 'https://dev.vocantly.com/api/v1';

export const WS_URL = import.meta.env.VITE_VOCANTLY_WS_URL || defaultWsUrl;
export const API_URL = import.meta.env.VITE_VOCANTLY_API_URL || defaultApiUrl;

const res = await api('/chat/start', {
  method: 'POST',
  body: JSON.stringify({ otherUserId }),
});
navigate(`/chat/${otherUserId}`, {
  state: {
    token: res.token,
    conversation_id: res.conversation_id,
    otherName: res.other_user?.name,
  },
});

import { Vocantly } from '@vocantly/sdk';
import { WS_URL, API_URL } from './config';

// token, conversationId (cid), current user id and other display name come from your app state/route
const cid = state.conversation_id || routeConversationId;
const currentUserId = String(user?.id ?? user?._id ?? '').trim();

const client = new Vocantly({
  wsUrl: WS_URL,
  apiUrl: API_URL,
  token,
  debug: true, // optional
});
const convo = client.conversations.get(cid);

// Optional: clear connection errors once connected
client.on('connected', () => setError(''));
client.on('disconnected', () => setConnected(false));
client.on('error', (err) => setError(err.message || 'Connection error'));

await client.connect();
await client.conversations.join(cid);
// Now you can send messages and fetch history.

const res = await convo.fetchMessages({ limit: 50 });
const history = res?.messages ?? res?.data?.messages ?? [];
const mapped = history.map((m) => ({
  id: m.id ?? m.message_id,
  content: m.content ?? m.body ?? m.text,
  senderId: m.sender_id ?? m.senderId,
  self: String(m.sender_id ?? m.senderId) === currentUserId,
}));
setMessages((prev) => {
  const combined = [...mapped, ...prev];
  return combined.filter((v, i, a) => v.id && a.findIndex((x) => x.id === v.id) === i);
});

convo.on('message', (msg) => {
  const id = msg.id ?? msg.message_id;
  const senderId = String(msg.senderId ?? msg.sender_id ?? '').trim();
  const self = currentUserId === senderId;

  setMessages((prev) => {
    // Dedupe: avoid duplicate keys / bubbles if SDK emits same message twice
    if (prev.some((m) => m.id === id)) return prev;
    return [...prev, { id, content: msg.content, senderId, self }];
  });
});

convo.sendMessage(input.trim());

client.conversations.leave(cid).catch(() => {});
client.disconnect();

convo.startTyping();
// After 2s idle or on blur:
convo.stopTyping();

convo.on('typing', (ev) => {
  const isOther = ev.userId && String(ev.userId) !== currentUserId;
  if (isOther) setOtherUserTyping(ev.state === 'start');
});

const { token } = await api('/chat/token');
const client = new Vocantly({ apiUrl: API_URL, token });
const { conversations } = await client.conversations.list({ limit: 50 });
// Then navigate to chat with conversation id and token in state