Monitor SIM Events
You can check on the events that take place during a Programmable Wireless SIM's life using the KORE Console, but for large volumes of SIMs, or to obtain a limited list of recent events, you can access the information using the KORE API. Event data is limited to the past 30 days; older events are purged.
SIM lifecycle events include changes made to its connection, status and Rate Plan as recorded by the Sim resource by which the Programmable Wireless API represents the SIM.
Access data
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 KORE 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:
Alternatively, to access connection state events, request events of the type wireless-sim.connection.updated, again using URL encoding:
To focus on a specific SIM, provide its SID as the request's ResourceID parameter:
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:
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:
or
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:
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.
Returned data
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:
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:
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.
Data paging
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:
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 KORE SDKs for Node, Python, etc. include tools to help you manage pages of information.
Last updated