Interactions

Interaction represents one of the possible steps in your conversation. It allows you to create a relation between what user says and what bot should do. You can connect interactions with each other and create references to existing ones.

Default interactions

Default interactions

In default interactions, you can define all available responses. To get more details, click here.

Welcome interaction

Welcome interaction allows you to start the conversation with your customer as first. Just send the welcome trigger to get the welcome message from our API. The response body will include Default Welcome interaction object to use in a welcome message to user.

Example response

{
  "result": {
    "source": "custom",
    "resolvedQuery": "",
    "trigger": "welcome",
    "confidence": 0.7,
    "score": 1,
    "lifespan": 2,
    "incomplete": false,
    "storyId": "592d4007b880ed000778dbda",
    "interaction": {
      "id": "592d4007b880ed000778dbdb",
      "name": "Welcome Interaction",
      "action": "default.welcome",
      "type": "welcome"
    },
    "parameters": {},
    "contexts": [],
    "fulfillment": [
      {
        "type": "text",
        "message": "Welcome in the BotEngine.ai!"
      },
      {
        "type": "quickReply",
        "messages": [
          {
            "type": "quickReply",
            "title": "Are you using botengine.ai?",
            "replies": [
              "Yes",
              "No"
            ]
          }
        ]
      }
    ]
  }
}

Fallback interaction

Fallback interaction allows you to support user messages not recognized in your story. You can also disable fallback interaction in your story.

Fallback interaction is closely related to lifespan parameter. Click here to read more.

User created interactions

Interaction has the following sections:

User Says

User says represents messages which are used to recognize this interaction. User says cannot be exactly the same as user input message. The accuracy of recognition depends on your confidence score which you can setup in Settings tab.

