4.0.4 • Published 1 month ago

abnk-assistant-js-client v4.0.4

Weekly downloads
-
License
ISC
Repository
-
Last release
1 month ago

ABNK Assistant JS Client

The ABNK Assistant JS Client is a versatile JavaScript library that simplifies interaction with the ABNK Assistant API. With this library, you can effortlessly send questions to the API and receive text responses. It provides flexibility by supporting multiple module systems, including UMD, CommonJS (CJS), and ECMAScript Modules (ESM).

Table of Contents

  1. Installation
  2. Usage
  3. API

Installation

You can install the ABNK Assistant JS Client via npm by running the following command:

npm install abnk-assistant-js-client

or

You can link this library just in your HTML using <script> tag. See more about it in Usage

<script src="https://unpkg.com/abnk-assistant-js-client"></script>

Usage

UMD Module (<script> tag)

When using the ABNK Assistant JS Client as a UMD module, you can include it directly in an HTML file using a <script> tag. Here's an example:

<!doctype html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <title>ABNK Assistant JS Client Example</title>
    </head>
    <body>
        <script src="https://unpkg.com/abnk-assistant-js-client"></script>
        <script>
            const clientConfig = {
                companyId: '12345678qwerty',
                baseUrl: 'https://api.example.com',
            }

            const client = new AbnkAssistantClient(clientConfig)
            // also possible to access from window.AbnkAssistantClient

            // Example usage:
            client.getChatBotAnswer('What is the weather today?').then((response) => {
                console.log(response)
            })
        </script>
    </body>
</html>

CommonJS (CJS) Module (Node.js)

When working in a Node.js environment, you can use the ABNK Assistant JS Client as a CommonJS module. Here's an example:

const AbnkAssistantClient = require('abnk-assistant-js-client') // Access the CJS module

const clientConfig = {
    companyId: '12345678qwerty',
    baseUrl: 'https://api.example.com',
}

const client = new AbnkAssistantClient(clientConfig)

// Example usage:
client.getChatBotAnswer('What is the weather today?').then((response) => {
    console.log(response)
})

ECMAScript Modules (ESM)

If you prefer using ECMAScript Modules (ESM) in modern JavaScript environments, you can import the ABNK Assistant JS Client like this:

import AbnkAssistantClient from 'abnk-assistant-js-client'

// Access the ESM module

const clientConfig = {
    companyId: '12345678qwerty',
    baseUrl: 'https://api.example.com',
}

const client = new AbnkAssistantClient(clientConfig)

// Example usage:
async function getResponse() {
    const response = await client.getChatBotAnswer('What is the weather today?')
    console.log(response)
}

getResponse()

API

AbnkAssistantClient(configUrl: ConfigUrlType)

When creating an instance of this class, you need to provide the clientConfig object according to the ClientConfigType type. This object should contain the following fields:

  • companyId (Required, string): The identifier of your company or organization.
  • baseUrl (Optional, string): The base URL for the API (default value).

AbnkAssistantClient methods:

getChatBotAnswer(question: string, questionerId?: string)

This method is used to query the ABNK Assistant API with a specific question and, optionally, a related questioner ID.

Parameters:

  • question (Required, string): The question to be sent to the ABNK Assistant API for a response.

  • questionerId (Optional, QuestionerIdType): The Mongo ObjectId string that relates to one of the existing questioners. If provided, it associates the question with a specific questioner. If not provided, a new questioner can be created using the createQuestioner method (described below).

Returns:

A Promise<FaqAnswerType> that resolves with the response from the ABNK Assistant API.

Example Usage:
const client = new AbnkAssistantClient(clientConfig)

try {
    const question = 'How can I reset my password?'
    const questionerId = '655b746ca72f81fcdded2839' // Optional

    const answer = await client.getChatBotAnswer(question, questionerId)
    console.log(answer)
} catch (error) {
    console.error('Error getting FAQ answer:', error)
}

getAssistantAnswer(question: string, assistantThreadId?: AssistantThreadIdType, questionerId?: QuestionerIdType)

This method is also used to query the ABNK Assistant API with a specific question, along with assistant id, and optionally, an assistant thread id and a related questioner ID. This method was created to use the new features of the OpenAI API.

