SDK Support Sessions - Vocantly Documentation

Overview

Support sessions enable customer-agent interactions with role-based features. The SDK provides support session management for both customers and agents.

Want a ready-made chat bubble instead of building the UI? See the Support Widget — it wraps everything below in a drop-in <script>.

Starting a support session (provisioning)

A support conversation is bot-eligible only when it’s linked to a customer + app. Use one of these endpoints to open one and get an SDK token for the visitor — then connect the SDK with them.

Server-side (one call)

POST /apps/:id/support-sessions — auth with X-Api-Key + X-Api-Secret (or a dashboard JWT in dev). Mints an SDK token and opens an app-linked support conversation in a single call.

curl -X POST "$API/apps/$APP_ID/support-sessions" \
  -H "X-Api-Key: pk_…" -H "X-Api-Secret: sk_…" -H "Content-Type: application/json" \
  -d '{ "external_user_id": "user_123", "name": "Ada", "email": "ada@acme.com" }'
# → { "data": { "token": "eyJ…", "conversation_id": "…", "expires_in": 86400 } }

Anonymous (public key, no secret)

POST /sdk/anonymous-session — browser-callable with X-Api-Key: <public key> for unauthenticated visitors. The request Origin must be in the app’s allowed_origins (set via PATCH /apps/:id). Great for static sites — this is what the widget’s anonymous mode calls.

curl -X POST "$API/sdk/anonymous-session" \
  -H "X-Api-Key: pk_…" -H "Origin: https://acme.com" -H "Content-Type: application/json" \
  -d '{ "visitor_id": "v_abc123" }'
# → { "data": { "token": "eyJ…", "conversation_id": "…" } }

Update a visitor’s contact info

PATCH /sdk/customers/me — auth with the SDK token. Lets a visitor add their name/email after starting (e.g. from a pre-chat form), so agents can reach them.

curl -X PATCH "$API/sdk/customers/me" \
  -H "Authorization: Bearer <SDK token>" -H "Content-Type: application/json" \
  -d '{ "name": "Ada Okafor", "email": "ada@acme.com" }'

Then connect the SDK and open the session:

const client = new Vocantly({ wsUrl, apiUrl, token });   // token from above
await client.connect();
await client.conversations.join(conversationId);
const support = client.support.get(conversationId, 'customer');
support.on('message', (m) => render(m));                    // bot + agent replies
client.conversations.get(conversationId).sendMessage('How long do refunds take?');

Getting a Support Session

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

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

Roles

Role	Description
`customer`	End user seeking support
`agent`	Support agent handling the request

// Customer session
const customerSession = client.support.get('conv-id', 'customer');

// Agent session
const agentSession = client.support.get('conv-id', 'agent');

Support Session API

Checking Role

const session = client.support.get('conv-id', 'customer');

// Check role
session.isCustomer(); // true
session.isAgent();    // false

Session Status

// Get current status
const status = session.getStatus();
console.log(status); // 'bot' | 'queued' | 'assigned' | 'closed'

Session States

State	Description
`bot`	Conversation with AI bot
`queued`	Waiting for agent assignment
`assigned`	Agent assigned and handling
`closed`	Support session closed

Listening for Events

const session = client.support.get('conv-id', 'customer');

// Agent assigned
session.on('assigned', (event) => {
  console.log('Agent assigned:', event.agentId);
  console.log('Agent name:', event.agentName);
});

// Bot takeover (handoff from agent to bot)
session.on('bot_takeover', () => {
  console.log('Bot has taken over the conversation');
});

// Session closed
session.on('closed', (event) => {
  console.log('Session closed');
  console.log('Resolution:', event.resolution);
});

Customer Flow

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

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

  await client.connect();
  
  const conversationId = 'support-conv-id';
  await client.conversations.join(conversationId);
  
  const conversation = client.conversations.get(conversationId);
  const support = client.support.get(conversationId, 'customer');

  // Listen for status changes
  support.on('assigned', (event) => {
    console.log(`You are now connected with ${event.agentName}`);
  });

  support.on('bot_takeover', () => {
    console.log('You are now chatting with our AI assistant');
  });

  support.on('closed', () => {
    console.log('Your support session has ended');
  });

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

  // Send message
  conversation.sendMessage('I need help with my order');
}

Agent Flow

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

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

  await client.connect();
  
  const conversationId = 'support-conv-id';
  await client.conversations.join(conversationId);
  
  const conversation = client.conversations.get(conversationId);
  const support = client.support.get(conversationId, 'agent');

  // Check if this is an assigned session
  console.log('Is agent:', support.isAgent()); // true
  console.log('Status:', support.getStatus()); // 'assigned'

  // Listen for messages from customer
  conversation.on('message', (message) => {
    console.log(`Customer: ${message.content}`);
    
    // Auto-reply example
    if (message.content.includes('order')) {
      conversation.sendMessage('Let me check your order status...');
    }
  });

  // Send response
  conversation.sendMessage('Hello! How can I help you today?');
}

