Once a device sends a message, there are 3 ways to fetch and use the data:

• Web interface on http://backend.sigfox.com
• REST API
• Callback mechanism

The web interface allows to filter data based on timestamp and export the raw data and other metrics (RSSI, TAP that received the message,…) to a .csv file for analysis.

To access the REST API, you need to set up your access first. To do so, go to the ‘Group’ section on http://backend.sigfox.com . In the sidebar, click on ‘API access’ and then click ‘New’ in the top-right corner. You should now see your credentials, and a link to the API documentation relevant to your access rights. Using the API you can :

• Retrieve the list of devices associated to a device type
• Retrieve the messages of a given device
• Get metrics about a device’s messages
• Register devices
• …

Callbacks are the easiest way to get the data from the SIGFOX backend to your own database. You can subscribe to receive a HTTP callback for every message received and processed by the SIGFOX backend.

To set a callback, navigate to the ‘Device Type’ section and select the device type for which you want to create the callback.
If you did not create a device type yet, please follow the separate section about this topic in the FAQ.

Click on ‘Callbacks’ in the left pane.

Create a new callback by clicking ‘New’ in the upper right corner.

SIGFOX provides multiple types of callbacks. For this tutorial we will be using the custom callback.

You can set a separate callback for data-, service- and error- messages. When receiving a callback, the client system must return an HTTP 2xx code within 10 seconds. If the client system fails to process the callback during this time, an automatic retry will be scheduled 1 minute later.

• A data callback can be uplink only (just pushing data to your servers) or bidirectional.
  In case of a bidirectional callback, your server will need to respond with the json formatted hex data that needs to be sent back to the SIGFOX device requesting the downlink.You can also decide not to send any answer to the device, even though it requested data. This allows you to create an ‘almost’ interactive application, without breaking the 4-downlink-per-day rule (note that this does come at a battery-lifetime cost). To do so, you can respond to the callback with the HTTP NO_CONTENT code (204) OR respond with json data containing the noData field set to true.

  You can enter a configuration to define custom variables that will be replaced by the parsed data. You can then use these variables in your callback. To get more information about the format of the configuration, please read the online help, they correspond to the custom automatic decoding when creating a device type.

  The available variables to use in a callback are:

  • device (string): device identifier (in hexadecimal – up to 8 characters <=> 4 bytes)
  • duplicate (bool): «true» if the message is a duplicate one, meaning that the backend has already processed this message from a different base station, «false» otherwise. To receive duplicate messages, you have to check the «send duplicate» box in the callback configuration page
  • snr (float): the signal to noise ratio (in dB – Float value with two maximum fraction digits)
  • rssi (float): the RSSI (in dBm – Float value with two maximum fraction digits). If there is no data to be returned, then the value is null.
  • avgSnr (float): the average signal to noise ratio computed from the last 25 messages (in dB – Float value with two maximum fraction digits) or «N/A». The device must have send at least 15 messages.
  • station (string): the base station identifier (in hexadecimal – 4 characters <=> 2 bytes)
  • data (string): the user data (in hexadecimal)
  • lat (float): the latitude, rounded to the nearest integer, of the base station which received the message
  • lng (float): the longitude, rounded to the nearest integer, of the base station which received the message
  • seqNumber (int): the sequence number of the message if available