In each user says you can use Entities by calling double brackets {{. By calling {{ you can see all available entities.

You can use one of them and assign a name to it, which is called parameter, e.g: {{sys.email:email}}. It means that the email is a parameter name. This allows you to recognize your correctly matched parameter from /query or use this parameter in your response.

The image below shows how you can create User Says with Entities.

Use entity

Related topics:

Parameters

Parameters allow you to recognize specific entities in User Says. The parameter is filled after it is recognized in the user input message.

You can use your parameters also in a response by putting {{your-alias-name}} in your response message.

Default parameters

Default parameters allow you to store data about users and ongoing conversation. These parameters are used as metadata in archive.

With integration of Facebook Messenger, LiveChat or Slack data is saved automatically.

Default parameters collect information regarding users, such as name, surname, avatar, gender, type of integration or source from which the conversation started. Parameters can be used directly in Response section by using {{name_parameter}}.

List of default parameters:

Parameter Description
{{default_avatar}} link to user’s avatar
{{default_name}} name and surname or user’s login
{{default_source}} type of integration from where the message comes, e.g. FB
{{default_url}} source from where the conversation has started, e.g. FB fanpage
{{default_language}} configured user’s language
{{default_timezone}} user’s timezone
{{default_gender}} user’s gender

Filling parameters

It’s possible to send any parameters during the ongoing conversation. They can subsitute already existing parameters or create new one that can be used at the specific scenario stage.

Parameters can be sent either in endpoint /query or as an answer for incoming webhook.

Example of use

Let’s assume that at the beginning of conversation you want to welcome user by using his full name. You can use endpoint /query in which Default Welcome Interaction will be triggered from particular scenario.

Let’s start with editing Default Welcome Interaction in scenario. Take a look at the picture below - we’ve simply added parameter {{default_name}} to the response.

Filling parameters

Now, let’s try to trigger Default Welcome Interaction by using our API.

curl -X POST \
  https://api.botengine.ai/query \
  -H 'authorization: Bearer ${PUBLIC_API_KEY}' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "sessionId": "1000000000",
    "storyId": "${YOUR_STORY_ID}",
    "trigger": "welcome",
    "parameters": {
        "default_name": "Dariusz Zabrzenski"
    }
  }'

Response

{
    "result": {
        "source": "custom",
        "resolvedQuery": "",
        "trigger": "welcome",
        "confidence": 0.7,
        "score": 1,
        "lifespan": 10,
        "incomplete": false,
        "storyId": "596e28b4d17bf3000737d424",
        "interaction": {
            "id": "596e28b4d17bf3000737d425",
            "name": "Welcome Interaction",
            "action": "default.welcome",
            "type": "welcome"
        },
        "parameters": {
            "default_name": "Dariusz Zabrzenski"
        },
        "contexts": [],
        "fulfillment": [
            {
                "type": "text",
                "message": "Hi Dariusz Zabrzenski"
            }
        ]
    },
    "sessionId": "1000000000",
    "timestamp": "2017-07-19T10:12:30.057Z",
    "status": {
        "code": 200,
        "type": "success"
    }
}

As you can see, the fullfillment object contains the text that we’ve filled before with parameter which was sent by endpoint /query.

Automatic parameters

If you are using parameters directly in User Says section, they will be added automatically to parameters section.

If you want to change the parameter name, check Parameters or User Says section.

Removing parameters

You can remove a parameter in parameters section, then your User Says automatically remove these parameters from every message.

Required parameters

Parameters are required only when your prompts are not empty.

Related topics:

Prompts

Prompts allow you to define specific questions for a parameter. The user will be asked by on of these questions to fill the parameter until the parameter is not filled. When your prompts are not empty, then your parameter will be required.

The maximum number of attempts to fill the parameter is related to lifespan.

Related topics:

Responses

You can define response messages that will be provided by your application when the interaction is triggered. You can set up different message types that will be sent one by one.

References to parameter aliases

You can show the extract values from parameters. If the parameters exist in the interaction parameter table, you can show extracted value by typing {{parameter_alias_name}}.

The image below shows how you can use parameters in a text response.

Use entity in responses

Text response

One possible type of responses is a text response. You can add several messages to single text block response. With this, when your interaction will be correctly matched, the response will be randomly chosen. It will make your chat bot more human-like.

You can also define several text response blocks to send the messages one by one.

Several text responses

The image presented above shows two text response blocks with several messages. When this interaction will be triggered, the user will receive two messages that will be randomly chosen from the first and second section respectively.

Rich messages

You can combine these messages to use in our one-click integration. You can also test rich messages in chat available in our application.

Rich messages

Card response

Card consists of several elements:

  • Image
  • Title
  • Subtitle
  • Buttons

Card response in Facebook Messenger Cards are simplified versions of Facebook Messenger generic template. You can add several cards to the same block response to display your cards in a horizontal scrollable carousel.

Fields

Field Properties Description
Image url This field is not required
Title The title cannot be empty (80 character limit)
Subtitle This field is not required (80 character limit)
Buttons title The field is required
postback This field is not required

Buttons

You can create a maximum of 3 buttons in a single card.

Postback

We will use your title as postback when this field is empty. A postback field must be a string, url or phone number.

Image

The image messages allow you to send images in one-click integrations. The url field is required. Supported formats and sizes:

  • Facebook Messenger: JPG, PNG, GIC

Quick replies

Quick replies are clickable buttons with pre-defined user responses. When you click one of these buttons, the button content will be send to the /query.

You can add only one Quick Replies block in the single interaction. The maximum number of Quick Replies is 11 and each reply button has a limit of 20 characters.

Quick Replies in Facebook Messenger

Quick replies is a simplified form of Facebook Messenger Quick Replies.

How to add postback to quick replies buttons?

As for now, you cannot add postback to Quick Replies. However, we are working on it.

Button template

Use Button Template to send a text response with buttons.

Button template in Facebook Messenger

Field Parameters Description
Text The field have a 640 character limit
Buttons title The field is required
postback This field is not required

Buttons

You can create maximum 3 buttons in single card.

Postback

We will use your title as postback when title will be empty. Postback field must be a string, url or phone number.

Advanced Settings

Triggers

Triggers allow you to invoke the interaction by a trigger name instead of a user query.

You can trigger specific interaction by passing the trigger name to /query request.

Default triggers

Some trigger names are reserved as default.

Trigger name Description
welcome By this trigger you can invoke Default Welcome Interaction

Trigger name

Trigger name has an 50 character limit. It may contain only alphanumeric values.

Trigger invoking

To trigger specific interaction, send a request to /query endpoint with a trigger name.

Following example presents how to invoke the Default Welcome Interaction which is available as default in each newly created story.

curl -X POST \
  https://api.botengine.ai/query \
  -H 'authorization: Bearer ${PUBLIC_API_KEY}' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'postman-token: d8aa685f-8560-bc90-b388-e6d16e59d576' \
  -d '{
    "sessionId": 1000000000, "trigger": "welcome"
  }'

Webhook

Webhooks allow you to pass information from a matched interaction to your web service and to get a result from it.

Webhook request

When an interaction has a filled Webhook section, our backend service send the matched interaction to the webhook by POST request.

Response for the webhook

To response the webhook from your web service you need to return the object with the response array.

Click here to read more about possible response objects.

Example response from the service:

{
    "responses": [
        {
            "type": "text",
            "messages": [
              "Ok, no problem"
            ]
        }   
    ]
}

Node.js example

'use strict';

const http = require('http');
const url = require('url');
const querystring = require('querystring');
const token = '${VERIFICATION_TOKEN}'; // type here your verification token

const server = http
    .createServer((req, res) => {
        const parsed = url.parse(req.url);

        req.url = parsed.pathname;
        req.query = querystring.parse(parsed.query);

        req.rawBody = '';

        req.on('data', chunk => {
            req.rawBody += chunk;
        });

        req.on('end', () => {
            if (req.rawBody) {
                req.body = JSON.parse(req.rawBody);
            }
        });

        handler(req, res);
    });

function handler(req, res) {
    // check token in every request
    if (req.query.token !== token) {
        res.writeHead(401);

        return res.end();
    }

    // verification request
    if (req.method === 'GET') {
        return res.end(req.query.challenge);
    }

    // it will contain query response
    console.log(req.body);

    const data = {
        responses: [
            {
                type: 'text',
                messages: ['Ok, no problem']
            }
        ]
    };

    res.end(JSON.stringify(data));
}

server.listen(3000);

Limits

Timeout for service response is 3 seconds.

Action

An action defines what interaction has been triggered. By action name, you can recognize what interaction was triggered on your backend side.