Attributes
Last updated
Last updated
Attributes are what OpenDialog calls the pieces of information that are stored during interaction with a user. For example, a user's first_name or last_name,the price for a specific item or a description of the user type (e.g. novice, intermediate, expert).
Attributes are used throughout the conversation in Conditions, Messages, Actions and Intents to provide relevant information for subsequent conversational reasoning or message construction.
Attributes have a type, a name and a value. The type might be something like String , the name might be first_name and the specific value would be John.
Attributes can be scalars (hold a single value), collections (hold multiple values of the same type) or composites (a combination of other attributes that can be scalars, collections or even other composites).
Attributes are stored in contexts. Different contexts can be used to separate different types of information as described in the page.
Generic attribute types are the ones you will typically use to capture specific values in your application. They are meant to cover a broad range of use cases to enable you to flexibly handle data in your application.
String: used for text based variables like words (EX: Small size, Medium size, Large size)
Boolean: Used for binary decisions.
Valid values are: True or False, Yes or No, 1 or 0. Any other values will evaluate to False.
Decimal (float): Numbers with decimal values (fractions must be converted to decimals)
Examples: 1.25, 23.456, 0.4
Whole number (int): Whole numbers without fractions or decimal values
Examples: 1, 2, 5, 403023
Timestamp: an attribute type for storing unix timestamps. Can be used in comparison condition operations such as greater than and less than. For example, last_seen and first_seen in the user context are timestamp attributes.
Collections
String Collection: A string collection is a collection of ... strings.
Example: Assume you have a collection of names called FavouriteNames . The structure would be ["Asterix", "Obelix", "Getafix"] and you can access them through FavouriteNames[0] which would return Asterix, etc.
In a message you could access it as shown below
and this would provide the output
Typically you would set the values of a collection attribute through an Action API call but you could also set it explicitly through the chat test panel to test the above example
Boolean Collection: Allows for multiple True/False statements to be included in the attribute. (Small size "True" and Cotton "True". Therefore, the boolean[] attribute's value is "True").
Decimal Collection: A collection of decimals.
Whole Number Collection: A collection of whole numbers.
Timestamp Collection: A collection of timestamps.
Composites
Composite: A composite attribute is an attribute made up of other attributes. These are attributes that are explicitly defined in code and have a specific schema. Examples of existsing composite attributes are Utterance, Location.
If you are defining new attributes through the interface it is unlikely that you will be defining a composite attribute on the fly. It usually will be something a developer defines in code and then makes available for use in the user interface. We will see examples of this later with Utterance and Location
JSON Inferred Composite: A JSON inferred composite attribute is a way to dynamically create a composite attribute based on a JSON object (typically received through an Action API call). OpenDialog will do a best effort to interpret the structure and provide something that can be accessed as usual via OpenDialog. This provides a way to deal with more complex data structures without having to create a dedicated Composite type through code avoiding development work.
Example
For example assume that the Action API returns the following JSON response
userPreferences has a composite structure that we want to use in our conversation. We can define a new attribute called userPreferences and give it a type of JSON Inferred Composite
When the Action is called it will read the data and attempt to infer appropriate attribute types or match to existing attribute types of the components of the Inferred Composite Attribute.
For the example above we will then be able to access information using the syntax
{user.userPreferences['chat_preferences']['tone']} or {user.userPreferences['theme']['dark']}
In addition to the types described above OpenDialog has a number of more specific attribute types
The Utterance Attribute type is used by the conversation engine to hold information about what a user said and the user who said it.
It has the following attributes:
utterance_user - this composite attribute holds a number of pieces of information about the user that uttered the utterance.
user_id
country
os
browser
timezone
Each one of the above attributes can be access in the following way
user.utterance['utterance_user'][<attribute_name>]
e.g. user.utterance['utterance_user']['user_id']
custom- custom (which is an attribute of type Form Data) contains any attributes that were defined in the custom section of the chatAPI call or in the custom section of the chat widget embed code.
utterance_platform - the platform through which the utterance was uttered. This is an indication of the conversational interface used. It will typically be ChatAPI but can be used to indicate different provenance platforms such as Alexa, WhatsApp, etc.
This can be accessed using user.utterance['utterance_platform']
utterance_type - the type of utterance (text, button, etc)
utterance_text - the actual text the user typed
This is also directly accessible as {user.utterance_text} without having to refer to the utterance composite attribute.
utterance_user_id - the user id
callback_id - the intent name
The Location attribute is a composite attribute that is used in map and other location functionality. If you want to store an address collected via a Location message you need to define a location attribute (otherwise OpenDialog will use a default Location attribute already available)
Location
formatted_address
postal_code
line_1
line_2
locality
province
country
lat
lng
The Form Data attribute type is used to store form data and it is not typically used for new attribute types. If you generate a form in a Message the data will be stored in a form attribute and then will be made available as scalar attributes in the user context for each access.
The File Collection is a collection of composite File attributes that can hold information on files upload through the file upload widget. For each file we collect the following information
name - the name of the file
url - the URL from where the file can be accessed
size - the size of the file
type - the type of file
Attributes are stored in contexts. For more information on contexts, check out the dedicated Contexts page.
In order to identify in what context an attribute should be stored in, or retrieved from we namespace attribute names. The format is context_name.attribute_name. Whenever OpenDialog encounters an attribute it will extract the attribute name and resolve it - i.e. it will determine what type (Int, String, etc) is the attribute and whether it is a supported attribute and then it will use the ContextManager to store or retrieve the attribute from an appropriate context.
"Out of the box" OpenDialog supports the following contexts
user - the user context stores attributes against the user node in Dgraph. As such attributes stored in the user context will persist across requests.
session - the session context is an in-memory context valid for a single request-response exchange. It is a convenient context to store application specific attributes that are only required within the space of a single request. We use the session context to store messages coming back from external NLU interpreters, for example, so that they can be embedded within a message and displayed to the user.
global - the global context is a persistent context that can be managed through the UI. By visiting admin/global-contexts you can add attributes to the global context. These attributes will then be available throughout your application by referencing global.attribute_name
Developers can create custom contexts to store and retrieve relevant information.
To define and use attributes, you can check detailed instructions in the section of this documentation.
