Create a virtual agent

In order to create a chat bot in Dialogflow, you can:

• Create it from Athento following this documentation.
• Go to https://dialogflow.cloud.google.com/ and log in with a Google account. Once inside, you will see the following screen. From here, click on Create Agent. Make the appropriate settings for your virtual agent.

Once the chat bot is created, you must create the Intents and Default fallback intents that will control the flow of the conversation.

Each Intent has:

• Contexts: using contexts, you can control the flow of a conversation. You can configure contexts for an intent by setting input and output contexts, which are identified by string names. Each active context has a lifespan that defines the number of conversational turns for which the context remains active.
  • Normal intents: default lifespan is 5, but it will be convenient to change it to 0.
  • Follow-up intents: default lifespan is 2.

• User expressions: what the user has to type so that the chat bot knows what to answer (dialogflow is responsible for detecting if similar phrases are typed, with uppercase, lowercase, etc.).

• Text responses: the possible responses of the chat bot to the defined User Expressions.

• Action and parameters: in this section, the different actions to be performed in Athento will be written. The available actions are:

  • Select space: this action will select the space in which the required document will be created (scheme: select-series, select-series{<serie's name>}).

  • Upload/update main binary: this action will update the binary of a document (scheme: update-principal-binary).

  • Fill field: this action will fill a specific field (scheme: set-metadata-type-value{<metadata type's slug>}).

In addition, the agent has two important booleans: 

• Fulfillment: in this Intent section, there are two options. "Enable webhook call for this Intent" must be checked for all intents, as shown in the following picture:
• Set this intent as end of conversation: this option must be checked when the current Intent is the end of a conversation flow (when this end point is reached, the actions decided from the previous intents in Athento will be executed).

Connecting DialogFlow with Athento

From the Advanced Administration, in API Key Permissions > API keys, you must create the key that will allow the connection with Dialogflow.

Just give it a name. Once you save, the API key will appear on the screen. Copy it and go to DialogFlow.

From DialogFlow, in the "Fulfillment" section, activate the "WEBHOOK" option and fill in the following fields:

• URL: type https://SUBDOMAIN.athento.com/dialogflow/api/fulfillment/execute/ where SUBDOMAIN is the name of your Athento installation.
• Add a HEADER that has as key "authorization" and as value "Api-Key <api key>" where <api key> must be replaced by the value of the key you copied from Athento.

Example use case

In this use case, a chat bot is defined which will manage the entry of job resumes in a company. This flow will create a document in the corresponding space with the fields requested by the chat bot.

Example of a conversation:

This is configured in Dialogflow as follows:

welcome intent: this intent has no actions.

welcome-no intent: this intent is an end of conversation if the user answered no to the "Would you apply for a job with us?" question. You should copy the input context text (welcome-followup) and set it in the output context with lifespan 0 in all intents except the welcome one.

welcome-yes intent: in this intent, you start to build the document you want to create in Athento, so you must indicate the space where you want to save the document. The action has to be select-serie{<name>}

welcome-yes-email intent: intent to fill the email field with action set-metadata-type-value. It uses a system entity to validate if the user is answering with a well formed e-mail. If you use entities that are not of type any (in this case, sys.email) you must change their "PARAMETER NAME" to the word "entities". Entities that are "sys.any" can be kept as they are.

welcome-yes-email-name intent: intent to fill the name field with action set-metadata-type-value. In the text response, you can put $<parameter name of entity> to make the agent respond with what has been detected in the entity.

welcome-yes-email-name-phone intent: intent to fill the phone field with action set-metadata-type-value. 

welcome-yes-email-name-phone-job intent: intent to fill the job choice field with action set-metadata-type-choice-value. In this case, a custom entity was defined with the internal values of the choice field, and the synonyms that each choice can have.

Custom entity:

welcome-yes-email-name-phone-job-git intent: intent to fill the github link field with action set-metadata-type-value. It also accepts a no for answer if the user does not have a github profile, in which case the field will not be filled in.

welcome-yes-email-name-phone-job-git-experience intent: intent to fill the experience choice field with action set-metadata-type-choice-value. Also in this case, a custom entity was defined with the internal values of the choice field, and the synonyms that each choice can have. In addition, as this field is a more abstract, the "any" entity is added so that the flow continues to respond to whatever the user responds to, even if it does not detect the experience entity.

welcome-yes-email-name-phone-job-git-experience-openanswer intent: intent to fill the open answer field with action set-metadata-type-value. It also accepts a no for answer if the user does not want to type an open answer, in which case the field will not be filled in.

welcome-yes-email-name-phone-job-git-experience-openanswer intent: intent to upload the principal binary of the document with action update-principal-binary. If the Kommunicate interface is used, KOMMUNICATE_MEDIA_EVENT must be written in EVENTS to validate that a binary has indeed been responded to.