Soracom Air for Cellular

Event Handler

Overview

The Event Handler feature is a service that allows you to build automations based on SIM events, such when a SIM status changes or when its data usage exceeds a particular threshold, in order to send email notifications, throttle or disable a SIM, execute a webhook, and so on. Event handlers can be applied to a single subscriber, a SIM that contains one or more subscriptions, a group of SIMs, or to all SIMs in your account.

Parameters

Each event handler consists of the following configuration parameters:

• Name and Description - Any name or description to identify the event handler.
• Target - Defines which SIMs or subscribers the event handler should apply to.
• Rule - Defines a condition that should be evaluated. When this condition is met, the actions will be performed.
• One or more Actions - Defines what actions should be performed when the event handler rule condition is met.
• Status - Enables or disables the event handler.

You can also use Variables with certain actions in order to dynamically change the value of the action parameter, such as using ${simId} to include the SIM ID of the matched SIM in an email notification or webhook.

Limitations

• If you configure multiple event handlers and their respective rule conditions are met at the same time, the actions of both event handlers will be executed.
• When the target of an event handler is set as a group, the rule condition will be evaluated for each individual SIM or subscriber belonging to the group, rather than to all SIMs or subscribers collectively.
• Each event handler is limited to a maximum of 5 actions.
• Each Soracom account is limited to the following number of event handler configurations:

Configuration

Targets

The event handler Target defines which SIMs or subscribers should be included. This allows you to control whether an event handler configuration should apply to a single SIM or subscriber, a group of SIMs or subscribers, or to all SIMs or subscribers in your account.

• Subscriber - Matches a single subscriber in your account. The IMSI of the subscriber is required.
• SIM - Matches a single SIM in your account, which itself may contain one or more Subscription Containers. The SIM ID of the SIM is required.
• Group - Matches one or more SIMs or subscribers in your account, which belong to a particular group. The Group ID of the group is required.
• Operator - Matches all SIMs or subscribers in your account.

Rules

The event handler Rule defines a condition that will be evaluated for the specified target. When the rule condition is met, the action(s) in the event handler will be performed. The available rules depend on which Target you select.

• Available rules for Subscriber, Group, and Operator targets:

  • Subscriber first traffic - Executes when a subscriber sends or receives data for the first time after the event handler is created.
  • Subscriber Daily traffic - Executes when a subscriber's daily data usage exceeds a specified value.
  • Subscriber Monthly traffic - Executes when a subscriber's monthly data usage exceeds a specified value.
  • Subscriber Cumulative traffic - Executes when a subscriber's lifetime cumulative data usage exceeds a specified value.
  • Subscriber status attribute - Executes when a subscriber's status changes and (optionally) matches a specified source (before) and/or target (after) value.
  • Subscriber speed class attribute - Executes when a subscriber's speed class changes and (optionally) matches a specified value.
  • Subscriber expired - Executes when a subscriber expires based on its Expiration settings.
  • Subscriber IMEI mismatched - Executes when the IMEI of the device using the subscriber does not match the subscriber's IMEI Lock settings.

• Available rules for SIM, Group, and Operator targets:

  • Sim Daily total traffic - Executes when a SIM's total daily data usage across all of its subscriptions exceeds a specified value.
  • Sim Monthly total traffic - Executes when a SIM's total monthly data usage across all of its subscriptions exceeds a specified value.
  • Sim Cumulative total traffic - Executes when a SIM's total lifetime cumulative data usage across all of its subscriptions exceeds a specified value.
  • Sim status attribute - Executes when a SIM's status changes and (optionally) matches a specified source (before) and/or target (after) value.
  • Sim speed class attribute - Executes when a SIM's speed class changes and (optionally) matches a specified value.
  • Sim expired - Executes when a SIM expires based on its Expiration settings.
  • Sim subscription status - Executes when a SIM's Subscription Containers status changes and (optionally) matches a specified value.
  • Sim IMEI mismatched - Executes when the IMEI of the device using the SIM does not match the SIM's IMEI Lock settings.

