IoT Creators Integration

IoT Creators Integration receives device data from the IoT Creators platform, the NB-IoT and LTE-M connectivity service of Deutsche Telekom. IoT Creators sends each uplink to ThingsBoard as an HTTP callback, and an uplink data converter transforms it into device data, including telemetry and attributes. In ThingsBoard, the integration type is called iotcreators.com (T-Mobile – IoT CDP). The integration is uplink-only: to send data to devices, a rule chain calls the IoT Creators API.

Use IoT Creators Integration when:

Your NB-IoT or LTE-M devices use IoT Creators SIM cards and send their data to the IoT Creators platform.
One callback URL must serve every device in an IoT Creators project: the converter resolves each device from its IMEI.

Architecture

Receive data. The device sends an uplink to the IoT Creators platform. IoT Creators sends it as an HTTP POST with a JSON body to the integration endpoint. The body holds a reports array; each report carries the device IMEI and the device payload as a hex string.
Decode the payload. The uplink converter reads each report, sets the device name from the IMEI, and decodes the payload into telemetry and attributes.
Process the message. ThingsBoard processes the converted data through the Rule Engine. If Allow create devices or assets is on, ThingsBoard creates the device on its first uplink.
Respond. The endpoint answers 200 OK once the data is processed.

To send data to devices, see Downlink to Devices.

Prerequisites

Access to ThingsBoard or ThingsBoard Cloud with integrations enabled for your tenant. The ThingsBoard endpoint must be reachable from the internet, because the IoT Creators platform calls it.
Permission to create integrations and data converters.
An IoT Creators account with a project and a SIM card, for example from a Starterkit.
An NB-IoT or LTE-M device that sends its payload to the IoT Creators platform, and its IMEI.

Prepare IoT Creators

Register the Device

IoT Creators forwards uplinks only from devices registered in the project. Register the device before it sends data.

Log in to the IoT Creators portal and open your project, for example Starterkit.
Click REGISTER DEVICE.
Enter the device IMEI.
Select the communication protocol. IoT Creators recommends UDP for NB-IoT modules.
Confirm the registration.

The device appears in the device list of the project. Its last message and payload stay empty until the device sends its first uplink.

Uplink Message Format

IoT Creators sends every device uplink to the callback URL as a JSON body. This guide uses the callback for an IMBUILDINGS Comfort Sensor, which measures temperature, humidity, CO₂, battery voltage, and presence:

{
  "reports": [
    {
      "serialNumber": "IMEI:866425033313638",
      "timestamp": 1600439712734,
      "subscriptionId": "fa37d89c-a7e2-4f3d-b12f-6002a3642b4c",
      "resourcePath": "uplinkMsg/0/data",
      "value": "0101d880396f026e000158a50a4b121503d301"
    }
  ],
  "registrations": [],
  "deregistrations": [],
  "updates": [],
  "expirations": [],
  "responses": []
}

reports — one entry per device uplink. A callback can hold several entries.
serialNumber — the device IMEI with the IMEI: prefix.
timestamp — the time IoT Creators received the uplink, in Unix milliseconds.
resourcePath — uplinkMsg/0/data for a device uplink.
value — the device payload as a hex string. Its byte layout is defined by the device manufacturer.

The value above decodes to status = 0, batteryVoltage = 3.44, temperature = 26.35, humidity = 46.29, co2 = 979, and presence = true. The byte layout is described in the IMBUILDINGS Comfort Sensor documentation.

Set Up IoT Creators Integration

Create the uplink converter and the integration, then set the integration endpoint as the callback URL of your IoT Creators project.

Create the Uplink Data Converter

The uplink converter parses the callback body and decodes the hex payload of each report. IoT Creators Integration uses the Generic converter: you write the decoder in TBEL or JavaScript. For converter types and the full decoder reference, see Uplink data converter.

The decoder in this guide maps:

serialNumber without the IMEI: prefix ⇾ device name NB-IoT-<IMEI>.
timestamp ⇾ telemetry timestamp.
Bytes of value ⇾ telemetry status, batteryVoltage, temperature, humidity, co2, and presence.
serialNumber, subscriptionId, and resourcePath ⇾ attributes, together with the fixed attribute model = Comfort Sensor.

Go to Integrations ⇾ Data converters and click + Add data converter ⇾ Create new converter.
Converter type — keep Uplink.
Integration type — select iotcreators.com (T-Mobile – IoT CDP).
Name — enter a name, for example IoT Creators Uplink Converter.

Main decoding configuration — the editor opens with the generic decoder template, which does not read the reports array. Replace it with the decoder below. The editor opens in TBEL; use the TBEL / JS toggle to switch to JavaScript.

