SDK Conversations - Vocantly Documentation

Overview

Conversations are the core of Vocantly messaging. The SDK provides a conversation-scoped API where you join a conversation, get a Conversation instance, and interact with it.

Joining Conversations

Before you can send or receive messages, you must join a conversation:

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

// Check if joined
const isJoined = client.conversations.has('conversation-id');
console.log('Is joined:', isJoined); // true

Getting Conversation Instance

After joining, get the Conversation instance to interact with it:

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

// Properties
console.log('ID:', conversation.id);
console.log('Is joined:', conversation.isJoined);

Conversation API

Properties

Property	Type	Description
`id`	`string`	The conversation ID
`isJoined`	`boolean`	Whether currently joined

Methods

Method	Returns	Description
`sendMessage(content, type?, metadata?)`	`void`	Send a message
`startTyping()`	`void`	Start typing indicator
`stopTyping()`	`void`	Stop typing indicator

Events

Event	Payload	Description
`message`	`Message`	New message received
`typing`	`{ userId, state }`	Typing indicator update
`receipt`	`{ messageId, state }`	Receipt update
`joined`	`{ conversation_id }`	Joined confirmation
`left`	`{ conversation_id }`	Left confirmation
`error`	`Error`	Error occurred

Sending Messages

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

// Simple text message
conversation.sendMessage('Hello, world!');

// With message type
conversation.sendMessage('Hello!', 'text');

// With metadata
conversation.sendMessage('Hello!', 'text', {
  customField: 'value',
  timestamp: Date.now()
});

Message Types

text - Regular text message (default)
system - System message

Receiving Messages

Listen for incoming messages on the conversation:

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

conversation.on('message', (message) => {
  console.log('Message ID:', message.id);
  console.log('Content:', message.content);
  console.log('Sender:', message.senderId);
  console.log('Sent at:', message.sentAt);
  console.log('Is optimistic:', message.isOptimistic);
});

Message Object

interface Message {
  id: string;              // Message ID
  conversationId: string;  // Conversation ID
  content: string;         // Message content
  senderId: string;        // Sender user ID
  senderType: string;      // 'sdk', 'api', 'bot', etc.
  messageType: string;     // 'text', 'system'
  sentAt: Date;            // Timestamp
  isOptimistic: boolean;   // Is optimistic (not yet confirmed)
  receiptState: string;    // 'sent', 'delivered', 'read'
  metadata?: object;       // Custom metadata
}

Typing Indicators

Sending Typing Status

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

// Start typing (send when user starts typing)
conversation.startTyping();

// Stop typing (send when user stops or sends message)
conversation.stopTyping();

Receiving Typing Status

conversation.on('typing', (event) => {
  if (event.state === 'start') {
    console.log(`${event.userId} is typing...`);
    // Show typing indicator in UI
  } else {
    console.log(`${event.userId} stopped typing`);
    // Hide typing indicator
  }
});

Typing indicators automatically expire after 5 seconds. The server handles this, so you don’t need to manually call stopTyping() after a timeout.

Read Receipts

Listening for Receipts

conversation.on('receipt', (event) => {
  console.log('Message:', event.messageId);
  console.log('State:', event.state); // 'delivered' or 'read'
  console.log('User:', event.userId);
});

Inbox and message history

To list the current user’s EXTERNAL conversations and fetch message history for a conversation, configure apiUrl and REST auth (Bearer token, API keys, or getRestHeaders). Then use:

List: client.conversations.list({ limit?, cursor?, externalUserId? })
History: conversation.fetchMessages({ limit?, cursor?, externalUserId? })

The SDK calls GET /sdk/conversations and GET /sdk/conversations/:id/messages. When using Bearer token, you can omit externalUserId (backend uses token sub). See Inbox & message history for full details and examples.

Leaving Conversations

When you’re done with a conversation:

await client.conversations.leave('conversation-id');

Minimal flow

const client = new Vocantly({ wsUrl, token });
await client.connect();
await client.conversations.join(conversationId);

const conversation = client.conversations.get(conversationId);
conversation.on('message', (msg) => console.log(msg.content));
conversation.sendMessage('Hello!');

// Cleanup when leaving the screen
await client.conversations.leave(conversationId);
await client.disconnect();

For the full app flow (backend token, start conversation, chat screen, fetch history, typing, dedupe), see the Implementation Guide.

Multiple Conversations

You can join multiple conversations simultaneously:

// Join multiple conversations
await client.conversations.join('conv-1');
await client.conversations.join('conv-2');
await client.conversations.join('conv-3');

// Get each conversation
const conv1 = client.conversations.get('conv-1');
const conv2 = client.conversations.get('conv-2');
const conv3 = client.conversations.get('conv-3');

// Each has independent event handlers
conv1.on('message', (msg) => console.log('Conv 1:', msg.content));
conv2.on('message', (msg) => console.log('Conv 2:', msg.content));
conv3.on('message', (msg) => console.log('Conv 3:', msg.content));

// Send to specific conversation
conv1.sendMessage('Hello conv 1!');
conv2.sendMessage('Hello conv 2!');

Error Handling

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

// Handle conversation-level errors
conversation.on('error', (error) => {
  console.error('Conversation error:', error.message);
});

// Try-catch for methods
try {
  conversation.sendMessage('Hello!');
} catch (error) {
  if (error.message.includes('not joined')) {
    console.error('Must join conversation first!');
    await client.conversations.join('conversation-id');
  }
}

Next Steps

Implementation Guide

Full backend + frontend flow

Inbox

List conversations and message history

Messaging

Messages in detail

Typing

Typing indicators

​Overview

​Joining Conversations

​Getting Conversation Instance

​Conversation API

​Properties

​Methods

​Events

​Sending Messages

​Message Types

​Receiving Messages

​Message Object

​Typing Indicators

​Sending Typing Status

​Receiving Typing Status

​Read Receipts

​Listening for Receipts

​Inbox and message history

​Leaving Conversations

​Minimal flow

​Multiple Conversations

​Error Handling

​Next Steps

Implementation Guide

Inbox

Messaging

Typing

Overview

Joining Conversations

Getting Conversation Instance

Conversation API

Properties

Methods

Events

Sending Messages

Message Types

Receiving Messages

Message Object

Typing Indicators

Sending Typing Status

Receiving Typing Status

Read Receipts

Listening for Receipts

Inbox and message history

Leaving Conversations

Minimal flow

Multiple Conversations

Error Handling

Next Steps