• Available rules for Group and Operator targets:

  • Daily total traffic - Executes when the total daily data usage across all SIMs and subscriptions exceeds a specified value.

  • Monthly total traffic - Executes when the total monthly data usage across all SIMs and subscriptions exceeds a specified value.

    When using one of the above rules with a Group target, if a SIM is removed from the group in the middle of the Event Handler's daily or monthly period, any data usage that occurred prior to removal will still be counted toward that group's total traffic. Similarly, if a SIM is added to the group in the middle of the period, any previous data usage before the change will not be counted.

• Available rules for the Operator target:

  • Monthly bill amount - Executes when the current month's bill total exceeds a specified value.

    The monthly bill total is not calculated in real time. There may be up to a 24-hour delay between the time when your service usage exceeds the threshold, and when the monthly bill total is updated and the configured action is triggered. Usage charges that exceed the defined amount in this window cannot be prevented and customers will still be responsible for payment of these charges.

In addition to selecting one of the above rules, you must also specify when the rule should be checked again using the Re-evaluate parameter. After the rule condition is met, this parameter defines how long the event handler should wait before it evaluates the rule again. You can configure longer intervals in order to prevent the event handler from executing actions too frequently. You can also specify the Offset parameter to add an additional delay, in minutes.

By default, when the event handler Target includes multiple subscribers (such as setting a SIM, Group, or Operator target), the Rule will be applied to each subscriber individually. For example, you can use the Sim Monthly total traffic rule to receive an email notification when a SIM uses too much data within any given month. By setting the re-evaluate parameter to Beginning of next month, once a SIM exceeds the data usage threshold, the event handler will wait until the following month before it checks that SIM's monthly data usage again. During that time, the event handler will still check the data usage of other SIMs in the target, ensuring that you will still receive additional emails if other SIMs use too much data, which may be useful for identifying which devices should be inspected for abnormal behavior.

If you prefer the action to be performed only once for the entire target regardless of which SIM or subscriber triggers the rule, you can check the Do not execute again until next re-evaluation option to suppress additional actions. In the example above, enabling this option will result in sending an email when a SIM exceeds the data usage threshold, but without sending any other emails even if other SIMs also use too much data. This may be useful in identifying trends, such as how quickly a SIM reaches a particular data usage amount.

Actions

The event handler Action defines one or more actions to perform once the Rule condition is met. You can specify up to 5 actions for each event handler configuration.

• Actions for sending emails:

  • Send email - Send an email to a specified email address.
  • Send email to Operator - Send an email to the Operator email address.

• Actions for changing a SIM's properties:

  • Activation - Set the SIM's status to Active.
  • Deactivation - Set the SIM's status to Inactive.
  • Standby - Set SIM's status to Standby.
  • Suspend - Set SIM's status to Suspended.
  • Change speed class - Change the SIM's speed class.

• Actions for calling external actions:

  • Execute web request - Execute a specified HTTP request.
  • Invoke AWS Lambda - Invoke a specified AWS Lambda function.

For each action, you must also specify the timing of when the action should be performed using the Run parameter. When the rule condition is met, this parameter defines how long the event handler should wait before performing the action. You can use this parameter to add a delay between when the rule is matched and when the action is performed. You can also specify the Offset to add an additional delay, in minutes.

Variables

When using an event handler to send an email or call an external action, you can customize the contents of the action, such as specifying the subject and body of an email, or the payload of a webhook or the parameters of a Lambda function call. In many cases, you may want to include details about the particular SIM and the rule condition that triggered the action. By using the following Variables directly inside the action parameters, the event handler will fill in the corresponding value.

• ${imsi} - The IMSI of the subscriber that met the rule condition.
• ${simId} - The SIM ID of the SIM that met the rule condition.
• ${operatorId} - The Operator ID that the SIM or subscriber is registered to.
• ${coverage} - The coverage type that the SIM or subscriber is registered to (g for Global coverage, or jp for Japan coverage).
• ${date} - The date that the rule condition is met (format: yyyy/m/d).
• ${year} - The year that the rule condition is met (format: yyyy).
• ${month} - The month that the rule condition is met (format: m).
• ${day} - The day that the rule condition is met (format: d).
• ${tags.<key>} - The value of a specific tag belonging to the SIM, such as ${tags.name} for the SIM name, or ${tags.myCustomTag} for a custom tag with the tag name myCustomTag that you have set.

When using the Subscriber status attribute, Sim status attribute, Subscriber expired, or Sim expired rules, you can also use these variables in the actions:

• ${oldStatus} - The SIM or subscriber's previous status.
• ${newStatus} - The SIM or subscriber's current status.

Similarly, when using the Subscriber speed class attribute or Sim speed class attribute rules, you can use these variables in the actions:

• ${oldSpeedClass} - The SIM or subscriber's previous speed class.
• ${newSpeedClass} - The SIM or subscriber's current speed class.

The Sim subscription status rule contains additional variables useful for checking the Subscription Container status:

• ${subscription} - The name of the subscription container being added to the SIM.
• ${otaStatus} - The delivery status of the subscription container (one of the following: started, finished, or failed).
• ${imsi} - The IMSI of the newly added subscription container, or of the original plan01s or plan-US subscription, based on the OTA status:
  • If the OTA status is started or failed, this variable will return the IMSI of the plan01s or plan-US subscription.
  • If the OTA status is finished, this variable will return the IMSI of the newly added subscription container.
• ${primaryImsi} - The IMSI of the original plan01s or plan-US subscription.

When using the Monthly bill amount rule, you can use the following variables in the actions:

• ${operatorId} - The Operator ID where the billing alert occurred.
• • ${coverage} - The coverage type where the billing alert occurred (g for Global coverage, or jp for Japan coverage).
• ${limitTotalAmount} - The bill alert threshold that was exceeded.
• ${currentTotalAmount} - The actual current monthly bill amount, at the time the billing alert was triggered.

Variables can be used in the following action parameters:

• Send email and Send email to Operator actions:
  • Title
  • Message
• Execute web request action:
  • URL
  • Headers
  • Body
• Invoke AWS Lambda action:
  • parameter1 value
  • parameter2 value
  • parameter3 value
  • parameter4 value
  • parameter5 value

Creating an Event Handler

1. Login to the User Console. From the Menu, open the Event Handler screen.

   https://console.soracom.io

   

2. Click the Create Event button.

3. Enter the event handler configuration parameters:

   https://console.soracom.io

   

   • Name (required) - A name that uniquely identifies the event handler.
   • Description (optional) - A brief description that describes the behavior of the event handler.
   • Target (required) - The subscribers that the event handler should be applied to.
   • Rule (required) - The condition that must be met in order for the event handler configuration to execute its actions.
   • Action (one or more required) - One or more actions to perform when an event handler configuration's rule condition is met.
   • Active - Enables or disables the event handler.
4. Click the Create button.

Editing an Event Handler

1. Login to the User Console. From the Menu, open the Event Handler screen.

2. From the list of event handlers, click the name of the event handler that you want to edit.

   https://console.soracom.io

   

3. Enter the event handler configuration parameters.

4. Click the Update button.

Deleting an Event Handler

1. Login to the User Console. From the Menu, open the Event Handler screen.

2. From the list of event handlers, click the for the event handler you want to delete, then click the Delete button.

   https://console.soracom.io

   

3. Click the Delete button again to confirm.

   

Advanced Configuration

Configuring an event handler can also be done using either the Soracom API or Soracom CLI. Each event handler configuration is defined using a JSON object, which contains the Target, Name and Description, Rule, Action, and Status properties.

Configuration Structure

{
  "name": "My event handler name",
  "description": "My event handler description",
  "targetImsi": "295050012345678", // match a single subscriber
  "targetSimId": "8942310000012345678", // match a single SIM
  "targetGroupId": "abcdef00-0000-0000-0000-000012345678", // match a group of SIMs or subscribers
  "targetOperatorId": "OP0012345678", // match all SIMs or subscribers
  "ruleConfig": {
    "type": "ruleType",
    "properties": {
      "inactiveTimeoutDateConst": "IMMEDIATELY",
      "inactiveTimeoutOffsetMinutes": "0",
      // ...additional rule parameters
    }
  },
  "actionConfigList": [
    {
      "type": "actionType",
      "properties": {
        "key": "value",
        // ...additional action parameters
      }
    },
    // ...additional actions
  ],
  "status": "active"
}

Event Handler Parameters

Regardless of which rule or actions you want to configure, all event handler configurations will contain the following parameters:

• name (string, required) - A unique name for the event handler.
• description (string, optional) - A brief description for the event handler.
• targetImsi (string, required) - The IMSI of a single subscriber.
• targetSimId (string, required) - The SIM ID of a single SIM.
• targetGroupId (string, required) - The Group ID of a group.
• targetOperatorId (string, required) - Your Operator ID.
• ruleConfig (object, required) - The rule configuration.
  • type (string, required) - The rule to use.
  • properties (object, required) - The settings for the rule. The attributes within this object depend on what rule you use. See the Rule Parameters below.
• actionConfigList (array of objects, required) - An array of actions to perform. Each action will consist of:
  • type (string, required) - The action to perform.
  • properties (object, required) - The settings for the action. The attributes within this object depend on what action you use. See Action Parameters below.
• status (string, required) - Enables or disables the event handler. Valid options: "active" or "inactive".

Rule Parameters

Each event handler's ruleConfig parameter should follow one of the following rule schemas.

Execute actions when a subscriber sends or receives data for the first time:

  // Matches whenever a subscriber uses data for the first time, and does not repeat again for that subscriber
  "ruleConfig": {
    "type": "SubscriberFirstTrafficRule",
    "properties": {
      "inactiveTimeoutDateConst": "NEVER"
    }
  },

Execute actions based on a SIM or subscriber's data usage, or total data usage across all SIMs and subscribers:

  // Matches whenever a SIM exceeds 100 MB of data usage in a day, and waits until the next day before checking that SIM again
  "ruleConfig": {
    "type": "SimDailyTrafficRule",
    "properties": {
      "limitTotalTrafficMegaByte": 100,
      "inactiveTimeoutDateConst": "BEGINNING_OF_NEXT_DAY"
    }
  },

Execute actions based on a SIM or subscriber's status (active, inactive, etc.):

  // Matches whenever a subscriber's status changes to Active, and does not repeat again for that subscriber
  "ruleConfig": {
    "type": "SubscriberStatusAttributeRule",
    "properties": {
      "targetStatus": "active",
      "inactiveTimeoutDateConst": "NEVER"
    }
  },

Execute actions based on a SIM's Subscription Container status (started, finished, etc.):

  // Matches whenever a subscription container is successfully added to a SIM, and does not repeat again for that SIM
  "ruleConfig": {
    "type": "SimSubscriptionStatusRule",
    "properties": {
      "targetStatus": "finished",
      "inactiveTimeoutDateConst": "NEVER"
    }
  },

Execute actions based on a SIM or subscriber's speed class (s1.minimum, s1.standard, etc.):

  // Matches whenever a SIM's speed class is changed, and waits 5 minutes before checking again for that SIM
  "ruleConfig": {
    "type": "SimSpeedClassAttributeRule",
    "properties": {
      "targetSpeedClass": null,
      "inactiveTimeoutDateConst": "IMMEDIATELY",
      "inactiveTimeoutOffsetMinutes": "5"
    }
  },

Execute actions when a subscriber has expired as a result of its Expiration settings:

  // Matches only the first SIM that expires, and does not repeat again even for other SIMs
  "ruleConfig": {
    "type": "SimExpiredRule",
    "properties": {
      "inactiveTimeoutDateConst": "NEVER",
      "runOnceAmongTarget": true
    }
  },

Execute actions when the IMEI of the device using a subscriber does not match the subscriber's IMEI Lock settings:

  // Matches whenever the IMEI of a device does not match a SIM's IMEI Lock setting, and waits until the next day before checking again for that SIM
  "ruleConfig": {
    "type": "SimImeiMismatchedRule",
    "properties": {
      "inactiveTimeoutDateConst": "BEGINNING_OF_NEXT_DAY",
      "runOnceAmongTarget": false
    }
  },

Execute actions when the current monthly bill total exceeds a specific amount:

  // Matches whenever the current month's bill total exceeds 100 USD, and waits until the next month before checking again
  "ruleConfig": {
    "type": "MonthlyChargeRule",
    "properties": {
      "limitTotalAmount": "100",
      "inactiveTimeoutDateConst": "BEGINNING_OF_NEXT_MONTH"
    }
  },

Additional Rule Properties

