State Keys
Zircel lets you define your own state model tailored to your needs. You can do so by setting up state keys. For every key, your end-users can provide a value. For example, you could have a state key "email" and your users would manipulate their state by entering their actual email address.
One can distinguish two different types of state keys: Internal State Keys, Explicit State Keys.
Internal State Keys
Internal State Keys can be defined in the Node Editor. You can set state keys for feedback fields (e.g. input fields) and buttons.
Keys associated with an input field (or a textarea) are mandatory and need to be defined upfront. They are needed to assign each input field with a specific purpose. For example, one input field expects the end-users' email address and another input field is here to get an end-users' name.
On the other hand, you can also define state keys for buttons. Maybe you want to know if an end-user is interested in buying a specific product. To do so you can simply ask this question and assign a state key (e.g. "wantsProductX") to the "Yes"-button. Whenever a user agrees by clicking this button your state will contain a boolean value: { wantsProductX: true }.
Explicit State Keys
Sometimes capturing state during an end-users' conversation is not enough and you have to import additional state to provide a pleasant and personalized experience to your user. Or maybe, you use an (anonymized) customer-id to identify your clients in your main IT system. By sharing this customer-id with Zircel, you can retain this id again at a later point in time with an integration endpoint and thus de-anonymize and reference the newly gained state with your main system.
You can set explicit state keys in the "Dev"-Tab by clicking the green "plus" sign at the bottom of the page. For every explicit state key, one has to set a data type (Boolean/String or Number) upfront. State keys are uniquely identified by their combination of data type and key-name.
Importing State
There are three ways to import state into your end-users conversation:
- If you use your conversational model as plugin to your personal website, you can set state before initializing the plugin with JavaScript. You can read more about this method here.
- Again, if you use Zircel as plugin you can use the Zircel Event API to update the state from within the browser using the function
page.setState(). This works during runtime of the conversation (when your end-user is already engaging in the conversation). - During runtime you can also load new state by using a server action.
However you decide to import state: don't forget to set state keys for every object property you try to import.
Session Management and State
Maybe you are wondering how Zircel connects a specific state to a user. In other words: how does Zircel know which state belongs to which user?
Generally, on has to distinguish two cases:
- Internal Use: If the browser bar says 'https://zircel.com/hello/...' you are using Zircel from our own domain. In that case zircel.com sets a cookie (= a user identifier) in the users' browser that lives there for up to 60 days. In that time period, a returning user can be identified and state can be associated.
- Plugin Use: If you are using a conversational model as a plugin within your own website (e.g. http://example.com) you have full control over user identification. You can learn more about the details here.
Using State
In this chapter, we'll learn about how you can use state in your application.
Logic Nodes
State can be used for intelligent routing. Based on a certain logical condition, you can route a user to certain subtree or the other. You can learn more about Logic here.
Listening to State Changes
With the plugin and the Zircel Event API you can listen to state changes continuously and update your own website accordingly.
Personalization with State Keys
One of the easiest ways to leverage state is to personalize messages to your end-users:
As you can see, the syntax to personalize text is pretty straight-forward Hi {#name | there} 👋. Let's look at it in more detail:
- A conditional clause used for personalization is enclosed by curly brackets.
- The content of the conditional clause is separated into two parts by a "|".
- The first part expects a state key with a leading hashtag '#'. If your state key is set the value corresponding to that state key is rendered. In the example above, an end-user provided his name "Marc" in a previous conversation.
- The second part is an arbitrary fallback text that is displayed when a state key doesn't exist or is not set.
If you are certain that a state key exists you can also use the simplified notation Hi #name 👋.