AI SmartTalk SDK

Official SDK for integrating with AI SmartTalk's powerful conversation and document management APIs.

Installation

npm i @aismarttalk/aismarttalk-sdk

Quick Start

import { AiSmartTalk, SourceType } from 'aismarttalk-sdk';

// Initialize the SDK
const client = new AiSmartTalk('your-chat-model-id', 'your-token', {
    baseUrl: 'https://aismarttalk.tech' // Optional, defaults to this URL
});

// Search documents
const searchResults = await client.searchDocuments({
    query: 'How do I reset my password?',
    limit: 5
});

// Import documents
const documents = [
    {
        id: '1',
        title: 'Password Reset Guide',
        content: 'Here are the steps to reset your password...'
    }
];
await client.importDocuments({
    documentDatas: documents,
    source: SourceType.FAQ
});

// Chat with admin
const chatResponse = await client.chatWithAdmin(
    'user-123',
    'chat-instance-456',
    'Hello, I need help!',
    'en' // Optional language parameter
);

// Get biography information easily
const responseBio = await client.getResponseBiography(true); // For connected users
const decisionBio = await client.getDecisionBiography(false); // For anonymous users
const adminResponseBio = await client.getAdminResponseBiography();

Key Features

✅ SmartForms: Create and manage forms, collect answers, trigger workflows
✅ Sequences: Multi-form workflows with delegation and contributor tracking
✅ SmartFlow: Execute workflows via webhooks
✅ Document Management: Search and import documents with advanced filtering
✅ Category Management: Create, update, and organize content categories
✅ Chat Integration: Send messages to personal chat admin
✅ Biography Access: Easy-to-use methods for biographies for different user types
✅ Type Safety: Full TypeScript support with comprehensive types

SmartForms & Sequences

SmartForms

// List all SmartForms
const forms = await client.listSmartForms(true); // includeFields = true

// Get a specific form
const form = await client.getSmartForm('form-id');

// Get form questions
const questions = await client.getSmartFormQuestions('form-id');

// Submit answers
const result = await client.submitSmartFormAnswers('form-id', {
    answers: {
        'question_key_1': 'Answer 1',
        'question_key_2': 'option_value'
    },
    executeWorkflow: true
});

// Get answers for an instance
const answers = await client.getSmartFormAnswers('form-id', { 
    instanceId: 'instance-id' 
});

Sequences (Multi-form Workflows)

// List sequences
const sequences = await client.listSequences();

// Start a sequence
const start = await client.startSequence('sequence-id', {
    email: '[email protected]'
});
console.log('Instance ID:', start.instanceId);
console.log('First question:', start.currentQuestion.question);

// Answer questions one by one
const answer = await client.answerSequenceQuestion(
    'sequence-id',
    start.instanceId,
    { value: 'My answer', email: '[email protected]' }
);
console.log('Next question:', answer.nextQuestion?.question);

// Delegate a form to someone else
const delegation = await client.delegateForm('sequence-id', start.instanceId, {
    formId: 'form-id',
    email: '[email protected]',
    message: 'Please complete this form',
    lang: 'fr'
});
console.log('Share this link:', delegation.delegation.shareLink);

// Cancel a delegation
await client.cancelDelegation('sequence-id', start.instanceId, {
    formId: 'form-id'
});

// Get instance details with all answers
const instance = await client.getSequenceInstance('sequence-id', start.instanceId);
instance.forms.forEach(form => {
    console.log(`${form.name}: ${form.status}`);
    console.log('Answers:', form.answers);
});

// Get multiple instances in batch (for dashboards)
const batch = await client.getSequenceInstancesBatch('sequence-id', {
    instanceIds: ['instance-1', 'instance-2', 'instance-3']
});

SmartFlow (Workflow Execution)

// Execute a workflow via webhook
const result = await client.executeWorkflow('workflow-id', {
    customer_email: '[email protected]',
    order_id: '12345',
    amount: 99.99
});

Webhooks

// List available webhooks
const webhooks = await client.listWebhooks();

API Reference

Constructor

new AiSmartTalk(chatModelId: string, token: string, config?: AiSmartTalkConfig)

• chatModelId: Your AI SmartTalk chat model ID
• token: Your API authentication token
• config: Optional configuration object
  • baseUrl: Custom API base URL (optional)

Methods

searchDocuments(filters: FilterParams): Promise<DocumentPublicResponse[]>

Search for relevant documents based on filters including query, sources, limit, and maxDistance.

importDocuments(documentSourceArgs: DocumentSourceArgs): Promise

Import documents in batch from various sources.

getChatModelConfiguration(): Promise

Get the complete chat model configuration including all configurations for different user types.

updateChatModelConfiguration(configuration: Configuration): Promise

Update a specific configuration (anonymous, connected user, or admin).

Category Management

getCategories(): Promise<CategoryWithChildren[]>

Get all categories with their hierarchical structure.

createCategory(category: CreateCategory): Promise

Create a new category.

updateCategory(category: UpdateCategory): Promise

Update an existing category.

deleteCategory(categoryId: string): Promise

Delete a category by ID.

