RingCentral Chatbot Framework for Python
Project description
ringcentral-chatbot-python
RingCentral Chatbot Framework for Python. With this framework, creating a RingCentral Glip chatbot would be seriously simple, developer could focus on writing bot logic.
To quick start, just jump to Use CLI tool to create an bot app.
Table of contents
- Features
- Use CLI tool to create an bot app
- Example bot apps
- Prerequisites
- Development & quick start
- Test bot
- Building and Deploying to AWS Lambda
- Use Extensions
- Write a extension your self
- Unit Test
- Todos
- Credits
- License
Features
- Token management
- Token/subscribe auto renew
- Built-in suport for filedb(local development/POC) and AWS dynamodb
- Stateless, built-in suport for AWS lambda
- Define custom bot behavior by
config.py
- Support fully customized db module, loaded when runtime check
DB_TYPE
in.env
- Custom every step of bot lifecycle throught
config.py
, including bot auth, bot webhook
Use CLI tool to create an bot app
- Using ringcentral-chatbot-factory-py to init a rinncentral chatbot app would be fast!
pip3 install ringcentral_chatbot_factory
rcf my-ringcentral-chat-bot
Then just fill the promots, follow my-ringcentral-chat-bot/README.md
's guide, it is done.
Example bot apps
- date-time-chatbot: simple Glip chatbot that can tell time/date.
- assistant-bot: simple assistant Glip bot to show user/company information, this bot will show you how to access user data.
- survey-bot: example survey bot, this bot will show you how to create/use custom database wrapper.
- translate-bot: translate bot for glip.
Prerequisites
- Python3.6+ and Pip3
- Create the bot App: Login to developer.ringcentral.com and create an
Server/Bot
app with permissions:ReadAccounts, Edit Extensions, WebhookSubscriptions, Glip
(or more as you may need).
Development & quick start
git clone git@github.com:zxdong262/ringcentral-chatbot-python.git
cd ringcentral-chatbot-python
# use virtualenv
pip3 install virtualenv # might need sudo
# init virtual env
virtualenv venv --python=python3
# use env
source ./venv/bin/activate
# install deps
pip install python-dotenv ringcentral pydash boto3 flask pylint
# run ngrok proxy
# since bot need https server,
# so we need a https proxy for ringcentral to visit our local server
./bin/proxy
# will show:
# Forwarding https://xxxxx.ngrok.io -> localhost:8989
# create env file
cp .sample.env .env
# then edit .env, set proper setting,
# and goto your ringcentral app setting page, set OAuth Redirect URI to https://https://xxxxx.ngrok.io/bot-oauth
RINGCENTRAL_BOT_SERVER=https://xxxxx.ngrok.io
## for bots auth required, get then from your ringcentral app page
RINGCENTRAL_BOT_CLIENT_ID=
RINGCENTRAL_BOT_CLIENT_SECRET=
# create custom bot config file, edit custom functions to define bot behavior
cp config.sample.py config.py
# run local dev server
./bin/start
Test bot
- Goto your ringcentral app's bot section, click 'Add to glip'
- Login to https://glip-app.devtest.ringcentral.com, find the bot by searching its name. Talk to the bot.
- Edit config.py to change bot bahavior and test in https://glip-app.devtest.ringcentral.com
Building and Deploying to AWS Lambda
AWS Lambda with API Gateway and DynamoDB would give us a flexible way to deploy the bot.
This requires Nodejs 8.10+/npm, recommend using nvm to install nodejs/npm.
*Be aware that AWS Lambda ONLY works in linux on an x64 architecture. For non-linux os, we need docker to build dependencies, should install docker first.
Get an AWS account, create aws_access_key_id
and aws_secret_access_key
and place them in ~/.aws/credentials
, like this:
[default]
aws_access_key_id = <your aws_access_key_id>
aws_secret_access_key = <your aws_secret_access_key>
For more information, refer to https://docs.aws.amazon.com/general/latest/gr/aws-security-credentials.html
# install serverless
npm i
# create serverless.yml
cp dev/lambda/serverless.sample.yml dev/lambda/serverless.yml
Edit dev/lambda/serverless.yml
, and make sure you set the proper name and required env.
# you can define service wide environment variables here
environment:
ENV: production
# ringcentral apps
## for bots auth, required
RINGCENTRAL_BOT_CLIENT_ID:
RINGCENTRAL_BOT_CLIENT_SECRET:
## for user auth, could be empty if do not need user auth
RINGCENTRAL_USER_CLIENT_ID:
RINGCENTRAL_USER_CLIENT_SECRET:
## common
RINGCENTRAL_SERVER: https://platform.devtest.ringcentral.com
RINGCENTRAL_BOT_SERVER: https://xxxxx.execute-api.us-east-1.amazonaws.com/dev
# db
DB_TYPE: dynamodb
DYNAMODB_TABLE_PREFIX: ringcentral-bot
DYNAMODB_REGION: us-east-1
DYNAMODB_ReadCapacityUnits: 1
DYNAMODB_WriteCapacityUnits: 1
Deploy to AWS Lambda with bin/deploy
# Run this cmd to deploy to AWS Lambda
bin/deploy
After successful deploy, you will get the https api url:
Service Information
service: ringcentral-bot
stage: dev
region: us-east-1
stack: ringcentral-bot-dev
api keys:
None
endpoints:
ANY - https://dddddd.execute-api.us-east-1.amazonaws.com/dev/{action+}
GET - https://dddddd.execute-api.us-east-1.amazonaws.com/dev/
Relpace RINGCENTRAL_BOT_SERVER: https://xxxxx.execute-api.us-east-1.amazonaws.com/dev
in serverless.yml with
RINGCENTRAL_BOT_SERVER: https://dddddd.execute-api.us-east-1.amazonaws.com/dev
and run bin/deploy
to deploy again.
Watch Lambda server log by run:
bin/watch
Do not forget to set your RingCentral app's redirect URL to Lambda's API Gateway URL, https://dddddd.execute-api.us-east-1.amazonaws.com/dev/bot-oauth
for bot app.
Use Extensions
RingCentral Chatbot Framework for Python Extensions will extend bot command support with simple setting in .env
.
Just set like this in .env
, support multiple extensions seperated by ,
EXTENSIONS=ringcentral_bot_framework_extension_botinfo,ringcentral_bot_framework_extension_world_time
And install these exetnsions by pip install ringcentral_bot_framework_extension_botinfo ringcentral_bot_framework_extension_world_time
, it is done.
You can search for more extension in pypi.org with keyword ringcentral_bot_framework_extension
.
Write a extension your self
Write one extension will be simple, just check out botinfo extension as an example, you just need to write one function there.
# botinfo extension's source code
# https://github.com/zxdong262/ringcentral-chatbot-python-ext-bot-info/blob/master/ringcentral_bot_framework_extension_botinfo/__init__.py
import json
name = 'ringcentral_bot_framework_extension_botinfo'
def botGotPostAddAction(
bot,
groupId,
creatorId,
user,
text,
dbAction
):
"""
bot got group chat message: text
bot extension could send some response
return True when bot send message, otherwise return False
"""
if not f'![:Person]({bot.id})' in text:
return False
if 'bot info' in text:
botInfo = bot.platform.get('/account/~/extension/~')
txt = json.loads(botInfo.text())
txt = json.dumps(txt, indent=2)
msg = f'![:Person]({creatorId}) bot info json is:\n' + txt
bot.sendMessage(
groupId,
{
'text': msg
}
)
return True
else:
return False
Unit Test
bin/test
Todos
Visit https://github.com/zxdong262/ringcentral-chatbot-python/issues
Credits
The core bot framework logic is implanted from ringcentral-ai-bot written by @tylerlong
License
MIT
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ringcentral_bot_framework-0.0.27.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | fbce3925435f09eaa3489fe9ae1cc343e0ac260e4698e15676d38c34fa7376c9 |
|
MD5 | dc137491e48b1172990a5a0bb8d680aa |
|
BLAKE2b-256 | 11094318164e73341b650058ff5be6f7eca4a655024b28e6848f1174ce3a3541 |
Hashes for ringcentral_bot_framework-0.0.27-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9f83168b878c05fe131910e91baa9d3deeedaf09318a9c10cefa83a965d125c1 |
|
MD5 | 83899ba1e889a68d9b4a8b6f04747962 |
|
BLAKE2b-256 | 5bea0bee277cc6c338f4030e045fd44357d9c70b9c6d0735deaf521efdda4e57 |