Parameters:

  • question (Required, string): The question to be sent to the ABNK Assistant API for a response.

  • assistantId (Required, AssistantIdType): The OpenAI Assistant ID that will be used for generating answers.

  • assistantThreadId (Optional, AssistantThreadIdType): The OpenAI Assistant Thread ID, that represents the id of the entity, that stores the context of a dialogue

  • questionerId (Optional, QuestionerIdType): The Mongo ObjectId string that relates to one of the existing questioners. If provided, it associates the question with a specific questioner. If not provided, a new questioner can be created using the createQuestioner method (described below).

Returns:

A Promise<AssistantAnswerType> that resolves with the response from the ABNK Assistant API.

Example Usage:
const client = new AbnkAssistantClient(clientConfig)

try {
    const question = 'How can I reset my password?'
    const assistantId = 'asst_abc123'
    const assistantThreadId = 'thread_abc123' // Optional
    const questionerId = '655b746ca72f81fcdded2839' // Optional

    const answer = await client.getAssistantAnswer(question, assistantId, assistantThreadId, questionerId)
    console.log(answer)
} catch (error) {
    console.error('Error getting assistant answer:', error)
}

getChatBotConfig()

This method is used to retrieve the configuration settings for the chatbot.

Returns:

A Promise<ChatBotConfigType> that resolves with the configuration settings for the chatbot.

The configuration settings for the chatbot include the following fields:

  • chatBotName (string): The name of the chatbot.
  • greetingMessage (string): The greeting message displayed by the chatbot.
  • greetSpontaneously (boolean, optional): Indicates whether the chatbot spontaneously show a welcome message.
  • role (string): The role of the chatbot.
  • responseLength (number): The maximum length of responses from the chatbot.

  • questionerInfo (object): The settings for what personal information should be collected from a user who asks questions to the chatbot. questionerInfo has the following structure:

    {
    required: boolean  // if true, the questioner will not be able to ask questions to the chatbot after the *afterMessages* number of questions in the chatbot
    fields: {
        email: {
            collect: boolean // whether to ask an email from the questioner
            message?: string // message for placeholder of an input field
        }
        name: {
            collect: boolean
            message?: string
        }
        phoneNumber: {
            collect: boolean
            message?: string
        }
    }
    afterMessages?: number // after this number of questions the questioner will not be able to ask questions, until they enter their personal data (if *required: true*)
}

  • suggestedQuestions (object): This field stores the configuration and a list of questions that can be suggested to the user as the most frequently asked questions. suggestedQuestions has the following structure:

    {
    _id: string
    suggest: boolean // indicates whether to suggest the questions to the questioner or not
    list: {
        // stores the list of all the questions
        suggest: boolean // indicates whether or not to offer this particular question to the questioner
        topic: string
        answer: string
    }
    ;[]
}

Example usage:

const client = new AbnkAssistantClient(clientConfig)

try {
    const chatBotConfig = await client.getChatBotConfig()
    console.log('Chatbot configuration:', chatBotConfig)
} catch (error) {
    console.error('Error while retrieving chatbot configuration:', error)
}

createQuestioner(questionerPersonalInfo: QuestionerPersonalInfoType, qnaIds: string[])

This method is used to create a new questioner and returns a Promise that resolves with the created CreateQuestionerReturnType.

Parameters:

  • questionerPersonalInfo (Required, QuestionerPersonalInfoType): Personal information of the questioner. It consists of:

    • name (Optional, string): The name of the questioner.
    • phoneNumber (Optional, string): The phone number of the questioner.
    • email (Optional, string): The email address of the questioner.

  • qnaIds (Optional, string[]): An array of the Mongo ObjectId strings of QnA IDs to associate with the newly created questioner. Each QnA ID will be linked to the questioner by setting their questionerId property.

  • assistantId (Optional, AssistantIdType): An ID of the assistant associated with new the newly create questioner.

Returns:

  • Promise<CreateQuestionerReturnType>: A promise that resolves with the created CreateQuestionerReturnType.

Example usage:

const client = new AbnkAssistantClient(clientConfig)

