Added 16.proactive-messages

samples/16.proactive-messages/README.md

@@ -0,0 +1,66 @@
+# Proactive messages
+
+Bot Framework v4 proactive messages bot sample
+
+This bot has been created using [Bot Framework](https://dev.botframework.com), it shows how to send proactive messages to users by capturing a conversation reference, then using it later to initialize outbound messages.
+
+## Concepts introduced in this sample
+
+Typically, each message that a bot sends to the user directly relates to the user's prior input. In some cases, a bot may need to send the user a message that is not directly related to the current topic of conversation. These types of messages are called proactive messages.
+
+Proactive messages can be useful in a variety of scenarios. If a bot sets a timer or reminder, it will need to notify the user when the time arrives. Or, if a bot receives a notification from an external system, it may need to communicate that information to the user immediately. For example, if the user has previously asked the bot to monitor the price of a product, the bot can alert the user if the price of the product has dropped by 20%. Or, if a bot requires some time to compile a response to the user's question, it may inform the user of the delay and allow the conversation to continue in the meantime. When the bot finishes compiling the response to the question, it will share that information with the user.
+
+This project has a notify endpoint that will trigger the proactive messages to be sent to
+all users who have previously messaged the bot.
+
+## Running the sample
+- Clone the repository
+```bash
+git clone https://github.com/Microsoft/botbuilder-python.git
+```
+- Activate your desired virtual environment
+- Bring up a terminal, navigate to `botbuilder-python\samples\16.proactive-messages` folder
+- In the terminal, type `pip install -r requirements.txt`
+- In the terminal, type `python app.py`
+
+## Testing the bot using Bot Framework Emulator
+[Microsoft Bot Framework Emulator](https://github.com/microsoft/botframework-emulator) is a desktop application that allows bot developers to test and debug their bots on localhost or running remotely through a tunnel.
+
+- Install the Bot Framework emulator from [here](https://github.com/Microsoft/BotFramework-Emulator/releases)
+
+### Connect to bot using Bot Framework Emulator
+- Launch Bot Framework Emulator
+- File -> Open Bot
+- Paste this URL in the emulator window - http://localhost:3978/api/messages
+
+With the Bot Framework Emulator connected to your running bot, the sample will now respond to an HTTP GET that will trigger a proactive message.  The proactive message can be triggered from the command line using `curl` or similar tooling, or can be triggered by opening a browser windows and nagivating to `http://localhost:3978/api/notify`.
+
+### Using curl
+
+- Send a get request to `http://localhost:3978/api/notify` to proactively message users from the bot.
+
+   ```bash
+    curl get http://localhost:3978/api/notify
+   ```
+
+- Using the Bot Framework Emulator, notice a message was proactively sent to the user from the bot.
+
+### Using the Browser
+
+- Launch a web browser
+- Navigate to `http://localhost:3978/api/notify`
+- Using the Bot Framework Emulator, notice a message was proactively sent to the user from the bot.
+
+## Proactive Messages
+
+In addition to responding to incoming messages, bots are frequently called on to send "proactive" messages based on activity, scheduled tasks, or external events.
+
+In order to send a proactive message using Bot Framework, the bot must first capture a conversation reference from an incoming message using `TurnContext.get_conversation_reference()`. This reference can be stored for later use.
+
+To send proactive messages, acquire a conversation reference, then use `adapter.continue_conversation()` to create a TurnContext object that will allow the bot to deliver the new outgoing message.
+
+## Further reading
+
+- [Bot Framework Documentation](https://docs.botframework.com)
+- [Bot Basics](https://docs.microsoft.com/azure/bot-service/bot-builder-basics?view=azure-bot-service-4.0)
+- [Send proactive messages](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-howto-proactive-message?view=azure-bot-service-4.0&tabs=js)

samples/16.proactive-messages/app.py

@@ -0,0 +1,119 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+import asyncio
+import sys
+import uuid
+from datetime import datetime
+from types import MethodType
+from typing import Dict
+
+from flask import Flask, request, Response
+from botbuilder.core import BotFrameworkAdapterSettings, TurnContext, BotFrameworkAdapter
+from botbuilder.schema import Activity, ActivityTypes, ConversationReference
+
+from bots import ProactiveBot
+
+# Create the loop and Flask app
+LOOP = asyncio.get_event_loop()
+APP = Flask(__name__, instance_relative_config=True)
+APP.config.from_object("config.DefaultConfig")
+
+# Create adapter.
+# See https://aka.ms/about-bot-adapter to learn more about how bots work.
+SETTINGS = BotFrameworkAdapterSettings(APP.config["APP_ID"], APP.config["APP_PASSWORD"])
+ADAPTER = BotFrameworkAdapter(SETTINGS)
+
+
+# Catch-all for errors.
+async def on_error(self, context: TurnContext, error: Exception):
+    # This check writes out errors to console log .vs. app insights.
+    # NOTE: In production environment, you should consider logging this to Azure
+    #       application insights.
+    print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr)
+
+    # Send a message to the user
+    await context.send_activity("The bot encountered an error or bug.")
+    await context.send_activity("To continue to run this bot, please fix the bot source code.")
+    # Send a trace activity if we're talking to the Bot Framework Emulator
+    if context.activity.channel_id == 'emulator':
+        # Create a trace activity that contains the error object
+        trace_activity = Activity(
+            label="TurnError",
+            name="on_turn_error Trace",
+            timestamp=datetime.utcnow(),
+            type=ActivityTypes.trace,
+            value=f"{error}",
+            value_type="https://www.botframework.com/schemas/error"
+        )
+        # Send a trace activity, which will be displayed in Bot Framework Emulator
+        await context.send_activity(trace_activity)
+
+ADAPTER.on_turn_error = MethodType(on_error, ADAPTER)
+
+# Create a shared dictionary.  The Bot will add conversation references when users
+# join the conversation and send messages.
+CONVERSATION_REFERENCES: Dict[str, ConversationReference] = dict()
+
+# If the channel is the Emulator, and authentication is not in use, the AppId will be null.
+# We generate a random AppId for this case only. This is not required for production, since
+# the AppId will have a value.
+APP_ID = SETTINGS.app_id if SETTINGS.app_id else uuid.uuid4()
+
+# Create the Bot
+BOT = ProactiveBot(CONVERSATION_REFERENCES)
+
+# Listen for incoming requests on /api/messages.
+@APP.route("/api/messages", methods=["POST"])
+def messages():
+    # Main bot message handler.
+    if "application/json" in request.headers["Content-Type"]:
+        body = request.json
+    else:
+        return Response(status=415)
+
+    activity = Activity().deserialize(body)
+    auth_header = (
+        request.headers["Authorization"] if "Authorization" in request.headers else ""
+    )
+
+    try:
+        task = LOOP.create_task(
+            ADAPTER.process_activity(activity, auth_header, BOT.on_turn)
+        )
+        LOOP.run_until_complete(task)
+        return Response(status=201)
+    except Exception as exception:
+        raise exception
+
+
+# Listen for requests on /api/notify, and send a messages to all conversation members.
+@APP.route("/api/notify")
+def notify():
+    try:
+        task = LOOP.create_task(
+            _send_proactive_message()
+        )
+        LOOP.run_until_complete(task)
+
+        return Response(status=201, response="Proactive messages have been sent")
+    except Exception as exception:
+        raise exception
+
+
+# Send a message to all conversation members.
+# This uses the shared Dictionary that the Bot adds conversation references to.
+async def _send_proactive_message():
+    for conversation_reference in CONVERSATION_REFERENCES.values():
+        return await ADAPTER.continue_conversation(
+            APP_ID,
+            conversation_reference,
+            lambda turn_context: turn_context.send_activity("proactive hello")
+        )
+
+
+if __name__ == "__main__":
+    try:
+        APP.run(debug=False, port=APP.config["PORT"])  # nosec debug
+    except Exception as exception:
+        raise exception

samples/16.proactive-messages/bots/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .proactive_bot import ProactiveBot
+
+__all__ = ["ProactiveBot"]

samples/16.proactive-messages/bots/proactive_bot.py

@@ -0,0 +1,41 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from typing import Dict
+
+from botbuilder.core import ActivityHandler, TurnContext
+from botbuilder.schema import ChannelAccount, ConversationReference, Activity
+
+
+class ProactiveBot(ActivityHandler):
+    def __init__(
+            self, conversation_references: Dict[str, ConversationReference]
+    ):
+        self.conversation_references = conversation_references
+
+    async def on_conversation_update_activity(self, turn_context: TurnContext):
+        self._add_conversation_reference(turn_context.activity)
+        return await super().on_conversation_update_activity(turn_context)
+
+    async def on_members_added_activity(
+        self, members_added: [ChannelAccount], turn_context: TurnContext
+    ):
+        for member in members_added:
+            if member.id != turn_context.activity.recipient.id:
+                await turn_context.send_activity("Welcome to the Proactive Bot sample.  Navigate to "
+                                                 "http://localhost:3978/api/notify to proactively message everyone "
+                                                 "who has previously messaged this bot.")
+
+    async def on_message_activity(self, turn_context: TurnContext):
+        self._add_conversation_reference(turn_context.activity)
+        return await turn_context.send_activity(f"You sent: {turn_context.activity.text}")
+
+    def _add_conversation_reference(self, activity: Activity):
+        """
+        This populates the shared Dictionary that holds conversation references. In this sample,
+        this dictionary is used to send a message to members when /api/notify is hit.
+        :param activity:
+        :return:
+        """
+        conversation_reference = TurnContext.get_conversation_reference(activity)
+        self.conversation_references[conversation_reference.user.id] = conversation_reference

samples/16.proactive-messages/config.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+import os
+
+""" Bot Configuration """
+
+
+class DefaultConfig:
+    """ Bot Configuration """
+
+    PORT = 3978
+    APP_ID = os.environ.get("MicrosoftAppId", "")
+    APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")

samples/16.proactive-messages/requirements.txt

@@ -0,0 +1,2 @@
+botbuilder-core>=4.4.0b1
+flask>=1.0.3