Messages

In this document we will cover everything you need to know about messages in Botfuel Dialog.

Messages in Botfuel Dialog are the classes provided by our SDK so you can work with Node.js objects and quickly build Views for the responses of your bot, without having to write outputs in the JSON format used by messaging channels.

These classes are subclasses of the abstract Message class. The Message class also extends ValidObject class that provides validators for string, array, uri and more to come.

All messages in Botfuel Dialog have the following structure:

{
  type: '<message_type>',
  sender: '<message_sender>', // bot or user
  user: '<user_id>',
  payload: {
    value: '<json_value>',
    options: '<optional_options_object>',
  },
}

There are two categories of Message classes in Botfuel Dialog: bot and user classes.

Bot message classes are called by views to generate JSONs, which are then sent to adapters and on to the messaging platforms. You can use them to create your own Views for the various responses of your bot, and provide rich formats to your users.

User message classes are used by adapters to convert JSONs from specific messaging platforms to the format used in Botfuel Dialog. Unless you want to write your own adapter, you don't need to manipulate user messages. The classes are shown here so you can understand their format when manipulating user messages as input for your bot.

Messages diagram

Bot message classes

BotTextMessage

The BotTextMessage is the main bot message class used to build text only messages.

Here is a basic "Hello world" example that can be integrated in your bot :

const { View, BotTextMessage } = require('botfuel-dialog');

class HelloView extends View {
  render() {
    return [new BotTextMessage('Hello world.')];
  }
}

module.exports = BotTextView;

It displays:

BotText message

QuickrepliesMessage

The QuickrepliesMessage is the bot message class used to build quick replies.

It allows your bot to suggest options of what the user could reply, by simply tapping one of them. Tapping an answer is equivalent to them typing and sending the text of the quick reply to the bot. Take note that Facebook limits the number of quick replies (11) and the length of their text (20 characters). The bot will process it as text, by passing it to the NLU.

Here is an example of prompting the user for a review using a 5 stars system:

const { View, QuickrepliesMessage } = require('botfuel-dialog');

class StarsRatingView extends View {
  render() {
    return [
      new QuickrepliesMessage(['1', '2', '3', '4', '5'], {
        text: 'Please give me a note.',
      }),
    ];
  }
}

module.exports = QuickrepliesView;

It displays the following message:

Quickreplies message

ActionsMessage

The ActionsMessage is the bot message class used to build messages with actions.

An Action is an abstract class that represents the content of an ActionsMessage. Actions can be either Links or Postbacks.

Links redirect users to any external url (e.g., product information).

Postback buttons allow you to trigger a new dialog in the bot and pass entities from the current dialog.

Postback buttons are similar to quick replies in appearance. However, they work in a different way. Unlike quick replies, Postback buttons skip the NLU and branch directly to the dialog provided.

This example displays both a link and a button to trigger the “greetings” dialog. Note the postback action takes 3 arguments:

  • text to be displayed
  • dialog to trigger
  • list of entities (empty in this example)
const { View, ActionsMessage, Link, Postback } = require('botfuel-dialog');

class BotfuelOrHelloView extends View {
  render() {
    const actions = [
      new Link('Botfuel', 'https://www.botfuel.io'),
      new Postback('Hello', {
        name: 'products',
        data: { messageEntities: [] },
      }),
    ];

    return [new ActionsMessage(actions)];
  }
}

module.exports = ActionView;

It displays the following message:

Action message

CardsMessage

The CardsMessage is the bot message class used to build card messages such as series of cards called carousels. It is composed of a list of Cards.

A Card contains an image and several buttons defined using the actions (links and postback) we introduced above in the "ActionsMessage" example. So the buttons in your cards and carousels can either take users to external links (using a "link") or trigger internal events using new dialogs (using a "postback").

This example:

const { View, CardsMessage, Card } = require('botfuel-dialog');

class HatsCarouselView extends View {
  render() {
    const cards = [
      new Card('Top hat', <top_hat_image_url>, [
        new Link('Details', <top_hat_url>),
        new Postback('Buy', { name: 'products', data: { messageEntities: [{ dim: 'product', values: ['product_1'] }]}}),
      ]),
      new Card('Cowboy hat', <cowboy_hat_image_url>, [
        new Link('Details', <cowboy_hat_url>),
        new Postback('Buy', { name: 'products', data: { messageEntities: [{ dim: 'product', values: ['product_2'] }]}}),
      ]),
      new Card('Detective hat', <detective_hat_image_url>, [
        new Link('Details', <detective_hat_url>),
        new Postback('Buy', { name: 'products', data: { messageEntities: [{ dim: 'product', values: ['product_3'] }]}}),
      ]);
    ];

    return [
      new CardsMessage(cards)
    ];
  }
}

module.exports = ActionView;

will display the following on Facebook Messenger:

Cards message products

BotImageMessage

The BotImageMessage is a class used to build bot messages that contain only an image.

This example:

const { View, BotImageMessage } = require('botfuel-dialog');

class HatImageView extends View {
  render() {
    return [
      new BotImageMessage('<image_url>');
    ]
  }
}

module.exports = ImageView;

will display:

Image message

BotTableMessage

The BotTableMessage is a bot message class used to build a table. The BotTableMessage can only be used with Botfuel's Webchat as adapter, it is not supported by other adapters such as Facebook Messenger.

This example:

const { View, BotTableMessage } = require('botfuel-dialog');

class NameCityTableView extends View {
  render() {
    const data = {
      schema: [{ key: 'name', label: 'Name' }, { key: 'city', label: 'City' }],
      rows: [
        { name: 'John', city: 'New York' },
        { name: 'Peter', city: 'Paris' },
      ],
    };
    return [new BotTableMessage(data)];
  }
}

module.exports = TableView;

will display the following:

Table message

User message classes

UserTextMessage

The UserTextMessage is a user message class used to build messages when user input is text.

This code:

const { UserTextMessage } = require('botfuel-dialog');

new UserTextMessage('Hello bot!');

const actions = [
  new Link('Botfuel', 'https://www.botfuel.io'),
  new Postback('Hello', { name: 'greetings', data: { messageEntities: [] } }),
];

UserImageMessage

The UserImageMessage is a user message class used to build messages when user input is an image.

This code:

const { UserImageMessage } = require('botfuel-dialog');

new UserImageMessage('<image_url>');

UserFileMessage

The UserFileMessage is a user message class used to build messages when user input is a file.

This code:

const { UserFileMessage } = require('botfuel-dialog');

new UserFileMessage('<file_url>');

PostbackMessage

The PostbackMessage is a user message class used to build messages when user input is postback.

This code:

const { PostbackMessage } = require('botfuel-dialog');

new PostbackMessage(<dialogData>);

JSON outputs

Each Message can generate JSONs outputs used by the adapters to link Botfuel Dialog and the messaging platforms. The ouputs below correspond to the examples given previously.

BotTextMessage

{
  type: 'text',
  sender: 'bot',
  user: userId,
  payload: {
    value: 'Hello user.',
  },
}

QuickrepliesMessage

{
  type: 'text',
  sender: 'bot',
  user: userId,
  payload: {
    value: ['1', '2', '3', '4', '5'],
    options: {
      text: 'Please give me a note.'
    }
  },
}

ActionMessage

{
  type: 'actions',
  sender: 'bot',
  user: userId,
  payload: {
    value: [
      {
        type: 'link',
        text: 'Botfuel',
        value: 'https://www.botfuel.io',
      },
      {
        type: 'postback',
        text: 'Hello',
        value: {
          name: 'greetings',
          data: {
            messageEntities: [],
          },
        },
      },
    ],
  },
}

CardMessage

{
  type: 'cards',
  sender: 'bot',
  user: userId,
  payload: {
    value: [
      {
        title: 'Top hat',
        image_url: <top_hat_image_url>,
        buttons: [
          {
            type: 'link',
            text: 'Details',
            value: <top_hat_url>,
          },
          {
            type: 'postback',
            text: 'Buy',
            value: {
              name: 'product',
              data: {
                messageEntities: ['top hat'],
              },
            },
          },
        ],
      },
      {
        title: 'Cowboy hat',
        image_url: <cowboy_hat_image_url>,
        buttons: [
          {
            type: 'link',
            text: 'Details',
            value: <cowboy_hat_url>,
          },
          {
            type: 'postback',
            text: 'Buy',
            value: {
              name: 'postback',
              data: {
                messageEntities: ['cowboy hat'],
              },
            },
          },
        ],
      },
      {
        title: 'Detective hat',
        image_url: <detective_hat_image_url>,
        buttons: [
          {
            type: 'link',
            text: 'Details',
            value: <detective_hat_url>,
          },
          {
            type: 'postback',
            text: 'Buy',
            value: {
              name: 'product',
              data: {
                messageEntities: ['detective hat'],
              },
            },
          },
        ],
      },
    ],
  },
}

ImageMessage

{
  type: 'image',
  sender: 'bot',
  user: userId,
  payload: {
    value: '<image_url>',
  },
}

BotTableMessage

{ type: 'table',
  sender: 'bot',
  user: userId,
  payload: {
    value: {
      schema: [Array],
      rows: [Array]
    },
  },
}

UserTextMessage

{
  type: 'text',
  sender: 'user',
  user: userId,
  payload: {
    value: 'Hello bot!',
  },
}

UserImageMessage

{
  type: 'image',
  sender: 'user',
  user: userId,
  payload: {
    value: '<image_url>',
  },
}

UserFileMessage

{
  type: 'file',
  sender: 'user',
  user: userId,
  payload: {
    value: '<file_url>',
  },
}

PostbackMessage

{
  type: 'postback',
  sender: 'user',
  user: userId,
  payload: {
    value: { ...dialogData },
  },
}