TeamViewer IoT Agent MQTT API

1. Introduction


This documentation describes the use of the TeamViewer IoT Agent API. The API uses version 3.1 of the MQTT protocol. The API is based on the publish-subscribe model.
For publish methods that expect a response, a subscribe topic is defined. The API also lets you subscribe to ErrorTopics to receive error messages and ErrorCodes. See Error Code Descriptions for possible errors and their descriptions.
You can find Mosquitto command line examples for all API requests in their descriptions.
Windows: API examples are provided for Command Prompt.

Note: you can use wildcards to subscribe to multiple topics at once. Refer to the MQTT man page under "Wildcard Topic Subscriptions".

2. Placeholder syntax

Placeholders are used to represent variables in topic declarations in the descriptions and examples below. You can identify a placeholder by the starting colon :

The table below describes the placeholder variables used in this documentation.

Placeholder Description
:version API version. Currently, only v1.0 is supported.
:clientId Client ID retrieved from the CommonName attribute of the certificate.
:sensorId Sensor ID retrieved in response to a Create Sensor request or defined by the user in a Push Metric Values request.
:metricId Metric ID retrieved in response to a Create Metric request or defined by the user in a Push Metric Values request.

3. Data model

The API uses a data model consisting of three main components: client, sensor and metric.

Client is the authorized unit that establishes a secure connection to the TeamViewer IoT Agent. All sensors and metrics are uniquely identified within the scope of a client.

Sensor is a logical unit that groups one or more metrics for pushing data to TeamViewer IoT. It is recommended to update all metrics that belong to the same sensor simultaneously to ensure that the data arrives with the same timestamp, so that it is better processed by rule engines.

Metric is the container for the actual value pushed to TeamViewer IoT. The metric must belong to a sensor and can’t exist independently.

4. Client

4.1. Create

Creating a new client and obtaining the client ID is the starting point for establishing a secure connection to the TeamViewer IoT Agent. The Agent only accepts fully authorized connections. To obtain an authorized client certificate, a CSR (Certificate Signing Request) must be generated. The CSR must be published to the TeamViewer IoT Agent. The signed client certificate will be provided back by the Agent through the subscribe topic.

Windows: As OpenSSL is not available in Command Prompt by default, examples using OpenSSL are provided for Git Bash.

Step 1: Generate a CSR

Generate a CSR using OpenSSL or any other similar tool. The certificate must be in PEM encoded format.
The CommonName attribute will be used as a client name. It cannot be empty and may contain only [a-z, A-Z], [0-9] and . * - , @ ' _ symbols.

Please note that after the agent signs the CSR, the CommonName attribute will be replaced with a unique ID, known as the Client ID.

openssl req -nodes -new -newkey rsa:2048 -sha256 -out csr.pem

Step 2: Request a Client Certificate

Publish the CSR created in Step 1 to MQTT API port 18883. Copy the contents of the CSR (csr.pem file generated in Step 1), wrap the text in quotes and send it as the message in the MQTT publish request.
The signed certificate will be sent back through the subscribe topic. Copy the received signed certificate and save as a file (e.g. clientCert.crt) for future use.
The :hash in the subcribe topic is the SHA-256 digest of the certificate signing request created in Step 1.

Publish Topic

/:version/createClient

Get Hash of CSR

openssl dgst -sha256 csr.pem

Subscribe Topic

/certBack/:hash

Error Topic

/certBack/:hash/error

Mosquitto Publish example

mosquitto_pub -h localhost -p 18883 --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/createClient -f csr.pem

Mosquitto Subscribe example

mosquitto_sub -h localhost -p 18883 --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /certBack/83a32b8cbae161ab995b1d3bce24715579c4c672f69ca48a24350baaaed40d17

Success Response

