@nlxai/core 1.2.4-alpha.8 → 1.2.4

package/README.md

@@ -13,7 +13,10 @@ import { createConversation } from "@nlxai/core";
 
 // Create some configuration
 const config = {
-  applicationUrl: "", // obtain from NLX deployments page
+  protocol: "httpsWithStreaming", // "httpsWithStreaming", "https" or "websocket"
+  host: "", // obtain from NLX deployments page
+  deploymentKey: "", // obtain from NLX deployments page
+  channelKey: "", // obtain from NLX deployments page
   headers: {
     "nlx-api-key": "", // obtain from NLX deployments page
   },
@@ -559,26 +562,60 @@ The configuration necessary to create a conversation.
 optional applicationUrl: string;
 ```
 
-The URL at which your conversational application is running.
-Fetch this from the application's API channel tab.
+The URL at which your conversational application is running. Fetch this from the application's API channel tab.
+Currently, there are a few ways to specify the application URL:
 
-##### headers
+- (recommended) leave out `applicationUrl` and specify `protocol`, `host`, `deploymentKey` and `channelKey`.
+- specify the full `applicationUrl` as well as the `protocol`.
+- (legacy) specify the `applicationUrl` generated either as an HTTP or websocket URL. Use `experimental.streamHttp` to control streaming.
+
+##### protocol?
 
 ```ts
-headers: Record<string, string> & object;
+optional protocol: Protocol;
 ```
 
-Headers to forward to the NLX API.
+Specify the protocol (http, websocket or httpWithStreaming)
 
-###### Type Declaration
+##### host?
+
+```ts
+optional host: string;
+```
+
+Hostname of the application deployment, without a leading `https://`.
+
+##### deploymentKey?
+
+```ts
+optional deploymentKey: string;
+```
+
+Deployment key.
+
+##### channelKey?
+
+```ts
+optional channelKey: string;
+```
+
+Channel key.
+
+##### apiKey?
+
+```ts
+optional apiKey: string;
+```
 
-###### nlx-api-key
+API key.
+
+##### headers?
 
 ```ts
-nlx-api-key: string;
+optional headers: Record<string, string>;
 ```
 
-The `nlx-api-key` is required. Fetch this from the application's API channel tab.
+Headers to forward to the NLX API.
 
 ##### conversationId?
 
@@ -695,7 +732,7 @@ The slots to populate
 sendChoice: (choiceId, context?, metadata?) => void;
 ```
 
-Respond to [a choice](https://docs.studio.nlx.ai/intentflows/documentation-flows/flows-build-mode/nodes#user-choice) from the application.
+Respond to [a choice](https://docs.nlx.ai/platform/nlx-platform-guide/flows-and-building-blocks/overview/nodes#user-choice) from the application.
 
 ###### Parameters
 
@@ -755,13 +792,13 @@ Trigger a specific flow.
 
 `string`
 
-the flow to trigger. The id is the name under the application's _Intents_.
+the flow to trigger. The id is the name under the application's _Flows_.
 
 ###### context?
 
 [`Context`](#context)
 
-[Context](https://docs.nlx.ai/platform/nlx-platform-guide/build-with-nlx/flows/context-variables#what-are-context-variables) for usage later in the intent.
+[Context](https://docs.nlx.ai/platform/nlx-platform-guide/build-with-nlx/flows/context-variables#what-are-context-variables) for usage later in the flow.
 
 ###### Returns
 
@@ -781,7 +818,7 @@ Send context without sending a message
 
 [`Context`](#context)
 
-[Context](https://docs.nlx.ai/platform/nlx-platform-guide/build-with-nlx/flows/context-variables#what-are-context-variables) for usage later in the intent.
+[Context](https://docs.nlx.ai/platform/nlx-platform-guide/build-with-nlx/flows/context-variables#what-are-context-variables) for usage later in the flow.
 
 ###### Returns
 
@@ -814,7 +851,7 @@ the response with optional timestamps.
 sendStructured: (request, context?) => void;
 ```
 
-Send a combination of choice, slots, and intent in one request.
+Send a combination of choice, slots, and flow in one request.
 
 ###### Parameters
 
@@ -826,7 +863,7 @@ Send a combination of choice, slots, and intent in one request.
 
 [`Context`](#context)
 
-[Context](https://docs.studio.nlx.ai/workspacesettings/documentation-settings/settings-context-attributes) for usage later in the intent.
+[Context](https://docs.nlx.ai/platform/nlx-platform-guide/flows-and-building-blocks/advanced/context-variables) for usage later in the flow.
 
 ###### Returns
 
@@ -1067,7 +1104,7 @@ Remove a listener to one of the handler's custom events
 
 ### SlotValue
 
-Values to fill an intent's [attached slots](https://docs.studio.nlx.ai/intents/documentation-intents/intents-attached-slots).
+Values to fill an flow's [attached slots](https://docs.nlx.ai/platform/nlx-platform-guide/flows-and-building-blocks/overview/setup#attached-slots).
 
 An array of `SlotValue` objects is equivalent to a [SlotsRecord](#slotsrecord).
 
@@ -1087,7 +1124,7 @@ The attached slot's name
 value: any;
 ```
 
-Usually this will be a discrete value matching the slots's [type](https://docs.studio.nlx.ai/slots/documentation-slots/slots-values#system-slots).
+Usually this will be a discrete value matching the slots's [type](https://docs.nlx.ai/platform/nlx-platform-guide/flows-and-building-blocks/overview/setup#custom-vs-built-in-slots).
 for custom slots, this can optionally be the value's ID.
 
 ---
@@ -1175,7 +1212,7 @@ as well as whether the client should poll for more application responses.
 optional payload: string;
 ```
 
-If configured, the [node's payload.](See: https://docs.studio.nlx.ai/intentflows/documentation-flows/flows-build-mode/advanced-messaging-+-functionality#add-functionality)
+If configured, the [node's payload](https://docs.nlx.ai/platform/nlx-platform-guide/flows-and-building-blocks/overview/nodes#node-payload).
 
 ##### modalities?
 
@@ -1208,7 +1245,7 @@ as well as whether the client should poll for more application responses.
 optional intentId: string;
 ```
 
-The conversation's intent
+The conversation's flow ID (called `intentId` here for legacy reasons).
 
 ##### escalation?
 
@@ -1339,7 +1376,7 @@ as well as whether the client should poll for more application responses.
 optional intentId: string;
 ```
 
-The message node's intent
+The message node's flow ID (called `intentId` here for legacy reasons).
 
 ---
 
@@ -1652,7 +1689,7 @@ Label for comment
 ### StructuredRequest
 
 The body of `sendStructured`
-Includes a combination of choice, slots, and intent in one request.
+Includes a combination of choice, slots, and flow in one request.
 
 #### Properties
 
@@ -1868,13 +1905,25 @@ optional nodeId: string;
 Required if you want to change a choice that's already been sent.
 The `nodeId` can be found in the corresponding [ApplicationMessage](#applicationmessage).
 
-##### intentId?
+##### ~~intentId?~~
 
 ```ts
 optional intentId: string;
 ```
 
-Intent ID, used for sending to the NLU to allow it to double-check
+Intent ID, used for sending to the NLU to allow it to double-check.
+
+###### Deprecated
+
+use `flowId` instead.
+
+##### flowId?
+
+```ts
+optional flowId: string;
+```
+
+Flow ID, used for sending to the NLU to allow it to double-check.
 
 ---
 
@@ -1918,6 +1967,38 @@ Interim message event handler
 
 ## Enumerations
 
+### Protocol
+
+The protocol used to communicate with the application
+
+#### Enumeration Members
+
+##### Https
+
+```ts
+Https: "https";
+```
+
+Regular encrypted HTTPS, without support for post-escalation message handling, interim messages and other streaming features.
+
+##### HttpsWithStreaming
+
+```ts
+HttpsWithStreaming: "httpsWithStreaming";
+```
+
+Encrypted HTTPS with streaming enabled. This is the default setting and supports interim messages. Does not support post-escalation message handling.
+
+##### Websocket
+
+```ts
+Websocket: "websocket";
+```
+
+Websocket, with support for post-escalation message handling.
+
+---
+
 ### ResponseType
 
 Response type
@@ -1967,7 +2048,7 @@ voicePlusCommand
 type Context = Record<string, any>;
 ```
 
-[Context](https://docs.studio.nlx.ai/workspacesettings/documentation-settings/settings-context-attributes) for usage later in the intent.
+[Context](https://docs.nlx.ai/platform/nlx-platform-guide/flows-and-building-blocks/advanced/context-variables) for usage later in the flow.
 
 ---
 
@@ -1977,11 +2058,11 @@ type Context = Record<string, any>;
 type SlotsRecord = Record<string, any>;
 ```
 
-Values to fill an intent's [attached slots](https://docs.studio.nlx.ai/intents/documentation-intents/intents-attached-slots).
+Values to fill an flow's [attached slots](https://docs.nlx.ai/platform/nlx-platform-guide/flows-and-building-blocks/overview/setup#attached-slots).
 
 `SlotRecord` Keys are the attached slot's name
 
-`SlotRecord` Values are usually a discrete value matching the slots's [type](https://docs.studio.nlx.ai/slots/documentation-slots/slots-values#system-slots).
+`SlotRecord` Values are usually a discrete value matching the slots's [type](https://docs.nlx.ai/platform/nlx-platform-guide/flows-and-building-blocks/overview/setup#custom-vs-built-in-slots).
 for custom slots, this can optionally be the value's ID.
 
 A `SlotsRecord` is equivalent to an array of [SlotValue](#slotvalue) objects.
@@ -1994,7 +2075,7 @@ A `SlotsRecord` is equivalent to an array of [SlotValue](#slotvalue) objects.
 type SlotsRecordOrArray = SlotsRecord | SlotValue[];
 ```
 
-Values to fill an intent's [attached slots](https://docs.studio.nlx.ai/intents/documentation-intents/intents-attached-slots).
+Values to fill an intent's [attached slots](https://docs.nlx.ai/platform/nlx-platform-guide/flows-and-building-blocks/overview/setup#attached-slots).
 
 Supports either a [SlotsRecord](#slotsrecord) or an array of [SlotValue](#slotvalue) objects
 
@@ -2061,7 +2142,7 @@ The user's message
 optional context: Context;
 ```
 
-[Context](https://docs.studio.nlx.ai/workspacesettings/documentation-settings/settings-context-attributes) for usage later in the intent.
+[Context](https://docs.nlx.ai/platform/nlx-platform-guide/flows-and-building-blocks/advanced/context-variables) for usage later in the flow.
 
 ```ts
 {
@@ -2094,7 +2175,7 @@ Correlates to a `choiceId` in the [ApplicationResponse](#applicationresponse)'s
 optional context: Context;
 ```
 
-[Context](https://docs.studio.nlx.ai/workspacesettings/documentation-settings/settings-context-attributes) for usage later in the intent.
+[Context](https://docs.nlx.ai/platform/nlx-platform-guide/flows-and-building-blocks/advanced/context-variables) for usage later in the flow.
 
 `object` & [`StructuredRequest`](#structuredrequest)
 

package/docs/README.md

@@ -214,6 +214,101 @@ sendTextWrapped("Hello").then((response) => {
 });
 ```
 
+---
+
+### sendVoicePlusStep()
+
+```ts
+function sendVoicePlusStep(configuration): Promise<void>;
+```
+
+Use this function when using **Voice+ scripts** to advance the conversation to the step specified.
+
+This functionality is orthogonal from other usage of the core SDK, as it may be used either using standard SDK communication channels or it can be used to provide a Voice+ script experience with for instance a telephony based channel.
+
+#### Parameters
+
+##### configuration
+
+Configuration for sending the step. Many of the values can be found on the deployment modal of the Voice+ script.
+
+###### apiKey
+
+`string`
+
+- the API key generated for the Voice+ script. Note that this value is different from the API key you would pass to [createConversation](#createconversation). You can control the API key on the Voice+ script settings page.
+
+###### scriptId?
+
+`string`
+
+The ID of the Voice+ script.
+
+###### workspaceId
+
+`string`
+
+Your workspace ID.
+
+###### conversationId
+
+`string`
+
+The active conversation ID, passed from the active NLX voice application. This is what ties the script exectution to the specific Voice application.
+
+_Note: This must be dynamically set by the voice application._ Normally, when the voice application directs the user to the webpage running this code, it will include the conversation ID as a URL parameter which you can extract and pass here.
+
+**Example**
+
+```typescript
+const conversationId = new URLSearchParams(window.location.search).get("cid");
+```
+
+###### languageCode
+
+`string`
+
+The user's language code, consistent with the language codes defined on the Voice+ script.
+
+###### step
+
+[`StepInfo`](#stepinfo)
+
+Which step to send.
+
+###### context
+
+[`Context`](#context)
+
+Any context.
+
+###### debug?
+
+`boolean` = `false`
+
+Set to `true` to help debug issues or errors. Defaults to `false`.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Example
+
+```typescript
+import { sendVoicePlusStep } from "@nlxai/core";
+
+await sendVoicePlusStep({
+  // hard-coded params
+  apiKey: "REPLACE_WITH_API_KEY",
+  workspaceId: "REPLACE_WITH_WORKSPACE_ID",
+  scriptId: "REPLACE_WITH_SCRIPT_ID",
+  step: "REPLACE_WITH_STEP_ID",
+  // dynamic params
+  conversationId: "REPLACE_WITH_CONVERSATION_ID",
+  languageCode: "en-US",
+});
+```
+
 ## Variables
 
 ### version
@@ -238,26 +333,60 @@ The configuration necessary to create a conversation.
 optional applicationUrl: string;
 ```
 
-The URL at which your conversational application is running.
-Fetch this from the application's API channel tab.
+The URL at which your conversational application is running. Fetch this from the application's API channel tab.
+Currently, there are a few ways to specify the application URL:
+
+- (recommended) leave out `applicationUrl` and specify `protocol`, `host`, `deploymentKey` and `channelKey`.
+- specify the full `applicationUrl` as well as the `protocol`.
+- (legacy) specify the `applicationUrl` generated either as an HTTP or websocket URL. Use `experimental.streamHttp` to control streaming.
 
-##### headers
+##### protocol?
 
 ```ts
-headers: Record<string, string> & object;
+optional protocol: Protocol;
 ```
 
-Headers to forward to the NLX API.
+Specify the protocol (http, websocket or httpWithStreaming)
 
-###### Type Declaration
+##### host?
+
+```ts
+optional host: string;
+```
+
+Hostname of the application deployment, without a leading `https://`.
 
-###### nlx-api-key
+##### deploymentKey?
 
 ```ts
-nlx-api-key: string;
+optional deploymentKey: string;
 ```
 
-The `nlx-api-key` is required. Fetch this from the application's API channel tab.
+Deployment key.
+
+##### channelKey?
+
+```ts
+optional channelKey: string;
+```
+
+Channel key.
+
+##### apiKey?
+
+```ts
+optional apiKey: string;
+```
+
+API key.
+
+##### headers?
+
+```ts
+optional headers: Record<string, string>;
+```
+
+Headers to forward to the NLX API.
 
 ##### conversationId?
 
@@ -1597,6 +1726,38 @@ Interim message event handler
 
 ## Enumerations
 
+### Protocol
+
+The protocol used to communicate with the application
+
+#### Enumeration Members
+
+##### Https
+
+```ts
+Https: "https";
+```
+
+Regular encrypted HTTPS, without support for post-escalation message handling, interim messages and other streaming features.
+
+##### HttpsWithStreaming
+
+```ts
+HttpsWithStreaming: "httpsWithStreaming";
+```
+
+Encrypted HTTPS with streaming enabled. This is the default setting and supports interim messages. Does not support post-escalation message handling.
+
+##### Websocket
+
+```ts
+Websocket: "websocket";
+```
+
+Websocket, with support for post-escalation message handling.
+
+---
+
 ### ResponseType
 
 Response type
@@ -1928,3 +2089,45 @@ The callback function for listening to all responses.
 #### Returns
 
 `void`
+
+---
+
+### StepInfo
+
+```ts
+type StepInfo =
+  | string
+  | {
+      stepId: string;
+      stepTriggerDescription?: string;
+    };
+```
+
+Step information, either a step ID as a single string or an object
+
+#### Type Declaration
+
+`string`
+
+```ts
+{
+  stepId: string;
+  stepTriggerDescription?: string;
+}
+```
+
+##### stepId
+
+```ts
+stepId: string;
+```
+
+Step ID
+
+##### stepTriggerDescription?
+
+```ts
+optional stepTriggerDescription: string;
+```
+
+Step trigger description