Client entities

tip

Client entities are entities that can be personalized by the client during a conversation with the bot. The contents of such an entity are accessible to the client only.

Client entities are used when personalization is required to identify intents. For example, they can be used to process a client contact list.

Client entities can be used in a bot script, intents and slot filling.

tip

More about working with entities in a script

Quick start

Here is an example of a slot filling script where client entities are used. The bot will add client contacts to an address book and schedule meetings. Each of the bot’s clients will have their own personalized address book.

Filling an entity

Create a @Contact entity. Click client under the entity name to make its value unique for each client. The entity will be filled in the course of the conversation.

Completion of intents

Then proceed to creating intents. Create and fill the AddContact intent that adds a contact to an address book as follows:

The AddContact intent is triggered when the client wants to add a new entry to the address book. We use slot filling here to fill the phone number and contact name slots.

The @duckling.phone-number and @duckling.email system entities will be used to fill the slot (ensure the entities are active).

Create and fill the Meeting intent that adds a contact to an address book as follows:

The Meeting intent is triggered when the client wants to schedule a meeting with a newly created contact. Please note that in our training phrases, we add the reference to the @Contact client entity we created before.

The script

Bot script:

require: slotfilling/slotFilling.sc
  module = sys.zb-common
theme: /

    state: Start                                    # Start of the script
        q!: $regex</start>
        a: I can add contacts to your address book.

    state: AddContact                               # Adding contact
        intent!: /AddContact
        script:
            $caila.addClientEntityRecords("Contact", [{"type": "synonyms", "rule": [$parseTree._Email], "value": $parseTree._Number}]);
        a: OK, contact {{$parseTree._Email}} added with number {{$parseTree._Number}}

    state: Meeting                                  # Scheduling a meeting with an added contact
        intent!: /Meeting
        a: OK, scheduling a meeting with {{$parseTree._Contact}}

    state: NoMatch
        event!: noMatch
        a: I did not get it. You said: {{$request.query}}

Activation of the AddContact intent triggers search for entities that match slots in the client phrase. If matching entities are found, the slot is filled.

After all the slots have been filled, control is passed to the main script with all the slots filled in $parseTree.

tip

The $caila.addClientEntityRecords method is used to add the entity entry to the dictionary for the current client.

After the contact is created, we can activate the Meeting intent and schedule a meeting.

Testing

Connect several different channels to the script in order to test client entities. Have a conversation with the bot as a client over all the channels, and attempt to address contacts who are not in your address book.

When you address contacts who are not in your address book, the script switches to the NoMatch state.

Working with entries

Method	Description
$caila.addClientEntityRecords	Adds a record for a certain client to existing records of an entity.
$caila.deleteClientEntityRecords	Removes the records with the specified id for a certain client.
$caila.getClientEntityRecords	Returns the list of all the records of an entity for a certain client.
$caila.setClientEntityRecords	Overwrites all the records of an entity for a certain client.
$caila.setClientEntityRecord	Update the record of an entity for a certain client.
$caila.setClientNerId	Sets a custom clientId that is to be used later to parse text.
$caila.clearClientNerId	Removes a custom clientId set by the $caila.setClientNerId method earlier.

tip

Apart from unique entries, client entities may have entries common for all clients. They can be filled when an Entity is created or via NLP Direct API.

Changes to client entity entries do not require re-training of the model. This means you do not need to re-deploy the bot script into the channel if any client entity entries have been modified for a certain client.

Client entities are detected only when the client flag is active for an entity. When this flag is modified, the model needs to be re-trained and the script must be re-deployed to the channel. For example, if an entity was switched from the client to the non-client state.

You can modify entity entries even for non-client entities, but they will not be detected. You will need to enable the client flag, re-train your model and deploy the bot into the channel.

User ID

$request.channelUserId is used by default as the unique user ID.

You can use the $caila.setClientNerId method to set a custom clientId to be used later to parse text.