For more information, refer to GitHub.
What Does This Plugin Do?
Botonic Plugin Contentful is one of the available plugins for Botonic. Contentful is a Content Management System (CMS)) which manages contents of a great variety of types, such as text, dates, numerics, images, ... These simple contents can be combined into custom complex contents (eg. a carousel or a message box) which can be queried over APIs.
Features* Web dashboard for defining complex contents and validation rules for their values * Web dashboard for creating, navigating and querying the custom contents * Multilanguage content values * Content values history revision * Role management * Migration and backup tools
- The contents and navigation of static menus, images and texts can be easily defined from a user-friendly UI.
- Benefiting from of a best in breed CMS solution.
- Updating the bot contents does not require redeploying the bot.
- Users will need to download a much lighter bundle to start using the bot.
Currently the Contentful plugin allows your bot to easily access these kind of contents:
- Combinations of the following Botonic UI components: Start up messages, Carousels and Texts. Their buttons can be configured to trigger other botonic components as well as opening external URLs.
- Images, which optionally can be assigned to different assets depending on the user language.
- Information about Botonic desk queues, such as its name and schedule.
For the previous content, the dashboard allows assigning a list of tags to your contents, so that your bot can query them by a given tag value.
- Schedules with configurable timing per week day, as well as exception for bank holidays or sales periods.
- Any kind of files uploaded to your Contentful account.
Create a Contentful Account
Create an account on www.contentful.com and select Create an empty space.
Go to the General Settings page and write down the space ID number.
Contentful General Settings
Create a Delivery API token and safely store its value (it grants read access to your account).
Creation of a Delivery API token
Create a Content Management token and click on Generate personal token to safely store its value (it grants write access to your account).
Creation of a Content Management token
Install the Plugin
Install the plugin in your bot's project by running :
Execute the following script to create content models required by the plugin. Replaced YOUR_ID and YOUR_TOKEN with the space id and token that you obtained in the previous section.
Define Your Contents
Go to the Contentful dashboard. Open the "Contents section" and create the contents required by your bot. Remember that they will not be available until you press the "publish" button and the button becomes green.
The content buttons may trigger different behaviours depending on the type of its target field:
- If you assign a StartUp, Text or Carousel, the button text will be automatically assigned to the Short Text field of the target content. When the button is pressed, it will send your bot a payload with value "\<MODEL_TYPE>$\<ID>". \<MODEL_TYPE> may be startUp, text or carousel, whereas \<ID> will be the ID of the target.
- If you assign a URL, the browser will open it when the button is pressed.
- In two cases you should assign a Button target. 1) When you want the button to have a text different than the target content's Short Text. 2) When you want to assign a custom Payload to trigger a bot action.
To define a content button, you have two options:
either create a new entry:
or link an existing one (which may be shared by other buttons):
In the case of Text's, you can also define Follow Up contents. This feature is used to automatically display a second message after a timeout. This can be used to ask the user to rate the bot, to display again the main carousel, ...
To internationalize your bot, first define the list of required languages at the Settings|Locales menu of you Contentful space. It's recommended to define fallback locales, in case that any content lacks the translation text for some reason. From the content edit page, click on "Change" at the translation section to enable the required languages.
You will see now that you can assign multiple values for the fields that can be internationalized (as defined at your content model).
The value of referenced contents (eg. a list of Button's) are not defined for a given locale, the plugin will deliver them as defined for the locale's fallback locale. In that case, the referenced contents will be delivered in the same locale as the referring content.
While entering data through the Contentful dashboard visual editor, the user automatically generates markdown text.
The Contentful plugin provides functions to parse and transform the markdown formatting if further customization needs to be processed by the bot.
The plugin also provides a library to convert the markdown text into WhatsApp's specific markup format, the latter only supporting bold and italic formatting at the moment.
Program Your Bot
Add the following to you bot's plugins.js file:
Rendering a Contentful Content With Botonic React
To render a Botonic StartUp, Texts and Carousels with the contents configured on the Contentful space:
- Create the following functions, which convert the result from the Contentful plugin to react components (They are not implemented within the Contentful plugin to keep the plugin fully decoupled from React)
- render it from your actions. To obtain \<YOUR TEXT CONTENT ID>, open the content at www.contentful.com and click the "Info" button on the top right corner and copy the "ENTRY ID" value.
plugin.cms.text(id) returns an object with all the fields configured at www.contentful.com. Instead of directly passing it to the renderText function, you can also process them according to your requirements (eg. you could be just interested on the text field).
- to render the content assigned to the buttons at the Contentful dashboard, you we'll need to assign these routes:
And define an action for each route:
Search by Keywords
Apart from fetching your contents by ID, you can also search them. From www.contentful.com, you can assign keywords to your contents of type StartUp, Text, Carousel, URL and Queue. Each keyword is a string of words that can be used to search your contents. To make the search more flexible, the plugin will perform the following preprocessing in both the content keywords and the search keywords:
- Conversion to lowercase.
- Removal of spaces and other separators (eg. commas)
- Stemming to remove suffixes without semantics.
- Removal of stop words (eg. "the", "and",...)
Keyword Edition in contenful.com
Be careful when editing the keywords in contenful.com. If you select "Tag" as the Appearance configuration for your keywords, remember to always press RETURN after typing a new keyword. Otherwise, it will be ignored.
Types of Search
searchByKeywords allows 3 different match types (all of them performing the previously specified preprocessing):
- ONLY_KEYWORDS_FOUND: the content must have a keyword with all the words from the search text.
- KEYWORDS_AND_OTHERS_FOUND: The keyword may be preceded and followed by other words in the search text.
- ALL_WORDS_IN_KEYWORDS_MIXED_UP: All the words in the keyword must appear on the search text, even if mixed up with other words in any order.
The plugin allows configuring weekly schedules from the Contentful dashboard.
To define exceptions to the general weekly schedule, create a Day Schedule at the Exceptions section. For these days, the corresponding weekday schedule will we ignored.
To define an empty day (such as bank holidays), just create the Day Schedule but don't specify any Hour range:
For days with exceptional schedule (such as sales days), create the Day Schedule and specify the special Hour range.