@nlxai/core

Interfaces

Type Aliases

Context

Ƭ Context:

Record<string, any>

Context for usage later in the intent.

Defined in

index.ts:18

SlotsRecord

Ƭ SlotsRecord:

Record<string, any>

Values to fill an intent's attached slots.

SlotRecord Keys are the attached slot's name

SlotRecord Values are usually a discrete value matching the slots's type. for custom slots, this can optionally be the value's ID.

SlotsRecord is equivalent to an array of SlotValue objects.

Defined in

index.ts:47

SlotsRecordOrArray

Ƭ SlotsRecordOrArray:

SlotsRecord | SlotValue[]

Values to fill an intent's attached slots.

Supports either a SlotsRecord or an array of SlotValue objects

Defined in

index.ts:54

ModalityPayloads

Ƭ ModalityPayloads:

Record<string, any>

Payloads for modalities as a key-value pair by modality name

Defined in

index.ts:117

UserResponsePayload

Ƭ UserResponsePayload: {

type: "text" ; text: string ; context?: Context } | { type: "choice" ; choiceId: string ; context?: Context } | { type: "structured" ; context?: Context } & StructuredRequest

The payload of the user response

Defined in

index.ts:282

Response

Ƭ Response:

BotResponse | UserResponse | FailureMessage

A response from the application or the user.

Defined in

index.ts:351

Time

Ƭ Time:

number

The time value in milliseconds since midnight, January 1, 1970 UTC.

Defined in

index.ts:356

NormalizedStructuredRequest

Ƭ NormalizedStructuredRequest:

StructuredRequest & { slots?: SlotValue[] }

Normalized structured request with a single way to represent slots

Defined in

index.ts:505

BotRequest

Ƭ BotRequest:

ApplicationRequest

Legacy name for application request

Deprecated

use ApplicationRequest

Defined in

index.ts:557

LanguageCode

Ƭ LanguageCode:

string

Language code named for clarity, may restrict it to a finite list

Defined in

index.ts:611

RequestOverride

Ƭ RequestOverride: (

botRequest: BotRequest, appendResponse: (res: BotResponsePayload) => void) => void

Instead of sending a request to the application, handle it in a custom fashion

Type declaration

▸ (

botRequest, appendResponse): void

Parameters

Name	Type	Description
`botRequest`	`BotRequest`	The BotRequest that is being overridden
`appendResponse`	( `res`: `BotResponsePayload`) => `void`	A method to append the BotResponsePayload to the message history

Returns

void

Defined in

index.ts:618

BotRequestOverride

Ƭ BotRequestOverride:

RequestOverride

Legacy name for bot request override

Deprecated

use RequestOverride instead

Defined in

index.ts:627

VoicePlusContext

Ƭ VoicePlusContext:

any

Voice+ context, type to be defined

Defined in

index.ts:632

ConversationHandlerEvent

Ƭ ConversationHandlerEvent:

"voicePlusCommand"

Handler events

Defined in

index.ts:647

Subscriber

Ƭ Subscriber: (

response: Response[], newResponse?: Response) => void

The callback function for listening to all responses.

Type declaration

▸ (

response, newResponse?): void

Parameters

Name	Type
`response`	`Response`[]
`newResponse?`	`Response`

Returns

void

Defined in

index.ts:825

Variables

version

•

Const version: string = packageJson.version

Package version

Defined in

index.ts:10

Functions

shouldReinitialize

▸ shouldReinitialize(

config1, config2): boolean

Helper method to decide when a new Config requires creating a new ConversationHandler or whether the old

Config's ConversationHandler can be used.

The order of configs doesn't matter.

Parameters

Name	Type
`config1`	`Config`
`config2`	`Config`

Returns

boolean

true if

createConversation should be called again

Defined in

index.ts:836

isConfigValid

▸ isConfigValid(

config): boolean

Check whether a configuration is value.

Parameters

Name	Type	Description
`config`	`Config`	Chat configuration

Returns

boolean

isValid - Whether the configuration is valid

Defined in

index.ts:891

createConversation

▸ createConversation(

config): ConversationHandler

