Adapters

This document covers the use of the pre-defined adapters and how to implement a custom adapter.

Adapters are responsible for connecting bots to messaging platforms. In other words, an adapter listens to incoming messages and converts them from the messaging platform's format to the format used by Botfuel Dialog. An adapter is also used to format the bot answers back to the platform's format and send them.

Web adapters

Some adapters are used locally for testing purposes (the shell adapter and the test adapter). But most chatbots provide a webhook that will be called by the messaging platform for each incoming user message. Botfuel Dialog provides a pre-defined web adapter (the botfuel adapter) and makes it easy to implement new ones.

Web adapters share common features:

  • They listen to incoming messages on the route webhook.
  • The route /static serves the content of the directory src/static of your bot directory. This can be used to send rich messages containing images, for example.
  • The route /templates/<TEMPLATE_NAME> serves the handlebars template src/templates/<TEMPLATE_NAME>.handlebars.

Pre-defined adapters

Botfuel Dialog comes with three pre-defined adapters.

shell adapter

The shell adapter is useful for testing a bot on a terminal during early development. It reads user messages and outputs the bot responses on the command line. Consequently, only the UserTextMessage and BotTextMessage are fully supported. Other types of user messages are not supported. Other types of bot messages are serialized as JSON.

test adapter

Contrary to the other adapters, the test adapter does not implement the run() method and thus cannot be used interactively. Instead, it implements the play() method that produces bot answers for a given list of user messages.

The test adapter supports all types of messages.

botfuel adapter

The botfuel adapter is a web adapter that connects a bot to Botfuel Webchat. See Botfuel Webchat for more details about the webchat.

The botfuel adapter supports the following kinds of messages:

  • ActionsMessage
  • BotTextMessage
  • PostbackMessage
  • QuickRepliesMessage
  • UserTextMessage

External adapter

The MessengerAdapter adapter is an external web adapter provided within an external module. It connects a bot to Facebook Messenger. See Modules for more details.

Implementing a custom adapter

If you want to connect your chatbot with a messaging platform that is not already supported out of the box by Botfuel Dialog, you can implement your own adapter. If your chatbot connects via an HTTP webhook to the messaging platform, please consider implementing a custom web adapter.

A custom adapter must extend the class Adapter.

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

class MyCustomAdapter extends Adapter {
  ...
}

module.exports = MyCustomAdapter

The subclass must be the unique export of a file named src/adapters/<ADAPTER_NAME>-adapter.js in your bot project directory.

Set the value of the member adapter.name of your bot configuration to <ADAPTER_NAME> in order to use this adapter.

The constructor of the custom adapter takes a unique parameter bot that should be passed to the super constructor:

  /**
   * @constructor
   * @param {Object} bot - the bot
   */
  constructor(bot) {
    super(bot);
    ...
    this.customParameter = bot.config.adapter.customParameter;
    ...
  }

The custom adapter should implement the following methods:

  • run() starts listening to user messages. The listening process should call this.handleMessage(userMessage) for each incoming message with a correctly formatted user message
  • sendMessage(botMessage) adapts a bot response to the format of the messaging platform and sends it

Implementing a custom web adapter

When a messaging platform connects via a web API, it is easier to create an adapter by extending the class WebAdapter. The class WebAdapter starts a listening web server and sends back bot responses as HTTP(S) POST requests.

The custom web adapter should implement the following methods:

  • handleRequest(req, res) is the Express callback to the route /webhook. handleRequest should adapt the incoming message and call this.handleMessage(userMessage)
  • getUrl(botMessage) provides the URL of the API used to send bot messages
  • getQueryParameters() provides the query parameters to send along with the POST request
  • getBody(botMessage) provides the body of the POST request as JSON