@nlxai/chat-core

Interfaces

SlotValue
BotResponse
BotResponsePayload
BotResponseMetadata
BotMessageMetadata
BotMessage
UploadUrl
Choice
UserResponse
FailureMessage
Config
StructuredRequest
BotRequest
ChoiceRequestMetadata
ConversationHandler

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.

A 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 bot 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:450

BotRequestOverride

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

Instead of sending a request to the bot, 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:530

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

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

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

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

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

Interfaces

Interface: BotMessage

A message from the bot, 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 bot.

Defined in

index.ts:180

Interface: BotMessageMetadata

Metadata for the individual bot message as well as whether the client should poll for more bot 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 bot, slightly different from UserResponsePayload, which includes some UI-specific information

Properties

conversationId

• Optional conversationId: string

The current conversation ID

Defined in

index.ts:464

userId

• Optional userId: string

The current user ID

Defined in

index.ts:468

context

• Optional context: Context

Request context, if applicable

Defined in

index.ts:472

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

Interface: BotResponse

A message from the bot

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 bot 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 bot 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 bot 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 bot.

Defined in

index.ts:507

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 bot.

Defined in

index.ts:513

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

intentId

• Optional intentId: string

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

Defined in

index.ts:522

Interface: Config

The configuration to create a conversation.

Properties

botUrl

• botUrl: string

Fetch this from the bot's Deployment page.

Defined in

index.ts:332

headers

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

Headers to forward to the NLX API.

Defined in

index.ts:336

conversationId

• Optional conversationId: string

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

Defined in

index.ts:346

userId

• Optional userId: string

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

Defined in

index.ts:350

responses

• Optional responses: Response[]

When responses is set, initialize the chatHandler with historical messages.

Defined in

index.ts:354

failureMessage

• Optional failureMessage: string

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

Defined in

index.ts:358

languageCode

• languageCode: string

The language code to use for the bot. 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:363

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 bot URL - used in special deployment environments such as the sandbox chat inside Dialog Studio

Defined in

index.ts:372

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

sendSlots

• sendSlots: (slots: SlotsRecordOrArray, context?: Context) => void

Send slots to the bot.

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

sendChoice

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

Respond to a choice from the bot.

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

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

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 Bot's Intents.
`context?`	`Context`	Context for usage later in the intent.

Returns

void

Defined in

index.ts:574

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

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

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

unsubscribeAll

• unsubscribeAll: () => void

Unsubscribe all callback from the conversation.

Type declaration

▸ (): void

Returns

void

Defined in

index.ts:595

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

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.