Call this to create a conversation handler.

Parameters

Name	Type
`config`	`Config`

Returns

ConversationHandler

The ConversationHandler is a bundle of functions to interact with the conversation.

Defined in

index.ts:903

getCurrentExpirationTimestamp

▸ getCurrentExpirationTimestamp(

responses): null | number

Get current expiration timestamp from the current list of reponses

Parameters

Name	Type	Description
`responses`	`Response`[]	the current list of user and bot responses (first argument in the subscribe callback)

Returns

null | number

an expiration timestamp in Unix Epoch (

new Date().getTime()), or null if this is not known (typically occurs if the bot has not responded yet)

Defined in

index.ts:1488

promisify

▸ promisify<

T>(fn, convo, timeout?): (payload: T) => Promise<Response | null>

This package is intentionally designed with a subscription-based API as opposed to a promise-based one where each message corresponds to a single bot response, available asynchronously.

If you need a promise-based wrapper, you can use the

promisify helper available in the package:

Type parameters

Name	Description
`T`	the type of the function's params, e.g. for `sendText` it's `text: string, context?: Context`

Parameters

Name	Type	Default value	Description
`fn`	( `payload`: `T`) => `void`	`undefined`	the function to wrap (e.g. `convo.sendText`, `convo.sendChoice`, etc.)
`convo`	`ConversationHandler`	`undefined`	the `ConversationHandler` (from createConversation)
`timeout`	`number`	`10000`	the timeout in milliseconds

Returns

fn

A promise-wrapped version of the function. The function, when called, returns a promise that resolves to the Conversation's next response.

▸ (

payload): Promise<Response | null>

Parameters

Name	Type
`payload`	`T`

Returns

Promise<Response | null>

Example


1import { createConversation, promisify } from "@nlxai/core";
2
3const convo = createConversation(config);
4
5const sendTextWrapped = promisify(convo.sendText, convo);
6
7sendTextWrapped("Hello").then((response) => {
8  console.log(response);
9});

Defined in

index.ts:1525

Interfaces

Interface: ApplicationRequest

The request data actually sent to the application, slightly different from UserResponsePayload, which includes some UI-specific information

Properties

conversationId

•

Optional conversationId: string

The current conversation ID

Defined in

index.ts:519

userId

•

Optional userId: string

The current user ID

Defined in

index.ts:523

context

•

Optional context: Context

Request context, if applicable

Defined in

index.ts:527

request

• request:

Object

Main request

Type declaration

Name	Type	Description
`unstructured?`	{ `text`: `string` }	Unstructured request
`unstructured.text`	`string`	Request body text
`structured?`	`StructuredRequest` & { `slots?`: `SlotValue`[] }	Structured request

Defined in

index.ts:531

Interface: BotMessage

A message from the application, as well as any choices the user can make.

Properties

messageId

•

Optional messageId: string

A unique identifier for the message.

Defined in

index.ts:198

nodeId

•

Optional nodeId: string

The node id that this message is associated with. This is must be sent with a choice when the user is changing a previously sent choice.

Defined in

index.ts:203

text

• text:

string

The body of the message. Show this to the user.

Defined in

index.ts:207

choices

• choices:

Choice[]

A selection of choices to show to the user. They may choose one of them.

Defined in

index.ts:211

metadata

•

Optional metadata: BotMessageMetadata

Metadata

Defined in

index.ts:215

selectedChoiceId

•

Optional selectedChoiceId: string

After a choice has been made by the user, this will be updated locally to the selected choice id. This field is set locally and does not come from the application.

Defined in

index.ts:220

Interface: BotMessageMetadata

Metadata for the individual application message as well as whether the client should poll for more application responses.

Properties

intentId

•

Optional intentId: string

The message node's intent

Defined in

index.ts:188

Interface: BotResponse

A message from the application

Properties

type

• type:

"bot"

The type of the response is

"bot" for bot and "user" for user, and "failure" for failure.

Defined in

index.ts:68

receivedAt

• receivedAt:

number

When the response was received

Defined in

index.ts:72

payload

• payload:

BotResponsePayload

