Introducing the Chatbot API module for Drupal 8

Drupal Chatbot API module

Conversational interfaces powered by artificial intelligences are rapidly growing in popularity for delivering more natural-feeling, convenient experiences for consumers. We’re very excited to announce the new Chatbot API module for Drupal 8, which helps surface content via bots and assistants without having to write reams of code for each AI you want to use.

Voice assistants like Amazon’s Alexa and Google Home allow people to perform a wide variety of tasks – from searching for answers to questions to ordering products – without having to pick up a device. Auto-responders (aka chatbots) which run in popular social networks like Facebook and Twitter, or in live-chat windows, can similarly help users perform common functions without requiring them to visit a separate app or website.

The ability to use Drupal as a ‘headless’ CMS makes it ideal for serving the content of a chatbot’s responses. The module we’ve created is designed specifically to help people using Drupal 8 as a CMS to surface their content for users via bots and assistants.

What’s your Intent?

In chatbot design, the Intent of the user (i.e. what they want to accomplish through their interaction) defines the range of possible responses that your bot can give. We help the artificial intelligence to determine the Intent of the user by mapping example phrases to specific Intents. The more phrases you map, the more chance the AI has of getting the Intent right.

For example, if the user is looking for an event they might utter, or type, something like:

  • “What’s on?”
  • “What’s happening?”
  • “What events are coming up?”

To which we might want to respond with a full list of upcoming events, pausing after each to ask the user if they’d like to know more.

And, of course, we can program our AI to listen for variables within such phrases:

  • “What’s happening today?”
  • “What’s happening in Brighton next Tuesday?”

With Chatbot API, we’ve simplified the coding and discovery of Intents by making them plugins (harnessing the powerful Drupal 8 Plugin API). All you have to do is make the Intent name match the Plugin ID. And because the API is platform-agnostic, you can use the same Intent for serving content via multiple services.

What does Chatbot API do?

If you’re using Drupal as a ‘headless’ CMS then you want to be able to surface your content through as many different services as possible e.g. Amazon Echo, Google Home, Facebook chatbots, or a custom service built with e.g. Api.AI

Previously you’d have to write custom code for each Intent on each chatbot/personal assistant platform you wanted to use.

before the drupal chatbot api

Chatbot API provides a common layer to serve Drupal content to any such service, so you only have to write your code for each Intent once. The handling of requests and responses is left to the specific module which implements your bot (e.g. Apa.AI) or voice assistant protocol (e.g. Alexa skill).

after the drupal chatbot api

Currently the module supports the following platforms:

  • Alexa, by using the internal chatbot_api_alexa submodule together with the Alexa module.
  • Api.Ai, by using the internal chatbot_api_ai submodule together with the Api.AI Webhook module

The roadmap

So far, in addition to a Custom Intent plugin, we’ve created a Views Intent which can be used to surface any content that you might normally surface on your site or app using Views.

Here’s an example of the kind of conversation it can power:

User: "Middle Earth, what cities have you got?"

Bot: "I've got Hobbiton, Bree, Moria, Lorien, Edoras and Minas Tirith."

User: "Tell me events in Bree happening today."

Bot: "Bilbo and Friends playing at The Prancing Pony today. Do you want to know more or skip to the next event?"

User: "Skip."

Bot: "Black Riders hanging around Bree from today to tomorrow. Do you want to know more or skip to the next event?"

User: "I want to know more."

Bot: "[...]"

At the moment this Intent is experimental. We’ll be looking to add better support for fields and taxonomies to allow for deeper and more complex experiences.

Additional functionality we’re looking to add in the short to medium term includes a Chatbot display mode, which will help you render your content in chatbot friendly way (e.g. no markup, restricted amount of characters). We also want to add the ability to suggest Drupal content entities (i.e. categories, tags etc) for the service to use when extracting parameter values in the user’s request, removing the need to maintain a full list of entries at both ends.

The long-term dream is to be able to expose forms and other complex interactions through chatbots and assistants.

How to get started

For now, you’ll find info on how to get your bots up and running at the project page and in the documentation. That documentation will expand over time, but stay tuned to the blog for walkthroughs on creating Custom Intents and surfacing content with the Views Intent.

Check out the Drupal console integration for quickly creating a Custom Intent plugin skeleton.

The module is quite stable, but it’s still in early stages. While the API may change, we’ll try to ensure backwards compatibility if and when interfaces are modified. An alpha/beta release is expected before the end of September. When the roadmap is completed and test coverage is satisfying, we’ll announce the first release candidate.


Are you a Drupal, WordPress or Joomla! developer, site-builder or tester? In London this Saturday 9th September? Join us for our Summer Open Source Sprint.


Leave a reply

You can use these tags:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

  1. ernesto fuentes says:

    Great article but Im reading in drupal web “This project is not covered by Drupal’s security advisory policy”. could you tell something about it? Thank you

  2. Sameer says:

    I have included the Chatbot API module, Dialoflow ApI.ai module and enabled the all subsequent modules. I have followed ‘Introducing the Chatbot API module for Drupal 8’ to proceed. After enabling all modules when i fire localhost/api.ai/webhook i recieve JSOn response {“status”:{“code”:405,”errorType”:”Method Not Allowed”},”speech”:”An error occurred.”}

    In error logs i find Php error log shows: PHP Fatal error: Class ‘ApiAi\Model\Query’ not found in x:\xxxxxx\api_ai_webhook\src\ApiAi\Model\Webhook\Request.php on line 17.

    What would be the issue i am unable to proceed

    • Hi Sameer, it seems you’ve installed the module without the required libraries (i.e. probably without using composer).
      I’ve replied to the issues you’ve opened on drupal.org https://www.drupal.org/project/api_ai_webhook/issues/2979761 and I suggest to continue the conversation in there, so it can become a documentation when we address your problem!

      • Sameer says:

        Yes i tried posting there but failed to do so beacuse of confirmed user issue. I have tried to make image attachments where i have included all libraries that is installed and enabled. But in-fact i have not used composer to do so. Is composer vital in installing those modules. I don’t receive proper json reponse on call tp api.ai/webhook. And i am unable to use Entity Collection interface as well and it returns

        [php7:notice] [pid 5188:tid 1784] [client ::1:53600] Uncaught PHP Exception UnexpectedValueException: “In order to use the api.ai remote entity push, you need to add your developer token to settings.php. E.g. $settings[‘api_ai_webhook_developer_token’] = ‘your token here’.
        modules\\api_ai_webhook\\src\\Plugin\\ChatbotApiEntities\\PushHandler\\ApiAiPushHandler.php line 142, referer: config/service/chatbot-api-entity-collection/add

        • Is composer vital in installing those modules.

          No it’s not, but it will help with dependencies management. If you don’t use it you need to make sure the libraries are downloaded and loaded, which is not an easy task (this is a D8 thing, not a Chatbot one).

          RE the Entities failure, the error already gives you a clue on what is missing (the developer token on settings.php). Also bare in mind current version on Dialogflow Webhook only supports API v1, and you have to switch to this version on Dialogflow backend as the default is now V2.
          PS: V2 support is coming soon though, and hopefully we can provide an upgrade path from V1 to V2.

  3. Sameer says:

    I am unable to add any entities as well in Entity collection Interface.

Sign up for the Manifesto newsletter and exclusive event invites