Package Exports
- captivate-chat-api
- captivate-chat-api/dist/captivate-chat-api.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (captivate-chat-api) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
captivate-chat-api
Hybrid WebSocket/REST-based chat API for real-time conversations with support for bot and human agents. Features WebSocket communication for real-time messaging and REST endpoints for data retrieval operations.
Installation
Install the package using npm:
npm install captivate-chat-api
Usage
Single API Key Usage (CaptivateChatAPI)
Most users will only need to use a single API key. Use the CaptivateChatAPI
class for all standard chat operations:
import { CaptivateChatAPI } from 'captivate-chat-api';
const api = new CaptivateChatAPI('YOUR_API_KEY');
await api.connect();
const conversation = await api.createConversation('user123');
You can use all the features described below (creating conversations, sending messages, etc.) with a single API key using this class.
Basic Setup
Import and initialize the API client:
Option 1: Using the static factory method (Recommended)
import { CaptivateChatAPI } from 'captivate-chat-api';
// Create and connect in one step
const api = await CaptivateChatAPI.create('YOUR_API_KEY');
// API is ready to use!
Option 2: Manual instantiation and connection
import { CaptivateChatAPI } from 'captivate-chat-api';
const api = new CaptivateChatAPI('YOUR_API_KEY');
// Connect to the WebSocket server
await api.connect();
Create a Conversation
Create a new conversation with the following options:
Basic setup with just a user ID:
const conversation = await api.createConversation('user123');
Include user information and custom data:
const conversation = await api.createConversation( 'user123', { name: 'John Doe', email: 'john@example.com' }, { customField: 'value' }, 'user-first' // Start the conversation with user-first or bot-first mode );
(New) Include private metadata (not visible to frontend):
const conversation = await api.createConversation( 'user123', { name: 'John Doe' }, { publicKey: 'visible' }, 'user-first', { secretKey: 'hidden', internalFlag: true } // privateMetadata );
- The
privateMetadata
parameter is optional and, if provided, will be sent under theprivate
key in the metadata. This is intended for backend/internal use and will not be returned to the frontend when fetching metadata. - This change is backwards compatible: existing usages of
createConversation
do not need to change.
- The
Send and Receive Messages
Send a text message to the conversation:
await conversation.sendMessage('Hello!');
Send a file with text message (recommended format):
await conversation.sendMessage({ text: "Here's the document you requested", files: [fileObject] });
Listen for responses:
conversation.onMessage((message, type) => { console.log(`${type}: ${message}`); });
File Handling with CaptivateChatFileInput
The CaptivateChatFileInput
class provides automatic file-to-text conversion and structured file handling for chat messages.
Basic File Upload
import { CaptivateChatFileInput } from 'captivate-chat-api';
// Upload a local file
const fileInput = await CaptivateChatFileInput.create(file, {
fileName: 'document.pdf',
includeMetadata: true
});
// Send file with text message
await conversation.sendMessage({
text: "Here's the document you requested",
files: fileInput.files
});
External URL File Processing
// Process file from external URL (S3, etc.)
const fileInput = await CaptivateChatFileInput.create({
fileName: 'document.pdf',
fileType: 'application/pdf',
url: 'https://s3.amazonaws.com/bucket/document.pdf',
includeMetadata: true
});
await conversation.sendMessage({
text: "Document from external storage",
files: fileInput.files
});
Multiple Files
// Process multiple files
const files = [file1, file2, file3];
const fileInputs = await Promise.all(
files.map(file => CaptivateChatFileInput.create(file, {
includeMetadata: true
}))
);
// Combine all files
const allFiles = fileInputs.flatMap(input => input.files);
await conversation.sendMessage({
text: "Multiple documents attached",
files: allFiles
});
File Input Structure
The CaptivateChatFileInput
creates a structured object with:
{
type: 'files',
files: [
{
filename: 'document.pdf',
type: 'application/pdf',
file?: File | Blob, // For direct uploads
url?: string, // For external URLs
textContent: {
type: 'file_content',
text: 'Extracted text from file...',
metadata: {
source: 'file_attachment',
originalFileName: 'document.pdf',
storageType: 'direct' | 'external'
}
}
}
]
}
Supported File Types
- Documents: PDF, DOCX, TXT
- Images: PNG, JPG, JPEG (with OCR text extraction)
- Any file type supported by the file-to-text API
WebSocket Payload Format
Files are sent in the following WebSocket payload structure:
{
"action": "sendMessage",
"event": {
"event_type": "user_message",
"event_payload": {
"type": "message_create",
"client_msg_id": "unique-message-id-1234567890",
"conversation_id": "your-conversation-id",
"content": {
"text": "Here's the document you requested",
"files": [
{
"filename": "document.pdf",
"type": "application/pdf",
"textContent": {
"type": "file_content",
"text": "Extracted text from PDF...",
"metadata": {
"source": "file_attachment",
"originalFileName": "document.pdf",
"storageType": "direct"
}
}
}
]
}
}
}
}
Edit a Message
Edit a previously sent message in the conversation:
await conversation.editMessage('messageId123', 'Updated message text');
// Or with a custom object:
await conversation.editMessage('messageId123', { type: 'text', text: 'Updated message text', files: [], actions: [] });
The method returns a promise that resolves when the edit is confirmed by the server (message_edited_success
event).
Handle Events
Use event listeners to handle various updates, errors, or custom actions:
Error handling:
conversation.onError((error) => { console.error('Error:', error); });
Updates on conversation status:
conversation.onConversationUpdate((update) => { console.log('Conversation Update:', update); });
Handling custom actions:
conversation.onActionReceived((actions) => { console.log(`Actions:`, actions); });
Get Conversation History
Retrieve the transcript of a conversation:
const transcript = await conversation.getTranscript();
console.log('Transcript:', transcript);
Delete Conversation
Delete the current conversation
const transcript = await conversation.delete();
console.log('Deleted conversation');
Retrieve User Conversations
Fetch a list of conversations associated with a specific user ID. This method supports both legacy (v1) and advanced (v2) usage with filter, search, and pagination. Both versions return the same response format. The method supports backward compatibility with both string and object parameters.
Note:
search
parameter uses wildcard matching by default (e.g., "fred" matches "frederick", "alfred", etc.)filter
parameter uses exact matching only (e.g., "fred" only matches "fred")
Legacy usage (v1) - String parameter (backward compatible):
const conversations = await api.getUserConversations('user123');
console.log('User Conversations:', conversations);
/*
Returns Conversation Object
*/
Legacy usage (v1) - Options object:
const conversations = await api.getUserConversations({
userId: 'user123'
});
console.log('User Conversations:', conversations);
/*
Returns Conversation Object
*/
Advanced usage (v2, with filter and pagination):
const conversations = await api.getUserConversations({
userId: 'user123',
filter: { mode: 'dbfred' }, // exact match only
pagination: { page: '1', limit: '10' }
});
console.log('Filtered & Paginated User Conversations:', conversations);
/*
Returns Conversation Object
*/
Advanced usage (v2, with search and pagination):
const conversations = await api.getUserConversations({
userId: 'user123',
search: { mode: 'fred' }, // wildcard match (matches "frederick", "alfred", etc.)
pagination: { page: '1', limit: '10' }
});
console.log('Searched & Paginated User Conversations:', conversations);
/*
Returns Conversation Object
*/
Advanced usage (v2, with both filter and search):
const conversations = await api.getUserConversations({
userId: 'user123',
filter: { mode: 'dbfred' }, // exact match
search: { mode: 'fred' }, // wildcard match
pagination: { page: '1', limit: '10' }
});
console.log('Filtered, Searched & Paginated User Conversations:', conversations);
/*
Returns Conversation Object
*/
Multi-API-Key Support (CaptivateChatManager)
For advanced use cases where you need to fetch and interact with conversations across multiple API keys, use the CaptivateChatManager
class. This manager handles multiple CaptivateChatAPI
instances and ensures each Conversation
uses the correct socket for its API key.
Note: Most users do not need this. Only use the manager if you need to aggregate or interact with conversations across multiple API keys.
Option 1: Using the static factory method (Recommended)
import { CaptivateChatManager } from 'captivate-chat-api';
const apiKeys = [
'YOUR_API_KEY_1',
'YOUR_API_KEY_2'
];
// Create and connect all instances in one step
const manager = await CaptivateChatManager.create(apiKeys, 'dev');
const { conversations, pagination } = await manager.getUserConversations({
userId: '66f016f09d5961b684ce05f0',
apiKeys,
pagination: { page: '1', limit: '90' }
});
for (const conv of conversations) {
const transcript = await conv.getTranscript();
console.log(`Transcript for ${conv.getConversationId()}:`, transcript);
}
Option 2: Manual instantiation and connection
import { CaptivateChatManager } from 'captivate-chat-api';
const apiKeys = [
'YOUR_API_KEY_1',
'YOUR_API_KEY_2'
];
const manager = new CaptivateChatManager(apiKeys, 'dev');
await manager.connectAll();
const { conversations, pagination } = await manager.getUserConversations({
userId: '66f016f09d5961b684ce05f0',
apiKeys,
pagination: { page: '1', limit: '90' }
});
for (const conv of conversations) {
const transcript = await conv.getTranscript();
console.log(`Transcript for ${conv.getConversationId()}:`, transcript);
}
- Use
CaptivateChatAPI
for single-key scenarios. - Use
CaptivateChatManager
for multi-key scenarios.
Delete User Conversations
Delete list of conversations associated with a specific user ID:
const conversations = await api.deleteUserConversations('user123');
console.log('Conversations Deleted successfully');
/*
Throws error if failed
*/
Example: Full Workflow
Here's a complete example of how to use the API:
import { CaptivateChatAPI, CaptivateChatFileInput } from 'captivate-chat-api';
(async () => {
try {
// Create and connect to the API in one step
const api = await CaptivateChatAPI.create('YOUR_API_KEY', 'prod');
console.log('Connected to CaptivateChat API');
// Create a conversation
const conversation = await api.createConversation(
'user123',
{
name: 'John Doe',
email: 'john@example.com',
},
{ role: 'admin' },
'bot-first'
);
console.log('Conversation started:', conversation);
// Listen for messages
conversation.onMessage((message, type) => {
console.log(`Received (${type}): ${message}`);
});
// Send a text message
await conversation.sendMessage('Hello! How can I assist you today?');
// Send a file with text message
const fileInput = await CaptivateChatFileInput.create(file, {
fileName: 'document.pdf',
includeMetadata: true
});
await conversation.sendMessage({
text: "Here's the document you requested",
files: fileInput.files
});
// Handle conversation updates
conversation.onConversationUpdate((update) => {
console.log('Conversation Update:', update);
});
// Fetch the transcript
const transcript = await conversation.getTranscript();
console.log('Transcript:', transcript);
// Get user conversations (backward compatible)
const conversations = await api.getUserConversations('user123');
console.log('User Conversations:', conversations);
// Get user conversations with advanced filtering (new API)
const filteredConversations = await api.getUserConversations({
userId: 'user123',
filter: { status: 'active' },
search: { title: 'meeting' },
pagination: { page: '1', limit: '10' }
});
console.log('Filtered Conversations:', filteredConversations);
// Delete the conversation
await conversation.delete();
console.log('Conversation deleted successfully.');
} catch (error) {
console.error('Error:', error);
}
})();
Development Mode
Switch to development mode for testing:
const api = new CaptivateChatAPI('YOUR_API_KEY', 'dev');
Environment Support
The API supports the following environments:
- Browser
- Node.js
- React Native
File Processing
File-to-text conversion is handled by the external API endpoint:
- Production:
https://file-to-text.prod.captivat.io/api/file-to-text
- Supported formats: PDF, DOCX, TXT, PNG, JPG, JPEG
- Features: OCR for images, metadata extraction, automatic text conversion
API Reference
CaptivateChatFileInput
A utility class for processing files and converting them to text for chat messages.
Methods
static create(file: File | Blob, options?: { fileName?: string; fileType?: string; includeMetadata?: boolean }): Promise<CaptivateChatFileInput>
Creates aCaptivateChatFileInput
from a local file with automatic text extraction.static create(options: { fileName: string; fileType: string; url: string; includeMetadata?: boolean }): Promise<CaptivateChatFileInput>
Creates aCaptivateChatFileInput
from an external URL with automatic text extraction.
Properties
type: 'files'
- Always 'files' for file inputsfiles: Array<FileObject>
- Array of processed file objects
FileObject Structure
{
filename: string;
type: string;
file?: File | Blob; // For direct uploads
url?: string; // For external URLs
textContent: {
type: 'file_content';
text: string;
metadata: {
source: 'file_attachment';
originalFileName: string;
storageType: 'direct' | 'external';
};
};
}
CaptivateChatAPI
Methods
constructor(apiKey: string, mode: 'prod' | 'dev' = 'prod')
Initializes the API with the given API key and mode.static create(apiKey: string, mode: 'prod' | 'dev' = 'prod'): Promise<CaptivateChatAPI>
(New) Static factory method that creates and connects a CaptivateChatAPI instance. Returns a promise that resolves to a ready-to-use, connected API instance.connect(): Promise<void>
Connects to the WebSocket server.isSocketActive(): boolean
(New) Checks if the WebSocket connection is active and open. Returns true if the socket is open, false otherwise.createConversation(userId: string, userBasicInfo?: object, userData?: object, autoConversationStart?: 'bot-first' | 'user-first'): Promise<Conversation>
Creates a new conversation.getConversation(conversationId: string): Conversation
Retrieves an existing conversation by its ID.getUserConversations(userIdOrOptions: string | { userId: string; filter?: object; search?: object; pagination?: { page?: string | number; limit?: string | number }; apiKeys?: string[] }): Promise<Conversation[]>
Fetches a list of conversations associated with the given user ID. Supports backward compatibility with string parameter or options object. Iffilter
,search
,pagination
, orapiKeys
is provided, uses the v2 API for advanced querying. Bothfilter
andsearch
parameters are supported for different querying needs. TheapiKeys
parameter allows grouping conversations by API key. Returns Conversation ObjectdeleteUserConversations(userId: string): Promise<void>
Deletes all conversations associated with the given user ID
Conversation
Methods
sendMessage(content: string): Promise<void>
Sends a text message to the conversation.sendMessage(content: object): Promise<void>
Sends a structured message. Supports:- Text only:
{ type: 'text', text: 'Hello' }
- Files only:
{ type: 'files', files: [...] }
- Combined:
{ text: 'Hello', files: [...] }
(recommended)
- Text only:
setMetadata(metadata: object): Promise<void>
Updates metadata for the conversation.setPrivateMetadata(privateMeta: object): Promise<void>
(New) Updates private metadata for the conversation (not visible to frontend). Example:await conversation.setPrivateMetadata({ secret: 'mySecretValue', internalFlag: true });
This will set the metadata under the
private
key. The private metadata is intended for backend/internal use only and will not be returned to the frontend when fetching metadata.getMetadata(): Promise<object>
Returns the metadata for that current conversation sessionsendAction(actionId: string, data?: object): Promise<void>
Sends a custom action to the conversation.editMessage(messageId: string, content: string | object): Promise<void>
Edits a previously sent message in the conversation. Resolves when the edit is confirmed by the server.getTranscript(): Promise<object[]>
Retrieves the conversation transcript.delete(): Promise<void>
Deletes the current conversation
Events
onMessage(callback: (message: string, type: string) => void): void
Listens for new messages.onError(callback: (error: any) => void): void
Listens for errors.onConversationUpdate(callback: (update: any) => void): void
Listens for updates to the conversation.onActionReceived(callback: (actions:[Action]) => void): void
Handles custom actions received during the conversation.
Interfaces
interface Action {
id: string;
data: any;
}