try {
    const questionerPersonalInfo = {
        name: 'John Doe',
        phoneNumber: '123-456-7890',
        email: 'john.doe@example.com',
    }
    const qnaIds = [
        '650b01a5cc7ff6d127bb85d1',
        '650b01a5cc7ff6d127bb85d2',
        '650b01a5cc7ff6d127bb85d3',
        '650b01a5cc7ff6d127bb85d4',
    ]
    const assistantId = 'asst_6SG2F95X8yU4Riyq4JcfMNeE'

    const result = await client.createQuestioner(questionerPersonalInfo, qnaIds, assistantId)
    console.log('Created Questioner:', result.questioner)
    console.log('Updated QnAs count:', result.updatedQnAs)
    console.log('Associated Assistant ID:', result.assistantId)
} catch (error) {
    console.error('Error while creating questioner:', error)
}

sendSupportEmail(supportEmail: SupportEmailType)

This method is used to send a support email and returns a Promise that resolves with the response of the email sending operation in the form of SendSupportEmailReturnType.

Parameters:

  • supportEmail (Required, SupportEmailType): An object containing the following properties:

    • email (Required, string): The email address to which the support email will be sent.
    • text (Required, string): The content of the support email.

  • assistantId (Required, AssistantIdType): An Id of the assistant.

Returns:

  • Promise<SendSupportEmailReturnType>: A promise that resolves with the response of the email sending operation.

Example usage:

const client = new AbnkAssistantClient(clientConfig)

try {
    const supportEmail = {
        email: 'support@example.com',
        text: 'This is a sample support request. Please assist.',
    }
    const assistantId = 'asst_6SG2F95X8yU4Riyq4JcfMNuE'

    const result = await client.sendSupportEmail(supportEmail, assistantId)
    console.log('Support Email Sent. Message ID:', result.body.messageId)
} catch (error) {
    console.error('Error while sending support email:', error)
}

getAssistantConfig()

This method is used to retrieve the configuration settings for the assistant.

Returns:

A Promise<AssistantType> that resolves with the configuration settings for the assistant. The configuration includes details such as the assistant's ID, name, description, model, tools, file IDs, metadata, allowed hosts, greeting message, whether it greets spontaneously, response length, blacklisted URLs, information about the questioner, suggested questions, maintenance mode, and whether human support is enabled.

Example Usage:

try {
    const assistantConfig = await client.getAssistantConfig()
    console.log('Assistant Configuration:', assistantConfig)
} catch (error) {
    console.error('Error while retrieving assistant configuration:', error)
}

getAIMode()

This method is used to retrieve the current AI mode.

Returns:

A Promise<GetAIModeReturnType> that resolves with the current AI mode, which can be either 'assistant' or 'completion'.

Example Usage:

try {
    const aiMode = await client.getAIMode()
    console.log('Current AI Mode:', aiMode.AIMode)
} catch (error) {
    console.error('Error while retrieving AI mode:', error)
}

Types

AssistantType

type AssistantType = {
    name: string
    greetingMessage?: string
    greetSpontaneously?: boolean
    responseLength: ChatBotResponseLengthEnum
    questionerInfo: QuestionerInfoType
    suggestedQuestions: SuggestedQuestionsType
    humanSupport?: boolean
    voiceTools: VoiceToolsType
}

ChatBotType

type ChatBotType = {
    chatBotName: string
    greetingMessage?: string
    greetSpontaneously?: boolean
    responseLength: ChatBotResponseLengthEnum
    questionerInfo: QuestionerInfoType
    suggestedQuestions: SuggestedQuestionsType
    humanSupport?: boolean
    voiceTools: VoiceToolsType
}

CreateQuestionerReturnType

type CreateQuestionerReturnType = {
    questioner: QuestionerType
    updatedQnAs?: number
}

ChatBotAnswerType

type FaqAnswerType = {
    _id: string
    companyId: string
    question: string
    answer: string
    createdAt: string
    updatedAt: string
    __v: number
}

AssistantAnswerType

type AssistantAnswerType = {
    _id: string
    companyId: string
    question: string
    answer: string
    questionerId?: QuestionerIdType
    assistantThreadId?: AssistantThreadIdType
    createdAt: string
    updatedAt: string
    __v: number
}

GetAIModeReturnType

type GetAIModeReturnType = {
    AIMode: AIModeEnum
}

MaintenanceModeType

type MaintenanceModeType = {
    maintenance: boolean
    message?: string
}

QuestionerInfoType

