Conversations

Overview

Conversations are the core unit of communication in Vocantly. They support four types: DIRECT, GROUP, SUPPORT, and EXTERNAL, each with specific use cases and behaviors.

Conversation Types

DIRECT Conversations

One-on-one conversations between two users. Characteristics:

Exactly 2 participants
No title required
Automatically created or retrieved
Cannot have more than 2 members

Use Cases:

Private messaging between users
Customer-to-agent direct communication
Peer-to-peer chat

GROUP Conversations

Multi-user conversations for team collaboration. Characteristics:

2-100 participants
Title required
Members can be added/removed
All members can send messages

Use Cases:

Team channels
Group discussions
Project collaboration

SUPPORT Conversations

Customer support conversations with routing capabilities. Characteristics:

Customer + Agent(s)
Can be routed to departments
Supports bot integration
Assignment tracking
Status management (open, closed, etc.)

Use Cases:

Customer support tickets
Help desk conversations
Support routing and escalation

EXTERNAL Conversations (External Chat)

Conversations owned by your app (e.g. orders, appointments, tickets). Participants are external users from your system—no internal member_ids. Ideal for SDK integrations: telemedicine (doctor–patient), e‑commerce (buyer–seller), marketplaces, etc. Characteristics:

external_id: Your app’s ID (order, appointment, ticket). Required; unique per tenant. Idempotent: same external_id → same conversation.
participants: At least 2; each has external_user_id (required) and optional role, name, email. Must match the users you pass when issuing SDK tokens.
No internal members; you cannot add members via “Add Member.” Use participants at creation only.

Use Cases:

Telemedicine: doctor–patient chat per appointment
E‑commerce: buyer–seller chat per order
Marketplaces: host–guest, freelancer–client
Any 1:1 or small group chat where your app owns the context and identities

Flow: Your backend creates the conversation (see below), issues SDK tokens for each participant (POST /apps/:id/tokens), and returns token + conversation_id to your frontend. The SDK joins by conversation_id and sends/receives messages. No dashboard login required—use Create EXTERNAL (API Key) and Issue SDK Token with your app keys. Inbox & history: To show “my conversations” and load past messages without building a backend route, you can:

Use the inbox client (@vocantly/inbox-client or packages/vocantly-inbox-client in the repo): pass your API URL and API keys, then call listConversations(externalUserId) and getMessages(conversationId, externalUserId, options). In production, prefer getHeaders() from your backend so the secret is never exposed in the frontend.
Or call the REST API directly: List EXTERNAL conversations and Get EXTERNAL messages. The SDK may also expose sdk.conversations.list() and convo.fetchMessages() that call these.

Creating Conversations

Create DIRECT Conversation

const conversation = await fetch('https://api.vocantly.com/api/v1/conversations', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'direct',
    member_ids: ['other-user-id']
  })
});

If a DIRECT conversation already exists between the two users, the API returns the existing conversation (409 Conflict).

Create GROUP Conversation

const conversation = await fetch('https://api.vocantly.com/api/v1/conversations', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'group',
    title: 'Engineering Team',
    member_ids: ['user-id-1', 'user-id-2', 'user-id-3']
  })
});

Create SUPPORT Conversation

const conversation = await fetch('https://api.vocantly.com/api/v1/conversations', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'support',
    title: 'Support Request',
    member_ids: ['agent-id'],
    customer_id: 'customer-id',
    department_id: 'department-id' // Optional
  })
});

Create EXTERNAL Conversation (API Key — recommended for backends)

Use API keys only (no dashboard login). Your backend calls POST /conversations/external with X-Api-Key and X-Api-Secret. See Create EXTERNAL (API Key) for the full reference.

// Your backend (e.g. Node, Laravel, Django)
const conversation = await fetch('https://dev.vocantly.com/api/v1/conversations/external', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': process.env.VOCANTLY_PK,
    'X-Api-Secret': process.env.VOCANTLY_SK
  },
  body: JSON.stringify({
    external_id: 'appointment_789',
    participants: [
      { external_user_id: 'doctor_123', role: 'doctor', name: 'Dr. Smith', email: 'dr@hospital.com' },
      { external_user_id: 'patient_456', role: 'patient', name: 'Jane Doe', email: 'jane@example.com' }
    ]
  })
});
const { data } = await conversation.json();
const conversationId = data.id;
// Then issue SDK token (POST /apps/:appId/tokens) and return { token, conversation_id } to frontend

external_user_id in each participant must match the external_user_id you use when issuing SDK tokens (POST /apps/:id/tokens) for that user. Your frontend receives token + conversation_id from your backend, then uses the SDK to join and chat.