• inactiveTimeoutDateConst (string, required) - Controls how long the event handler should wait before it re-evaluates the rule. Valid options:
  • IMMEDIATELY - Re-evaluate the rule immediately.
  • BEGINNING_OF_NEXT_MONTH - Re-evaluate the rule at the beginning of the next month.
  • BEGINNING_OF_NEXT_DAY - Re-evaluate the rule at the beginning of the next day (at 00:00 UTC).
  • AFTER_ONE_DAY - Re-evaluate the rule one day (24 hours) later.
  • NEVER - Do not re-evaluate.
• inactiveTimeoutOffsetMinutes (string, optional) - Adds an additional delay in minutes after inactiveTimeoutOffsetMinutes, before the event handler re-evaluates the rule.
• runOnceAmongTarget (boolean, optional) - When enabled, specifies that the event handler should run only one across all SIMs or subscribers in the target, rather than for each SIM or subscriber individually, until the event handler is scheduled to re-evaluate. This parameter has no effect for Subscriber targets.

Action Parameters

Each event handler's actionConfigList parameter should be an array that consists of one or more actions, each of which follows one of the following action schemas.

Send an email:

  // Send an email right away
  "actionConfigList": [
    {
      "type": "SendMailAction",
      "properties": {
        "to": "sora@soracom.io",
        "title": "Event Handler Called",
        "message": "This email was sent to inform you that your event handler was called.",
        "executionDateTimeConst": "IMMEDIATELY"
      }
    }
  ],

Change a SIM or subscriber's status:

  // Wait 1440 minutes (24 hours), then change the SIM or subscriber status to Standby
  "actionConfigList": [
    {
      "type": "StandbyAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "executionOffsetMinutes": "1440"
      }
    }
  ],

Change a SIM or subscriber's speed class:

  // Change the SIM or subscriber speed class to s1.minimum right away
  "actionConfigList": [
    {
      "type": "ChangeSpeedClassAction",
      "properties": {
        "speedClass": "s1.minimum",
        "executionDateTimeConst": "IMMEDIATELY"
      }
    }
  ],

Run a Webhook:

  // Wait 1 minute, then execute a webhook
  "actionConfigList": [
    {
      "type": "ExecuteWebRequestAction",
      "properties": {
        "url": "https://www.example.com/my/api",
        "httpMethod": "POST",
        "contentType": "application/json",
        "body": "{ \"text\": \"The event handler was called from SIM ${simId}\" }",
        "executionDateTimeConst": "IMMEDIATELY",
        "executionOffsetMinutes": "1"
      }
    }
  ],

Invoke an AWS Lambda Function:

{
  "imsi": "295050012345678",
  "parameter1": "my parameter 1",
  "parameter2": "my parameter 2",
  "parameter3": "my parameter 3",
  "parameter4": "my parameter 4",
  "parameter5": "my parameter 5"
}

exports.handler = function(event, context) {
  console.log('Function called from IMSI ', event.imsi);
  console.log('The value of parameter1 is ', event.parameter1);
  context.succeed(event.imsi);
};

  // Invoke an AWS Lambda function right away
  "actionConfigList": [
    {
      "type": "InvokeAWSLambdaAction",
      "properties": {
        "endpoint": "https://lambda.us-east-2.amazonaws.com",
        "functionName": "my-lambda-function",
        "accessKey": "ABC123XXXXXXXXXX",
        "secretAccessKey": "ABC123XXXXXXXXXX",
        "parameter1": "my value",
        "executionDateTimeConst": "IMMEDIATELY"
      }
    }
  ],

Variables

The SendMailAction, SendMailToOperatorAction, ExecuteWebRequestAction, and InvokeAWSLambdaAction actions allow you to define custom values or parameters that will be used in the email, webhook, or Lambda function.

See Variables above for the list of available variables.

Additional Action Properties

• executionDateTimeConst (string, required) - Controls how long the event handler should wait before it performs the action. Valid options:
  • IMMEDIATELY - Execute the action immediately.
  • BEGINNING_OF_NEXT_MONTH - Execute the action at the beginning of the next month.
  • BEGINNING_OF_NEXT_DAY - Execute the action at the beginning of the next day (at 00:00 UTC).
  • AFTER_ONE_DAY - Execute the action one day (24 hours) later.
  • NEVER - Do not execute.
• executionOffsetMinutes (string, optional) - Adds an additional delay in minutes after executionDateTimeConst, before the event handler performs the action.

