Notification API Response Documentation
Notification messages
Several messages are provided through the https://events.iot.telenor.com/connect/subscribe endpoint of the Notification API. These are provided through a Server Sent Event (SSE) stream. Note that only one subscriber per domain may be connected at the same time.
Getting started
To get started the first step is to retrieve an access token using the same credentials as for accessing any of the other APIs. Refer to Authentication for an explanation on how to retrieve an access token.
The next step is to make a request to the Notifications API endpoint (https://events.iot.telenor.com/connect/subscribe) providing the access token by setting it in the Authorization header field as a bearer token.
An example using curl:
curl --header "Authorization: Bearer <TOKEN>" https://events.iot.telenor.com/connect/subscribe
You will then get a continuous stream of events as described in the documentation below.
There will always be a HEARTBEAT event every 30 seconds and the session will be valid for 30 minutes. After that you will be disconnected and have to reconnect.
Only one concurrent subscriber may be connected per domain!
Base format
event: <Event>
id: <Event id>
retry: <Milliseconds>
data: <JSON>
Possible event values:
- CMP_EVENT
- HEARTBEAT
- SUBSCRIPTION_STARTED
- SUBSCRIPTION_ENDED
- LOCALIZATION
Data format (JSON):
{
"createdDateTime": <timestamp>,
"detailedMessage": <string> or <stringified JSON>,
"operation": <string>,
"principal": <domainId>,
"state": <state>
}
Notification subscription events
Subscription started
Will be sent at the beginning of the subscription. Example event:
event: SUBSCRIPTION_STARTED
id: 1586333282311
retry: 5000
data: {
"createdDateTime": "2020-04-08T10:08:02.311Z",
"detailedMessage": "Subscription started for principal 1bu9s9t4-4khtvflt",
"operation": "-",
"principal": "1bu9s9t4-4khtvflt",
"state": "IN_PROGRESS"
}
Subscription ended
Will be sent at the end of the subscription. Each subscription session is open for 30 minutes. Example event:
event: SUBSCRIPTION_ENDED
id: 268
data: {
"createdDateTime":"2020-04-08T10:37:12.001Z",
"detailedMessage":"Subscription ended since session expired",
"operation":"-",
"principal":"1bu9s9t4-4khtvflt",
"state":"COMPLETED"
}
Heartbeat events
Session alive event
Will be sent every 30 seconds to indicate that the connection is alive. Example event:
event: HEARTBEAT
id: 1586334611999
retry: 5000
data: {
"createdDateTime":"2020-04-08T10:30:11.999Z",
"detailedMessage":"Heartbeat",
"operation":"-",
"principal":"1bu9s9t4-4khtvflt",
"state":"IN_PROGRESS"
}
Localization events
These events are sent during the localization process which is triggered through the /iot-connect/subscriptions/v1/euiccs/{eid}/localize endpoint in the Subscriptions API.
The detailedMessage property is a stringified JSON.
Success example:
event: LOCALIZATION
id: 1586334611999
retry: 5000
data: {
"createdDateTime": "2020-04-08T10:30:11.999Z",
"operation": "LOCALIZED",
"principal": "1bu9s9t4-4khtvflt",
"state": "COMPLETED",
"detailedMessage": {
"eid": "89046024208000441900000000000251",
"localizedProfile": {
"iccid": "89450206016400000674",
"countryCode": "BR"
},
}
}
Error example:
event: LOCALIZATION
id: 1586334611999
retry: 5000
data: {
"createdDateTime": "2020-04-08T10:30:11.999Z",
"operation": "ALLOCATED",
"principal": "1bu9s9t4-4khtvflt",
"state": "FAILED",
"detailedMessage": {
"eid": "89046024208000441900000000000251",
"localizedProfile": {
"iccid": "89450206016400000674",
"countryCode": "BR"
},
"errorCode": "START_PROFILE_ALLOCATION_FAILED",
"detailedError": [
{
"errorCode": "START_PROFILE_ALLOCATION_FAILED"
"errorMessage": "Failed to start profile allocation. Please retry localization or contact your system administrator if this problem persists."
"errorType": "CMP_ERROR"
}
]
}
}
The operation property can be used to determine how far localization has come. These are all possible values that operation can have, listed in order from first to last:
| Property | Description |
|---|---|
| DOWNLOADED | Downloads a profile to the eUICC. A notification for this operation is only sent if the operation failed. |
| ALLOCATED | Allocates the profile in the underlying connectivity management platform. This is a preparatory step for activating the profile. A notification for this operation is only sent if the operation failed. |
| ACTIVATED | Activates the profile in the underlying connectivity management platform. A notification for this operation is only sent if the operation failed. |
| PROVISIONED | Provisions the profile in Local Access. Completion of this operation results in the profile being reachable through the Subscriptions API. When this operation is completed the billing for the profile has started. |
| ENABLED | Enables the profile on the eUICC. A notification for this operation is sent for failed operations. |
| FALLBACK_SET | Sets the fallback profile on the eUICC. Completion of this operation means that whenever the subscription loses connection for an extended period of time, the profile will not revert back to the non-localized profile of the eUICC. An event will be sent in both success and error cases. |
Some customers have special setups which means that the customer is responsible for setting the fallback profile. For these special cases, the FALLBACK_SET operation is not present and the ENABLED operation will be the last step. In this case a success event will be sent indicating that the localization is done after ENABLED has finished.
Properties appearing in detailedMessage are listed and explained below:
| Property | Description |
|---|---|
| eid | String that specifies the EID of the eUICC affected by the localization. |
| localizedProfile | JSON object containing two properties: iccid and countryCode. |
| iccid | String that specifies the ICCID of the profile that has been downloaded and will be enabled as part of the localization. Can have value null if there is no ICCID present, e.g. if profile download failed. |
| countryCode | Two character string specifying the country that the profile belongs to using the ISO 3166-1 alpha-2 standard. |
| errorCode | String which states the error code. Only present if state has value "FAILED". Refer to Localization related errors for all possible values. |
| detailedError | Array containing one or more JSON objects. Only present if state has value "FAILED". The content of the JSON objects can vary and is not standardized. It is primarily intended to be manually inspected and used for advanced troubleshooting. |
Localization related errors
The localization process can fail for a variety of reasons. Unless otherwise stated, it is always recommended to retry localization by performing the localization request again using the Subscriptions API. If the retry fails you can try again a few minutes later. If it keeps failing contact Telenor Connexion support and, if possible, provide them with the content of the error notification for faster troubleshooting. Note that no billing for the profile is done if the localization process failed.
All errorCode values are listed below:
| Property | Description |
|---|---|
| START_PROFILE_DOWNLOAD_FAILED | Occurs when the profile failed to be downloaded to the specified eUICC. This means that the localization process has resulted in no changes being made to the eUICC. Reason for failure could be that the eUICC is not inserted into a device or that the eUICC does not have any network connectivity. |
| START_PROFILE_ALLOCATION_FAILED | Occurs when the profile failed to be allocated in the connectivity management platform. The profile exists on the eUICC but is not currently usable. The profile's ICCID is provided as part of the notification response. This error should occur rarely and is not a client error. |
| START_PROFILE_ACTIVATION_FAILED | Occurs when the profile failed to be activated in the connectivity management platform. The profile exists on the eUICC but is not currently usable. The profile's ICCID is provided as part of the notification response. This error should occur rarely and is not a client error. |
| PROVISION_PROFILE_FAILED | Occurs when the profile failed to be provisioned internally in Local Access. The profile exists on the eUICC but is not currently usable. The profile's ICCID is provided as part of the notification response. This error should occur very rarely and is not a client error. |
| START_PROFILE_ENABLE_FAILED | Occurs when the profile failed to be enabled as the active profile on the eUICC. The profile exists on the eUICC and is also reachable through the Subscriptions API but is not currently usable. Reason for failure could be that the eUICC is not inserted into a device or that the eUICC does not have any network connectivity. |
| SET_FALLBACK_PROFILE_FAILED | Occurs when the fallback profile for the eUICC could not be set properly. If this fails it means that the eUICC can swap back to the non-localized profile when losing connectivity for an extended period of time. Reason for failure could be that the eUICC is unable to establish a connection to the network. |
Connectivity Management Platform (CMP) events
Change subscription state event
These events are sent when changing the state of a subscription using the /iot-connect/subscriptions/v1/connectivity-subscriptions/change/{idType}/{id}/mode endpoint in the Subscriptions API.
The detailedMessage property is a stringified JSON.
Success example:
event: CMP_EVENT
id: 1586333283458
retry: 5000
data: {
"createdDateTime": "2020-04-08T10:08:03.469Z",
"operation": "CHANGE_SUBSCRIPTIONSTATE",
"state": "COMPLETED",
"principal": "1bu9s9t4-4khtvflt",
"detailedMessage": {
"subscriptionRequestId": "REQ200003929435",
"subscriptionRequestType": "CHANGE_SUBSCRIPTIONSTATE",
"subscriptionRequestState": "COMPLETED",
"createdBy": "tester@mycompany.com",
"companyId": "12345678",
"companyName": "My_company",
"timeCreated": {
"epochSecond": 1558946309,
"nano": 538000000
},
"lastUpdated": {
"epochSecond": 1558946310,
"nano": 75000000
},
"size": 1,
"subscriptionRequestResourceCounters": {
"inProgress": 0,
"pending": 0,
"canceled": 0,
"rejected": 0,
"completed": 1,
"failed": 0
},
"subscriptionRequestResources": [
{
"resourceProperties": [
{
"type": "IMSI",
"value": "100334000007954",
"operation": "SUBSCRIPTION_STATE_CHANGE"
},
{
"type": "MSISDN",
"value": "200334000007954",
"operation": "SUBSCRIPTION_STATE_CHANGE"
},
{
"type": "ICCID",
"value": "99987100334000007954",
"operation": "SUBSCRIPTION_STATE_CHANGE"
},
{
"type": "TARGET_SUBSCRIPTION_STATE",
"value": "PAUSE",
"operation": "SUBSCRIPTION_STATE_CHANGE"
}
],
"resourceState": "COMPLETED",
"resourceId": "INT200005284453"
}
]
}
}
Error example:
event: CMP_EVENT
id: 1586333283458
retry: 5000
data: {
"createdDateTime": "2020-04-08T10:08:03.469Z",
"operation": "CHANGE_SUBSCRIPTIONSTATE",
"state": "COMPLETED",
"principal": "1bu9s9t4-4khtvflt",
"detailedMessage": {
"subscriptionRequestId": "REQ200003964899",
"subscriptionRequestType": "CHANGE_SUBSCRIPTIONSTATE",
"subscriptionRequestState": "COMPLETED_WITH_FAILURES",
"createdBy": "tester@mycompany.com",
"companyId": "12345678",
"companyName": "My_company",
"timeCreated": {
"epochSecond": 1558962035,
"nano": 928000000
},
"lastUpdated": {
"epochSecond": 1558962036,
"nano": 243000000
},
"size": 1,
"subscriptionRequestResourceCounters": {
"inProgress": 0,
"pending": 0,
"canceled": 0,
"rejected": 0,
"completed": 0,
"failed": 1
},
"subscriptionRequestFailureInfos": [
{
"errorObject": {
"errorCode": "70",
"errorMessage": "Cannot change the current subscription state to the given subscription state."
},
"errorType": "DCP_ERROR"
}
],
"subscriptionRequestResources": [
{
"resourceProperties": [
{
"type": "IMSI",
"value": "100344000031733",
"operation": "SUBSCRIPTION_STATE_CHANGE"
},
{
"type": "MSISDN",
"value": "200344000031658",
"operation": "SUBSCRIPTION_STATE_CHANGE"
},
{
"type": "ICCID",
"value": "99987100344000031733",
"operation": "SUBSCRIPTION_STATE_CHANGE"
},
{
"type": "TARGET_SUBSCRIPTION_STATE",
"value": "DEACTIVATED",
"operation": "SUBSCRIPTION_STATE_CHANGE"
}
],
"resourceState": "FAILED",
"resourceFailureInfos": [
{
"errorObject": {
"errorCode": "70",
"errorMessage": "Cannot change the current subscription state to the given subscription state."
},
"errorType": "DCP_ERROR"
}
],
"resourceId": "INT200005320116"
}
]
}
}
Change subscription package event
These events are sent when changing a device's service policy using the /iot-connect/subscriptions/v1/connectivity-subscriptions/change/{idType}/{id}/service-policy endpoint in the Subscriptions API.
The detailedMessage property is a stringified JSON.
Success example:
event: CMP_EVENT
id: 1586333283458
retry: 5000
data: {
"createdDateTime": "2020-04-08T10:08:03.469Z",
"operation": "CHANGE_SUBSCRIPTIONPACKAGE",
"state": "COMPLETED",
"principal": "1bu9s9t4-4khtvflt",
"detailedMessage": {
"subscriptionRequestId": "REQ201003138990",
"subscriptionRequestType": "CHANGE_SUBSCRIPTIONPACKAGE",
"subscriptionRequestState": "COMPLETED",
"createdBy": "tester@mycompany.com",
"companyId": "12345678",
"companyName": "My_company",
"timeCreated": {
"epochSecond": 1558761529,
"nano": 400000000
},
"lastUpdated": {
"epochSecond": 1558761530,
"nano": 161000000
},
"size": 1,
"subscriptionRequestResourceCounters": {
"inProgress": 0,
"pending": 0,
"canceled": 0,
"rejected": 0,
"completed": 1,
"failed": 0
},
"subscriptionRequestResources": [
{
"resourceProperties": [
{
"type": "IMSI",
"value": "100883000029828",
"operation": "SUBSCRIPTION_PACKAGE_CHANGE"
},
{
"type": "MSISDN",
"value": "200883000022568",
"operation": "SUBSCRIPTION_PACKAGE_CHANGE"
},
{
"type": "ICCID",
"value": "99987100883000029828",
"operation": "SUBSCRIPTION_PACKAGE_CHANGE"
},
{
"type": "TARGET_SUBSCRIPTION_PACKAGE",
"value": "88000001003_SP_24",
"operation": "SUBSCRIPTION_PACKAGE_CHANGE"
}
],
"resourceState": "COMPLETED",
"resourceId": "INT201004416492"
}
]
}
}
Error example:
event: CMP_EVENT
id: 1586333283458
retry: 5000
data: {
"createdDateTime": "2020-04-08T10:08:03.469Z",
"operation": "CHANGE_SUBSCRIPTIONPACKAGE",
"state": "COMPLETED",
"principal": "1bu9s9t4-4khtvflt",
"detailedMessage": {
"subscriptionRequestId": "REQ201003139998",
"subscriptionRequestType": "CHANGE_SUBSCRIPTIONPACKAGE",
"subscriptionRequestState": "COMPLETED_WITH_FAILURES",
"createdBy": "tester@mycompany.com",
"companyId": "12345678",
"companyName": "My_company",
"timeCreated": {
"epochSecond": 1558764266,
"nano": 142000000
},
"lastUpdated": {
"epochSecond": 1558764266,
"nano": 541000000
},
"size": 1,
"subscriptionRequestResourceCounters": {
"inProgress": 0,
"pending": 0,
"canceled": 0,
"rejected": 0,
"completed": 1,
"failed": 1
},
"subscriptionRequestFailureInfos": [
{
"errorObject": {
"errorCode": "73",
"errorMessage": "It is not possible to move a subscription to the same Subscription Package which it already belongs to."
},
"errorType": "DCP_ERROR"
}
],
"subscriptionRequestResources": [
{
"resourceProperties": [
{
"type": "IMSI",
"value": "100883000000228",
"operation": "SUBSCRIPTION_PACKAGE_CHANGE"
},
{
"type": "MSISDN",
"value": "200883000000228",
"operation": "SUBSCRIPTION_PACKAGE_CHANGE"
},
{
"type": "ICCID",
"value": "99987100883000000228",
"operation": "SUBSCRIPTION_PACKAGE_CHANGE"
},
{
"type": "TARGET_SUBSCRIPTION_PACKAGE",
"value": "12345678_001_SP_01",
"operation": "SUBSCRIPTION_PACKAGE_CHANGE"
}
],
"resourceState": "FAILED",
"resourceFailureInfos": [
{
"errorObject": {
"errorCode": "73",
"errorMessage": "It is not possible to move a subscription to the same Subscription Package which it already belongs to."
},
"errorType": "DCP_ERROR"
}
],
"resourceId": "INT201004417596"
}
]
}
}