chatWithAdmin(userId: string, chatInstanceId: string, query: string, lang?: string): Promise

Send a message to the personal chat admin.

SmartForm Methods

• listSmartForms(includeFields?: boolean) - List all SmartForms
• getSmartForm(smartFormId, instanceId?) - Get SmartForm details
• getSmartFormQuestions(smartFormId) - Get SmartForm questions
• getSmartFormAnswers(smartFormId, params?) - Get answers for a SmartForm instance
• submitSmartFormAnswers(smartFormId, request) - Submit answers
• getByShareLink(shareLink) - Get SmartForm or Sequence by share link

Sequence Methods

• listSequences() - List all sequences
• createSequence(request) - Create a new sequence
• getSequence(sequenceId) - Get sequence details
• updateSequence(sequenceId, request) - Update a sequence
• deleteSequence(sequenceId) - Delete a sequence
• startSequence(sequenceId, request?) - Start a sequence
• answerSequenceQuestion(sequenceId, instanceId, request) - Answer current question
• getSequenceInstance(sequenceId, instanceId) - Get instance details
• getSequenceInstancesBatch(sequenceId, request) - Get multiple instances in batch
• delegateForm(sequenceId, instanceId, request) - Delegate a form
• cancelDelegation(sequenceId, instanceId, request) - Cancel a delegation

SmartFlow & Webhooks

• executeWorkflow(workflowId, variables) - Execute a workflow via webhook
• listWebhooks() - List available webhooks
• createNotification(request) - Create a notification
• importCustomers(request) - Import customers in bulk

Biography Methods

Simple methods to retrieve biography information for different user types.

What are Biographies?

• Response Biography: Defines how the AI should respond and behave when answering user questions
• Decision Biography: Defines how the AI should make decisions and route conversations

These methods provide easy access to biography configurations without having to manually parse the complex configuration structure:

getResponseBiography(isConnected?: boolean): Promise

Get response biography. Defaults to connected user, falls back to anonymous if not found.

getDecisionBiography(isConnected?: boolean): Promise

Get decision biography. Defaults to connected user, falls back to anonymous if not found.

getAnonymousResponseBiography(): Promise

Get response biography specifically for anonymous users.

getAnonymousDecisionBiography(): Promise

Get decision biography specifically for anonymous users.

getConnectedResponseBiography(): Promise

Get response biography specifically for connected users.

getConnectedDecisionBiography(): Promise

Get decision biography specifically for connected users.

getAdminResponseBiography(): Promise

Get response biography for admin users.

getAdminDecisionBiography(): Promise

Get decision biography for admin users.

Biography Usage Examples

// Simple way to get biographies for different user types
const client = new AiSmartTalk('your-chat-model-id', 'your-token');

// For connected users (default behavior)
const connectedResponseBio = await client.getResponseBiography();
const connectedDecisionBio = await client.getDecisionBiography();

// For anonymous users
const anonymousResponseBio = await client.getResponseBiography(false);
const anonymousDecisionBio = await client.getDecisionBiography(false);

// Or use specific methods for clarity
const specificAnonymousResponse = await client.getAnonymousResponseBiography();
const specificConnectedResponse = await client.getConnectedResponseBiography();

// For admin users
const adminResponseBio = await client.getAdminResponseBiography();
const adminDecisionBio = await client.getAdminDecisionBiography();

Before vs After: Simplified Biography Access

❌ Old way (complex):

// Had to manually navigate the configuration structure
const chatModel = await client.getChatModelConfiguration();
const connectedConfig = chatModel.configurations.find(
    config => config.configurationType === ConfigurationType.CHAT_CONNECTED_USER
);
const responseBio = connectedConfig?.responseBiography || '';

✅ New way (simple):

// Just one method call
const responseBio = await client.getConnectedResponseBiography();

Types

interface FilterParams {
    query: string;
    sources?: SourceType[];
    limit?: number;
    maxDistance?: number;
    categoryIds?: string[];
}

interface DocumentSourceArgs {
    documentDatas: any[];
    source: SourceType;
}

interface CreateCategory {
    name: string;
    description?: string;
    color: ColorValue;
    type: CategoryType[];
    parentId?: string | null;
}

interface UpdateCategory extends CreateCategory {
    id: string;
}

enum SourceType {
    FAQ = 'FAQ',
    IMPORTED_PRODUCT = 'IMPORTED_PRODUCT',
    DEFAULT = 'DEFAULT'
}

enum ConfigurationType {
    CHAT_ANONYMOUS = 'CHAT_ANONYMOUS',
    CHAT_CONNECTED_USER = 'CHAT_CONNECTED_USER',
    SMART_ADMIN = 'SMART_ADMIN'
}

Error Handling

The SDK throws typed errors that include:

• HTTP status code
• Error message from the API
• Additional context when available

try {
    await client.searchDocuments('query');
} catch (error) {
    console.error(error.message, error.status);
}

Rate Limiting

The API has rate limiting in place:

• Personal Chat Admin: 30 requests per minute
• Other endpoints: Standard rate limits apply

Support

For any questions or support, please contact us at [email protected].

License

MIT