The payload of the response

Defined in

index.ts:76

Interface: BotResponseMetadata

Global state about the current conversation as well as whether the client should poll for more application responses.

Properties

intentId

•

Optional intentId: string

The conversation's intent

Defined in

index.ts:127

escalation

•

Optional escalation: boolean

Whether the current conversation has been marked as incomprehension.

Defined in

index.ts:131

frustration

•

Optional frustration: boolean

Whether the current conversation has been marked frustrated

Defined in

index.ts:135

incomprehension

•

Optional incomprehension: boolean

Whether the current conversation has been marked as incomprehension.

Defined in

index.ts:139

uploadUrls

• uploadUrls:

UploadUrl[]

Upload URL's

Defined in

index.ts:143

hasPendingDataRequest

•

Optional hasPendingDataRequest: boolean

Whether the client should poll for more application responses.

Defined in

index.ts:147

sources

•

Optional sources: KnowledgeBaseResponseSource[]

Knowledge base sources

Defined in

index.ts:151

Interface: BotResponsePayload

The payload of the bot response

Properties

expirationTimestamp

•

Optional expirationTimestamp: number

If there isn't some interaction by this time, the conversation will expire.

Defined in

index.ts:86

conversationId

•

Optional conversationId: string

The active conversation ID. If not set, a new conversation will be started.

Defined in

index.ts:90

messages

• messages:

BotMessage[]

Any messages from the bot.

Defined in

index.ts:94

metadata

•

Optional metadata: BotResponseMetadata

Global state about the current conversation as well as whether the client should poll for more application responses.

Defined in

index.ts:99

payload

•

Optional payload: string

If configured, the node's payload.

Defined in

index.ts:103

modalities

•

Optional modalities: ModalityPayloads

If configured, the node's modalities and their payloads.

Defined in

index.ts:107

context

•

Optional context: Context

If the node is set to send context, the whole context associated with the conversation.

Defined in

index.ts:111

Interface: Choice

A choices to show to the user.

Properties

choiceId

• choiceId:

string

choiceId is used by sendChoice to let the user choose this choice.

Defined in

index.ts:244

choiceText

• choiceText:

string

The text of the choice

Defined in

index.ts:248

choicePayload

•

Optional choicePayload: any

An optional, schemaless payload for the choice.

Defined in

index.ts:252

Interface: ChoiceRequestMetadata

Helps link the choice to the specific message in the conversation.

Properties

responseIndex

•

Optional responseIndex: number

The index of the Response associated with this choice. Setting this ensures that local state's

selectedChoiceId on the corresponding BotResponse is set. It is not sent to the application.

Defined in

index.ts:590

messageIndex

•

Optional messageIndex: number

The index of the BotMessage associated with this choice. Setting this ensures that local state's

selectedChoiceId on the corresponding BotResponse is set. It is not sent to the application.

Defined in

index.ts:596

nodeId

•

Optional nodeId: string

Required if you want to change a choice that's already been sent. The

nodeId can be found in the corresponding BotMessage.

Defined in

index.ts:601

intentId

•

Optional intentId: string

Intent ID, used for sending to the NLU to allow it to double-check

Defined in

index.ts:605

Interface: Config

The configuration to create a conversation.

Properties

applicationUrl

•

Optional applicationUrl: string

Fetch this from the application's Deployment page.

Defined in

index.ts:372

botUrl

•

Optional botUrl: string

Legacy name for application URL

Deprecated

use the applicationUrl field instead

Defined in

index.ts:377

headers

• headers:

Record<string, string> & { nlx-api-key: string }

Headers to forward to the NLX API.

Defined in

index.ts:381

conversationId

•

Optional conversationId: string

Set

conversationId to continue an existing conversation. If not set, a new conversation will be started.

Defined in

index.ts:391

userId

•

Optional userId: string

Setting the

userID allows it to be searchable in application history, as well as usable via {System.userId} in the intent.

Defined in

index.ts:395

responses

•

Optional responses: Response[]

When

responses is set, initialize the chatHandler with historical messages.

Defined in

index.ts:399

failureMessage

•