-----BEGIN CERTIFICATE-----
MIIEPjCCAiagAwIBAgIBADANBgkqhkiG9w0BAQsFADBEMQswCQYDVQQGEwJERTEc
MBoGA1UEAwwTVGVhbVZpZXdlckF1dGhvcml0eTEXMBUGA1UECgwOVGVhbVZpZXdl
ckdtYkgwHhcNMTgwMTExMDkyNzQ0WhcNMTkwMTExMDkyNzQ0WjBwMQswCQYDVQQG
EwJERTETMBEGA1UECAwKU29tZS1TdGF0ZTEhMB8GA1UECgwYSW50ZXJuZXQgV2lk
Z2l0cyBQdHkgTHRkMSkwJwYDVQQDDCAwNmE5ZDkyMTllYjk0OTdjOTk1MjE2ZTEz
MGFiNjc0ODCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALxww/Pyulld
+zK2I3EeokpxvmD/y2xS/x0/bDwxbHIl4Apk8CebpZRil+VhtDwHwwkHk90jMuRb
EOeYsXvuoE7r7EUbQnpf8/WO+orLyBwFO0x7BP1GYuene78b9jkWRaKVaek5uhld
N4I3WBKDj2mdxzTS1ZoZIoyFYD5LzCDXcm4igfyEZutHa0757gHNrVRbe3iWNpVY
w9wqoTGPvH2G+Hcvec64hYHccVOuR/UEbcSb553wLnFWKRWLGi6f3WJFGX6tqFw1
QoLyE2p24mrUAqP0/myDbEc+dEPksbYqPunz/0d71jtS+W+/XmTAw5WyLq3D/k8i
NQI/ODzGho0CAwEAAaMPMA0wCwYDVR0PBAQDAgOoMA0GCSqGSIb3DQEBCwUAA4IC
AQA/W3GyvxuZw8GtA+5VoJT5hqBxak3puOAQf1khTqVF1eimOMbgSgcTXWg97LhZ
BoN6ZDrKZDpQmLznR217PCLdErH9/O04ofEkufXWdr10/Sj8u4OGtTOW3rfSsPDV
cACLYMVs+pqJwiTVWLchY0XYrOQ5bUr2qTapaKMF8t3+Do5u1b7cIC1+hf88NTkF
f9laNCICzVhB+RrwACcjeOMXqc/1iha8pdSL6i/J2Y2TxQ99c+0p2Rn31wJv7zBV
1hSUI5U8ixVfWE2UFMsqnPtFE8Y3HRhAHWdWthWkccya5FnFTo7+asPwYoVXkOXP
Vqgcj4NbZVpu7vBkTMmMc6H2a/Ilh1YkuSrGnY1ObVcXLatMfT0yX4fG0fkJD/qV
MMMxY2lclkaTQlePDIjDua1ifHZMFJzCBd95VYpucdKkTizumA7o/YVgbjMO8zfr
bhLkad7N18Y/7QWEjU0hTx362xt3uBXdo/3Kcwu3eK6Giozkdeeaov3wjviSIEY2
zcOee9o8ihr4P0zBbRhXmfLA1CRnp7UMe6AFz9vfLoOb0dj9rfJ1WP4f+njirBox
ooLdsd+d5hTaBO/cCAekbd6+ooAQRQfcDxdMTSu66mjo16QmGEs28+Q5o1NS1l3S
U1c+5xNCrVzI4lYd2jvpatunvtvuyj/S9PEzE1C0dUYR6g==
-----END CERTIFICATE-----

Step 3: Get Client ID

After receiving the certificate, you can retrieve a unique Client ID by parsing the CommonName attribute of the certificate. The client ID is required in every future request through the API.

openssl x509 -noout -subject -in clientCert.crt -nameopt multiline | grep commonName | sed -r 's/commonName/ /g' | sed -r 's/=/ /g' | xargs | tr -d " \t\n\r"

4.2. Connection Check

This publish request checks if the connection to the TeamViewer IoT Agent is alive. A custom JSON message can be sent to verify the connection. If the connection is alive, a response containing the published message will be received back. You must subscribe to the subscribe topic defined below to receive the response.

Success Response

Name Type Description
Message String The same message published to the request.

Publish Topic

/:version/:clientId/ping

Subscribe Topic

/:version/:clientId/ping/info/inbox

Error Topic

/:version/:clientId/ping/error/inbox

Mosquitto Publish example

mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/ping -m  "{ \"request\" : \"Some Message\" }"

Mosquitto Subscribe example