Create EXTERNAL with JWT (dashboard)

If you prefer to use dashboard JWT instead of API keys, use POST /conversations with Authorization: Bearer <access_token> and body { type: "external", external_id, participants }. See Create Conversation.

Managing Conversations

List Conversations

const conversations = await fetch('https://api.vocantly.com/api/v1/conversations', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

Query Parameters:

type - Filter by type (direct, group, support, external)
limit - Number of results (default: 50)
cursor - Pagination cursor

Get Conversation Details

const conversation = await fetch(
  `https://api.vocantly.com/api/v1/conversations/${conversationId}`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

Add Member to Conversation

await fetch(
  `https://api.vocantly.com/api/v1/conversations/${conversationId}/members`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      user_id: 'new-member-id'
    })
  }
);

Only OWNER and ADMIN can add members to GROUP conversations. DIRECT conversations cannot have members added. EXTERNAL conversations cannot have internal members added via this endpoint; participants are set at creation only.

Remove Member from Conversation

await fetch(
  `https://api.vocantly.com/api/v1/conversations/${conversationId}/members/${userId}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

Conversation Members

Each conversation has members with roles:

OWNER: Creator of the conversation, full control
ADMIN: Can manage members (GROUP only)
MEMBER: Can send/receive messages
AGENT: Support agent (SUPPORT conversations)

Using the SDK

The SDK does not create conversations. Your backend creates them via POST /conversations. The SDK joins by conversation_id (from your backend) and sends/receives messages over WebSocket.

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

// token + conversationId from your backend (e.g. after create conv + issue token)
const client = new Vocantly({
  wsUrl: 'wss://ws.dev.vocantly.com/ws',
  token,
  debug: true
});

await client.connect();

const conversationId = 'conv-uuid'; // from your backend
const conversation = client.conversations.get(conversationId);

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

await client.conversations.join(conversationId);
conversation.sendMessage('Hello!');

For EXTERNAL conversations, your backend creates with type: "external", external_id, and participants, then issues tokens. The frontend uses token + conversation_id to join and chat. See Create EXTERNAL and Issue SDK Token.

Real-time Updates

When you join a conversation via WebSocket, you’ll receive:

New messages
Member additions/removals
Conversation updates
Presence changes

Next Steps

Messages

Learn about sending and receiving messages

API Reference

View all conversation endpoints (including EXTERNAL)

External Chat

Create EXTERNAL conversations (orders, appointments, SDK)

Issue SDK Token

Issue tokens for SDK users (external participants)

Support Routing

Support conversation routing

Realtime

Real-time conversation features

Get Started

Chat

Customer Support

Voice & Video

Team

Integrations

Overview

Conversation Types

DIRECT Conversations

GROUP Conversations

SUPPORT Conversations

EXTERNAL Conversations (External Chat)

Creating Conversations

Create DIRECT Conversation

Create GROUP Conversation

Create SUPPORT Conversation

Create EXTERNAL Conversation (API Key — recommended for backends)

Create EXTERNAL with JWT (dashboard)

Managing Conversations

List Conversations

Get Conversation Details

Add Member to Conversation

Remove Member from Conversation

Conversation Members

Using the SDK

Real-time Updates

Next Steps

Messages

API Reference

External Chat

Issue SDK Token

Support Routing

Realtime

​Overview

​Conversation Types

​DIRECT Conversations

​GROUP Conversations

​SUPPORT Conversations

​EXTERNAL Conversations (External Chat)

​Creating Conversations

​Create DIRECT Conversation

​Create GROUP Conversation

​Create SUPPORT Conversation

​Create EXTERNAL Conversation (API Key — recommended for backends)

​Create EXTERNAL with JWT (dashboard)

​Managing Conversations

​List Conversations

​Get Conversation Details

​Add Member to Conversation

​Remove Member from Conversation

​Conversation Members

​Using the SDK

​Real-time Updates

​Next Steps

Messages

API Reference

External Chat

Issue SDK Token

Support Routing

Realtime

Overview

Conversation Types

DIRECT Conversations

GROUP Conversations

SUPPORT Conversations

EXTERNAL Conversations (External Chat)

Creating Conversations

Create DIRECT Conversation

Create GROUP Conversation

Create SUPPORT Conversation

Create EXTERNAL Conversation (API Key — recommended for backends)

Create EXTERNAL with JWT (dashboard)

Managing Conversations

List Conversations

Get Conversation Details

Add Member to Conversation

Remove Member from Conversation

Conversation Members

Using the SDK

Real-time Updates

Next Steps