How To Monitor Programmable Wireless SIM Events

Unlike other SIM-specific data, lifecycle events are accessed from the Monitor API. Events are published when you update a SIM's Rate Plan or status, or its connection state changes. You can use events to see when a change occurred and what the before and after values were.

The Monitor API is used to deliver logging information for all Twilio API resources, so it's important to make use of the API's filtering options in order to ensure you receive the data you want, in manageable volumes.

You access SIM status and rate events by requesting a series of Event resources of the Event Type wireless-sim.updated, which you specify using URL encoding:

EventType=wireless-sim.updated

Alternatively, to access connection state events, request events of the type wireless-sim.connection.updated, again using URL encoding:

EventType=wireless-sim.connection.updated

To focus on a specific SIM, provide its SID as the request's ResourceID parameter:

ResourceSid=YOUR_SIM_SID 

This will return events of both of the above types, if they are present.

You can use either of the EventType and ResourceSid parameters, but not both. If you do, the API's response will have a status code of 400 and the following error structure:

1
{ "code": 20004, 
2
  "message": "Invalid combination of AuditEvent filters, no combinations of ResourceSid, SourceIpAddress, ActorSid, and EventType are supported.",
3
  "more_info": "https://www.twilio.com/docs/errors/20004", 
4
  "status": 400 }

Put these request parameters and values together using URL encoding and, to issue the request using the curl command line tool, you have the command:

1
curl -X GET 'https://monitor.twilio.com/v1/Events/?ResourceId=YOUR_SIM_SID' \
2
    -u YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN

or

1
curl -X GET 'https://monitor.twilio.com/v1/Events/?EventType=wireless-sim.updated \
2
    -u YOUR_ACCOUNT_SID:YOUR_AUTH_TOKEN

To narrow the window of possible responses further — for example, to zero in on the period during which an end-user experienced a connectivity problem — include the StartDate and EndDate parameters:

StartDate=2020-04-01T00:00:00Z&EndDate=2020-04-02T00:00:00Z

The API requires that these dates are provided in the ISO8601 format, or it will respond with an error. These date parameters are compatible with both the ResourceId and EventType parameters.

The request will return JSON data containing two primary properties, meta and events. The latter is an array of Event resources, each of which has the following structure:

1
{   "account_sid": "...",
2
    "actor_sid": "...",
3
    "actor_type": "account",
4
    "description": "...",
5
    "event_date": "2020-04-10T14:57:03Z",
6
    "event_type": "wireless-sim.updated",
7
    "resource_sid": "DE6ab41851778e5ccc07d67b843c1fc44a",
8
    "resource_type": "wireless-sim",
9
    "sid": "...",
10
    "url": "https://monitor.twilio.com/v1/Events/...",
11
    "source": "api",
12
    "source_ip_address": "...",
13
    "event_data": {
14
        "resource_properties": {
15
            "status": {
16
                "updated": "...",
17
                "previous": "..."
18
            },
19
            "rate_plan_sid": {
20
                "previous": "...",
21
                "updated": "..."
22
            }
23
        }
24
    },
25
    "links": {
26
        "actor": "https://api.twilio.com/2010-04-01/Accounts/...",
27
        "resource": null
28
    }
29
}

The API does not return empty strings; it returns null.

Each event has an event_data property; its value is a data structure that contains the SIM event information. A typical event_data structure looks like this:

1
"event_data": {
2
  "resource_properties": {
3
    "rate_plan_sid": {
4
      "previous": "...",
5
      "updated": "..."
6
    },
7
    "status": {
8
      "previous": "new",
9
      "updated": "active"
10
    }
11
  }
12
}

The resource_properties property will always be present, but you will see either rate_plan_sid, status, or both depending on the actual change made to the SIM.

If you make a request using the ResourceSid parameter, you may see events of the types wireless-sim.updated and wireless-sim.connection.updated depending on the events history of the Sim resource specified.

If you make a request using the EventType parameter, you will only see events of the specified type.

Events of the type wireless-sim.connection.updated have no event_data record. They map to the Console-listed event Connection Reset, which you may see if you select a SIM and view its Events tab.

The Event resource's event_date property provides an ISO8601-format timestamp for the event described above. Other Event resource properties you may not have encountered before include actor_sid and actor_type. Together, these properties indicate the Twilio account to which the SIM is registered.

The returned JSON data's meta property contains paging data that will help you retrieve extended lists of data. The page number and the URLs of the first, the previous and the next pages in the sequence are helpful for this process:

1
"meta": {
2
    "page": 0,
3
    "page_size": 20,
4
    "first_page_url": "https://monitor.twilio.com/v1/Events?StartDate=2020-04-01T00%3A00%3A00Z&EndDate=2020-04-23T00%3A00%3A00Z&EventType=wireless-sim.updated&PageSize=20&Page=0",
5
    "previous_page_url": null,
6
    "url": "https://monitor.twilio.com/v1/Events?StartDate=2020-04-01T00%3A00%3A00Z&EndDate=2020-04-23T00%3A00%3A00Z&EventType=wireless-sim.updated&PageSize=20&Page=0",
7
    "next_page_url": null,
8
    "key": "events"
9
}

If the value of next_page_url is null then there are no further pages to access; the value of page will tell you exactly where you are in the sequence; the first page of results has the page value 0.

The Twilio SDKs for Node, Python, etc. include tools to help you manage pages of information.