Once your event handler JSON configuration is ready, you can pass it into the Soracom API or Soracom CLI.

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "name": "...",
>        "targetGroupId": "abcdef00-0000-0000-0000-000012345678",
>        "ruleConfig": { ... },
>        "actionConfigList": [ ... ],
>        "status": "active"
>      }' \
>  https://g.api.soracom.io/v1/event_handlers

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "name": "...",
>        "targetGroupId": "abcdef00-0000-0000-0000-000012345678",
>        "ruleConfig": { ... },
>        "actionConfigList": [ ... ],
>        "status": "active"
>      }' \
>  https://jp.api.soracom.io/v1/event_handlers

soracom event-handlers create --body "<CONFIG>" --coverage-type g

soracom event-handlers create --body "<CONFIG>" --coverage-type jp

Examples

Setting an Operator-Level Data Cap

This Event Handler configuration will set any SIM in your account that exceeds 25MB of data in a month to Inactive status, send an email to the specified address identifying the SIM that has exceeded the limit, and reactivate any SIM cards deactivated this way at the start of the next month.

{
  "targetOperatorId": "OP0012345678",
  "name": "25MB-Cap",
  "description": "Deactivate until next month when 25MB is used",
  "ruleConfig": {
    "type": "SimMonthlyTotalTrafficRule",
    "properties": {
        "inactiveTimeoutDateConst": "BEGINNING_OF_NEXT_MONTH",
        "limitTotalTrafficMegaByte": "25"
    }
  },
  "actionConfigList": [
    {
      "type": "DeactivationAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY"
      }
    },
    {
      "type": "SendMailAction",
      "properties": {
          "executionDateTimeConst": "IMMEDIATELY",
          "to": "sora@soracom.io",
          "title": "${simId} Has Exceeded the Data Usage Threshold",
          "message": "${simId} has exceeded the 25 MB monthly data usage threshold configured in your account. It has been deactivated and will be automatically reactivated at the start of next month."
      }
    },
    {
      "type": "ActivationAction",
      "properties": {
        "executionDateTimeConst": "BEGINNING_OF_NEXT_MONTH"
      }
    }
  ],
  "status": "active"
}

Explanation:

• This event handler will apply to all SIMs that belong to targetOperatorId OP0012345678.
• It uses the SimMonthlyTotalTrafficRule rule, with the limitTotalTrafficMegaByte parameter set to 25, which will cause the rule to execute when the SIM exceeds 25MB of data usage in a month.
• The rule interval inactiveTimeoutDateConst is set to BEGINNING_OF_NEXT_MONTH, meaning that the event handler will execute the actions once when the rule conditions are met, and then will wait until the start of the next month before checking the SIM that triggered it again.
• The event handler contains three actions:
  1. DeactivationAction which will IMMEDIATELY change the SIM status to Inactive.
  2. SendMailAction which will IMMEDIATELY send an email notification informing a user of the deactivation.
  3. ActivationAction which will set the SIM status to Active at the BEGINNING_OF_NEXT_MONTH.

Slack Notification

This Event Handler configuration will send a message to a Slack channel using Slack's incoming webhooks API when a SIM's Speed Class is changed.

{
  "targetOperatorId": "OP0012345678",
  "name": "SpeedClass-Slack",
  "description": "Send a notification to Slack when a Speed Class changes",
  "ruleConfig": {
    "type": "SimSpeedClassAttributeRule",
    "properties": {
      "inactiveTimeoutDateConst": "IMMEDIATELY"
    }
  },
  "actionConfigList": [
    {
      "type": "ExecuteWebRequestAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
        "httpMethod": "POST",
        "contentType": "application/json",
        "body": "{\"text\":\"${imsi} speed class changed from ${oldSpeedClass} to ${newSpeedClass}!\"}"
      }
    }
  ],
  "status": "active"
}

Explanation:

• This event handler will apply to all subscribers that belong to targetOperatorId OP0012345678.
• It uses the SimSpeedClassAttributeRule rule, and omits the targetSpeedClass parameter, which means the rule will match all speed class changes.
• The rule interval inactiveTimeoutDateConst is set to IMMEDIATELY, meaning that once the rule conditions are met, the rule will be effective again with no delay.
• The event handler contains one action:
  1. ExecuteWebRequestAction, which is configured IMMEDIATELY send a POST request to https://hooks.slack.com/services/..., with content type application/json, and custom body content which includes variables ${imsi}, ${oldSpeedClass}, and ${newSpeedClass}.

