Subscribe to a device's reachability status. The operator sends a notification when the device becomes reachable through data, can only receive SMS, or disconnects from the network.
The device is reachable through mobile data, and the operator sends a notification.
The device is connected only to SMS service, so the service provider can switch to SMS to reach it.
The device is disconnected from the network. The service provider can pause sending and resume when the connection returns.
How it differs from a queryA query responds with the current status; a subscription lets the operator send notifications when the status changes.
One event type per subscriptionCreate separate subscriptions for reachability through data, SMS only, and disconnection.
Device Reachability Status Subscriptions: How it works
- Create subscriptionThe service provider submits the notification URL and one event type. The device is identified by the authorization token or specified in the request. An expiration time and maximum number of notifications can be set.
- Wait for an eventOnce the subscription takes effect, the operator monitors whether this device is reachable.
- Send notificationWhen an event occurs, the operator sends a notification to the specified URL. It also sends a notification when the subscription ends.
Device Reachability Status Subscriptions: API spec
POST /subscriptions to create; GET /subscriptions to list; GET/DELETE /subscriptions/{subscriptionId} to look up or deleteprotocol (HTTP), notification URL sink, types (one event type), device config.subscriptionDetail.device (identified by the token and omitted from the request when using a three-party authorization token)config.subscriptionExpireTime: expiration time; config.subscriptionMaxEvents: maximum number of notifications; when config.initialEvent is true, send one initial notification if the condition is already met when the subscription is created (this notification also counts toward the limit)| Event details | Meaning | Example |
|---|---|---|
| reachability-data | Device connected to the mobile network and reachable through data | …v0.reachability-data |
| reachability-sms | Only SMS is available on the device | …v0.reachability-sms |
| reachability-disconnected | Device disconnected from the network | …v0.reachability-disconnected |
| data.terminationReason | Subscription end reasons: MAX_EVENTS_REACHED, NETWORK_TERMINATED, SUBSCRIPTION_EXPIRED, ACCESS_TOKEN_EXPIRED, SUBSCRIPTION_DELETED | SUBSCRIPTION_EXPIRED |
Responses for three scenarios (excerpts)
org.camaraproject.device-reachability-status-subscriptions.v0.reachability-dataReachable through mobile data550e8400-e29b-41d4Corresponding subscription IDorg.camaraproject.device-reachability-status-subscriptions.v0.reachability-smsOnly SMS is availableorg.camaraproject.device-reachability-status-subscriptions.v0.reachability-disconnectedOfflineSpec source: CAMARA DeviceReachabilityStatus r1.2 (Device Reachability Status Subscriptions v0.8.0)