SPooN's Developers

# Chatbots

SPooN's solution can be connected to different chatbots:

# Dialogflow

Spoon solution can be connected to chatbots (or agents) created in DialogFlow ES.

In order to create a new chatbot, you can follow the tutorial proposed by Google (opens new window)

# Google & DialogFlow authentication system using Service Accounts

For a service to be allowed to communicate with a DialogFlow chatbot, this service needs to use validated credentials. To do so, Google proposes a system using “Service accounts”, that corresponds to validated identities to which we can add the needed permissions to communicate with the DialogFlow chatbot.

TIP

In order for Spoon software to be able to communicate with your DialogFlow chatbot, you will need a Service Account.

# Generate a service account for your chatbot

# Retrieve the project ID of your DialogFlow agent

Dialogflow parameters

  • Click on the ProjectID field and it will redirect you to the corresponding project on the Google Cloud Platform
# Create a Service Account with proper role & permissions + Key

Once on Google Cloud Platform (see previous section):

  • Go to Menu > IAM & Admin > Service Accounts
  • Create ServiceAccount
    • Click on + Create Service Account
    • Give a name to your service account, for example SpoonClient
    • Click on Create
    • In Select Role, choose role DialogFlow API Client
    • Click on Continue
    • Do nothing in Grant users access to this service account
    • Click on Done
  • Create a key for your newly created Service Account
    • You should see your Service Account in the displayed list
    • Click on the ... button in the Actions column + choose Create Key
    • Choose JSON in the popup + Click on Create
    • Download the json file on your computer (and keep it !)

TIP

Thanks to this JSON key file, Spoon software will be able to authenticate itself as the Service account, with the right permissions to communicate with your DialogFlow agent.

WARNING

  • Do not commit your json file in a git repository ! Everybody will be able to use your identity. Your billing will increase a lot. (if you want to git your configuration, use a .gitignore to remove your json file)
  • Only add the DialogFlow API Client role in IAM. In case of unwanted share of identity, the hacker is limited by this role.
  • Copy/paste your chatbots service account JSON key files in Spoon release folder
  • Open the release.conf file
  • Fill the key “chatbotConfigurations” with a list of objects corresponding to your chatbots
"chatbotConfigurations": [
 {	 
   "engineName": "DialogFlow",
   "name": <string>,
   "connectionConfiguration":
   {
     "serviceAccountFileName": <string>,
     "platformName": <string>, 
     "environmentName": <string>
   },
   "canBeProposed": <bool>,
   "iconName": <string>,
   "explanation": {
     "fr_FR": <string>,
     "en_US": <string>
   },
   "trigger": {
     "fr_FR": <string>,
     "en_US": <string>
   },
   "timeout": <int>
 },
 {...}
]
  • engineName: set it to “DialogFlow” as your are using DialogFlow chatbot engine
  • name: internal reference for the chatbot (for example MyBestChatbot)
  • connectionConfiguration: will include the informations to properly connect Spoon software with your DialogFlow Chatbot
    • serviceAccountFileName: full name of your service account JSON file “projectID-XXX.json (make sure this file has actually been copied/pasted next in the Spoon release folder)
    • platformName: (for expert usage) allow you to choose which DialogFlow platform messages from your agent to use in this connection with Spoon software
      • DialogFlow proposes multiple integration platforms (Default, Slack, Telegram, …) with different message types, Spoon can be connected to all of them
      • For non-experts usage, we recommend to use the Default platform, for this, you just need to set an empty platformName : “platformName”: “” or not set the platformName variable
    • environmentName: makes it possible to select a specific environment for your chatbot if you are using versions and environments (see documentation (opens new window))
      • you just need to specify the name of the environment in this field. Example : “environmentName”: “Production”. By default, if you haven't published a version, you can use environmentName: Draft
  • canBeProposed: whether or not you want to define a main entry point to your chatbot, that will accessible in the Launcher and described during the Explanation
  • iconName: the name of the icon that will be displayed in the Launcher for your main entry
    • for the moment the available iconName are : [“calendar”, “candidate”, “car”, “car2”, “form”, “foodfinder”, “jokes”, “learning”, “map”, “matcha”, “motivation”, “news”, “orientation”, “registration”, “sms”, “startups”, “takethepose”]
    • we can add other icons in the release on demand
  • trigger: sentence in french and english that will be displayed in the Launcher (at the same time as the icon) as an example of trigger for the service
  • explanation: sentence in french and english that the robot will use to describe the service to the user during the Explanation
  • timeout: time in seconds after which the robot will exit the scenario if the user has left the personal zone. Usually 10 to 15s.

# How to bind your main entry with your DialogFlow chatbot

As described above, if you set the flag canBeProposed of your chatbot to true, it will create a main entry point, that will be accessible in the Launcher

  • by clicking on its icon
  • by clicking on its trigger example
  • by saying its trigger example

TIP

This will send the event “Spoon_GenericStart” to your chatbot

For your chatbot to react to this event, you just need to add this event “Spoon_GenericStart” to one of the intent of your agent

SPooN Generic Start intent

# Declare a scenario end from chatbot & set end type

In your chatbot, when you think the service has been delivered, it is important that you declare that your service has ended.

If you do not declare this end, the user will not be able to do anything else with Spoony until the timeout of the chatbot is reached.

When you declare your scenario end, you have to define 3 elements :

  • status
  • afterEndType
  • message

Status: The status of the ending, i.e how the scenario ended

The possible values are :

  • “Succeeded”: the scenario finished correctly, the user got what they wanted
  • “Failed”: the scenario did not finished as expected, the user did not get what they wanted
  • “CancelledByUser”: the scenario stopped because the user decided to stop it
  • “Error”: something went wrong

