Background<\/h2>\n
Ovamba is a USA-based startup focused on helping Africa\u2019s small and medium enterprises (SMEs) with short-term trade and growth capital funding<\/a>. Given that the majority of their customers are currently using feature phones (not smartphones), Ovamba wanted a solution to facilitate their funding application process with new customers that would run great on a feature phone.<\/p>\n Using the Microsoft Bot Framework<\/a> (MBF), we were able to build a\u00a0bot that could tap into a multitude of channels, including Ovamba’s existing Android application, to meet their\u00a0customers on their preferred conversation platforms.<\/p>\n Bots enable you\u00a0to communicate with users through conversation; these conversations can take place through text, speech, cards, buttons, and other visuals. The advantage of building a bot is that it enables you\u00a0to reach users through their preferred method of communication with a single codebase.<\/p>\n Microsoft Bot Framework is a platform that enables you to build bots using the C# or Node.js SDKs. Essentially, when you build a bot, you are building a RESTful web service. The Bot Framework service enables you to easily connect to channels such as Facebook, Skype, Slack, etc. If you’d like to learn more about the Bot Framework, the documentation provides great information<\/a>.<\/p>\n Because the Bot Framework can be localized to\u00a0any language and connected\u00a0to channels like SMS, Facebook\u00a0Messenger, and mobile apps, Ovamba\u00a0decided that a bot would be the best avenue\u00a0to help\u00a0them to communicate with, and gather information from their customers.\u00a0The\u00a0Microsoft Bot Framework<\/a> was a good fit because it provides all these features, in particular:<\/p>\n The localization feature<\/a> enables users to communicate with the bot in multiple languages. One of Ovamba’s top feature requirements was the ability to communicate with each\u00a0customer in his or her local dialect.<\/p>\n Although we didn’t focus on SMS at this hack, SMS and Android support was a top priority for Ovamba, since most of their\u00a0customers use either Android\u00a0or simple feature phones that don’t run apps. One useful feature of the Bot Framework is\u00a0support for SMS<\/a> as a channel; no matter how complex and visual your bot is, the communication is stripped down so that it works well on SMS, too.<\/p>\n In addition to text-based communication, the Bot Framework enables a user to speak to a bot and have the bot to respond back in speech. In some cases, you may\u00a0have to provide your own speech to text<\/a>\u00a0support on the client based on the channel you’re using\u00a0(for example, Android). One way to accomplish this task is to record what the user says, translate it (on the device or in the cloud), then send the text to the bot. Alternatively, the Bot Framework has a third party NodeJS npm package,\u00a0botbuilder-calling<\/a>, that enables similar functionality.<\/p>\n To get a simple, modular, and testable architecture, we merged two bot templates:\u00a0SWELL Generator<\/a> and transmute-bot<\/a>. This combination became the building block for the hackfest. The resulting architecture<\/a>\u00a0includes scripts for automated building, packaging of our release code, testing (using mochajs, chaijs, and sinonjs), and visual code coverage.<\/p>\n The modularity came in the form of what we called “Skills”. A skill encapsulates all the code for your Once you’ve created a skill, simply register it with the bot to give the bot those capabilities and dialogs.<\/p>\n bot.ts:<\/strong><\/p>\n You can find\u00a0our botbuilder template<\/a> on GitHub.<\/p>\n Ultimately, Ovamba’s goal is to localize their applications and services into their customers’ regional African dialects. Given the current lack of translations from English to these lesser-known dialects, we focused on an initial set of 3 languages: English, French, and Arabic. The full-featured Bot Framework has support for localization built in<\/a><\/strong>:<\/p>\n By default, the localization system will search for the bot’s prompts in the .\/locale\/{lang-tag}\/index.json<\/strong> file where {lang-tag}<\/strong> is a valid IETF language tag<\/a> representing the preferred locale for which to find prompts.<\/p><\/blockquote>\n To accomplish this task, we created a locale<\/span>\u00a0\u00a0folder in the bot and defined sub-folders of\u00a0ISO language codes<\/a> (e.g.\u00a0locale\/fr<\/span>) and included our\u00a0index.json<\/span>\u00a0\u00a0file there (locale\/fr\/index.json<\/span>).<\/p>\n Now you can use the session.localizer.gettext(session.preferredLocale(), “B-CNPS”)<\/span>\u00a0\u00a0 and the Bot Framework will automatically retrieve the correct localized string for you. Note that if session.preferredLocale()<\/span>\u00a0isn’t set, the Bot Framework will default to the English locale.<\/p>\n Since we were using dependencies (botbuilder-forms<\/a>\u00a0and\u00a0adaptive cards<\/a>) that did not directly support localization, we had to add that support explicitly. For adaptive cards, we wrote a helper method that converts specific text found in the JSON schema of adaptive cards to the localized versions at run-time:<\/p>\n We added support for localization to BotBuilder-Forms by appropriately calling session.localizer.gettext(session.preferredLocale(), “sometext”)<\/span>\u00a0\u00a0where needed. These updates were submitted as a pull request<\/a> back to the open source project.<\/p>\n We ran into several interesting issues while adding localization support. The first was directly related to how the Bot Framework resolves file names for the localization choice.\u00a0This problem is described in Issue #2 – Botbuilder Framework<\/a>,\u00a0which is still open at the time of writing. In The constant botLocalePath<\/span>\u00a0in the first block must be set to the NodeJS internal variable of __dirname<\/span><\/strong>, concatenated to the path of the locale files. The __dirname<\/span><\/strong>\u00a0value is the directory of the startup script at runtime, so the concatenation generates an absolute path. In the setUp<\/span>\u00a0function, the localizerSettings<\/span>\u00a0are initialized with the path based on the botLocalePath<\/span>\u00a0.<\/p>\n The second issue is related to the first. \u00a0When you use WebPack\u00a0for bundling and optimization, the\u00a0__dirname<\/span><\/strong>\u00a0variable is optimized away unless you make an appropriate configuration setting. If the\u00a0__dirname<\/span><\/strong>\u00a0variable is optimized away, then the code above will fail. This issue applies generally to any NodeJS application using __dirname<\/span><\/strong>\u00a0\u00a0or __filename<\/span><\/strong>\u00a0\u00a0bundling with WebPack. To prevent this optimization, go to the webpack.config.js<\/span>\u00a0\u00a0file, and ensure that the node<\/span>\u00a0\u00a0property contains an object with the { __dirname: false, __filename: false }<\/span>\u00a0, which will prevent both variables from being optimized out and should appear as is in the optimized bundle.<\/p>\n A third issue faced was with the new adaptive cards features in the Bot Framework, using the JSON template. The issue was that data from input fields were not being picked up. Adaptive cards enable you to create a form with a submit action, which looks something like this:<\/p>\n Upon pressing the submit button, it will gather up the input fields and merge them with the optional data field in the submit action. It then generates an event to the client asking for data to be submitted; it’s then completely up to the client to determine how that data is processed. In the Bot Framework, the data is sent as an activity through the message endpoint. We wrote some middleware to pick this up and handle the submission of the data to Ovamba’s backend.<\/p>\n But the input field data was\u00a0not getting picked up. Turns out there is an issue using \u00a0ColumnSet<\/span>\u00a0 (like in the code snippet below), that prevents the data from those input fields from being picked up.\u00a0This issue has been raised on the project’s GitHub repo<\/a>. It was an interesting bug because our code for the adaptive card worked in the browser (for example, this form<\/a>) but in our bot, the data from input fields wasn’t getting passed through.<\/p>\n Again, the issue is related to using ColumnSet<\/span>, so we worked around the issue by\u00a0removing the columns.<\/p>\n This project with Ovamba has\u00a0given us a solid template<\/a> for future Bot Framework projects that includes\u00a0automated scripts for building, packaging,\u00a0and testing code. We’ve also built\u00a0solutions to localize adaptive cards<\/a> and botbuilder-forms<\/a>. This knowledge can be reused in similar projects that require localization and adaptive cards or turn-based prompts.<\/p>\n We plan to continue our work with Ovamba, especially building an African dialect language recognition system to enable application localization and cater to the specific dialects of their customers. This task presents many\u00a0interesting challenges. For example, during the hackfest, we learned\u00a0that some African languages we\u00a0wanted to support existed in spoken form only (no written form), which left us considering how might we localize text for these languages. We look forward to tackling these challenges and more in our future work with Ovamba.<\/p>\n","protected":false},"excerpt":{"rendered":" We built a bot with Microsoft Bot Framework (MBF) to tap into a multitude of channels, including a client’s existing Android app, and implemented localization features, to connect with potential customers on their preferred online platforms.<\/p>\n","protected":false},"author":21389,"featured_media":11983,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[13],"tags":[26,109,110,235,384],"class_list":["post-3972","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-bots","tag-adaptive-cards","tag-bot-framework-sdk","tag-bots","tag-localization","tag-webpack"],"acf":[],"blog_post_summary":" We built a bot with Microsoft Bot Framework (MBF) to tap into a multitude of channels, including a client’s existing Android app, and implemented localization features, to connect with potential customers on their preferred online platforms.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/posts\/3972","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/users\/21389"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/comments?post=3972"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/posts\/3972\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/media\/11983"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/media?parent=3972"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/categories?post=3972"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/ise\/wp-json\/wp\/v2\/tags?post=3972"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}![\"A](\"https:\/\/devblogs.microsoft.com\/cse\/wp-content\/uploads\/sites\/55\/2020\/03\/ovamba-android.png\")
Bot Framework<\/h2>\n
![\"A](\"https:\/\/devblogs.microsoft.com\/cse\/wp-content\/uploads\/sites\/55\/2020\/03\/MBF-overview.png\")
Localization<\/strong><\/h3>\n
Android & SMS Availability<\/strong><\/h3>\n
Speech<\/h3>\n
Bot Architecture<\/h2>\n
![\"A](\"https:\/\/devblogs.microsoft.com\/cse\/wp-content\/uploads\/sites\/55\/2020\/03\/ovamva-test-cov.png\" "\\"Tests\\"")
Dialogs<\/code><\/strong>, Messages<\/code><\/strong>, Intents<\/code><\/strong>,\u00a0and other capabilities. Skills enable you to break down the functionality of your bot into modular pieces.<\/p>\n![\"A](\"https:\/\/devblogs.microsoft.com\/cse\/wp-content\/uploads\/sites\/55\/2020\/03\/ovamba-bot-architecture.png\" "\\"Architecture\\"")
private registerDialogs() {\r\n \/\/ this.bot.dialog('\/', this.dialogs);\r\n RootSkill.register(this.bot, this.dialogs);\r\n StartSkill.register(this.bot, this.dialogs);\r\n MainMenuSkill.register(this.bot, this.dialogs); \/\/ Add a line like this for every dialog\r\n BasicInfoFormSkill.register(this.bot, this.dialogs);\r\n LanguageSelectionSkill.register(this.bot, this.dialogs);\r\n}\r\n\r\nprivate bindDialogsToIntents() {\r\n this.dialogs.matches('start', StartSkill.Dialogs.Start);\r\n this.dialogs.matches('mainMenu', MainMenuSkill.Dialogs.MainMenu); \/\/ Add a line like this for every intent\r\n this.dialogs.matches('basicInfoForm', BasicInfoFormSkill.Dialogs.BasicInfoForm);\r\n this.dialogs.matches('languageSelection', LanguageSelectionSkill.Dialogs.LanguageSelection);\r\n}\r\n<\/pre>\nLocalization<\/h2>\n
![\"A](\"https:\/\/devblogs.microsoft.com\/cse\/wp-content\/uploads\/sites\/55\/2020\/03\/Screen-Shot-2017-06-27-at-4.06.35-PM.png\")
{ \r\n .\r\n .\r\n .\r\n\r\n \"B-CNPS\": \"Quel est votre num\u00e9ro CNPS?\",\r\n \"B-DrivingLicense\": \"Quel est votre num\u00e9ro de permis de conduire?\",\r\n \"B-NationalId\": \"Quel est votre num\u00e9ro d'identification nationale?\",\r\n \"B-LanguagesSpoken\": \"Quelles langues connaissez-vous?\",\r\n \"B-Occupation\": \"Quel est votre occupation?\",\r\n \"B-Address\": \"Quelle est la premi\u00e8re ligne de votre adresse?\",\r\n \"B-City\": \"Dans quelle ville vis-vous?\",\r\n .\r\n .\r\n .\r\n}<\/pre>\nLocalization Issues<\/h3>\n
export function localizeAdaptiveCards(cardQuestions: any, session: Session) {\r\n for (const q of cardQuestions.body) {\r\n q.text = (q.hasOwnProperty(\"text\")) ? session.localizer.gettext(session.preferredLocale(), q.text) : null;\r\n q.speak = (q.hasOwnProperty(\"speak\")) ? session.localizer.gettext(session.preferredLocale(), q.speak) : null;\r\n q.placeholder = (q.hasOwnProperty(\"placeholder\")) ? session.localizer.gettext(session.preferredLocale(), q.placeholder) : null;\r\n }\r\n for (const a of cardQuestions.actions) {\r\n a.title = session.localizer.gettext(session.preferredLocale(), a.title);\r\n }\r\n}\r\n<\/pre>\n![\"A](\"https:\/\/devblogs.microsoft.com\/cse\/wp-content\/uploads\/sites\/55\/2020\/03\/ovamba-adaptive-cards-localized.png\" "\\"Adaptive")
Challenges<\/h2>\n
Localization<\/h3>\n
bot.ts<\/code><\/strong>\u00a0, the following code loads the localization JSON files from the proper directory.<\/p>\nconst botLocalePath = __dirname + '\/locale';\r\n<\/pre>\n
private setUp() {\r\n const url = config.luis.url.replace('##APP##', config.luis.app).replace('##KEY##', config.luis.key);\r\n this.recognizer = new builder.LuisRecognizer(url);\r\n this.dialogs = new builder.IntentDialog({ recognizers: [this.recognizer] });\r\n\r\n this.bot.set(localizerSettings, {\r\n botLocalePath: botLocalePath, \/\/config.languages.path,\r\n defaultLocale: 'en'\/\/languageChoices[languageChoice]\r\n });\r\n}\r\n<\/pre>\nWebPack<\/h3>\n
module.exports = {\r\n target: \"node\",\r\n entry: \".\/release\/server.js\",\r\n output: {\r\n path: __dirname + \"\/release\/\",\r\n filename: \"bundle.js\",\r\n library: '',\r\n libraryTarget: 'commonjs-module'\r\n },\r\n node: {\r\n __dirname: false,\r\n __filename: false\r\n }\r\n};\r\n<\/pre>\nAdaptive Cards<\/h3>\n
{\r\n \"$schema\": \"http:\/\/adaptivecards.io\/schemas\/adaptive-card.json\",\r\n \"type\": \"AdaptiveCard\",\r\n \"version\": \"1.0\",\r\n \"body\": [\r\n {\r\n \"type\": \"TextBlock\",\r\n \"text\": \"Your name\",\r\n \"wrap\": true\r\n },\r\n {\r\n \"type\": \"Input.Text\",\r\n \"id\": \"myName\",\r\n \"placeholder\": \"Last, First\"\r\n },\r\n {\r\n \"type\": \"TextBlock\",\r\n \"text\": \"Your email\",\r\n \"wrap\": true\r\n },\r\n {\r\n \"type\": \"Input.Text\",\r\n \"id\": \"myEmail\",\r\n \"placeholder\": \"youremail@example.com\",\r\n \"style\": \"email\"\r\n },\r\n ],\r\n \"actions\": [\r\n {\r\n \"type\": \"Action.Submit\",\r\n \"title\": \"Submit\"\r\n }\r\n ]\r\n}\r\n<\/pre>\nif (this.bot) {\r\n this.bot.use(\r\n this.routingMiddleware()\r\n );\r\n}\r\n\r\npublic routingMiddleware() {\r\n return {\r\n botbuilder: (session: any, next: Function) => {\r\n \/\/ value contains the data from the adaptive card form\r\n if (session.message.value) {\r\n const formData = session.message.value;\r\n\r\n request.post(\r\n 'OVAMBA_ENDPOINT_URL',\r\n {\r\n json: formData\r\n },\r\n\r\n .\r\n .\r\n .\r\n<\/pre>\n\"body\": [\r\n {\r\n \"type\": \"ColumnSet\",\r\n \"columns\": [\r\n {\r\n \"type\": \"Column\",\r\n \"size\": 1,\r\n \"items\": [\r\n {\r\n \"type\": \"Input.Text\",\r\n \"id\": \"myName\",\r\n \"placeholder\": \"Last, First\"\r\n },\r\n<\/pre>\n \"body\": [\r\n {\r\n \"type\": \"TextBlock\",\r\n \"text\": \"B-DOB\",\r\n \"speak\": \"B-DOB\",\r\n \"wrap\": true\r\n },\r\n {\r\n \"type\": \"Input.Date\",\r\n \"id\": \"basic_dateofbirth\"\r\n },\r\n<\/pre>\nConclusion<\/h2>\n
Future Work<\/h3>\n