The core package of our official JavaScript SDK to communicate with NLX conversational bots.
import { createConversation } from "@nlxai/chat-core";
// Create some configuration
const config = {
botUrl: "", // obtain from NLX deployments page
headers: {
"nlx-api-key": "", // obtain from NLX deployments page
},
userId: "abcd-1234", // optional property to identify the user
conversationId: "", // start with a specific conversation ID - useful if you want to resume a previous conversation
languageCode: "es-US", // optional language code for standard bots that do not run on US English
environment: "production", // optional environment name for multi-environment bots to control which data request environment should be used. "production" or "development" are the only supported values.
};
// Start the conversation
const convo = createConversation(config);
// Subscribe to changes in the list of responses; the newest response is sent as a second argument
convo.subscribe((responses, newResponse) => {
console.log(responses);
});
// Send a message from the user's end
convo.sendText("hello");
The package exports a main function called createConversation
, which is called with the bot configuration and returns a conversation handler object.
The conversation handler has the following methods. For each send method, conversation context can be optionally specified as a second argument.
Send a simple text to your bot.
Your bot may send a list of choices to choose from, each with a choiceText
and a choiceId
field. You can use choiceText
as button labels, and include the choiceId
in this method when sending responses.
Send slot values directly through custom widgets such as interactive maps.
Trigger a specific intent. The most common use of this method is to show welcome messages by sending the NLX.Welcome
intent.
Send a combination of choice, slots and intent ID in one request.
Subscribe to the current state of messages whenever there is a change. The second argument returns the new response that is triggering the subscription, if there is one.
Remove a subscription.
Remove all subscriptions.
Reset the conversation. This makes sure that information previously collected by your bot will not affect the logic of the conversation any longer.
Starting 1.0.0, the language code is automatically appended to the bot URL. If you're upgrading your SDK, please make sure:
- you initialize the app with a
languageCode
parameter (this is now mandatory). - if you appended the language code to the URL manually before, make sure to remove it (
https://bots.studio.nlx.ai/abcd/efgh
instead ofhttps://bots.studio.nlx.ai/abcd/efgh-en-US
).
The automatic language code append can be disabled by setting the config.experimental.completeBotUrl
field to true
.
This SDK is written in TypeScript so you can use our type definitions in your project.
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:
import { createConversation, promisify } from "@nlxai/chat-core";
const convo = createConversation(config);
const sendTextWrapped = promisify(convo.sendText, convo);
sendTextWrapped("Hello").then((response) => {
console.log(response);
});
IMPORTANT: the wrapped promise will resolve with the first available bot response - subsequent, asynchronously arriving responses are ignored. Use this pattern only if you know that there is a single response. This is currently a reasonably safe assumption for bots working over HTTP.
Issues and feature requests are always welcome.
MIT.