Configuration file¶

Central to your chatbot is its configuration file (which we will also call the config). In this file, you declare which messaging and NLP service you want to use and include all information required to authenticate with the distinctive services. You have to follow a predefined format specified in the Typings of the framework.

Important: Without a valid configuration file the framework will start in the default configuration. In default configuration the framework provides a simple communication test which is accessible through the CLI client.

Basic structure¶

The minimum requirements necessary to start a bot are the specification of:

The variables required for the chat platform of your choice (config.platform.chat).
The variables required for the NLP service of your choice (config.platform.nlp).
The variables used to configure your server (config.server).

Furthermore, you can add more configuration variables for additional services, like a database.

Exemplar Configuration File¶

In this exemplar configuration file, we use the Facebook Messenger as our messaging platform and Dialogflow as our NLP Service. We have also provided some configuration files for various combinations of messaging platforms and NLP services here. If you want to change the platforms, you can simply change the respective section (e.g. platform.chat) in the configuration file. More information on which variables you need for each platform and how you can get these variables can be found in the distinctive section (see below for more information).

 import {Config, FacebookAdapter, DialogflowV2Adapter} from 'emubot'

 export const config: Config<FacebookAdapter, DialogflowV2Adapter> = {
     platform: {
         chat: {
             appSecret: 'YOUR_APP_SECRET',
             constructor: FacebookAdapter,
             name: 'facebook',
             pageAccessToken:
                 'YOUR_FACEBOOK_PAGE_TOKEN',
             url: 'https://graph.facebook.com/',
             verifyToken: 'YOUR_FACEBOOK_VERIFY_TOKEN',
             version: 'v3.3',
             webhook_path: '/webhook',
         },
         nlp: {
             agents: {
                 name_of_first_agent: {
                     defaultLifespan: 2,
                     executionIndex: 1,
                     languageCode: 'de',
                     minScore: 0.75,
                     project_id: 'SOME_GCP_ID',
                     token: 'PATH_TO_SOME_TOKEN',
                     url: 'https://DIALOGFLOW-BASE-URL.com',
                 },
                 name_of_second_agent: {
                     defaultLifespan: 2,
                     executionIndex: 0,
                     languageCode: 'de',
                     minScore: 0.75,
                     project_id: 'ANOTHER_GCP_ID',
                     token: 'PATH_TO_ANOTHER_TOKEN',
                     url: 'https://DIALOGFLOW-BASE-URL.com',
                 },
             },
             constructor: DialogflowAdapter,
             name: 'dialogflow',
         },
     },
     server: {
         port: 61133, // The port your bot listens on.
     },
     interceptors: {
         chatToCore: MirrorInterceptor.getInstance,
         nlpToCore: MirrorInterceptor.getInstance,
         nlpToNlp: MirrorInterceptor.getInstance,
     }
 };

The second agent (the lines with the yellow background) is not necessarily required. We will talk about the use of this in the NLP Platform Configuration section below.

Messaging Platform Configuration¶

If you want to use another chat platform (e.g. Slack):

First of all, change the imported adapter. In our example change line 1 and 3 from

import {Config, FacebookAdapter, DialogflowV2Adapter} from 'emubot'

export const config: Config<FacebookAdapter, DialogflowV2Adapter> = {
    platform: {
        ....

to

import {Config, SlackAdapter, DialogflowV2Adapter} from 'emubot'

export const config: Config<SlackAdapter, DialogflowV2Adapter> = {
    platform: {
        ....

Then change the configuration itself. Which variables you require depends on the messaging platform you use.

Supported platforms currently are

Facebook: use FacebookAdapter. For more information regarding the configuration, see Exemplar Facebook Config.
Slack: use SlackAdapter. For more information regarding the configuration, see Exemplar Slack Config.

If you want to support a different platform, take a look at Support Your NLP Platform and Support Your Chat Platform respectively.

NLP Platform Configuration¶

If you want to use another NLP platform (e.g. Rasa):

Change the imported adapter and modify the respective variables. The changes are synonymous to the changes in the messaging platform above. Currently we support

Dialogflow (API version 1): use DialogflowAdapter (deprecated).
Dialogflow (API version 2): use DialogflowV2Adapter. For more information regarding the configuration, see Exemplar Dialogflow Configuration.
Rasa: use RasaAdapter. For more information regarding the configuration, see Exemplar Rasa Configuration.
Snips: use SnipsAdapter. For more information regarding the configuration, see Exemplar Snips Configuration.

Multiple agents¶

Many chatbots are able to talk about different topics, e.g. perform smalltalk and offer an additional service that offers direct utility (such as ordering a pizza). These topics can (and sometimes should) be separated into different agents. An agent encompasses all the information required to fulfull user requests and is often also referred to simply as the bot. But a bot as a whole can also include multiple agents, even if the user does not realize that different agents are handling his requests. The emubot framework allows you to send requests to multiple agents.

Each of your agents has an executionIndex. The lower the index, the earlier a request will be sent to this agent. The NLP service will then return a score between 0 and 1: If it is 100% sure that it can answer the query correctly, it will return 1, otherwise it will return a value below 1. The higher the value, the higher is the confidence of the NLP service that the query is classified correctly. This is why a minScore is declared for each agent, which is a minimal threshold of confidence the service has to have to accept the response and not ask a different agent.

Example for a minScore of 0.6: If the NLU service returns a probability for an intent >0.6: use the intent. If the probability is <0.6: send to next agent, determined by the executionIndex.

Best Practices¶

The tokens used to authenticate with the services are very senstive information. You do not want to publish the respective strings or files in a public repository at any cost. A good way to handle this is to use some CI/CD service (like GitLab CI/CD) to assemble the respective files.

Furthermore, separating the configuration file into multiple individual blocks/files can help you. Using this allows you to reuse the same configuration for a specific platform, which also means that you only have to change it in one place afterwards.