type QuestionerInfoType = {
    required: boolean
    fields: {
        email: {
            collect: boolean
            message?: string
        }
        name: {
            collect: boolean
            message?: string
        }
        phoneNumber: {
            collect: boolean
            message?: string
        }
    }
    afterMessages?: number
}

QuestionerPersonalInfoType

type QuestionerPersonalInfoType = {
    name?: string
    email?: string
    phoneNumber?: string
}

QuestionerType

type QuestionerType = {
    _id: QuestionerIdType
    name?: string
    phoneNumber?: string
    email?: string
    companyId: CompanyIdType
    createdAt?: Date
    updatedAt?: Date
}

SendSupportEmailReturnType

type SendSupportEmailReturnType = {
    body: { messageId?: string; messageIds?: string[] }
}

SupportEmailType

type SupportEmailType = {
    email: string
    text: string
}

SuggestedQuestionsType

type SuggestedQuestionsType = {
    suggest: boolean
    list: {
        suggest: boolean
        topic: string
        answer: string
    }[]
}

AssistantAppearanceType

type AssistantAppearanceType = {
    placement?: AssistantPlacementType | null
    themes: AssistantThemeType[]
    activeTheme?: AssistantThemeType['name'] | null
}

AssistantPlacementType

type AssistantPlacementType = {
    defaultOffset: AssistantOffsetType
    breakpoints: AssistantPlacementBreakpointType[]
}

AssistantOffsetType

type AssistantOffsetType = {
    [K in AssistantOffsetPropertiesEnum]: number | null
}

AssistantPlacementBreakpointType

type AssistantPlacementBreakpointType = {
    offset: AssistantOffsetType
    maxWidth: number | null
    minWidth: number | null
}

AssistantThemeType

type AssistantThemeType = {
    name: string
    colors: AssistantThemeColorsType
}

AssistantThemeColorsType

type AssistantThemeColorsType = {
    [T in AssistantThemeColorsEnum]?: string | null
}

Enums

AIModeEnum

enum AIModeEnum {
    ASSISTANT = 'assistant',
    COMPLETION = 'completion',
}

ChatBotResponseLengthEnum

enum ChatBotResponseLengthEnum {
    SHORT = 'short',
    MEDIUM = 'medium',
    LONG = 'long',
}

ChatBotRoleEnum

enum ChatBotRoleEnum {
    SYSTEM = 'system',
    USER = 'user',
    ASSISTANT = 'assistant',
}

AssistantThemeColorsEnum

enum AssistantThemeColorsEnum {
    BACKGROUND_PRIMARY = 'backgroundPrimary',
    BACKGROUND_SECONDARY = 'backgroundSecondary',
    BACKGROUND_ALT = 'backgroundAlt',
    BACKGROUND_ACCENT = 'backgroundAccent',
    BACKGROUND_BOT_MESSAGE = 'backgroundBotMessage',
    BACKGROUND_QUESTIONER_MESSAGE = 'backgroundQuestionerMessage',
    BACKGROUND_SUCCESS = 'backgroundSuccess',
    BACKGROUND_ERROR = 'backgroundError',
    TEXT_COLOR_PRIMARY = 'textColorPrimary',
    TEXT_COLOR_SECONDARY = 'textColorSecondary',
    TEXT_COLOR_ALT = 'textColorAlt',
    TEXT_COLOR_ACCENT = 'textColorAccent',
    TEXT_COLOR_SUCCESS = 'textColorSuccess',
    TEXT_COLOR_ERROR = 'textColorError',
}

AssistantOffsetPropertiesEnum

enum AssistantOffsetPropertiesEnum {
    TOP = 'top',
    BOTTOM = 'bottom',
    RIGHT = 'right',
    LEFT = 'left',
}
node
lodash
@everything-registry/sub-chunk-1090abnk-assistant-chatbot
4.0.4

1 month ago

4.0.3

1 month ago

4.0.2

2 months ago

4.0.1

2 months ago

4.0.0

3 months ago

3.2.0

4 months ago

3.1.1

4 months ago

3.1.0

5 months ago

2.2.0

5 months ago

2.1.2

5 months ago

2.1.1

6 months ago

2.1.0

6 months ago

3.0.0

7 months ago

2.0.0

8 months ago

1.0.1

8 months ago

1.0.0

8 months ago