Subscribe to roaming status for a phone number. The operator notifies the service provider when the phone number starts roaming, changes countries, or stops roaming.
The phone connects to a local operator in Japan. The operator sends a “roaming started” event.
The country changes while roaming, and the event includes the new country.
The phone reconnects to the network in Taiwan. The operator sends a “roaming ended” event.
One event type per subscriptionCreate separate subscriptions for roaming starting, changing countries, and roaming ending.
Roaming status eventYou can also subscribe to “roaming status”: receive notifications when roaming starts or ends, with country information if available.
Device Roaming 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 the roaming status of this phone number.
- Send notificationWhen an event occurs, the operator sends a notification to the specified URL. It also sends a notification when the subscription ends.
Device Roaming 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 does not apply to country-change events (this notification also counts toward the limit)| Event details | Meaning | Example |
|---|---|---|
| roaming-on/roaming-off | Roaming starts or ends | …v0.roaming-on |
| roaming-change-country | Country changed while roaming, with countryCode and countryName | 450, ["KR"] |
| roaming-status | Roaming status changed, with roaming and optional country information | true |
| 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-roaming-status-subscriptions.v0.roaming-onRoaming starts550e8400-e29b-41d4Corresponding subscription IDorg.camaraproject.device-roaming-status-subscriptions.v0.roaming-change-countryCountry changed while roaming450Korea's mobile country code (MCC)["KR"]Country code: Koreaorg.camaraproject.device-roaming-status-subscriptions.v0.roaming-offRoaming endsSpec source: CAMARA DeviceRoamingStatus r1.2 (Device Roaming Status Subscriptions v0.8.0)