Sigfox Cloud Integration

Sigfox Cloud is the central hub where messages and information from your devices are stored. You must integrate Sigfox Cloud in order to retrieve and use the data from your devices, as well as administrating devices from your own platform. 

Integrating means creating a link between Sigfox Cloud and your platform. Two methods are available: The Callback API and the REST API. Each serves a purpose for communicating between Sigfox Cloud and your server, that we explore in this page. In short, Callbacks are used to retrieve devices' messages, and the REST API is used to administrate the devices' fleet as well as building related service, such as a customer platform. 

Introduction

To understand the main difference between the Callbacks API and the REST API, you need to understand how the Sigfox Cloud works. 

On Sigfox Cloud, a company is usually represented by a "Group", which contains at least one "Device type". Each device type can be attributed to a "family" of devices. A device type regroups all units of the same product, to allow them to behave exactly in the same way when the Sigfox network receives a message. This is called a same-device behavior. 

A Callback-based integration is defined on a per-device type basis. 

Subscription management is assigned on a per-device basis too. 

All this is represented in the diagram below:  

Callbacks

Callback queries are HTTP requests which are notification messages (one-way only) and are tied to a device type: your server can only obtain data through callbacks, not manage devices through the Cloud. 

When Sigfox Cloud receives a message from an emitting device, it instantly generates a callback message and sends it to your platform's servers. This way, you don't have to regularly check for new data: the system sends any new content your way when it receives it. 

 

REST API

REST API queries are HTTP requests which are bi-directional and work at the Group level: your server can request and receive data from Sigfox Cloud through the API. The Sigfox REST API follows a “fair use” policy: you can make requests as long as you follow the API rate limits and you agree to never use more resources than is nominally required by your application (see the Terms and Conditions).

The REST API allows you to automatically register and manage all your devices on the Sigfox Cloud, including their subscription lifecycles. This way, you don't have to connect to the Sigfox Backend website to perform recurring operations, such as callback declaration, device management, etc. You should use the REST API to handle your registered devices directly from your platform. 

Callbacks

Callbacks are available through device types, as they will be triggered every time any device of this device type sends a message. 

They are used to deliver data and information to your platform, which can then rework into a proper dashboard. 

Callbacks can be of three types: Data, Service, and Error. 

Callback type Description
DATA Delivers device messages. Messages can be “Uplink” or “Bidir”.
SERVICE Delivers lifecycle events about the device and its subscription. This allows your platform to remain up to date with what Sigfox Cloud sees.
ERROR Checks the device for support information

Data callbacks are the most immediate use of Callbacks when approaching Sigfox data retrieval. You can create an uplink or a bidirectional callback: 

  • UPLINK: Used to deliver uplink messages to a customer platform. 
  • BIDIR: Same as the UPLINK type and includes a downlink payload processing. 

To optimize resource usage, it is recommended that customers integrate only with the Advanced data callback service to collect the data, most notably for business cases where delivery time is not critical, where a 30-second delay is acceptable, AND where a downlink mechanism is not required.  

 

Creating a callback 

Callback creation information can be found on the Sigfox Support portal: 

 

Custom callbacks

If you wish to instantly send incoming messages to your private server or to a custom service, you will have to complete information about the service: 

  • Is it for an uplink message or a downlink message? 
  • What is the URL pattern? 
  • What are the payload parameters? 
  • etc. 

By doing so, you will be able to process data sent from the device server-side and render the information gathered intelligibly for the end-user -- after decoding the hexadecimal frame. 

To get all the details about callback configuration, see this page on the Sigfox Backend portal (connection required).

 

Built-in callbacks

Here is the list of currently available platforms. 

Service Name & URL Available callbacks
 UPLINK   DOWNLINK   DATA_ADVANCED 
 AWS IoT 
 AWS Kinesis 
 Microsoft Azure Event Hub 
 Microsoft Azure IoT Hub 
 IBM Watson IoT Platform 

REST API

Description of the Sigfox REST API  

The Sigfox REST API has a different objective than the Callback API. For instance, after setting up your callbacks, you will be able to receive messages from your device directly on your platform. Great! 

But callbacks are not meant for: 

  • Managing a huge list of devices. 
  • Registering new devices when customers activate them.  
  • Knowing whether is Sigfox coverage at a designated location.  
  • Recovering failed callback messages. 
  • Automating callback management. 
  • ... 

We have built a very powerful REST API which will allow you to automate every required action. Through this API, you can manage every Sigfox-related aspects of your business by yourself, through your platform. 

 

Accessing the REST API 

To access this API, you need to create an API User for yourself. To do so, when logged on Sigfox Cloud, click on your group, and navigate to the "API Access" tab on the left.  

You can browse the API v2 apidoc (in OpenAPI format), which describes the different endpoints available and how to access them. Find more information on the API documentation page


More resources on the API:

Changes in REST APIv2

Version 2 is a major upgrade introducing usage of simple HTTPS methods such as GET, POST, PUT and DELETE, in addition to extended device management capabilities and standardized OpenAPI specifications (available here: https://support.sigfox.com/apidocs). 

Migrating your implementation of the Sigfox REST API from v1 to v2 means knowing what v2 brings and changes. Here are the main items. 

Generalities 

Fundamentally, everything changes, since endpoints are not the same between v1 and v2.  

Also, the API now has: 

  • a time limit of 3 days of messages. It is up to you to store all of your devices messages on your platform if you want to perform long-term calculations and data analysis. 
  • a rate limit. Read more here: https://support.sigfox.com/docs/api-rate-limiting

Also: 

  • REST verbs. The REST API now fully supports these REST verbs: GET, POST, PUT, DELETE. 
  • OpenAPI spec. The API specification has been normalized to the OpenAPI format using industry-standard tools. 
  • New resources manageable by APIs: users, API users, profiles, customers, orders (read-only). 
  • New features to manage devices and subscription lifecycle. 

Updated Entities 

*Messages* 

The v2 API can only provide the last 3 days of data. 


*New names for endpoint* 

Some operations have been transferred to new endpoints: 

V1 V2
/api/devicetypes/{devicetype-id}/devices?snr={snr} GET /api/device with device type fields
/api/devicetypes/{devicetype-id}/devices/bulk/create/async Moved to device resource POST /devices/bulk
/api/devicetypes/{devicetype-id}/registration/{job-id} GET /devices filtered with device type id which return the PAC per device
/api/devicetypes/{devicetype-id}/id-pac Supported in GET/devices/{id}
/api/devices/{device-id}/token-state Integrated in PUT /devices/{id}
/api/devices/token/forbid-renewal Supported in PUT device not new operation
/api/callbacks/messages/error Covered by Group/DeviceType/Device messages not sent in API v2

See the v1-v2 traceability matrix (.xlsx) for a full overview.


New Entities 

The Sigfox REST API v2 brings the following new entities: 

 

New Services 

The Sigfox REST API v2 brings the following new services: 

 

Removed Operations 

The Sigfox REST API v2 removes the following new services: 

  • Downlink entity. It was mostly administrative functions, not user functions. 
  • Device and DeviceType entities:  

  - status => Transferred to PUT /devices/{id} 

  - count => Should come in roadmap 

  - messages deleted => no message purge by API 

  - token renewal => Supported in PUT device not new operation 

More resources