Create conversational experiences with the Chatbot API for Drupal 8

Drupal Chatbot API Tutorial

This is my second post based on the talk I delivered at DrupalCamp London 2018: “Hi user, I am Drupal. How can I help you?” In the first post I looked at some of the scenarios in which chatbots and personal assistants might be used to beneficially serve website content to your audiences and briefly introduced the Chatbot API for Drupal 8. In this post, I’ll walk through the second half of the talk in which I show how easy it is to surface content through a chatbot using the API.

Check out the slides and code examples used in this post on GitHub.

Chatbot API features

To recap, Chatbot API provides a common flexible extra layer that sits between Drupal, your NLP and your various chatbots and personal assistants. It makes your website chatbot-friendly so you don’t have to write new code each time you translate your conversational experiences from one interface to another.

Chatbot API works with Dialogflow and Alexa out of the box, with support for more platforms on the way.

Using Chatbot API, Intents become plugins, making use of the flexible Drupal Plugin API.

Entities can be  supplied by your website data, and pushed easily to the NLP where you’re creating your conversational experience.

The module also provides a Views integration to easily create Intents  to return lists of content items for the user to explore further e.g. event listings, news articles, pages, reviews etc.

Creating an Intent plugin

You create the plugin in the usual way, using the Intent Name (the machine name of your intent) as the Plugin ID, adding your logic and defining the responses of the bot/assistant.


The module includes a Drupal Console command generate:plugin:chatbotintent utility to easily create Intent plugin skeleton through a wizard.

Pushing Entities to your NLP

Entities are great for improving the way your NLP understands and recognises the parts of the conversation you want to perform logic on. The more the Entities entries you provide, the easier it will be for you to write your intents and their logic. Most NLPs also support synonyms, and again the more, the better.

In the Drupal context, these Entities may be nodes of a specific content type, or taxonomy terms. But what if we have a lot of entries in our Entities list? We need to push the Entities from our website to the NLP so they can be used in our logic. This is a simple matter with the Chatbot API Entities submodule: the configuration wizard will help you create an Entity Collection, selecting what from your website should be synced as an NLP Entity. It supports synonyms too, and also gives high flexibility on what or where exactly are the Entities you want to push (nodes, terms, fields, bespoke condition, results from a database query, etc) by creating new ChatbotApiEntities/QueryHandler plugins.

As part of the Entity Collection setup, you can choose to which endpoint (in this case, API.AI – the old name for Dialogflow) to push the Entities during the next cron run.


Adding new Entities within those collections can now be done entirely in Drupal. The NLP, in this case Dialogflow, will then automatically synchronise after the next cron run.

Serving content via Views integration

If we were to answer a user’s query like ‘show me a list of properties in Shoreditch’ on our Drupal website, we’d serve a list of search results using Views.

In a conversational experience, we can do the same thing, with the (voice) assistant, for example, presenting one result at a time and asking the user if they’d like to hear more or skip to the next result. To achieve this, we set up a view with pagination, showing only one result per page.

With the Views integration provided by Chatbot API you just need to create – or reuse – your view and add a Chatbot Intent display. By doing this the module will automatically select best default options (pagination, 1 item per page), but you are free to personalise anything you want. For instance you may want to add a “Footer” element (in a conversational context that will be the suffix of your response) and a No Result message (which will be our response when there are no results).


The only requirement is for you to set up the Intent Name exactly as its name on the NLP. That’s it, your view is now exposed. Go ahead and play with it.
The code examples have both the Dialogflow configuration and a View for you to play with.

Chatbots: a new way to serve your website content

Here’s an example of my Drupal Concierge in action, demoing the maintenance_support intent.


As you’ll see, the chatbot is merely serving content to the end user from the repository of available content on my site. The difference is, it’s using natural language processing to determine the user’s intent and the entities referenced, and serving content in a way that makes navigating the content easier via text and speech interfaces. Designing a conversational experience requires that you take these differences into account.

With that in mind, here are my top tips for serving content via chatbots:

  • Plan your Intents in advance – think about the context in which the user is asking for the information and the how it can be served to them in the best way;
  • Consider the variety of utterances that might be used to ask for the same thing – there will be surprises. A useful resource here is answerthepublic.com, which returns Google’s suggested searches for any query;
  • Train your bot – as sophisticated as the NLPs are, they’re still pretty dumb. But by answering queries left unanswered by the bot (kind of like marking its homework), you can train it become smarter.
  • Build your content with Intents in mind – your content may not be ready to be exposed by a chatbot. You may want to redesign some of your content types with shorter titles, chatbot-only content snippets etc.
  • Create a Display Mode for your bot – this can also help present content in a bot-friendly way, by stripping out extraneous fields or media which would be inappropriate to serve via a bot.

Have fun! And do let me know about how you’re using Chatbot API to serve content – I’m sure I’ve only thought of a small number of the potential uses for  .