Optional failureMessage: string

When set, this overrides the default failure message ("We encountered an issue. Please try again soon.").

Defined in

index.ts:403

languageCode

• languageCode:

string

The language code to use for the application. In the browser this can be fetched with

navigator.language. If you don't have translations, hard-code this to the language code you support.

Defined in

index.ts:408

bidirectional

•

Optional bidirectional: boolean

Specifies whether the conversation is bidirectional

Defined in

index.ts:417

experimental

•

Optional experimental: Object

Experimental settings

Type declaration

Name	Type	Description
`channelType?`	`string`	Simulate alternative channel types
`completeBotUrl?`	`boolean`	Prevent the `languageCode` parameter to be appended to the application URL - used in special deployment environments such as the sandbox chat inside Dialog Studio

Defined in

index.ts:421

Interface: ConversationHandler

A bundle of functions to interact with a conversation, created by createConversation.

Properties

sendText

• sendText: (

text: string, context?: Context) => void

Send user's message

Type declaration

▸ (

text, context?): void

Parameters

Name	Type	Description
`text`	`string`	the user's message
`context?`	`Context`	Context for usage later in the intent.

Returns

void

Defined in

index.ts:668

sendSlots

• sendSlots: (

slots: SlotsRecordOrArray, context?: Context) => void

Send slots to the application.

Type declaration

▸ (

slots, context?): void

Parameters

Name	Type	Description
`slots`	`SlotsRecordOrArray`	The slots to populate
`context?`	`Context`	Context for usage later in the intent.

Returns

void

Defined in

index.ts:674

sendChoice

• sendChoice: (

choiceId: string, context?: Context, metadata?: ChoiceRequestMetadata) => void

Respond to a choice from the application.

Type declaration

▸ (

choiceId, context?, metadata?): void

Parameters

Name	Type	Description
`choiceId`	`string`	-
`context?`	`Context`	Context for usage later in the intent.
`metadata?`	`ChoiceRequestMetadata`	links the choice to the specific message and node in the conversation.

Returns

void

Defined in

index.ts:681

sendWelcomeFlow

• sendWelcomeFlow: (

context?: Context) => void

Trigger the welcome flow. This should be done when the user starts interacting with the chat.

Type declaration

▸ (

context?): void

Parameters

Name	Type	Description
`context?`	`Context`	Context for usage later in the intent.

Returns

void

Defined in

index.ts:691

sendWelcomeIntent

• sendWelcomeIntent: (

context?: Context) => void

Trigger the welcome intent. This should be done when the user starts interacting with the chat.

Deprecated

use

sendWelcomeFlow instead

Type declaration

▸ (

context?): void

Parameters

Name	Type	Description
`context?`	`Context`	Context for usage later in the intent.

Returns

void

Defined in

index.ts:698

sendFlow

• sendFlow: (

flowId: string, context?: Context) => void

Trigger a specific flow.

Type declaration

▸ (

flowId, context?): void

Parameters

Name	Type	Description
`flowId`	`string`	the flow to trigger. The id is the name under the application's Intents.
`context?`	`Context`	Context for usage later in the intent.

Returns

void

Defined in

index.ts:705

sendIntent

• sendIntent: (

intentId: string, context?: Context) => void

Trigger a specific intent.

Deprecated

use

sendFlow instead

Type declaration

▸ (

intentId, context?): void

Parameters

Name	Type	Description
`intentId`	`string`	the intent to trigger. The id is the name under the application's Intents.
`context?`	`Context`	Context for usage later in the intent.

Returns

void

Defined in

index.ts:713

sendContext

• sendContext: (

context: Context) => Promise<void>

Send context without sending a message

Type declaration

▸ (

context): Promise<void>

Parameters

Name	Type	Description
`context`	`Context`	Context for usage later in the intent.

Returns

Promise<void>

Defined in

index.ts:719

getVoiceCredentials

• getVoiceCredentials: (

context?: Context) => Promise<VoiceCredentials>

Obtain Voice credentials to run the experience in voice.

Type declaration

▸ (

context?): Promise<VoiceCredentials>

Parameters

