From d2860d4df21f1a7fba02147e269b7e3d66b0b0a5 Mon Sep 17 00:00:00 2001 From: Michael Szul Date: Thu, 24 Aug 2017 15:52:05 -0400 Subject: [PATCH 1/2] Update bot-builder-nodejs-send-suggested-actions.md --- articles/nodejs/bot-builder-nodejs-send-suggested-actions.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/articles/nodejs/bot-builder-nodejs-send-suggested-actions.md b/articles/nodejs/bot-builder-nodejs-send-suggested-actions.md index 7fd44fc26..dbf2e6016 100644 --- a/articles/nodejs/bot-builder-nodejs-send-suggested-actions.md +++ b/articles/nodejs/bot-builder-nodejs-send-suggested-actions.md @@ -30,6 +30,8 @@ This code example shows how to send a message that presents three suggested acti When the user taps one of the suggested actions, the bot will receive a message from the user that contains the `value` of the corresponding action. +Be aware that the `imBack` method will post the `value` to the chat window of the channel you are using. If this is not the desired effect, you can use the `postBack` method, which will still post the selection back to your bot, but will not display the selection in the chat window. Some channels do not support `postBack`, however, and in those instances the method will behave like `imBack`. + ## Additional resources * [Preview features with the Channel Inspector][inspector] @@ -45,4 +47,4 @@ When the user taps one of the suggested actions, the bot will receive a message [inspector]: ../portal-channel-inspector.md -[channelInspector]: https://docs.botframework.com/en-us/channel-inspector/channels/Skype/ \ No newline at end of file +[channelInspector]: https://docs.botframework.com/en-us/channel-inspector/channels/Skype/ From 7b40c547abb2fb74ad23623fae35c02ebd623044 Mon Sep 17 00:00:00 2001 From: Michael Szul Date: Wed, 30 Aug 2017 11:32:50 -0400 Subject: [PATCH 2/2] Added ConsoleConnector language and example --- articles/includes/code/node-getstarted.js | 13 +++++- .../nodejs/bot-builder-nodejs-concepts.md | 3 ++ .../nodejs/bot-builder-nodejs-quickstart.md | 43 ++++++++++++++++--- 3 files changed, 53 insertions(+), 6 deletions(-) diff --git a/articles/includes/code/node-getstarted.js b/articles/includes/code/node-getstarted.js index f54b2e383..db98fbd40 100644 --- a/articles/includes/code/node-getstarted.js +++ b/articles/includes/code/node-getstarted.js @@ -1,4 +1,15 @@ +// + +var builder = require('botbuilder'); + +var connector = new builder.ConsoleConnector().listen(); +var bot = new builder.UniversalBot(connector, function (session) { + session.send("You said: %s", session.message.text); +}); +// + // + var restify = require('restify'); var builder = require('botbuilder'); @@ -21,4 +32,4 @@ server.post('/api/messages', connector.listen()); var bot = new builder.UniversalBot(connector, function (session) { session.send("You said: %s", session.message.text); }); -// \ No newline at end of file +// diff --git a/articles/nodejs/bot-builder-nodejs-concepts.md b/articles/nodejs/bot-builder-nodejs-concepts.md index 65805f43f..29be3cd2a 100644 --- a/articles/nodejs/bot-builder-nodejs-concepts.md +++ b/articles/nodejs/bot-builder-nodejs-concepts.md @@ -27,6 +27,8 @@ For an example that demonstrates using these classes, see [Create a bot with the The Connector also normalizes the messages that the bot sends to channels so that you can develop your bot in a platform-agnostic way. Normalizing a message involves converting it from the Bot Framework’s schema into the channel’s schema. In cases where the channel does not support all aspects of the framework’s schema, the Connector will try to convert the message to a format that the channel supports. For example, if the bot sends a message that contains a card with action buttons to the SMS channel, the Connector may render the card as an image and include the actions as links in the message’s text. The [Channel Inspector][ChannelInspector] is a web tool that shows you how the Connector renders messages on various channels. +The `ChatConnector` requires an API endpoint to be setup within your bot. With the Node.js SDK, this is usually accomplished by installing the `restify` Node.js module. Bots can also be created for the console using the [ConsoleConnector][ConsoleConnector], which does not require an API endpoint. + ## Messages Messages can consist of text to be displayed, text to be spoken, attachments, rich cards, and suggested actions. You use the [session.send][SessionSend] method to send messages in response to a message from the user. Your bot may call `send` as many times as it likes in response to a message from the user. For an example that demonstrates this, see [Respond to user messages][RespondMessages]. @@ -75,6 +77,7 @@ Bot Builder lets you use LUIS to add natural language understanding to your bot [PersistConversationData]: https://docs.botframework.com/en-us/node/builder/chat-reference/interfaces/_botbuilder_d_.iuniversalbotsettings.html#persistconversationdata [UniversalBot]: https://docs.botframework.com/en-us/node/builder/chat-reference/classes/_botbuilder_d_.universalbot.html [ChatConnector]: https://docs.botframework.com/en-us/node/builder/chat-reference/classes/_botbuilder_d_.chatconnector.html +[ConsoleConnector]: https://docs.botframework.com/en-us/node/builder/chat-reference/classes/_botbuilder_d_.consoleconnector.html [ChannelInspector]: https://docs.botframework.com/en-us/channel-inspector/channels/Skype diff --git a/articles/nodejs/bot-builder-nodejs-quickstart.md b/articles/nodejs/bot-builder-nodejs-quickstart.md index f0b231c18..073e90eb5 100644 --- a/articles/nodejs/bot-builder-nodejs-quickstart.md +++ b/articles/nodejs/bot-builder-nodejs-quickstart.md @@ -35,26 +35,59 @@ npm init Follow the prompt on the screen to enter information about your bot and npm will create a **package.json** file that contains the information you provided. ## Install the SDK -Next, install the Bot Builder SDK for Node.js and restify by running the following **npm** commands: +Next, install the Bot Builder SDK for Node.js by running the following **npm** command: ```nodejs npm install --save botbuilder -npm install --save restify ``` -Once you have the SDK and Restify in place, you're ready to write your bot. - -## Create your bot +Once you have the SDK installed, you are ready to write your first bot. For your first bot, you will create a bot that simply echoes back any user input. To create your bot, follow these steps: 1. In the folder that you created earlier for your bot, create a new file named **app.js**. 2. Open **app.js** in a text editor or an IDE of your choice. Add the following code to the file: + [!code-javascript[consolebot code sample Node.js](../includes/code/node-getstarted.js#consolebot)] + +3. Save the file. Now you are ready to run and test out your bot. + +### Start your bot + +Navigate to your bot's directory in a console window and start your bot: + +```nodejs +node app.js +``` + +Your bot is now running locally. Try out your bot by typing a few messages in the console window. +You should see that the bot responds to each message you send by echoing back your message prefixed with the text *"You said:"*. + +## Install Restify + +Console bots are good text-based clients, but in order to use any of the Bot Framework channels (or run your bot in the emulator), your bot will need to run on an API endpoint. Install restify by running the following **npm** command: + +```nodejs +npm install --save restify +``` + +Once you have Restify in place, you're ready to make some changes to your bot. + +## Edit your bot + +You will need to make some changes to your **app.js** file. + +1. Add a line to require the `restify` module. +2. Change the `ConsoleConnector` to a `ChatConnector`. +3. Include your Microsoft App ID and App Password. +4. Have the connector listen on an API endpoint. + [!code-javascript[echobot code sample Node.js](../includes/code/node-getstarted.js#echobot)] 3. Save the file. Now you are ready to run and test out your bot. +Please note that you do not need a Microsoft App ID or App Password to run your bot in the Bot Framework Emulator. + ## Test your bot Next, test your bot by using the [Bot Framework Emulator](../debug-bots-emulator.md) to see it in action. The emulator is a desktop application that lets you test and debug your bot on localhost or running remotely through a tunnel.