And finally, if you’d like to discuss the possibility of working together on an implementation or new integration, don’t hesitate to get in touch.

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. Ulf says:


    interesting article. We’re about to release a new Drupal site any time soon and would like to hook up a chatbot to serve our customers. We will have content on our site with news, projects, people, booking site and more and think it would be great to have assistant finding in large data sets. What do you recommend (we’re a swedish based site), Webhooks with api.ai/Google? e.g. Where to start? Thanks!

  2. karthik Company says:

    Hello, First would like to thank you for posting such a nice intuitive blog. We are about to implement chatbot for our website using NLP engine dialogflow. The site is made using drupal 7.XX version, and we want to server content of this site using chatbot via NLP. I see chatbot module designed only for drupal 8 version but we want this to be implemented in 7.xx version. I’m got only high level knowledge on Drupal and good with Dialogflow. Could you please help us on this. Any suggestion/advice are highly appreciated.

    • Hi KArthik,
      We’ve received quite few requests for porting the module to D7. The issue is Chatbot API and its drivers rely on APIs existing only in D8, i.e. Plugin API, so it will require a whole refactoring.
      That doesn’t mean porting is impossible though, and in fact we are evaluating if it’s worth investing in a D7 version.
      We are also looking for developers and agencies happy to donate and/or contribute for this to happen sooner rather than later. So please feel free to get in touch directly if you want to help in any way.
      I’ll write a blog post if porting is going to happen.

  3. Kevin McGinley says:


    great article and currently just playing about with your example. At the moment just one thing that I’m a little stumped on and its around the views integration. I have added 5 messages on the Drupal site and when I ask “Any new messages?” it brings back a message however when I ask “next message” it always brings back the same message.

    So my question is should this work out of the box or do I need to update the next_messages intent or the view intent?

    Also I assume I need create a drupal intent for the list messages – more intent?


    • Hi Kevin,
      glad you are playing with the Views integration. The support is only on its first instance, but it works quite well. I’m sure there are thousands of opportunities out there, Chatbot API just offers the simplest ones.

      The “next/more” functionality works out of the box, however if your intent “Get the next message” is different from the intent to list messages – in the linked Concierge.zip it is -, then Yes! You need to manually create the other intent.
      That’s quite simple and you can see an approach in the examples: https://github.com/gambry/chatbot-api-presentation/blob/master/drupalcamp_london/src/Plugin/Chatbot/Intent/NextMessageIntent.php

      In that piece of code I just say “Drupal if list_messages_next intent comes, forward everything to list_messages intent”. That’s it.

      In my TODOs list I have got to provide a way to link intent, like the approach above, from the UI so site builder don’t have to write code at all. Just need to find the time to do it 😀

      Thanks a lot and send through your feedbacks!

      • Kevin McGinley says:

        Thanks for getting back,

        So that’s the thing I’m using all the code you’ve provided, and imported the zip file. Everything is how you used it for your demo, and its doing the next message intent however its always the same message and the more intent doesn’t appear to trigger anything on the Drupal site.

        Perhaps I’m missing something, how does it know what the next message will be? I cant see any parameters passed between drupal and dialogflow. As I say maybe its just my understanding.


        • Hi Kevin,

          It should work in this way:
          – The “Get Messages” intent is triggered
          – The linked view is executed, pagination is correctly setup by default to 1 result per page.
          – The first result is fetched and the context used for pagination is incremented (see http://cgit.drupalcode.org/chatbot_api/tree/src/Plugin/Chatbot/Intent/ViewsIntent.php#n121)
          – Result and context(s) are sent to Dialogflow
          – The “Next/More Messages” intent is triggered
          – The linked View is executed, taking in consideration the context used for pagination (see http://cgit.drupalcode.org/chatbot_api/tree/src/Plugin/Chatbot/Intent/ViewsIntent.php#n115)
          – The next result is fetched and the context used for pagination is incremented again.
          – Result and context(s) are sent to Dialogflow

          So if something is not working you should make sure:
          1) Context is correctly sent to Dialogflow and back to Drupal.
          2) Context name is consistent (See issue https://www.drupal.org/project/chatbot_api/issues/2952148 )

          I believe all is working correctly and you are just hitting the issue linked above “#2952148 Dialogflow context names are case insensitive”, a funny think from Dialogflow. If that’s the case use the patch or the -dev version for now, until we don’t release a new version.

          Let me know!

          • Kevin McGinley says:

            Hi Gabriele,

            Again thanks for the reply and all your help thus far. I’ve applied the patch and the iterator now gets me back the second row but then it constantly does that i.e. gets me back the second row. Not having any luck with the more intent. So need to do a bit of debugging to figure out why, just a little awkward given that I’m doing it via platform.sh, dialogflow and local. If i figure anything out I’ll get back to you.

            Cheers Kevin

          • That’s weird Kevin. Yeah I believe at this point you need to debug.
            If it can be of any help I normally debug using my local dev environment, exposing the website through https://ngrok.com/ .

Sign up for the Manifesto newsletter and exclusive event invites