AfterEndType: When a scenario has ended, the robot can have 2 possible behaviour :

  • “Passive”: the robot does not do anything proactively after the scenario end
  • “Active”: the robot asks the user if we wants to do something else (and starts the launcher if the user says “yes”)

Message: Stores additional information about the scenario end (can be used to have more precise statistics in SpoonAnalytics for example)

TIP

In order to call the scenario end from your chatbot, see the EndScenario action

# Spoon Actions bindings with DialogFlow messages

# Default platform

# Say (basic, without expression)

Action description: Spoony says something

Message description:

  • Message type: Text Response
  • Content : “textToSay”
# Say With Expression

Action description: Spoony says something while expressing a chosen expression

WARNING

For the moment, the expressions are not connected yet and will not be called when executing the action. However you can already use this action with an expression, so that your chatbot will be ready for when the expressions will be connected.

Message description:

  • Message type : Custom Payload
  • Content:
{
  "spoon" :
  {
    "id": "Say",
    "text": <string>,
    "expression":
    {
	"type": <TypeEnum>,
      "intensity": <float>,
      "gazeMode": <GazeModeEnum>
    }
  }
}
  • id: ID of the Action ⇒ “Say”
  • text: text to say
  • expression: expression to be expressed by Spoony while saying the text
    • type: type of the expression
      • enum among the following list : [“Neutral”, “Happy”, “Sad”, “Surprised”, “Scared”, “Curious”, “Proud”, “Mocker”, “Crazy”]
    • intensity: intensity of the expression
    • float between 0 and 1 (1 corresponding to the maximum intensity of the expression)
    • gazeMode: corresponds to the expected behavior of the gaze (eyes) of Spoony during the expressing
      • enum among the following list
        • “Focused” : Spoony will keep looking at the user during the whole expression
        • “Disctracted” : Spoony might not look at the user during the whole expression and look away (but it will look back at the user at the end of the expression)
# Multiple Choice Questions

Action description: Spoony asks a question and suggests a list of expected responses (displayed on the screen as interactive buttons)

Message description:

  • Message type : Custom Payload
  • Content:
{
  "spoon" :
  {
    "id": "MCQ",
    "question": <string>,
    "answers": [
    {
    	"displayText": <string>,
    	"content": <string>
    },
    {...}
    ]
  }
}
  • id: ID of the Action ⇒ “MCQ”
  • question: question that will be asked by Spoony
  • answers: list of expected answers
    • for each answer
      • displayText: text displayed in the corresponding interactive button, that can trigger the answer
      • content: simulated input to the chatbot when answer is selected (by voice or by button validation)
# Display Image

Action description: Spoony will display an image on the screen (it can also display a Gif, based on the extension of the image url)

Message description:

  • Message type : Custom Payload
  • Content:
{
  "spoon" :
  {
    "id": "DisplayImage",
    "imagePath": <string>,
    "caption": <string>,
    "duration": <float>
  }
}
  • id: ID of the Action ⇒ “DisplayImage”
  • imagePath: url of the image
    • compatible extensions : png, jpg, gif
  • caption: (optional) caption of the image
  • duration: (optional) how long to display the image for in seconds
    • if the duration is less or equal to zero, then the image is displayed until the next user's input (the default value is 0)
# Expressive Reaction

Action description: Spoony will express a short expressive reaction

WARNING

For the moment, the expressive reaction only contains a short sound

Message description:

  • Message type : Custom Payload
  • Content:
{
  "spoon" :
  {
    "id": "ExpressiveReaction",
    "expression":
    {
	"type": <TypeEnum>,
      "intensity": <float>,
      "gazeMode": <GazeModeEnum>
    }
  }
}
  • id: ID of the Action ⇒ “ExpressiveReaction”
  • expression: expression to be expressed by Spoony while saying the text
    • type: type of the expression
      • enum among the following list : [“Neutral”, “Happy”, “Sad”, “Surprised”, “Scared”, “Curious”, “Proud”, “Mocker”, “Crazy”]
    • intensity: intensity of the expression
    • float between 0 and 1 (1 corresponding to the maximum intensity of the expression)
    • gazeMode: corresponds to the expected behavior of the gaze (eyes) of Spoony during the expressing
      • enum among the following list
        • “Focused” : Spoony will keep looking at the user during the whole expression
        • “Disctracted” : Spoony might not look at the user during the whole expression and look away (but it will look back at the user at the end of the expression)
# Change Language

Action description: Spoony will change its interaction language

Message description:

  • Message type : Custom Payload
  • Content:
{
  "spoon" :
  {
    "id": "Language",
    "language": <LanguageEnum>
  }
}
  • id: ID of the Action ⇒ “Language”
  • language: target language
    • enum among the following list [ “en_US”, “fr_FR”, “ja_JP”, “zh_CN”]
# Wait

Action description: Spoony will wait for the given amount of time.

Message description:

  • Message type : Custom Payload
  • Content:
{
  "spoon":
  {
    "id": "Wait",
    "timeToWait": <float>
  }
}
  • id: ID of the Action ⇒ “Wait”
  • timeToWait: the time to wait for, in seconds
# End Scenario

Action description: Spoony will end the current scenario (see explanation here)

Message description:

  • Message type : Custom Payload
  • Content:
{
  "spoon" :
  {
    "id": "EndScenario",
    "status": <StatusEnum>,
    "afterEndType": <EndTypeEnum>,
    "message": <string>
  }
}
  • id: ID of the Action ⇒ “EndScenario”
  • status: scenario end status (see here for usage and possible values)
  • afterEndType: scenario end type (see here for usage and possible values)
  • message: scenario end message (see here for usage and possible values)

← Guidelines →