Name	Type
`context?`	`Context`

Returns

Promise<VoiceCredentials>

Defined in

index.ts:726

sendStructured

• sendStructured: (

request: StructuredRequest, context?: Context) => void

Send a combination of choice, slots, and intent in one request.

Type declaration

▸ (

request, context?): void

Parameters

Name	Type	Description
`request`	`StructuredRequest`
`context?`	`Context`	Context for usage later in the intent.

Returns

void

Defined in

index.ts:733

• subscribe: (

subscriber: Subscriber) => () => void

Subscribe a callback to the conversation. On subscribe, the subscriber will receive all of the Responses that the conversation has already received.

Type declaration

▸ (

subscriber): () => void

Parameters

Name	Type	Description
`subscriber`	`Subscriber`	The callback to subscribe

Returns

fn

▸ ():

void

Returns

void

Defined in

index.ts:738

unsubscribe

• unsubscribe: (

subscriber: Subscriber) => void

Unsubscribe a callback from the conversation.

Type declaration

▸ (

subscriber): void

Parameters

Name	Type	Description
`subscriber`	`Subscriber`	The callback to unsubscribe

Returns

void

Defined in

index.ts:743

unsubscribeAll

• unsubscribeAll: () =>

void

Unsubscribe all callback from the conversation.

Type declaration

▸ ():

void

Returns

void

Defined in

index.ts:747

currentConversationId

• currentConversationId: () =>

undefined | string

Get the current conversation ID if it's set, or undefined if there is no conversation.

Type declaration

▸ ():

undefined | string

Returns

undefined | string

Defined in

index.ts:751

currentLanguageCode

• currentLanguageCode: () =>

string

Get the current language code

Type declaration

▸ ():

string

Returns

string

Defined in

index.ts:755

setLanguageCode

• setLanguageCode: (

languageCode: string) => void

Set the language code

Type declaration

▸ (

languageCode): void

Parameters

Name	Type
`languageCode`	`string`

Returns

void

Defined in

index.ts:759

reset

• reset: (

options?: { clearResponses?: boolean }) => void

Forces a new conversation. If

clearResponses is set to true, will also clear historical responses passed to subscribers. Retains all existing subscribers.

Type declaration

▸ (

options?): void

Parameters

Name	Type	Description
`options?`	`Object`	-
`options.clearResponses?`	`boolean`	If set to true, will clear historical responses passed to subscribers.

Returns

void

Defined in

index.ts:764

destroy

• destroy: () =>

void

Removes all subscribers and, if using websockets, closes the connection.

Type declaration

▸ ():

void

Returns

void

Defined in

index.ts:773

setBotRequestOverride

• setBotRequestOverride: (

override: undefined | RequestOverride) => void

Optional RequestOverride function used to bypass the bot request and handle them in a custom fashion

Deprecated

use

setRequestOverride instead

Type declaration

▸ (

override): void

Parameters

Name	Type
`override`	`undefined` \| `RequestOverride`

Returns

void

Defined in

index.ts:778

setRequestOverride

• setRequestOverride: (

override: undefined | RequestOverride) => void

Optional RequestOverride function used to bypass the bot request and handle them in a custom fashion

Type declaration

▸ (

override): void

Parameters

Name	Type
`override`	`undefined` \| `RequestOverride`

Returns

void

Defined in

index.ts:782

addEventListener

• addEventListener: (

event: "voicePlusCommand", handler: (payload: any) => void) => void

Add a listener to one of the handler's custom events

Type declaration

▸ (

event, handler): void

Parameters

Name	Type
`event`	`"voicePlusCommand"`
`handler`	( `payload`: `any`) => `void`

Returns

void

Defined in

index.ts:786

removeEventListener

• removeEventListener: (

event: "voicePlusCommand", handler: (payload: any) => void) => void

Remove a listener to one of the handler's custom events

Type declaration

▸ (

event, handler): void

Parameters

Name	Type
`event`	`"voicePlusCommand"`
`handler`	( `payload`: `any`) => `void`

Returns

void

Defined in

index.ts:793

sendVoicePlusContext