React Integration

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

type SupportStatus = 'bot' | 'queued' | 'assigned' | 'closed';

function useSupportSession(client: Vocantly, conversationId: string, role: 'customer' | 'agent') {
  const [status, setStatus] = useState<SupportStatus>('bot');
  const [agentInfo, setAgentInfo] = useState<{ id: string; name: string } | null>(null);

  useEffect(() => {
    const session = client.support.get(conversationId, role);
    setStatus(session.getStatus());

    session.on('assigned', (event) => {
      setStatus('assigned');
      setAgentInfo({ id: event.agentId, name: event.agentName });
    });

    session.on('bot_takeover', () => {
      setStatus('bot');
      setAgentInfo(null);
    });

    session.on('closed', () => {
      setStatus('closed');
    });
  }, [client, conversationId, role]);

  return { status, agentInfo };
}

// Usage
function SupportChat({ client, conversationId }) {
  const { status, agentInfo } = useSupportSession(client, conversationId, 'customer');

  return (
    <div>
      <div className="status-bar">
        {status === 'bot' && '🤖 Chatting with AI assistant'}
        {status === 'queued' && '⏳ Waiting for an agent...'}
        {status === 'assigned' && `👤 Connected with ${agentInfo?.name}`}
        {status === 'closed' && '✅ Session ended'}
      </div>
      
      {/* Chat messages */}
    </div>
  );
}

Support Events

Event	Payload	Description
`assigned`	`{ agentId, agentName }`	Agent assigned to session
`bot_takeover`	-	Bot took over conversation
`closed`	`{ resolution? }`	Session closed

Complete Example

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

class SupportChat {
  private client: Vocantly;
  private conversationId: string;
  private role: 'customer' | 'agent';

  async initialize(token: string, conversationId: string, role: 'customer' | 'agent') {
    this.conversationId = conversationId;
    this.role = role;

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

    await this.client.connect();
    await this.client.conversations.join(conversationId);

    const conversation = this.client.conversations.get(conversationId);
    const support = this.client.support.get(conversationId, role);

    // Handle messages
    conversation.on('message', (message) => {
      this.displayMessage(message);
    });

    // Handle support events
    support.on('assigned', (event) => {
      this.showNotification(`Agent ${event.agentName} has joined`);
    });

    support.on('bot_takeover', () => {
      this.showNotification('AI assistant is now helping you');
    });

    support.on('closed', () => {
      this.showNotification('Support session has ended');
    });

    // Show initial status
    this.showStatus(support.getStatus());
  }

  sendMessage(content: string) {
    const conversation = this.client.conversations.get(this.conversationId);
    conversation.sendMessage(content);
  }

  private displayMessage(message: any) {
    const sender = message.senderType === 'bot' ? '🤖 Bot' :
                   message.senderType === 'agent' ? '👤 Agent' : '👨 You';
    console.log(`${sender}: ${message.content}`);
  }

  private showNotification(message: string) {
    console.log(`📢 ${message}`);
  }

  private showStatus(status: string) {
    const statusMap = {
      bot: '🤖 Chatting with AI',
      queued: '⏳ Waiting for agent',
      assigned: '👤 Connected with agent',
      closed: '✅ Session closed'
    };
    console.log(`Status: ${statusMap[status] || status}`);
  }
}

// Usage
const chat = new SupportChat();
await chat.initialize('your-token', 'conv-id', 'customer');
chat.sendMessage('I need help with my order');

Next Steps

Conversations

Conversation management

Messaging

Sending messages

Examples

Complete examples

Support Routing

Support routing guide

​Overview

​Starting a support session (provisioning)

​Server-side (one call)

​Anonymous (public key, no secret)

​Update a visitor’s contact info

​Getting a Support Session

​Roles

​Support Session API

​Checking Role

​Session Status

​Session States

​Listening for Events

​Customer Flow

​Agent Flow

​React Integration

​Support Events

​Complete Example

​Next Steps

Conversations

Messaging

Examples

Support Routing

Overview

Starting a support session (provisioning)

Server-side (one call)

Anonymous (public key, no secret)

Update a visitor’s contact info

Getting a Support Session

Roles

Support Session API

Checking Role

Session Status

Session States

Listening for Events

Customer Flow

Agent Flow

React Integration

Support Events

Complete Example

Next Steps