This repository is the part of the open source NotifyOne project.
'notifyone-handler' provides handlers implementation for the supported channels (channels of notifications i.e. sms/email/push/whatsapp etc.) in the NotifyOne project.
> email - ["SparkPost", "AWS SES"]
> sms - ["SMS Country", "Plivo", "AWS SNS"]
> push - ["FCM"]
> whatsapp - ["Interkt"]
- Python - version 3.9.10
- Framework - torpedo [ A lightweight wrapper around the open source Sanic framework ]
- AWS SQS - for asynchronous processing of the notifications and status updates
- Sanic OpenApi - for automatic OAS3 documentation of the APIs & out of the box Swagger UI
> Supports muli deployment - handler for each channel can be deplyed seprately
> Default priority logic b/w gateways for a channel - this is used to decide the gateway for a communication request
> Custom Priority Logic - you can write a dynamic priotity logic based on the parameters availble in the request.
Custom priority logic can be used to overwirte the default priority logic.
> Support for the multiple instances for the same gateway.
> Adding new gateway (from the supported gateways list) is as easy as adding a config in your service.
> Exposes endpoints to recive callbacks from Gateways.
For the list of all available keys, checkout the Config Template file.
Config Template provides a template (actual keys, dummy values) for the actual config file.
The actual config.json file must be generated by the service owner with the real values.
config.NAME : Name of the service
config.HOST : Host name for interface binding. Default value - 0.0.0.0
config.PORT : Port for the service
config.WORKER : Number of Sanic works. Default is 1
config.DEBUG : Available values [true/false]. If set to true, the service runs in DEBUG mode
config.TIMEOUT : Default timeout for all the http APIs exposed
config.SENTRY : Sentry configuraition details. Leave it empty if sentry integration is not needed
config.APM : APM configurtion. Leave it empty if APM integration is not needed
config.SQS : SQS queue details for PUBLISH and SUBSCRIBE
config.SQS.PUBLISH.LOGGING : SQS queue details for status updates
config.SQS.SUBSCRIBE.EMAIL : SQS queue details for `email` channel
config.SQS.SUBSCRIBE.SMS : SQS queue details for `sms` channel
config.SQS.SUBSCRIBE.PUSH : SQS queue details for `push` channel
config.SQS.SUBSCRIBE.WHATSAPP : SQS queue details for `whatsapp` channel
config.SQS_AUTH : SQS auth credentitals
config.ENABLED_CHANNELS : List of channels active for this deployment. This config key can be used to control the
channel handlers active in a deployment.
The config file has keys for handlers configurations for each channel config.SMS_HANDLER, config.EMAIL_HANDLER, config.PUSH_HANDLER and config.WHATSAPP_HANDLER are the handlers for sms, email, push and whatsapp channels respectively.
Each handler config has got same set of keys. So, we have explained the handlers config keys only for config.SMS_HANDLER here. For rest of the handlers, meaning of the keys remains the same.
config.SMS_HANDLER : SMS handler configuration
config.SMS_HANDLER.DEFAULT_PRIORITY : Default priority of configured gateways
config.SMS_HANDLER.PRIORITY_LOGIC : Custom priority logic. A python one-liner eval expression that returns gateways priority for current request.
config.SMS_HANDLER.PRIORITY_LOGIC takes presendece over config.SMS_HANDLER.DEFAULT_PRIORITY
You can use variable `data` to refer to the request details in you custom logic.
Example -
config.SMS_HANDLER.PRIORITY_LOGIC: """['GATEWAY2', 'GATEWAY1'] if data.get('to') == '<customer1_number>' else ['GATEWAY1', 'GATEWAY2']"""
* To get all the keys available in `data`, checkout the /notify API document in the API Documents section.
config.SMS_HANDLER.GATEWAYS : A list of all the configured gateways. See the config template for details
about how to add gateways here.
The repository code can be deployed as a single service that handles requests for all the channels.
But, to better handle the scale, we have provisioned a multi-service deployment of handlers using the config.ENABLED_CHANNELS config key.
Based on your use case and expected load for a channel (number of notification requests for a channel) you can run multiple deployments of the code each handling requests for a particular channel or a set of channels.
Example usecase - let's say in your setup, there is considerable load for email and sms channels but comparatively less load for push and whatsapp. You can now choose to run 3 deployments here, 1st for email channel (config.ENABLED_CHANNELS: ["email"]), 2nd for sms channel (config.ENABLED_CHANNELS: ["sms"]) and 3rd for push and whatsapp channels (config.ENABLED_CHANNELS: ["push", "whatsapp"])
1. git clone https://github.com/tata1mg/notifyone-handler.git
2. cd notifyone-handler
3. touch config.json
4. Generate actual keys and values for config.json file. Refer to config_template.json for keys.
5. pip isntall pipenv (if not alread installed)
6. python3 -m pipenv shell
7. python3 -m pipenv install
8. python3 -m app.service
1. git clone https://github.com/tata1mg/notifyone-handler.git
2. cd notifyone-handler
3. touch config.json
4. Generate actual keys and values for config.json file. Refer to config_template.json for keys.
5. docker build . --tag notifyone-handler --build-arg SERVICE_NAME=notifyone_handler
6. docker run -p <service-host-port>:<service-container-port> --name notifyone-handler --detach notifyone-handler
We have used sanic_openapi to automatically generate the OAS3 specification API documents for the APIs exposed in this service.
Once you are done with the service setup, the API documentation can be accessed at - :/swagger
Example - If you started your service at port number 9401, the documentation can be accessed at - localhost:9401/swagger
If you wish to have a look at the API documentation without deploying the service, you can use an independent swagger UI to view the documentation by pointing the swagger UI to the api_doc.json file.
Or, import the api_doc.json file into Postman as OAS3 API collection.
Please refer to our Contribution Guidlines before for more details.
This project is licensed under the Apache-2.0 License.