Exchanging data between NDEP and the Dialog service
By retrieving engagement data from NDEP, your virtual assistant can provide custom responses, show relevant personalized information from a backend system, or direct the dialog flow based on actions of the end user. The virtual assistant can also send data to NDEP—for example, to trigger custom events in NDEP, or to relay information about the end user such as their name and the language they were using.
Passing data and events from NDEP to the Dialog service
NDEP can send engagement data and settings at the start of a session, and it can also set variables or trigger events during a conversation.
Engagement data available to the Dialog service at the start of every session
At the start of every session, NDEP sends values for these parameters of the Dialog service’s Start method. See StartRequest in the Dialog service gRPC API documentation, for more information.
StartRequest parameter | Description |
---|---|
session_id | For synchronous chats: NDEP engagement ID prepended with the string nvaa ; for asynchronous chats: NDEP conversation ID prepended with the string nvaa . |
selector.channel | Maps the NDEP conversationChannel or deviceType to a Mix channel name using dlgaasChannelMapping from the NVAA configuration. |
selector.language | dlgaasLanguage from the NVAA configuration. |
selector.library | dlgaasLibrary from the NVAA configuration. |
payload.model_ref.uri | dlgaasModelUrn from the NVAA configuration. |
payload.data.VARIABLE_NAME | Key-value pairs from the NDEP settings.automatonDataMap and customerDataList received before the start triggers. VARIABLE_NAME represents a variable that must be defined in Mix.dialog for the Dialog service to have access to this data. |
payload.data.userData.userChannelID | Available through the userChannelID field of the predefined session variable userData, in Mix.dialog. Populated from the AEAPI engagement.settings.clientId . Not set if clientId is not found in engagement.settings or is empty. See the Agent Engagement API documentation for more information. |
sessionTimeoutSec | Session timeout value, in seconds, configured in NVAA, for the Dialog service. Default value is 90000 seconds (25 hours), maximum value is 259200 seconds (72 hours). |
client_data[“platformSessionID”] | NDEP engagement ID. Used for reporting. |
client_data[“journeyID”] | NDEP conversation ID. Used for reporting. Only available for asynchronous engagements. |
Specify engagement settings to pass to the Dialog service at the start of a session
At the start of a session, NDEP can also send engagement settings via payload.data
parameters of the Dialog service’s Start method. To give your virtual assistant access to the value of any NDEP engagement setting, you must have defined, in Mix.dialog, a variable of type string, with a name starting with ndep followed by the property name. For example, add the variable ndepBrowserType in Mix.dialog to receive the value of the NDEP engagement setting browserType
at runtime.
StartRequest parameter | Mix variable | Description |
---|---|---|
payload.data.ndepEngagementID | ndepEngagementID | NDEP engagement ID, populated from the AEAPI id property. |
payload.data.ndepConversationId | ndepConversationId | NDEP conversation ID, populated from the AEAPI engagement.settings.conversationId property. |
payload.data.ndepNameOfTheProperty | ndepNameOfTheProperty | NDEP property populated from the AEAPI engagement.settings. nameOfTheProperty, where nameOfTheProperty is one of the values of the NVAA configuration parameter dlgaasEngagementSettingsForMix . Relevant properties include agentGroupId , agentGroupName , browserType , browserVersion , businessRuleId , businessUnitId , businessUnitName , chatTitle , clientId , clientName , conversationChannel , deviceType , initialCustomerId , launchPage , launchType , operatingSystemType , scriptTreeId , and siteId . (Other NDEP engagement settings such as language and visitorAttributes are not fully supported.) |
Specify custom engagement data to pass to the Dialog service at the start of a session
Custom engagement data that could be relevant to a virtual assistant include username, user email ID, current page, user party ID, page marker, zip code, customer ID, order status, for example.
If you would like your virtual assistant to receive such custom engagement data from NDEP at the start of a session, it is possible to achieve this by creating data variables configured as engagement settings in NDEP. This involves defining business rules and an automatonDataMap.
In Mix.dialog, for each parameter of interest, your must create a variable with the same name as the corresponding NDEP variable.
Since the data variables are configured as engagement settings, NDEP sends them via payload.data
parameters of the Dialog service’s Start method at runtime.
Specify data variables to pass during a conversation
To allow NDEP to pass data to the Dialog service during a conversation, a prerequisite is to configure NDEP for datapass, either by creating business rules or by using an API request.
At runtime, NVAA gets the specified variables from NDEP via the the customerData
field of the messages endpoint in AEAPI, and passes them on to the Dialog service via the updateRequest endpoint.
In Mix.dialog, for each NDEP variable of interest, you must have created a variable with the same name as the corresponding variable in customerData
.
Trigger events when passing data during a conversation
When passing data from NDEP to the Dialog service during a conversation, some scenarios might require the virtual assistant to be aware that certain variables were updated—for example, when the dialog flow is to take a different course of action upon reception of the data. This involves sending a JSON structure with the list of variables and values, in addition to the name of the event to trigger on the dialog side.
For example, in a scenario where the virtual assistant is expected to perform certain operations once the name of the user associated with an account number has been verified on the NDEP side, the JSON structure could look like this:
{
"ndepVaEvent": {
"data": {
"personalAccountNumber": "12345678",
"userNameAndStatus": {
"name": "parker",
"isValidUser": true
}
},
"event": "myEvent"
}
}
Where ndepVaEvent
identifies that this structure contains information for triggering an event, data
identifies the variables to set and their values, and event
identifies the event to trigger.
In Mix.dialog, for each NDEP variable of interest, you must have created a variable with the same name as the corresponding variable in the data
element of ndepVaEvent
, and a custom event with the same name as the one that appears next to the event
element of ndepVaEvent
. In this example scenario you would:
- Add a simple variable of type string named personalAccountNumber.
- Create a schema named UserNameAndStatus, for example, with two fields of type string: name and isValidUser.
- Add a complex variable named userNameAndStatus, based on this schema.
- Add the custom event to be triggered when these variables are updated: for example, myEvent.
- Configure an event handler for this event, either in the Start node of your dialog design or in an Enter node.
At runtime, whenever NDEP sends thendepVaEvent
JSON structure, this will trigger the specified event in the virtual assistant and the dialog flow will jump to the node you specified in your event handler configuration.
Passing data and events from a virtual assistant to NDEP
Virtual assistants created in Mix can send information to NDEP via question and answer nodes and data access nodes.
Pass custom events from a virtual assistant to NDEP
In your dialog design, at any point where the dialog flow requires triggering a custom event on the NDEP side, you can use a question and answer node to send two variables: the reserved variable ndepCustomEvent holding the name of the event to trigger, and a complex variable named after the specified event and holding the payload data required for the purposes of the event.
In NDEP, custom events are defined as business rules.
In Mix.dialog, for each custom NDEP event to trigger, you must define a schema and the complex variable (based on this schema) that will hold the required payload. Remember to preinitialize the complex variable before assigning values to its fields.
- Add a simple variable of type string named ndepCustomEvent, if it hasn’t been created already.
- Create a schema with the required fields.
- Add a complex variable based on this schema.
- In the component called Main, select the Start node, and preinitialize the complex variable.
- Switch to the component from where the virtual assistant is to initiate the launch of a custom event by NDEP.
- Select the Enter node (or a node upstream from the question and answer node that will send the required data to NDEP).
- Add an assign action that sets ndepCustomEvent to the name of the custom NDEP event to trigger.
- Add an assign action for each field of the complex variable.
- Select the question and answer node (or add one if this hasn’t yet been done).
- Add two Send parameters: one for ndepCustomEvent, and one for the complex variable.
Notes:
- This feature doesn’t allow sending more than one event at a time (because there’s only one variable to hold an event name).
- The question and answer node must have an initial message; otherwise, NDEP won’t receive the data and the event won’t be triggered.
Pass client details from a virtual assistant to NDEP
In your dialog design, at any point where the dialog flow requires passing client details on to NDEP, you can use a data access node to send the reserved variable ndepClientDetails holding the customer name, language, and the title of the chat.
- In Mix.dialog, create the schema for ndepClientDetails, and add this complex variable to your dialog design, if this hasn’t been done already.
Refer to Create a schema, and Create a complex variable, in the Mix.dialog documentation, for more information. - In the component called Main, select the Start node, and preinitialize ndepClientDetails.
- Switch to the component from where the virtual assistant is to pass client details on to NDEP.
- Select the Enter node (or a node upstream from the data access node that will send the required data to NDEP).
- For each piece of information you want to pass on to NDEP, add an assign action that sets the corresponding field of ndepClientDetails—for example, set the value of the clientName field to the name of the user.
- Select the data access node (or add one if this hasn’t yet been done).
- Add a Send parameter for ndepClientDetails.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.