This document introduces Totogi customers and prospective developers to the concept of Totogi Notifications. First, these docs will explain what is required to receive notifications and how to set this up. Next, they’ll show which Notification event detail records (EDRs) or call detail records (CDRs) are triggered, when they are triggered and the structure, and information contained within the message received in your environment. Finally, in the three appendices of this document, there are a set of troubleshooting instructions and advanced configuration options.
Requirements
In order to begin working with Totogi Notifications, you will need to:
- have a Totogi OCS tenant
- have your own AWS Account
- create an Amazon EventBridge EventBus via the process described in the next section
Creating your notifications EventBus
Totogi Notifications work by sending notification events to your Amazon EventBridge bus from Totogi. This means, we need the ARN number of your EventBridge EventBus to send the message to you.
In your AWS account, you can create an EventBus that will receive all the notifications from Totogi either manually or with this CloudFormation template that we provide you:
Sign into the AWS account you want to use, then click the template button above to create a CloudFormation stack with all the EventBridge resources you need and an initial CloudWatch Logs integration to see events flowing through your provider.
The CloudFormation template will create:
- An EventBus with a policy allowing Totogi to send you events
- An EventBus archive
- A
CloudWatchlog group - An EventBus rule that sends all events to a
CloudWatchlog group
After the CloudFormation stack is deployed, sign in to Plan Design with your tenant’s Admin user.
Browse to the Network section, and open the EventBridge feature. Click the ‘Set up Event Bridge’ button, and provide the ARN number created by the Cloudformation script.
Save the setting and your Event Bridge will be ready for use. You should be able to see any new events in the CloudWatch log group appear whenever you’re triggering new events.
Acting on Notifications
Ultimately, you decide which notifications to process and how. You can use these events to send SMS messages to your subscribers, trigger promotional offers, send email reminders, and much more.
You can add any rules to send EventBridge events to any of the supported targets in the AWS Documentation.
Appendix C shows instructions for building a Totogi charging emulator demo app that can help you understand how to use Totogi Notifications.
Available Notifications
Totogi provides different notification types that allow you to take action on distinct system events. With these events, you can act on common lifecycle triggers like upcoming plan expiration or low balances to trigger your own event-driven workflows. Often, these include SMS reminders, email marketing campaigns, new retention offers and other high-value actions.
Plan Expiry Warning: Triggered X <hours|days> before a Plan End Date as configured in the plan or general settings. Does not trigger when the expiry is for an upgrade to a new plan version or a plan that auto-renews
Plan Expired: Triggered when a non auto-renewable plan has expired.
Plan Canceled: Triggered when a Plan is removed from an account, however not triggered when it is upgraded to a new plan version
Plan Rollover: Triggered when any allowance is rolled over into a new period. The notification payload includes all data types and the quantity rolled over.
Service Provider Credit Limit: Triggered when the value of the main currency balance is equal to a value set when the plan is provisioned to a subscriber. The default value is 0.
Account Credit Limit: Triggered when the value of the main currency balance is equal to a value set when the plan is provisioned to an account.
This Credit Limit is for account self-care enforcement where they want to ensure their own spend does not exceed some budget. This can not be set to a value higher than the Service Provider Credit Limit.
Auto-renew Success: Triggered when a recurring plan successfully auto-renews and for pre-paid the renewal fee is deducted from the monetary balance.
Auto-renew Failure: Triggered when a recurring plan is unable to auto-renew. A renewal grace period can be configured in the plan and there is an auto-retry mechanism in place. The renewal will be attempted on each charging request until the grace period runs out. An auto-renew failure notification will be triggered each time a renewal is unsuccessful.
Allowance Threshold: Associated with any allowance balance (MB, text, min) and is intended to trigger a notification when the allowance falls below threshold.
Please note: In Plan Design the threshold is set as a percentage of the total balance.
New Plan Activated: Triggered when a new plan is successfully provisioned to a subscriber. In addition to the standard payload the Plan ID is also included.
Notification Structure
The base notification event includes the following fields
| Field Name | Description |
|---|---|
providerid | Identifying the provider. |
invocationtimestamp | This field holds the timestamp when the API invocation request is submitted to the charging function. |
day | The day of the month the notification was generated |
month | The month the notification was generated |
year | The year the notification ws generated |
eventdata | Structure containing the details of the notification information |
accountid | The account for which the notification is raised |
deviceid | (optional) The device that triggered the notification |
charginginformation | Structure containing charging relevant information |
chargingsessionidentifier | Session Id in which context the notification was triggered |
notificationInformation | Structure containing notification information |
name | Notification name (see Identifying Notifications on the EventBus) |
state | Current state of the notification counter |
prevstate | Last state of the counter |
threshold | Threshold value that triggered the state change |
notificationfields | Structure containing addition notification specific information (see Additional Information for Specific Notifications |
Identifying Notifications on the EventBus
The following table maps the defined Notifications to the values used in the notification structure
| Notification | Name | state |
| Plan Expiry Warning | PlanExpiryWarning | warning |
| Plan Expired | PlanExpired | expired |
| Plan Canceled | PlanCancelled | cancelled |
| Plan Rollover | PlanRollover | rolloverOccured |
| Service Provider Credit Limit | OutOfCredit | outOfCredit |
| Account Credit Limit | AccountCreditWarning | warning |
| Auto-renew Success | AutoRenewSuccess | renewSuccess |
| Auto-renew Failure | AutoRenewFailure | renewFailure |
| Allowance Threshold | UnitAllowanceThreshold | low |
| New Plan Activated | NewPlanActivated | active |
Additional Information for Specific Notifications
| Notification | Additional Notification Fields | Description |
| Plan Rollover | rolloveramount | Amount rolled over |
rollovergraceperiod | Period the roll over amount remain valid | |
| New Plan Activated | planid | PlanId of the Plan activated on the account. |
Appendix A
Advance Configuration of the EventBus
If you’d like to remove the rule targeting CloudWatch or make any other changes, copy and modify this template.
At that point, you can also add new targets to the EventBus to help manage any custom workflows you want to support while processing these events.
Appendix B
Troubleshooting and Debugging EventBus Permissions
Depending on how you create the EventBus and how you configure Rules and targets you may need to set additional permissions if you want events to be shown in the CloudWatch logs group. Our template creates a log group under /aws/events/{logGroupName}, which is a supported location from the default EventBridge policy when you create the rule.
However, if you’re not seeing events after testing, make sure to check the resource policy on the log groups. You can do this via the AWS CLI:
aws logs describe-resource-policies
An easy way to view the policy that comes out more easily you can use jq:
aws logs describe-resource-policies --region us-east-1 | jq | jq '.resourcePolicies[0].policyDocument | fromjson'
Result:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "TrustEventsToStoreLogEvent",
"Effect": "Allow",
"Principal": {
"Service": [
"delivery.logs.amazonaws.com",
"events.amazonaws.com"
If those components of the policy are missing, you should use the Put Resource Policy command to add a new policy that includes permissions for EventBridge to add logs to the target resource:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "TrustEventsToStoreLogEvent",
"Effect": "Allow",
"Principal": {
"Service": [
"delivery.logs.amazonaws.com",
"events.amazonaws.com"
]
},
"Action": [
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": "arn:aws:logs:us-east-1:123456789012:log-group:/aws/events/*:*"
}
]
}
If you see events.amazonaws.com in the policy under the Principal section and the CreateLogStream and PutLogEvents actions as shown above – then your EventBridge should have permissions to publish events to CloudWatch.
Appendix C
Using Notifications in a charging emulator demo app
We’ve created a how-to guide with step-by-step instructions on how to build a Totogi charging emulator demo app (the tool we use to demonstrate some of the functionality of our charger across multiple demo tenants.) Use the charging emulator demo app to process low balance notifications and records them to be looked up based on tenant, account, and time.
The charging emulator demo app shows a Serverless Framework service that triggers a Lambda Function to review all EventBridge Events. Then, on certain events (such as low balance notifications), the demo app records the events and makes them accessible via an API. However, you could easily change this application for your own purposes by rewriting the handle_threshold function to take any action you’d like based on different event types.