mosquitto_sub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/ping/info/inbox

Success Response

{
   "answer": "Some Message"
}

4.3. Update

This publish request updates the client. JSON message containing the new name must be published to the publish topic.

Success Response

Field Type Description
name String New name of the client.

Publish Topic

/:version/:clientId/update

Subscribe Topic

/:version/:clientId/update/info/inbox

Error Topic

/:version/:clientId/update/error/inbox

Mosquitto Publish example

mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/update -m "{ \"name\" : \"New client name\" }"

Mosquitto Subscribe example

mosquitto_sub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/update/info/inbox

Success Response

"Client name was successfully updated."

4.4. Delete

This publish request deletes the client specified in the publish topic. The request will also result in deletion of the sensors and metrics associated with the client. No message will be given in the response topic. The client authorization certificate will be invalid after this call.

Publish Topic

/:version/:clientId/delete

Mosquitto Publish example

mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/delete -m "{}"

5. Monitoring

5.1. Push Metric Values

This publish request updates metric values. Prior creation of a sensor and metrics is not required. The system checks for the existence of the given sensor and metric IDs. If these don't exist, the system creates the missing sensor or metrics. For newly created metrics and sensors:

  • name is equal to ID
  • value type is automaticaly detected based on metric value (double, string or boolean)
  • value annotation is empty

ID can contain only [a-z, A-Z], [0-9], [ _ - ] symbols, space and has a limitation of maximum 32 characters.
If metric values are successfully updated, the same values are also sent to the livedata topic. Real-time data analysis applications can subscribe to the livedata topic to get metric values and do data analysis.

Message definition

Field Type Description
metrics Array List of metric objects and their updated values.
metricId String Unique metric ID defined by user or received upon registration of a new metric.
value String New metric value.
timestamp optional Long Timestamp (milliseconds since Epoch) of the measurement. Timestamp will be automatically set to current time if not specified.

Publish Topic

/:version/:clientId/sensor/:sensorId/metric/pushValues

Subscribe Topic

/:version/:clientId/sensor/:sensorId/info/inbox

Live Data Topic

/:version/:clientId/sensor/:sensorId/livedata

Error Topic

/:version/:clientId/sensor/:sensorId/error/inbox

Mosquitto Publish example

mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/weather/metric/pushValues -m  "{ \"metrics\": [ {\"value\" : 21.5, \"metricId\" : \"temp\" }, {\"value\" : 21.5, \"metricId\" : \"humidity\" } ] , \"timestamp\": 1590394246545}"

Mosquitto Subscribe example

mosquitto_sub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/weather/info/inbox

Success-Response

"Sensor was updated."

5.2 Sensor

5.2.1. Create

This publish request creates a new sensor. A JSON message containing the name of the new sensor must be published to the topic. A message containing a JSON object with the name of the sensor and a unique ID will be received through the subscribe topic.

Success Response

Name Type Description
sensorId String Unique ID used in API requests to identify the sensor. This ID must be stored and reused by your application.
name String Sensor name - same as sent by the user in the publish request.

Publish Topic

/:version/:clientId/sensor/create

Subscribe Topic

/:version/:clientId/sensor/inbox

Error Topic

/:version/:clientId/sensor/error/inbox

Mosquitto Publish example

mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/create -m  "{ \"name\" : \"SensorName\" }"

Mosquitto Subscribe example

mosquitto_sub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/inbox

Success-Response

{
   "name": "SensorName",
   "sensorId": "d4170d999b9240a5863df622aad9fc4a"
}

5.2.2. List

This publish request returns a list of all sensors and metrics associated with the given client.

Success Response

Name Type Description
name String Sensor name.
sensorId String Sensor ID.
metricId String Metric ID.
link String Topic which can be used to obtain more information about a particular metric.

Publish Topic

/:version/:clientId/sensor/list

Subscribe Topic

/:version/:clientId/inventory/inbox

Error Topic

/:version/:clientId/inventory/error/inbox

Mosquitto Publish example

mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/list -m "{}"

Mosquitto Subscribe example

mosquitto_sub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/inventory/inbox

Success Response

