@nlxai/chat-core

Interfaces

Type Aliases

Context

Ƭ Context:

Record<string, any>

Context for usage later in the intent.

Defined in

index.ts:13

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:42

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:49

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:242

Response

Ƭ Response:

BotResponse | UserResponse | FailureMessage

A response from the application or the user.

Defined in

index.ts:311

Time

Ƭ Time:

number

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

Defined in

index.ts:316

NormalizedStructuredRequest

Ƭ NormalizedStructuredRequest:

StructuredRequest & { slots?: SlotValue[] }

Normalized structured request with a single way to represent slots

Defined in

index.ts:455

LanguageCode

Ƭ LanguageCode:

string

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

Defined in

index.ts:555

BotRequestOverride

Ƭ BotRequestOverride: (

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

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

Type declaration

▸ (

botRequest, appendBotResponse): void

Parameters

Name	Type	Description
`botRequest`	`BotRequest`	The BotRequest that is being overridden
`appendBotResponse`	( `res`: `BotResponsePayload`) => `void`	-

Returns

void

Defined in

index.ts:562

VoicePlusContext

Ƭ VoicePlusContext:

any

Voice+ context, type to be defined

Defined in

index.ts:570

ConversationHandlerEvent

Ƭ ConversationHandlerEvent:

"voicePlusCommand"

Handler events

Defined in

index.ts:585

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:743

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:754

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:781

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:793

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:1321

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/chat-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:1358

Interfaces

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:158

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:163

text

• text:

string

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

Defined in

index.ts:167

choices

• choices:

Choice[]

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

Defined in

index.ts:171

metadata

•

Optional metadata: BotMessageMetadata

Metadata

Defined in

index.ts:175

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:180

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:148

Interface: BotRequest

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:469

userId

•

Optional userId: string

The current user ID

Defined in

index.ts:473

context

•

Optional context: Context

Request context, if applicable

Defined in

index.ts:477

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:481

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:63

receivedAt

• receivedAt:

number

When the response was received

Defined in

index.ts:67

payload

• payload:

BotResponsePayload

The payload of the response

Defined in

index.ts:71

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:117

escalation

•

Optional escalation: boolean

Whether the current conversation has been marked as incomprehension.

Defined in

index.ts:121

frustration

•

Optional frustration: boolean

Whether the current conversation has been marked frustrated

Defined in

index.ts:125

incomprehension

•

Optional incomprehension: boolean

Whether the current conversation has been marked as incomprehension.

Defined in

index.ts:129

uploadUrls

• uploadUrls:

UploadUrl[]

Upload URL's

Defined in

index.ts:133

hasPendingDataRequest

•

Optional hasPendingDataRequest: boolean

Whether the client should poll for more application responses.

Defined in

index.ts:137

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:81

conversationId

•

Optional conversationId: string

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

Defined in

index.ts:85

messages

• messages:

BotMessage[]

Any messages from the bot.

Defined in

index.ts:89

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:94

payload

•

Optional payload: string

If configured, the node's payload.

Defined in

index.ts:98

modalities

•

Optional modalities: Record<string, any>

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

Defined in

index.ts:102

context

•

Optional context: Context

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

Defined in

index.ts:106

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:204

choiceText

• choiceText:

string

The text of the choice

Defined in

index.ts:208

choicePayload

•

Optional choicePayload: any

An optional, schemaless payload for the choice.

Defined in

index.ts:212

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:534

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:540

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:545

intentId

•

Optional intentId: string

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

Defined in

index.ts:549

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:332

botUrl

•

Optional botUrl: string

Legacy name for application URL

Deprecated

use the applicationUrl field instead

Defined in

index.ts:337

headers

• headers:

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

Headers to forward to the NLX API.

Defined in

index.ts:341

conversationId

•

Optional conversationId: string

Set

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

Defined in

index.ts:351

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:355

responses

•

Optional responses: Response[]

When

responses is set, initialize the chatHandler with historical messages.

Defined in

index.ts:359

failureMessage

•

Optional failureMessage: string

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

Defined in

index.ts:363

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:368

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:377

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:606

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:612

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:619

sendWelcomeIntent

• sendWelcomeIntent: (

context?: Context) => void

Trigger the welcome intent. 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:629

sendIntent

• sendIntent: (

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

Trigger a specific intent.

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:636

getLiveKitCredentials

• getLiveKitCredentials: () =>

Promise<LiveKitCredentials>

Obtain LiveKit credentials to run the experience in voice.

Type declaration

▸ ():

Promise<LiveKitCredentials>

Returns

Promise<LiveKitCredentials>

Defined in

index.ts:643

terminateLiveKitCall

• terminateLiveKitCall: () =>

Promise<void>

Terminate LiveKit call

Type declaration

▸ ():

Promise<void>

Returns

Promise<void>

Defined in

index.ts:649

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:656

• 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:661

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:666

unsubscribeAll

• unsubscribeAll: () =>

void

Unsubscribe all callback from the conversation.

Type declaration

▸ ():

void

Returns

void

Defined in

index.ts:670

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:674

currentLanguageCode

• currentLanguageCode: () =>

string

Get the current language code

Type declaration

▸ ():

string

Returns

string

Defined in

index.ts:678

setLanguageCode

• setLanguageCode: (

languageCode: string) => void

Set the language code

Type declaration

▸ (

languageCode): void

Parameters

Name	Type
`languageCode`	`string`

Returns

void

Defined in

index.ts:682

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:687

destroy

• destroy: () =>

void

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

Type declaration

▸ ():

void

Returns

void

Defined in

index.ts:696

setBotRequestOverride

• setBotRequestOverride: (

override: undefined | BotRequestOverride) => void

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

Type declaration

▸ (

override): void

Parameters

Name	Type
`override`	`undefined` \| `BotRequestOverride`

Returns

void

Defined in

index.ts:700

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:704

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:711

sendVoicePlusContext

• sendVoicePlusContext: (

context: any) => void

Send voicePlus message

Type declaration

▸ (

context): void

Parameters

Name	Type
`context`	`any`

Returns

void

Defined in

index.ts:718

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:594

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:292

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:296

receivedAt

• receivedAt:

number

When the failure occurred.

Defined in

index.ts:305

Interface: LiveKitCredentials

Credentials to connect to a LiveKit channel

Properties

url

• url:

string

LiveKit URL

Defined in

index.ts:510

roomName

• roomName:

string

LiveKit room name

Defined in

index.ts:514

token

• token:

string

LiveKit token

Defined in

index.ts:518

participantName

• participantName:

string

LiveKit participant name

Defined in

index.ts:522

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:24

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:29

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:423

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:428

intentId

•

Optional intentId: string

The intent to trigger. The

intentId is the name under the application's Intents.

Defined in

index.ts:432

slots

•

Optional slots: SlotsRecordOrArray

The slots to populate

Defined in

index.ts:436

uploadIds

•

Optional uploadIds: string[]

Upload ID

Defined in

index.ts:440

utterance

•

Optional utterance: string

Upload utterance

Defined in

index.ts:444

Interface: UploadUrl

The upload destination for handling conversing with files

Properties

url

• url:

string

The URL of the upload

Defined in

index.ts:190

uploadId

• uploadId:

string

The ID of the upload

Defined in

index.ts:194

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:228

receivedAt

• receivedAt:

number

When the response was received

Defined in

index.ts:232

payload

• payload:

UserResponsePayload

The payload of the response

Defined in

index.ts:236

Interface: VoicePlusMessage

Messages sent to the Voice+ socket

Properties

context

• context:

any

Voice+ context

Defined in

index.ts:579