Downgrade Speed for One Day

This event handler configuration will execute a series of actions when a specific subscriber exceeds 100MB of data usage.

{
  "targetImsi": "295050012345678",
  "name": "100MB-Limit",
  "description": "Slow down for 1 day and notify when 100MB is used",
  "ruleConfig": {
    "type": "SubscriberDailyTrafficRule",
    "properties": {
      "inactiveTimeoutDateConst": "AFTER_ONE_DAY",
      "limitTotalTrafficMegaByte": 100
    }
  },
  "actionConfigList": [
    {
      "type": "ChangeSpeedClassAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "speedClass": "s1.slow"
      }
    },
    {
      "type": "SendMailAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "to": "sora@soracom.io",
        "title": "High Data Usage",
        "message": "This device has reached 100MB in daily data usage, so its speed will be limited for one day.",
      }
    },
    {
      "type": "ChangeSpeedClassAction",
      "properties": {
        "executionDateTimeConst": "AFTER_ONE_DAY",
        "speedClass": "s1.fast"
      }
    },
    {
      "type": "SendMailAction",
      "properties": {
        "executionDateTimeConst": "AFTER_ONE_DAY",
        "to": "sora@soracom.io",
        "title": "Device speed limit removed",
        "message": "This device's speed limit has been removed.",
      }
    }
  ],
  "status": "active"
}

Explanation:

• This event handler applies to an individual subscriber with targetImsi 295000012345678.
• It uses the SubscriberDailyTrafficRule rule, with the limitTotalTrafficMegaByte parameter set to 100, which will cause the rule to execute when the subscriber exceeds 100MB of data usage.
• The rule interval inactiveTimeoutDateConst is set to AFTER_ONE_DAY, meaning that the event handler will execute the actions once when the rule conditions are met, and then will wait one day before checking again.
• The event handler contains four actions:
  1. ChangeSpeedClassAction, which will IMMEDIATELY change the speed class to s1.slow.
  2. SendMailAction, which will IMMEDIATELY send an email notification informing a user of the speed change.
  3. ChangeSpeedClassAction, which will reset the speed class to s1.fast AFTER_ONE_DAY passes.
  4. SendMailAction, which will send another email notification AFTER_ONE_DAY informing the user that the speed limit has been removed.

Invoke Lambda on Active Status

This event handler configuration will invoke an AWS Lambda function whenever a SIM's status changes to Active.

{
  "targetOperatorId": "OP0012345678",
  "name": "Status-Lambda",
  "description": "Invoke Lambda function when a SIM is activated",
  "ruleConfig": {
    "type": "SimStatusAttributeRule",
    "properties": {
      "inactiveTimeoutDateConst": "IMMEDIATELY",
      "targetStatus": "active"
    }
  },
  "actionConfigList": [
    {
      "type": "InvokeAWSLambdaAction",
      "properties": {
        "executionDateTimeConst": "IMMEDIATELY",
        "endpoint": "https://lambda.us-east-2.amazonaws.com",
        "functionName": "my-lambda-function",
        "accessKey": "ABC123XXXXXXXXXX",
        "secretAccessKey": "ABC123XXXXXXXXXX",
        "parameter1": "${oldStatus}",
        "parameter2": "${newStatus}"
      },
    }
  ],
  "status": "active"
}

Explanation:

• This event handler will apply to all subscribers that belong to targetOperatorId OP0012345678.
• It uses the SimStatusAttributeRule rule, with the targetStatus parameter set to "active", which will cause the rule to execute when any SIM is activated (status is changed to Active).
• The rule interval inactiveTimeoutDateConst is set to IMMEDIATELY, meaning that once the rule conditions are met, the rule will be effective again with no delay.
• The event handler contains one action:
  1. InvokeAWSLambdaAction, which is configured to IMMEDIATELY invoke the my-lambda-function function at https://lambda.ap-northeast-1.amazonaws.com using the provided access key, pass the SIM's previous and current statuses to the Lambda function in the properties parameter1 and parameter2 respectively.