[
   {
      "metrics" : [
         {
            "link" : "/v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/d4170d999b9240a5863df622aad9fc4a/metric/94c2c5e193bb437195368c08f0bd86ab/inventory",
            "metricId" : "94c2c5e193bb437195368c08f0bd86ab"
         },
         {
            "link" : "/v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/d4170d999b9240a5863df622aad9fc4a/metric/94c2c5e193bb437195368c08f0bd86ac/inventory",
            "metricId" : "94c2c5e193bb437195368c08f0bd86ac"
         },
         {
            "link" : "/v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/d4170d999b9240a5863df622aad9fc4a/metric/94c2c5e193bb437195368c08f0bd86ad/inventory",
            "metricId" : "94c2c5e193bb437195368c08f0bd86ad"
         }
      ],
      "name" : "unispeed6",
      "sensorId" : "d4170d999b9240a5863df622aad9fc4a",
      "store" : true
   }
]

5.2.3. Update

This publish lets you update the name and status of the sensor.

Message definition

Name Type Description
name String Name of the sensor.
state optional Integer
  • 1 - Offline
  • 2 - Online

Publish Topic

/:version/:clientId/sensor/:sensorId/update

Subscribe Topic

/:version/:clientId/sensor/:sensorId/update/info/inbox

Error Topic

/:version/:clientId/sensor/:sensorId/update/error/inbox

Mosquitto Publish example

mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/d4170d999b9240a5863df622aad9fc4a/update -m  "{ \"name\" : \"SensorName\" }"

Mosquitto Subscribe example

mosquitto_sub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/d4170d999b9240a5863df622aad9fc4a/update/info/inbox

Success-Response

"Sensor was changed."

5.2.4. Delete

This publish request deletes the sensor specified in the publish topic. After deletion no updates are possible for that sensor.

Publish Topic

/:version/:clientId/sensor/:sensorId/delete

Subscribe Topic

/:version/:clientId/sensor/:sensorId/delete/info/inbox

Error Topic

/:version/:clientId/sensor/:sensorId/delete/error/inbox

Mosquitto Publish example

mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/d4170d999b9240a5863df622aad9fc4a/delete -m  "{}"

Mosquitto Subscribe example

mosquitto_sub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/d4170d999b9240a5863df622aad9fc4a/delete/info/inbox

Success-Response

"Sensor was deleted."

5.3 Metric

5.3.1. Create

This publish request creates new metrics within the sensor specified in the publish topic. The published message must contain the necessary metadata for the metrics, which can be defined in two ways:

Definition over predefined units of values:

When defining a metric with a unit of value that is already defined in the valueUnit table below, the following fields must be present in the JSON message: matchingId, valueUnit and the name of the metric.

Definition over custom defined units of values:

When defining a metric with a custom unit of value, the following fields must be present in the JSON message: matchingId, valueType, name and valueAnnotation. This way of defining a metric gives complete flexibility in what kind of data you want to push to TeamViewer IoT.

Message definition

Field Type Description
metrics Array Lists of metric objects.
matchingId String Used to match data received in the subscribe topic.
name String Name of the metric.
valueUnit String Optional field to define a predefined unit for metric values. The metric type will be a double in the case of these units. Predefined valid units are:
  • SI.ElectricCurrent.AMPERE
  • SI.DataAmount.BIT
  • SI.Temperature.CELSIUS
  • SI.ElectricCapacitance.FARAD
  • SI.Mass.KILOGRAM
  • SI.Frequency.HERTZ
  • SI.Energy.JOULE
  • SI.Length.METER
  • SI.Velocity.METERS_PER_SECOND
  • SI.AmountOfSubstance.MOLE
  • SI.Force.NEWTON
  • SI.ElectricResistance.OHM
  • SI.Pressure.PASCAL
  • SI.Angle.RADIAN
  • SI.Duration.SECOND
  • SI.Area.SQUARE_METRE
  • SI.ElectricPotential.VOLT
  • SI.Power.WATT
  • SI.LuminousIntensity.CANDELA
  • SI.Acceleration.METERS_PER_SQUARE_SECOND
  • NoSI.Dimensionless.PERCENT
  • NoSI.Dimensionless.DECIBEL
  • NoSI.Location.LATITUDE
  • NoSI.Location.LONGITUDE