TBEL (Recommended)
JavaScript

// Decode an IoT Creators callback
// payload - array of bytes (the callback body)
// metadata - key/value object

/** Decoder **/

var data = decodeToJson(payload);
var reports = data.reports != null ? data.reports : [];
var result = [];

for (var i = 0; i < reports.size(); i++) {
  var report = reports[i];

  // Decode only device uplinks.
  if (report.resourcePath == "uplinkMsg/0/data" && report.value != null) {
    // The device payload is a hex string.
    var bytes = hexToBytes(report.value);

    // The Comfort Sensor payload is 19 bytes long.
    if (bytes.size() >= 19) {
      // IoT Creators identifies the device by "IMEI:<imei>".
      var serialNumber = "" + report.serialNumber;
      var imei = serialNumber.replace("IMEI:", "");

      var entry = {
        deviceName: "NB-IoT-" + imei,
        deviceType: "NB-IoT sensor",
        attributes: {
          serialNumber: serialNumber,
          subscriptionId: report.subscriptionId,
          resourcePath: report.resourcePath,
          model: "Comfort Sensor"
        },
        telemetry: {
          ts: report.timestamp,
          values: {
            status: bytes[8] & 0xFF,
            batteryVoltage: (((bytes[9] & 0xFF) << 8) | (bytes[10] & 0xFF)) / 100.0,
            temperature: (((bytes[12] & 0xFF) << 8) | (bytes[13] & 0xFF)) / 100.0,
            humidity: (((bytes[14] & 0xFF) << 8) | (bytes[15] & 0xFF)) / 100.0,
            co2: ((bytes[16] & 0xFF) << 8) | (bytes[17] & 0xFF),
            presence: (bytes[18] & 0xFF) == 1
          }
        }
      };
      result.add(entry);
    }
  }
}

/** Helper functions 'decodeToJson' and 'hexToBytes' are already built-in **/

return result;

// Decode an IoT Creators callback
// payload - array of bytes (the callback body)
// metadata - key/value object

/** Decoder **/

var data = decodeToJson(payload);
var reports = data.reports || [];
var result = [];

for (var i = 0; i < reports.length; i++) {
  var report = reports[i];

  // Decode only device uplinks.
  if (report.resourcePath === "uplinkMsg/0/data" && report.value != null) {
    // The device payload is a hex string.
    var bytes = hexToBytes(report.value);

    // The Comfort Sensor payload is 19 bytes long.
    if (bytes.length >= 19) {
      // IoT Creators identifies the device by "IMEI:<imei>".
      var serialNumber = String(report.serialNumber);
      var imei = serialNumber.replace("IMEI:", "");

      result.push({
        deviceName: "NB-IoT-" + imei,
        deviceType: "NB-IoT sensor",
        attributes: {
          serialNumber: serialNumber,
          subscriptionId: report.subscriptionId,
          resourcePath: report.resourcePath,
          model: "Comfort Sensor"
        },
        telemetry: {
          ts: report.timestamp,
          values: {
            status: bytes[8],
            batteryVoltage: ((bytes[9] << 8) | bytes[10]) / 100,
            temperature: ((bytes[12] << 8) | bytes[13]) / 100,
            humidity: ((bytes[14] << 8) | bytes[15]) / 100,
            co2: (bytes[16] << 8) | bytes[17],
            presence: bytes[18] === 1
          }
        }
      });
    }
  }
}

/** Helper functions **/

function decodeToString(payload) {
  return String.fromCharCode.apply(String, payload);
}

function decodeToJson(payload) {
  return JSON.parse(decodeToString(payload));
}

function hexToBytes(hex) {
  var bytes = [];
  for (var j = 0; j < hex.length; j += 2) {
    bytes.push(parseInt(hex.substr(j, 2), 16));
  }
  return bytes;
}

return result;

To adapt:

Another device — replace the byte offsets (8, 9–10, 12–13, and so on), the / 100 scaling, and the 19-byte length check with the values from your device’s payload specification.
Device name — replace "NB-IoT-" + imei to use the bare IMEI or another identifier.
Base64 payload — if value holds Base64 instead of hex, decode it with base64ToBytesList(report.value) in TBEL, or atob() and charCodeAt() in JavaScript.
Timestamp — remove ts to use the time ThingsBoard receives the callback.
Attributes — add or remove fields in attributes. Keep values that change with every uplink in telemetry.

Click Test decoder function and check the result (see Test the Decoder).
Click Add.

Decoder Inputs

The decoder signature is function decoder(payload, metadata): object | object[].