• sendVoicePlusContext: (

context: any) => void

Send voicePlus message

Type declaration

▸ (

context): void

Parameters

Name	Type
`context`	`any`

Returns

void

Defined in

index.ts:800

Interface: EventHandlers

Dictionary of handler methods per event

Properties

voicePlusCommand

• voicePlusCommand: (

payload: any) => void

Voice+ command event handler

Type declaration

▸ (

payload): void

Parameters

Name	Type
`payload`	`any`

Returns

void

Defined in

index.ts:656

Interface: FailureMessage

A failure message is received when the NLX api is unreachable, or sends an unparsable response.

Properties

type

• type:

"failure"

The type of the response is

"bot" for bot and "user" for user.

Defined in

index.ts:332

payload

• payload:

Object

The payload only includes an error message.

Type declaration

Name	Type	Description
`text`	`string`	The error message is either the default, or the `failureMessage` set in the Config.

Defined in

index.ts:336

receivedAt

• receivedAt:

number

When the failure occurred.

Defined in

index.ts:345

Interface: KnowledgeBaseResponseSource

Response for knowlege base sources

Properties

fileName

•

Optional fileName: string

File name

Defined in

index.ts:161

pageNumber

•

Optional pageNumber: number

Page number

Defined in

index.ts:165

content

•

Optional content: string

Content

Defined in

index.ts:169

metadata

•

Optional metadata: Record<string, unknown>

Metadata

Defined in

index.ts:173

presignedUrl

•

Optional presignedUrl: string

Presigned URL for direct retrieval

Defined in

index.ts:177

Interface: SlotValue

Values to fill an intent's attached slots.

An array of

SlotValue objects is equivalent to a SlotsRecord.

Properties

slotId

• slotId:

string

The attached slot's name

Defined in

index.ts:29

value

• value:

any

Usually this will be a discrete value matching the slots's type. for custom slots, this can optionally be the value's ID.

Defined in

index.ts:34

Interface: StructuredRequest

The body of

sendStructured Includes a combination of choice, slots, and intent in one request.

Properties

choiceId

•

Optional choiceId: string

The

choiceId is in the BotResponse's .payload.messages[].choices[].choiceId fields

Defined in

index.ts:468

nodeId

•

Optional nodeId: string

Required if you want to change a choice that's already been sent. The

nodeId can be found in the corresponding BotMessage.

Defined in

index.ts:473

intentId

•

Optional intentId: string

The intent to trigger. The

intentId is the name under the application's Intents.

Deprecated

use

flowId instead.

Defined in

index.ts:478

flowId

•

Optional flowId: string

The flow to trigger. The

flowId is the name under the application's Flows.

Defined in

index.ts:482

slots

•

Optional slots: SlotsRecordOrArray

The slots to populate

Defined in

index.ts:486

uploadIds

•

Optional uploadIds: string[]

Upload ID

Defined in

index.ts:490

utterance

•

Optional utterance: string

Upload utterance

Defined in

index.ts:494

Interface: UploadUrl

The upload destination for handling conversing with files

Properties

url

• url:

string

The URL of the upload

Defined in

index.ts:230

uploadId

• uploadId:

string

The ID of the upload

Defined in

index.ts:234

Interface: UserResponse

A message from the user

Properties

type

• type:

"user"

The type of the response is

"bot" for bot and "user" for user, and "failure" for failure.

Defined in

index.ts:268

receivedAt

• receivedAt:

number

When the response was received

Defined in

index.ts:272

payload

• payload:

UserResponsePayload

The payload of the response

Defined in

index.ts:276

Interface: VoiceCredentials

Credentials to connect to a Voice channel

Properties

url

• url:

string

Voice Connection URL

Defined in

index.ts:566

roomName

• roomName:

string

Voice room name

Defined in

index.ts:570

token

• token:

string

Voice token

Defined in

index.ts:574

participantName

• participantName:

string

Voice participant name

Defined in

index.ts:578

Interface: VoicePlusMessage

Messages sent to the Voice+ socket

Properties

context

• context:

any

Voice+ context

Defined in

index.ts:641