• A service callback defines the reception of an operational message from a device.
  It has the following additional status variables next to those available for a data callback:
  • batt (float): the voltage of the battery (in Volt – Float value with two maximum fraction digits)
  • temp (float): the temperature of the device (in °C – Float value with two maximum fraction digits)
  • infocode (int): this is the status code of the downlink
    • 0 (ACKED) the station emitted the answer
    • 1 (NO_ANSWER) the client did not give any answer
    • 2 (INVALID_PAYLOAD) the data to send to the device is invalid,
    • 3 (OVERRUN_ERROR) the device exceeded its daily downlink quota, so it was blocked because of a lower priority than transmissions for devices that did not exceed their quota
    • 4 (NETWORK_ERROR) it was not possible to transmit the answer
    • 5 (PENDING) not technically a code that is sent in the callback because it is a transient state before the answer is sent
    • 6 (NO_DOWNLINK_CONTRACT) the device asked for an answer but its BSS order does not allow downlink
    • 7 (TOO_MANY_REQUESTS) the device asked for an answer before the expiration of the listening time
    • 8 (INVALID_CONFIGURATION) the device type is configured to get data by callback, but no BIDIR callback was defined
  • infomessage (string): a message associated to the code
  • downlinkOverusage (bool): «true» if the device exceeded its daily quota, «false» else.
  • downlinkAck (bool): «true» if the station acknowledged the transmission, «false» else.

• An error callback defines the communication los for a device.
  Custom variables are:
  • info (string): information on error, in case of communication loss, contains the last received message date of the device.
  • severity (string): «ERROR» when it’s a device problem, «WARN» when the network has experienced some issues that could cause some message loss or delay.

There are three mediums the callbacks can be sent to: URL, BATCH_URL and EMAIL.

• EMAIL: You will need to setup a valid e-mail, a subject and the message body. The subject and the body can contain arbitrary text with defined markup which are the name of variables surrounded by brackets for this callback type.
• URL: For URL and BATCH_URL, you will need to implement a RESTful, web-facing service. With URL, each message is directly forwarded in a single HTTP request. You can use a HTTP GET, POST or PUT method, although POST method is recommended.According the type of callback, different variables are available. The available variables list is displayed above the URL field. These variables can be used in 3 places :
  • URL: as path variables or request parameters.
  • Headers: as values of a header. Variables cannot be used in header keys because the format is standardized.
  • Body: If you choose to use the POST or PUT method, you can define a body template that contains variables. These variables are replaced the same way as in URL or Headers.

  GET method, everything inURL (recommended as an easy way to get started):

  GET http://hostname/path?id={device}&time={time}&key1={data}&key2={signal}

  A simple example PHP script that can store the incoming URLs with the set values to a text-file would be:

  $actual_link = “http://$_SERVER[HTTP_HOST]$_SERVER[REQUEST_URI]rn”;
  $file = ‘test.txt’;
  // Open the file to get existing content
  $current = file_get_contents($file);
  // Append the data to the file
  $current .= $actual_link;
  // Write the contents back to the file
  file_put_contents($file, $current);

  In practice you would use $_GET[“name”] to fetch the individual variables.

  POST or PUT method allows you to set the content-type and the body of your request You can choose the content-type between 3 :

  • application/x-www-form-urlencoded
    This is the default content type for a POST or PUT request. When using this content-type, you can set the body in a form encoded format :device={device}&data={data}&time={time}If this format is not respected, it will be rejected. Note that if you put some variables in the query part of the URL, these parameters will be appended to the body, whether it is empty or not. Eg :

    POST http://hostname/path?id={device}&time={time}&key1={data}&key2={signal}

    with a body template:

    device={device}&data={data}&time={time}

    will result in the following body:

    id={device}&time={time}&key1={data}&key2={signal}&device={device}&data={data}&time={time}

  • application/json
    You can set a JSON object in the body:

    {
    “device” : “{device}”,
    “data” : “{data}”,
    “time” : {time}
    }
    
    When this content type is chosen, JSON content is validated. If the content does not respect the JSON standard, it will be rejected.

  • text/plain
    This content type can be freely chosen. No validation is performed (except forbidden characters). Eg:
    
    device => {device}
    data => {data}
    time => {time}
    
    

• BATCH_URL: Messages are gathered together per callbacks, each line representing a message, then sent in batch using a single HTTP request every second. This avoids a possible peak load that your server can’t handle. As the payload contains multiple messages, only HTTP POST method are supported.POST http://hostname/path?batch={batch} where batch={device};{data};{signal};…

If a data-callback is succesfull, you will see a green arrow next to the message like you can see in the following image: