# Introduction
[](https://pypi.python.org/pypi/webex_bot) [](https://github.com/fbradyirl/webex_bot/actions)
By using this module, you can create a [Webex Teams][5] messaging bot quickly in just a couple of lines of code.
This module does not require you to set up an ngrok tunnel to receive incoming messages when behind a firewall or
inside a LAN. This package instead uses a websocket to receive messages from the Webex cloud.
## Features
* Uses the [websockets][1] module to receive incoming messages, thus avoiding the need to have a public IP or use
incoming webhooks.
* Simply add 'commands' which are just strings which instruct the bot to perform some action and reply with some result.
* Allows for single or multi-post responses. This is useful if you want to reply with a lot of data, but it won't all
fit in a single response.
* Restrict bot to certain users or domains.
* Uses the [webexteamssdk][2] package to send back replies from the bot.
## 🚀 Getting started
---
### ✨ Sample Project
You can find a sample project, using OpenAI/ChatGPT with this library here: https://github.com/fbradyirl/openai_bot
----
**Only Python 3.9 is tested at this time.**
1. Install this module from pypi:
`pip install webex_bot`
2. On the Webex Developer portal, create a new [bot token][3] and expose it as an environment variable.
```sh
export WEBEX_TEAMS_ACCESS_TOKEN=<your bots token>
```
3. Run your script:
`python example.py`
See [example.py][4] for details:
```python
import os
from webex_bot.commands.echo import EchoCommand
from webex_bot.webex_bot import WebexBot
# Create a Bot Object
bot = WebexBot(teams_bot_token=os.getenv("WEBEX_TEAMS_ACCESS_TOKEN"),
approved_rooms=['06586d8d-6aad-4201-9a69-0bf9eeb5766e'],
bot_name="My Teams Ops Bot",
include_demo_commands=True)
# Add new commands for the bot to listen out for.
bot.add_command(EchoCommand())
# Call `run` for the bot to wait for incoming messages.
bot.run()
```
where EchoCommand is defined as:
```python
import logging
from webexteamssdk.models.cards import Colors, TextBlock, FontWeight, FontSize, Column, AdaptiveCard, ColumnSet, \
Text, Image, HorizontalAlignment
from webexteamssdk.models.cards.actions import Submit
from webex_bot.formatting import quote_info
from webex_bot.models.command import Command
from webex_bot.models.response import response_from_adaptive_card
log = logging.getLogger(__name__)
class EchoCommand(Command):
def __init__(self):
super().__init__(
command_keyword="echo",
help_message="Echo Words Back to You!",
chained_commands=[EchoCallback()])
def pre_execute(self, message, attachment_actions, activity):
"""
(optional function).
Reply before running the execute function.
Useful to indicate the bot is handling it if it is a long running task.
:return: a string or Response object (or a list of either). Use Response if you want to return another card.
"""
image = Image(url="https://i.postimg.cc/2jMv5kqt/AS89975.jpg")
text1 = TextBlock("Working on it....", weight=FontWeight.BOLDER, wrap=True, size=FontSize.DEFAULT,
horizontalAlignment=HorizontalAlignment.CENTER, color=Colors.DARK)
text2 = TextBlock("I am busy working on your request. Please continue to look busy while I do your work.",
wrap=True, color=Colors.DARK)
card = AdaptiveCard(
body=[ColumnSet(columns=[Column(items=[image], width=2)]),
ColumnSet(columns=[Column(items=[text1, text2])]),
])
return response_from_adaptive_card(card)
def execute(self, message, attachment_actions, activity):
"""
If you want to respond to a submit operation on the card, you
would write code here!
You can return text string here or even another card (Response).
This sample command function simply echos back the sent message.
:param message: message with command already stripped
:param attachment_actions: attachment_actions object
:param activity: activity object
:return: a string or Response object (or a list of either). Use Response if you want to return another card.
"""
text1 = TextBlock("Echo", weight=FontWeight.BOLDER, size=FontSize.MEDIUM)
text2 = TextBlock("Type in something here and it will be echo'd back to you. How useful is that!",
wrap=True, isSubtle=True)
input_text = Text(id="message_typed", placeholder="Type something here", maxLength=30)
input_column = Column(items=[input_text], width=2)
submit = Submit(title="Submit",
data={
"callback_keyword": "echo_callback"})
card = AdaptiveCard(
body=[ColumnSet(columns=[Column(items=[text1, text2], width=2)]),
ColumnSet(columns=[input_column]),
], actions=[submit])
return response_from_adaptive_card(card)
class EchoCallback(Command):
def __init__(self):
super().__init__(
card_callback_keyword="echo_callback",
delete_previous_message=True)
def execute(self, message, attachment_actions, activity):
return quote_info(attachment_actions.inputs.get("message_typed"))
```
4. Now, just interact 1-1 with the bot. Send it a message with the text:
`echo`
and off you go!
# Help
* If you are a Cisco employee, you can join the [discussion space here][7].
* Alternatively, open an issue or PR with a question on usage.
# History
### 0.1.2 (2021-03-15)
* First release on PyPI.
### 0.1.4 (2021-03-23)
* Better retry on websocket connection failure
* Added support for approved domains
* Other cleanup
### 0.1.5 (2021-03-23)
* Retry websocket connection on socket.gaierror. ([#1][i1])
### 0.1.6 (2021-03-25)
* Send ack on websocket message received. ([#2][i2])
### 0.1.7 (2021-03-26)
* Minor cleanup.
* Log bot email on startup.
### 0.1.8 (2021-05-04)
* Fetch incoming message ID as base64.
### 0.2.0 (2021-05-07)
* Switch format entirely to use cards.
### 0.2.1 (2021-05-07)
* Import fix
### 0.2.2 (2021-05-08)
* Typo fix
### 0.2.3 (2021-05-10)
* Fix no module found error
### 0.2.5 (2021-05-10)
* Pin websockets version
### 0.2.6 (2021-05-21)
* Couple of bug fixes and support python 3.8 fully
### 0.2.7 (2021-09-27)
* Fix for #11 server rejected WebSocket connection: HTTP 404
### 0.2.8 (2022-01-06)
#### Breaking change for existing cards:
* Pass activity down to execute function so attibutes such as email can be fetched from card actions.
* Update your existing `execute` functions to include the extra `activity` parameter.
```python
def execute(self, message, attachment_actions, activity):
log.info(
f"activity={activity} ")
email = activity["actor"]['emailAddress']
return quote_info(f"person email is '{email}'")
```
### 0.2.9 (2022-03-03)
* Fixes for #14 & #16
### 0.2.10 (2022-03-03)
* Add new workflow for Github releases.
### 0.2.11 (2022-03-08)
* Add `pre_execute` function to Command. (optional function to overide). Reply before running the execute function.
Useful to indicate the bot is handling it if it is a long running task.
* See echo.py for example usage.
### 0.2.12 (2022-03-09)
* Check for duplicate card callback keywords and raise exception if one exists.
### 0.2.13 (2022-03-09)
* add support for `pre_card_load_reply` overide. Reply before sending the initial card. Useful if it takes a long time
for the card to load.
### 0.2.14 (2022-03-09)
* add support for deleting previous card in a chain.
### 0.2.15 (2022-03-09)
* Support for chained cards
### 0.2.16 (2022-03-10)
* Add support for approved rooms.
### 0.2.17 (2022-03-11)
* Add support for using [pyadaptivecards][6]
### 0.2.18 (2022-03-11)
* Remove pyadaptivecards as it is actually built into [webexteamssdk][2]
* Add options for bot name, help message etc.
### 0.2.19 (2022-03-14)
* Bug fix Thanks @muhammad-rafi
### 0.2.20 (2022-04-07)
* Fix for [#6][i6]
* Fix for [#20][i20]
* Use system SSL context when connecting websocket.
### 0.2.21 (2022-04-07)
* Fix for [#13][i13] - Update websockets lib to latest.
### 0.2.22 (2022-04-11)
* Allow for commands to only respond if you are in the approved space.
### 0.3.0 (2022-04-26)
* Add `chained_commands` as a parameter of Command. This allows multiple related cards to be added at once.
* Updated Echo to use Adaptive Card objects (instead of JSON/Dict blob)
* Added docs for some function params.
### 0.3.1 (2022-04-26)
* Fix old school dict cards
### 0.3.3 (2022-06-07)
* Update [webexteamssdk][2] to latest release.
### 0.3.4 (2022-11-01)
* Auto re-connect on websockets.exceptions.ConnectionClosedOK
### 0.4.0 (2023-April-03)
* Bot will reply in response to the original message via the thread ID. This is not always possible in the case of a
card action response due to some server side issue.
### 0.4.1 (2023-Sept-07)
* Always ensure there is a thread ID in the Activity before accessing it
[1]: https://github.com/aaugustin/websockets
[2]: https://github.com/CiscoDevNet/webexteamssdk
[3]: https://developer.webex.com/docs/bots
[4]: https://github.com/fbradyirl/webex_bot/blob/main/example.py
[5]: https://www.webex.com
[6]: https://github.com/CiscoSE/pyadaptivecards
[7]: https://eurl.io/#TeBLqZjLs
[i1]: https://github.com/fbradyirl/webex_bot/issues/1
[i2]: https://github.com/fbradyirl/webex_bot/issues/2
[i6]: https://github.com/fbradyirl/webex_bot/issues/6
[i13]: https://github.com/fbradyirl/webex_bot/issues/13
[i20]: https://github.com/fbradyirl/webex_bot/issues/20
Raw data
{
"_id": null,
"home_page": "https://github.com/fbradyirl/webex_bot",
"name": "webex-bot",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "webex_bot",
"author": "Finbarr Brady",
"author_email": "finbarr.brady@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ad/33/0dd88a5364a3e939bec14c61edeb4b4016393043cb62e5c03395c7d3964d/webex_bot-0.4.1.tar.gz",
"platform": null,
"description": "# Introduction\n\n[](https://pypi.python.org/pypi/webex_bot) [](https://github.com/fbradyirl/webex_bot/actions)\n\nBy using this module, you can create a [Webex Teams][5] messaging bot quickly in just a couple of lines of code.\n\nThis module does not require you to set up an ngrok tunnel to receive incoming messages when behind a firewall or\ninside a LAN. This package instead uses a websocket to receive messages from the Webex cloud.\n\n## Features\n\n* Uses the [websockets][1] module to receive incoming messages, thus avoiding the need to have a public IP or use\n incoming webhooks.\n* Simply add 'commands' which are just strings which instruct the bot to perform some action and reply with some result.\n* Allows for single or multi-post responses. This is useful if you want to reply with a lot of data, but it won't all\n fit in a single response.\n* Restrict bot to certain users or domains.\n* Uses the [webexteamssdk][2] package to send back replies from the bot.\n\n## \ud83d\ude80 Getting started\n\n---\n\n### \u2728 Sample Project\n\nYou can find a sample project, using OpenAI/ChatGPT with this library here: https://github.com/fbradyirl/openai_bot\n\n----\n\n**Only Python 3.9 is tested at this time.**\n\n1. Install this module from pypi:\n\n`pip install webex_bot`\n\n2. On the Webex Developer portal, create a new [bot token][3] and expose it as an environment variable.\n\n```sh\nexport WEBEX_TEAMS_ACCESS_TOKEN=<your bots token>\n```\n\n3. Run your script:\n\n`python example.py`\n\nSee [example.py][4] for details:\n\n```python\nimport os\n\nfrom webex_bot.commands.echo import EchoCommand\nfrom webex_bot.webex_bot import WebexBot\n\n# Create a Bot Object\nbot = WebexBot(teams_bot_token=os.getenv(\"WEBEX_TEAMS_ACCESS_TOKEN\"),\n approved_rooms=['06586d8d-6aad-4201-9a69-0bf9eeb5766e'],\n bot_name=\"My Teams Ops Bot\",\n include_demo_commands=True)\n\n# Add new commands for the bot to listen out for.\nbot.add_command(EchoCommand())\n\n# Call `run` for the bot to wait for incoming messages.\nbot.run()\n```\n\nwhere EchoCommand is defined as:\n\n```python\nimport logging\n\nfrom webexteamssdk.models.cards import Colors, TextBlock, FontWeight, FontSize, Column, AdaptiveCard, ColumnSet, \\\n Text, Image, HorizontalAlignment\nfrom webexteamssdk.models.cards.actions import Submit\n\nfrom webex_bot.formatting import quote_info\nfrom webex_bot.models.command import Command\nfrom webex_bot.models.response import response_from_adaptive_card\n\nlog = logging.getLogger(__name__)\n\n\nclass EchoCommand(Command):\n\n def __init__(self):\n super().__init__(\n command_keyword=\"echo\",\n help_message=\"Echo Words Back to You!\",\n chained_commands=[EchoCallback()])\n\n def pre_execute(self, message, attachment_actions, activity):\n \"\"\"\n (optional function).\n Reply before running the execute function.\n\n Useful to indicate the bot is handling it if it is a long running task.\n\n :return: a string or Response object (or a list of either). Use Response if you want to return another card.\n \"\"\"\n\n image = Image(url=\"https://i.postimg.cc/2jMv5kqt/AS89975.jpg\")\n text1 = TextBlock(\"Working on it....\", weight=FontWeight.BOLDER, wrap=True, size=FontSize.DEFAULT,\n horizontalAlignment=HorizontalAlignment.CENTER, color=Colors.DARK)\n text2 = TextBlock(\"I am busy working on your request. Please continue to look busy while I do your work.\",\n wrap=True, color=Colors.DARK)\n card = AdaptiveCard(\n body=[ColumnSet(columns=[Column(items=[image], width=2)]),\n ColumnSet(columns=[Column(items=[text1, text2])]),\n ])\n\n return response_from_adaptive_card(card)\n\n def execute(self, message, attachment_actions, activity):\n \"\"\"\n If you want to respond to a submit operation on the card, you\n would write code here!\n\n You can return text string here or even another card (Response).\n\n This sample command function simply echos back the sent message.\n\n :param message: message with command already stripped\n :param attachment_actions: attachment_actions object\n :param activity: activity object\n\n :return: a string or Response object (or a list of either). Use Response if you want to return another card.\n \"\"\"\n\n text1 = TextBlock(\"Echo\", weight=FontWeight.BOLDER, size=FontSize.MEDIUM)\n text2 = TextBlock(\"Type in something here and it will be echo'd back to you. How useful is that!\",\n wrap=True, isSubtle=True)\n input_text = Text(id=\"message_typed\", placeholder=\"Type something here\", maxLength=30)\n input_column = Column(items=[input_text], width=2)\n\n submit = Submit(title=\"Submit\",\n data={\n \"callback_keyword\": \"echo_callback\"})\n\n card = AdaptiveCard(\n body=[ColumnSet(columns=[Column(items=[text1, text2], width=2)]),\n ColumnSet(columns=[input_column]),\n ], actions=[submit])\n\n return response_from_adaptive_card(card)\n\n\nclass EchoCallback(Command):\n\n def __init__(self):\n super().__init__(\n card_callback_keyword=\"echo_callback\",\n delete_previous_message=True)\n\n def execute(self, message, attachment_actions, activity):\n return quote_info(attachment_actions.inputs.get(\"message_typed\"))\n```\n\n4. Now, just interact 1-1 with the bot. Send it a message with the text:\n\n`echo`\n\nand off you go!\n\n# Help\n\n* If you are a Cisco employee, you can join the [discussion space here][7].\n* Alternatively, open an issue or PR with a question on usage.\n\n# History\n\n### 0.1.2 (2021-03-15)\n\n* First release on PyPI.\n\n### 0.1.4 (2021-03-23)\n\n* Better retry on websocket connection failure\n* Added support for approved domains\n* Other cleanup\n\n### 0.1.5 (2021-03-23)\n\n* Retry websocket connection on socket.gaierror. ([#1][i1])\n\n### 0.1.6 (2021-03-25)\n\n* Send ack on websocket message received. ([#2][i2])\n\n### 0.1.7 (2021-03-26)\n\n* Minor cleanup.\n* Log bot email on startup.\n\n### 0.1.8 (2021-05-04)\n\n* Fetch incoming message ID as base64.\n\n### 0.2.0 (2021-05-07)\n\n* Switch format entirely to use cards.\n\n### 0.2.1 (2021-05-07)\n\n* Import fix\n\n### 0.2.2 (2021-05-08)\n\n* Typo fix\n\n### 0.2.3 (2021-05-10)\n\n* Fix no module found error\n\n### 0.2.5 (2021-05-10)\n\n* Pin websockets version\n\n### 0.2.6 (2021-05-21)\n\n* Couple of bug fixes and support python 3.8 fully\n\n### 0.2.7 (2021-09-27)\n\n* Fix for #11 server rejected WebSocket connection: HTTP 404\n\n### 0.2.8 (2022-01-06)\n\n#### Breaking change for existing cards:\n\n* Pass activity down to execute function so attibutes such as email can be fetched from card actions.\n* Update your existing `execute` functions to include the extra `activity` parameter.\n\n```python\n def execute(self, message, attachment_actions, activity):\n log.info(\n f\"activity={activity} \")\n email = activity[\"actor\"]['emailAddress']\n return quote_info(f\"person email is '{email}'\")\n```\n\n### 0.2.9 (2022-03-03)\n\n* Fixes for #14 & #16\n\n### 0.2.10 (2022-03-03)\n\n* Add new workflow for Github releases.\n\n### 0.2.11 (2022-03-08)\n\n* Add `pre_execute` function to Command. (optional function to overide). Reply before running the execute function.\n Useful to indicate the bot is handling it if it is a long running task.\n* See echo.py for example usage.\n\n### 0.2.12 (2022-03-09)\n\n* Check for duplicate card callback keywords and raise exception if one exists.\n\n### 0.2.13 (2022-03-09)\n\n* add support for `pre_card_load_reply` overide. Reply before sending the initial card. Useful if it takes a long time\n for the card to load.\n\n### 0.2.14 (2022-03-09)\n\n* add support for deleting previous card in a chain.\n\n### 0.2.15 (2022-03-09)\n\n* Support for chained cards\n\n### 0.2.16 (2022-03-10)\n\n* Add support for approved rooms.\n\n### 0.2.17 (2022-03-11)\n\n* Add support for using [pyadaptivecards][6]\n\n### 0.2.18 (2022-03-11)\n\n* Remove pyadaptivecards as it is actually built into [webexteamssdk][2]\n* Add options for bot name, help message etc.\n\n### 0.2.19 (2022-03-14)\n\n* Bug fix Thanks @muhammad-rafi\n\n### 0.2.20 (2022-04-07)\n\n* Fix for [#6][i6]\n* Fix for [#20][i20]\n* Use system SSL context when connecting websocket.\n\n### 0.2.21 (2022-04-07)\n\n* Fix for [#13][i13] - Update websockets lib to latest.\n\n### 0.2.22 (2022-04-11)\n\n* Allow for commands to only respond if you are in the approved space.\n\n### 0.3.0 (2022-04-26)\n\n* Add `chained_commands` as a parameter of Command. This allows multiple related cards to be added at once.\n* Updated Echo to use Adaptive Card objects (instead of JSON/Dict blob)\n* Added docs for some function params.\n\n### 0.3.1 (2022-04-26)\n\n* Fix old school dict cards\n\n### 0.3.3 (2022-06-07)\n\n* Update [webexteamssdk][2] to latest release.\n\n### 0.3.4 (2022-11-01)\n\n* Auto re-connect on websockets.exceptions.ConnectionClosedOK\n\n### 0.4.0 (2023-April-03)\n\n* Bot will reply in response to the original message via the thread ID. This is not always possible in the case of a\n card action response due to some server side issue.\n\n### 0.4.1 (2023-Sept-07)\n\n* Always ensure there is a thread ID in the Activity before accessing it\n\n[1]: https://github.com/aaugustin/websockets\n\n[2]: https://github.com/CiscoDevNet/webexteamssdk\n\n[3]: https://developer.webex.com/docs/bots\n\n[4]: https://github.com/fbradyirl/webex_bot/blob/main/example.py\n\n[5]: https://www.webex.com\n\n[6]: https://github.com/CiscoSE/pyadaptivecards\n\n[7]: https://eurl.io/#TeBLqZjLs\n\n[i1]: https://github.com/fbradyirl/webex_bot/issues/1\n\n[i2]: https://github.com/fbradyirl/webex_bot/issues/2\n\n[i6]: https://github.com/fbradyirl/webex_bot/issues/6\n\n[i13]: https://github.com/fbradyirl/webex_bot/issues/13\n\n[i20]: https://github.com/fbradyirl/webex_bot/issues/20\n\n\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "Python package for a Webex Bot based on websockets.",
"version": "0.4.1",
"project_urls": {
"Homepage": "https://github.com/fbradyirl/webex_bot"
},
"split_keywords": [
"webex_bot"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5312cd4cb8c65a80440eab6d2649118ab4f6cb73cb72a71bac61816daed08b3e",
"md5": "5c1c88fbd6b31e35ddbc70bd7c09f448",
"sha256": "b538254cc6df03ff999a6cadcac4a0f5be53d76373d0f41375e3c716be47aa54"
},
"downloads": -1,
"filename": "webex_bot-0.4.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "5c1c88fbd6b31e35ddbc70bd7c09f448",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 19493,
"upload_time": "2023-09-07T15:01:57",
"upload_time_iso_8601": "2023-09-07T15:01:57.295967Z",
"url": "https://files.pythonhosted.org/packages/53/12/cd4cb8c65a80440eab6d2649118ab4f6cb73cb72a71bac61816daed08b3e/webex_bot-0.4.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ad330dd88a5364a3e939bec14c61edeb4b4016393043cb62e5c03395c7d3964d",
"md5": "27cb08380c9a904fe9f24469128d2dcb",
"sha256": "cbd8d2135b5f32eef342c7f90c447387426603a3718032d4a457c02c28a9a906"
},
"downloads": -1,
"filename": "webex_bot-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "27cb08380c9a904fe9f24469128d2dcb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 25634,
"upload_time": "2023-09-07T15:01:58",
"upload_time_iso_8601": "2023-09-07T15:01:58.957814Z",
"url": "https://files.pythonhosted.org/packages/ad/33/0dd88a5364a3e939bec14c61edeb4b4016393043cb62e5c03395c7d3964d/webex_bot-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-07 15:01:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fbradyirl",
"github_project": "webex_bot",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "webex-bot"
}
JSON
