Developer Docs

Headless API

API reference

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

A

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
NameTypeDescription
botRequestBotRequestThe BotRequest that is being overridden
appendResponse(res: BotResponsePayload) => voidA 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
NameType
responseResponse[]
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

NameType
config1Config
config2Config

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

NameTypeDescription
configConfigChat 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

NameType
configConfig

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

NameTypeDescription
responsesResponse[]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

NameDescription
Tthe type of the function's params, e.g. for sendText it's text: string, context?: Context

Parameters

NameTypeDefault valueDescription
fn(payload: T) => voidundefinedthe function to wrap (e.g. convo.sendText, convo.sendChoice, etc.)
convoConversationHandlerundefinedthe ConversationHandler (from createConversation)
timeoutnumber10000the 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
NameType
payloadT
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
NameTypeDescription
unstructured?{ text: string }Unstructured request
unstructured.textstringRequest 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

See also:

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
NameTypeDescription
channelType?stringSimulate alternative channel types
completeBotUrl?booleanPrevent 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
NameTypeDescription
textstringthe user's message
context?ContextContext 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
NameTypeDescription
slotsSlotsRecordOrArrayThe slots to populate
context?ContextContext 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
NameTypeDescription
choiceIdstring-
context?ContextContext for usage later in the intent.
metadata?ChoiceRequestMetadatalinks 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
NameTypeDescription
context?ContextContext 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
NameTypeDescription
context?ContextContext 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
NameTypeDescription
flowIdstringthe flow to trigger. The id is the name under the application's Intents.
context?ContextContext 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
NameTypeDescription
intentIdstringthe intent to trigger. The id is the name under the application's Intents.
context?ContextContext 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
NameTypeDescription
contextContextContext 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
NameType
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
NameTypeDescription
requestStructuredRequest
context?ContextContext for usage later in the intent.
Returns

void

Defined in

index.ts:733


subscribe

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
NameTypeDescription
subscriberSubscriberThe 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
NameTypeDescription
subscriberSubscriberThe 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
NameType
languageCodestring
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
NameTypeDescription
options?Object-
options.clearResponses?booleanIf 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
NameType
overrideundefined | 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
NameType
overrideundefined | 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
NameType
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
NameType
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
NameType
contextany
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
NameType
payloadany
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
NameTypeDescription
textstringThe 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

See also:

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