valueAnnotation String Optional field to define a custom unit for metric values.
valueType String Defines the type of the custom defined unit. Valid entries are:
  • bool
  • string
  • double
  • integer

Success Response

Name Type Description
matchingId String Matches the requested metric with the response metric.
metricId String Unique ID used in API requests to identify the metric. This ID must be stored and reused by your application.

Publish Topic

/:version/:clientId/sensor/:sensorId/metric/create

Subscribe Topic

/:version/:clientId/sensor/:sensorId/metric/inbox

Error Topic

/:version/:clientId/sensor/:sensorId/metric/error/inbox

Mosquitto Publish example

mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/d4170d999b9240a5863df622aad9fc4a/metric/create -m "{\"metrics\" : [{\"matchingId\" : \"1\", \"valueUnit\": \"NoSI.Dimensionless.PERCENT\",  \"name\" : \"CPUUsage\" },{\"matchingId\" : \"2\",\"valueUnit\": \"NoSI.Dimensionless.PERCENT\", \"name\" :\"CPUIdle\" }, {\"matchingId\" : \"3\", \"valueType\" : \"integer\" , \"valueAnnotation\": \"goods per minute\", \"name\" : \"ShopFloor1\"}]}"

Mosquitto Subscribe example

mosquitto_sub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/d4170d999b9240a5863df622aad9fc4a/metric/inbox

Success Response

[
   {
      "matchingId" : "1",
      "metricId" : "94c2c5e193bb437195368c08f0bd86ab"
   },
   {
      "matchingId" : "2",
      "metricId" : "94c2c5e193bb437195368c08f0bd86ac"
   },
   {
      "matchingId" : "3",
      "metricId" : "94c2c5e193bb437195368c08f0bd86ad"
   }
]

5.3.2 Describe

This publish request returns a JSON object containing the metadata definition of the metric specified in the publish topic. The metric must belong to the sensor specified in the publish topic.

Success Response

Name Type Description
lastUpdated String Epoch timestamp in microseconds.
metricId String Metric ID.
name String Metric name.
value String Last value of the metric received by the API.
valueUnit String Present if a metric is defined with predefined units for values.
valueType String Present if a metric is defined with a custom unit for values.
valueAnnotation String Present if a metric is defined with a custom unit for values.

Publish Topic

/:version/:clientId/sensor/:sensorId/metric/:metricId/inventory

Subscribe Topic

/:version/:clientId/sensor/:sensorId/metric/:metricId/inventory/inbox

Error Topic

/:version/:clientId/sensor/:sensorId/metric/:metricId/inventory/error/inbox

Mosquitto Publish example

mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/d4170d999b9240a5863df622aad9fc4a/metric/94c2c5e193bb437195368c08f0bd86ab/describe -m "{}"

Mosquitto Subscribe example

mosquitto_sub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/d4170d999b9240a5863df622aad9fc4a/metric/94c2c5e193bb437195368c08f0bd86ab/inventory/inbox

Success-Response

{
	"lastUpdated" : 9223372036854775,
	"metricId" : "94c2c5e193bb437195368c08f0bd86ab",
	"name" : "CPUUsage",
	"value" : 0.0,
	"valueUnit" : "NoSI.Dimensionless.PERCENT"
}

5.3.3 Update

This publish request updates the name and valueAnnotation of the registered metrics. A JSON message containing the new name, valueAnnotation and respective metric IDs must be published to the publish topic.

Message definition

Field Type Description
metrics Array List of all metric objects to be updated.
metricId String Metric ID.
name optional String Metric name.
valueAnnotation optional String Custom value annotation of the metric.

Publish Topic

/:version/:clientId/sensor/:sensorId/metric/update

Subscribe Topic

/:version/:clientId/sensor/:sensorId/metric/update/info/inbox

Error Topic

/:version/:clientId/sensor/:sensorId/metric/update/error/inbox

Mosquitto Publish example

mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/910f591dd35e424d8303a22b9a50cb0a/metric/update -m "{ \"metrics\": [ {\"metricId\" : \"94c2c5e193bb437195368c08f0bd86ad\", \"name\" : \"metric new name\", \"valueAnnotation\": \"new description of measurement\" } ] }"

Mosquitto Subscribe example

mosquitto_sub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/910f591dd35e424d8303a22b9a50cb0a/metric/update/info/inbox

Success-Response

"All metrics were successfully modified."

5.3.4 Delete

This publish request deletes metrics specified in the publish request JSON message. All metrics specified in the request must belong to the sensor specified in the publish topic. After deletion no updates are possible for the deleted metrics.

Message definition

Field Type Description
metrics Array List of metric objects.
metricId String Metric ID.

Publish Topic

/:version/:clientId/sensor/:sensorId/metric/delete

Subscribe Topic

/:version/:clientId/sensor/:sensorId/metric/delete/info/inbox

Error Topic

/:version/:clientId/sensor/:sensorId/metric/error/inbox

Mosquitto Publish example

mosquitto_pub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/d4170d999b9240a5863df622aad9fc4a/metric/delete -m  "{\"metrics\": [{\"metricId\" : \"94c2c5e193bb437195368c08f0bd86ab\" },{\"metricId\" : \"94c2c5e193bb437195368c08f0bd86ac\" }] }"

Mosquitto Subscribe example

mosquitto_sub -h localhost -p 18884 --cert clientCert.crt --key privkey.pem --cafile /var/lib/teamviewer-iot-agent/certs/TeamViewerAuthority.crt -t /v1.0/6d69c58223fb44a7b76ae61a18faf37c/sensor/d4170d999b9240a5863df622aad9fc4a/metric/delete/info/inbox

Success-Response

"All metrics were successfully deleted."

6. Error Handling

In case a publish message results in an error, an error response will be published to the respective error topic.

Error Response Structure

Name Type Description
errorMessage String Description of the error
errorcode Integer Numerical code for the specific error
metrics Array An optional property, which provides the list of metric IDs for the following errors: 23, 24, 26, 27. See the information about error codes in the table bellow.

Error Codes

Error Code Error Name Description
1 NoBackendConnection Server is not reachable.
2 Reserved Reserved for future use.
3 InternalError Internal Error. Please check the logs at /var/log/teamviewer-iot-agent/teamviewer-iot-agent_logfile.log.
4 InvalidJson Content is not valid JSON.
5 JsonIsNotAnObject Content is not valid JSON.
6 MissingParameter The message you provided does not contain a required key. Please refer to the error message and message definition to fix the error.
7 ParameterIsNotAString The key indicated in the error message is not of type string.
8 ParameterIsNotADouble The key indicated in the error message is not of type double.
9 ParameterIsNotABool The key indicated in the error message is not of type bool.
10 ParameterIsNotAnArray The key indicated in the error message is not an array.
11 ParameterIsNotAnInteger The key indicated in the error message is not of type integer.
12 UnknownValueUnit The provided valueUnit is not valid.
13 UnknownMetricType Only bool, string, double and integer value types are supported.
14 ValueUnitOrValueTypeHasToBeProvided valueUnit or valueType and valueAnnotation is missing.
15 UnknownSensorId The provided sensor ID does not exist.
16 UnknownMetricId The provided metric ID does not exist.
17 NoMetricsUpdated [deprecated] There were errors on every metric provided. No metric was updated.
18 ForbiddenAccess The requested resource does not exist.
19 OutOfRange The frequency value is out of range.
20 CertificateFormatError An error occurred while parsing the certificate signing request.
21 CertificateIsEmptyError The submitted certificate signing request is empty.
22 CertificateWithoutCommonName Cannot retrieve the CommonName attribute from the certificate signing request.
23 DeleteMetricsFailed Failed to delete the following metrics.
24 ChangeMetricsFailed Failed to modify some metrics.
25 InvalidClientName Client name is not valid.
26 CreateMetricsFailed Failed to create the following metrics.
27 PushValuesFailed Failed to push values to some metrics.
28 SensorNameExistsError Sensor name already exists.
Show examples in:
Wobble API Documentation