Variable	Type	Content
`payload`	byte array	The callback body, as compact JSON.
`metadata`	`{[key: string]: string}`	`integrationName` and the key–value pairs from the integration’s Metadata field. Request headers are not passed.

Return an array to create data for several devices from one callback. Return an empty array ([]) when the callback holds no device uplinks, for example when reports is empty.

Built-in helpers:

Function	Result
`decodeToJson(payload)`	Parses the bytes as JSON and returns an object. In JavaScript, the decoder above defines it.
`hexToBytes(hex)`	TBEL only. Converts a hex string to a list of bytes. Bytes are signed: mask them with `& 0xFF` before you combine them. The JavaScript decoder above defines its own `hexToBytes`, which returns unsigned values.
`base64ToBytesList(base64)`	TBEL only. Converts a Base64 string to a list of bytes, like `hexToBytes`.

For other scripting patterns, see Common scripting patterns.

Test the Decoder

Click Test decoder function below the editor. Keep Payload content type set to JSON, replace the payload with the callback body from Uplink Message Format, and click Test. The Output panel shows:

[
  {
    "deviceName": "NB-IoT-866425033313638",
    "deviceType": "NB-IoT sensor",
    "attributes": {
      "serialNumber": "IMEI:866425033313638",
      "subscriptionId": "fa37d89c-a7e2-4f3d-b12f-6002a3642b4c",
      "resourcePath": "uplinkMsg/0/data",
      "model": "Comfort Sensor"
    },
    "telemetry": {
      "ts": 1600439712734,
      "values": {
        "status": 0,
        "batteryVoltage": 3.44,
        "temperature": 26.35,
        "humidity": 46.29,
        "co2": 979,
        "presence": true
      }
    }
  }
]

Check that deviceName holds the IMEI and telemetry.values holds the expected keys. If the output is an empty array, check resourcePath and the length of value. If it shows an error, fix the decoder and test again.

Create the Integration

The wizard has no downlink step, because the integration only receives data.

Go to Integrations ⇾ Integrations and click + Add integration.
Basic settings:
- Integration type — select iotcreators.com (T-Mobile – IoT CDP).
- Name — keep the default iotcreators.com (T-Mobile – IoT CDP) integration or enter your own.
- Enable integration and Allow create devices or assets — keep both on, so the device is created on its first uplink.
- Click Next.
Uplink data converter:
- Click Select existing and choose IoT Creators Uplink Converter.
- Alternatively, click Create new to write a decoder here.
- Click Next.
Connection:
- Copy the HTTP endpoint URL. You need it for the IoT Creators callback.
- Leave the other parameters at their defaults. See Connection Settings for details.
Click Add.

Connection Settings

Parameter	Default	Description
Base URL	Address of your ThingsBoard server	Used to build the endpoint URL. Example: `https://thingsboard.cloud`. Required.
HTTP endpoint URL	—	Read-only. Format: `{Base URL}/api/v1/integrations/tmobile_iot_cdp/{integrationKey}`, where `integrationKey` is a UUID assigned at creation. A request with `Content-Type: application/json` is processed as an uplink. A request with `Content-Type: text/plain`, such as a validation request, gets `200 OK` and is not processed. Other content types are rejected.
Execute remotely	Off	Runs the integration as a separate process outside the ThingsBoard cluster. ThingsBoard generates an Integration key and Integration secret for it. IoT Creators needs a public endpoint, so the standard setup keeps this off. See Remote Integration.
Replace response status from ‘No-Content’ to ‘OK’	Off	In Advanced settings. Has no effect on this integration: the endpoint answers every processed callback with `200 OK`, also when the decoder returns no data.
Description	—	In Advanced settings. Free-text description.
Metadata	—	In Advanced settings. Key–value pairs added to the `metadata` of every message from this integration.

Set the Callback URL in IoT Creators

The callback URL forwards the uplinks of every device in the project to the integration endpoint. To stop forwarding, set the toggle to off and click Save.

Sign in to the IoT Creators portal.
Open Projects, select your project, and open the YOUR APPLICATION SERVER tab.
Paste the HTTP endpoint URL of the integration into the CALLBACK URL field.
Set the endpoint toggle to ON and click Save.

Test Uplink

Send an uplink, then confirm that ThingsBoard decoded it and created the device.

Send a Test Uplink

Switch on the registered device and wait for its first uplink. IoT Creators forwards it to the callback URL.

To test without a device, send a callback in the Uplink Message Format to the endpoint with curl. Replace $HTTP_ENDPOINT_URL with the HTTP endpoint URL and run:

curl -v -X POST "$HTTP_ENDPOINT_URL" \
  -H "Content-Type: application/json" \
  -d '{"reports":[{"serialNumber":"IMEI:866425033313638","timestamp":1792660558000,"subscriptionId":"fa37d89c-a7e2-4f3d-b12f-6002a3642b4c","resourcePath":"uplinkMsg/0/data","value":"0101d880396f026e000158a50a4b121503d301"}],"registrations":[],"deregistrations":[],"updates":[],"expirations":[],"responses":[]}'

The endpoint returns 200 (HTTP/2 200 on ThingsBoard Cloud). ThingsBoard stores the telemetry with the time in timestamp, in Unix milliseconds. Change it to the current time to see the data as the latest values.

Verify the Result

Integration events — go to Integrations ⇾ Integrations, open the integration, and click the Events tab. The callback appears as an event of type Uplink with status OK. Click ⋅⋅⋅ in the Message column to see the received body.
Converter events — open IoT Creators Uplink Converter in Integrations ⇾ Data converters and click the Events tab. In shows the callback body, Out shows the decoded result, and Metadata holds only integrationName. Request headers are not passed.
Device — go to Devices & assets ⇾ Devices. The integration has created a device named NB-IoT-<IMEI> with the NB-IoT sensor profile, for example NB-IoT-866425033313638. Open it and check status, batteryVoltage, temperature, humidity, co2, and presence on the Latest telemetry tab, and serialNumber, subscriptionId, resourcePath, and model on the Attributes tab.

Downlink to Devices

IoT Creators Integration does not send downlinks. It has no downlink converter, and the wizard has no downlink step. To send data to a device, call the IoT Creators API. It queues the message for the device:

Request — PUT https://api.scs.iot.telekom.com/m2m/endpoints/{serialNumber}/downlinkMsg/0/data, where serialNumber is the device IMEI with the IMEI: prefix, for example IMEI:866425033313638.
Authentication — HTTP Basic, with the credentials of your IoT Creators API user. The API user must have a registered application URL.
Body — {"resourceValue": "<value>"}, with Content-Type: application/json.
Response — 202 Accepted. IoT Creators queues up to 10 downlinks per device, each up to 512 bytes.

For details, see the IoT Creators API documentation.

Send a Downlink from the Rule Engine

Call the IoT Creators API from a rule chain with a rest api call node. In this example, every change of a shared attribute on the device is sent to it as a downlink. The rule chain keeps only shared attribute updates, reads the device IMEI from the serialNumber attribute that the decoder stores, packs the changed attributes into resourceValue as JSON, and calls the API.

Go to Data processing ⇾ Rule chains and open the Root Rule Chain.
From the Filter section, drag a script node onto the canvas:
- Name — Shared attributes only.
- Replace the script with return metadata.scope == 'SHARED_SCOPE';. Client and server attributes, such as the ones the decoder stores, stay in ThingsBoard.
- Click Add.
From the Enrichment section, drag an originator attributes node onto the canvas:
- Name — Add IMEI.
- Client attributes — serialNumber. The node adds it to the metadata as cs_serialNumber.
- Click Add.

From the Transformation section, drag a script node onto the canvas:

Name — Build downlink body.

Replace the script with:

// IoT Creators takes one string per downlink.
// Send the changed shared attributes as JSON, for example {"temperatureUploadFrequency":60}.
return {
    msg: { resourceValue: JSON.stringify(msg) },
    metadata: metadata,
    msgType: msgType
};

Click Add.

From the External section, drag a rest api call node onto the canvas:
- Name — Send to IoT Creators.
- Endpoint URL pattern — https://api.scs.iot.telekom.com/m2m/endpoints/${cs_serialNumber}/downlinkMsg/0/data.
- Request method — PUT.
- Headers — Content-Type = application/json.
- Credentials — set Credentials type to Basic and enter the username and password of your IoT Creators API user. The default Anonymous sends no credentials.
- Click Add.
Connect the nodes:
- message type switch ⇾ Shared attributes only with the Attributes Updated relation.
- Shared attributes only ⇾ Add IMEI with the True relation.
- Add IMEI ⇾ Build downlink body with the Success relation.
- Build downlink body ⇾ Send to IoT Creators with the Success relation.
Click Apply changes.

To send a downlink, open the device, go to Attributes, select Shared attributes, and add or update an attribute, for example temperatureUploadFrequency = 60. Turn on Debug for Send to IoT Creators: on success, its Events tab shows an event with the Success relation, and IoT Creators answers 202 Accepted. On failure, the event has the Failure relation, and its metadata holds statusCode, status, error, and error_body with the response of IoT Creators.