Thing events · Documentation

Inform the Copilot.cx system of events related to the connected device (Thing).

Please refer the user_id and thing_id best practices here.

Thing Created

Notifies Copilot.cx that a new Thing was created in your system.

Including a user_id in this call does not constitute a User-Thing association (See below).

Type: thing_created
Payload fields:

Field	Type	Description	Mandatory
`thing_id`	String	Your unique Thing identifier. See thing_id.	Y
`user_id`	String	Your unique identifier of the User responsible for the action (described above).
`firmware_version`	String	The firmware version of the Thing.
`model`	String	The hardware model name of the Thing.
`custom_properties`	Dictionary	Custom properties or attributes for a given Thing

Example

{
  "events": [
    {
      "type": "thing_created",
      "event_id": "15775ead-c5d0-4894-b570-e4627e41cd78",
      "timestamp": 1559570638730,
      "payload": {
        "thing_id": "63:64:78:26:b1:c7",
        "custom_properties": {
          "default_state": "rectangle",
          "length": 20.5,
          "is_upgraded": false
        }
      }
    }
  ]
}

Thing Updated

Notifies Copilot.cx that a Thing was updated in your system.

Type: thing_updated
Payload fields:

Field	Type	Description	Mandatory
`thing_id`	String	Your unique Thing identifier. See thing_id.	Y
`user_id`	String	Your unique identifier of the User responsible for the action (described above).
`firmware_version`	String	The firmware version of the Thing.
`model`	String	The hardware model name of the Thing.
`custom_properties`	Dictionary	Custom properties or attributes for a given Thing

Example

{
  "events": [
    {
    "type": "thing_updated",
      "event_id": "f6496fdd-deb4-4d85-9af6-f947964c84fa",
      "timestamp": 1559627990338,
      "payload": {
        "firmware_version": "14.52",
        "thing_id": "07:1c:9f:92:70:71",
        "custom_properties": {
          "chipset_type": "Intel",
          "height": 20.5,
          "is_max": false
        }
      }
    }
  ]
}

Thing Associated

Notifies Copilot.cx of an association between a User and a Thing in Copilot.

Type: user_thing_associated
Payload fields:

Field	Type	Description	Mandatory
`user_id`	String	Your unique identifier of the User to be associated with the `thing_id` in Copilot.cx (described below)	Y
`thing_id`	String	Your unique identifier of the Thing to be associated with the `user_id` in Copilot.cx (described above)	Y

Example

{
  "events": [
    {
      "type": "user_thing_associated",
      "event_id": "d8a4ee55-da8f-4f0a-99b7-3f48629462fd",
      "timestamp": 1559570638730,
      "payload": {
        "user_id": "325ca496-afe8-4f44-bd37-b0dc90bdfdea",
        "thing_id": "63:64:78:26:b1:c7"
      }
    }
  ]
}

Thing Disassociated

Notifies Copilot.cx of an disassociate between a User and a Thing in Copilot.

Type: user_thing_dissociated
Payload fields:

Field	Type	Description	Mandatory
`user_id`	String	Your unique identifier of the User to be disassociated with the `thing_id` in Copilot.cx (described below)	Y
`thing_id`	String	Your unique identifier of the Thing to be disassociated with the `user_id` in Copilot.cx (described above)	Y

Example

{
  "events": [
    {
      "type": "user_thing_dissociated",
      "event_id": "d8a4ee55-da8f-4f0a-99b7-3f48629462fd",
      "timestamp": 1559570638730,
      "payload": {
        "user_id": "325ca496-afe8-4f44-bd37-b0dc90bdfdea",
        "thing_id": "63:64:78:26:b1:c7"
      }
    }
  ]
}

Thing Status Changed

Notifies Copilot.cx about a status change of a Thing, as specified by the status_key field. For example, a status may represent the battery level.

Type: thing_status_changed
Payload fields:

Field	Type	Description	Mandatory
`thing_id`	String	Your unique identifier of the Thing whose status changed. See thing_id.	Y
`status_key`	String	Specifies a unique identifier of the status of a Thing. Status values are retained in Copilot.cx according to the string specified here.	Y
`status_value`	String	Specifies the value of the `status_key` (described above). This value is a string, even though it can be used to specify numbers.	Y
`status_date`	Date	Specifies the timestamp of the `status_value` (described above).	Y
`user_id`	String	Your unique identifier of the User of the Thing whose status changed, if known.

Only a single status_key, status_value and status_date field can be specified in each request.

Example

{
  "events": [
    {
      "type": "thing_status_changed",
      "event_id": "d8a4ee55-da8f-4f0a-99b7-3f48629462fd",
      "timestamp": 1559570638730,
      "payload": {
        "thing_id": "63:64:78:26:b1:c7",
        "status_key": "battery",
        "status_value": "50",
        "status_date": 1559570238730
      }
    }
  ]
}

Thing Interaction

Notifies Copilot.cx about an interaction that occurred on a Thing, such as pressing a button on the Thing, powering on the Thing and

Type: thing_interaction
Payload fields:

Field	Type	Description	Mandatory
`thing_id`	String	Your unique identifier of the Thing on which an interaction occurred.	Y
`user_id`	String	Your unique identifier of the User of the Thing whose status changed, if known.
Any other field	String	Any custom field describing the interaction that was performed. Multiple fields can be specified.

my_custom_interaction_int_value and my_custom_interaction_name are just example of how you can use the custom fields for the thing_interaction event.

Example

{
  "events": [
    {
      "type": "thing_interaction",
      "event_id": "d1d777e1-98f6-4b7d-998c-85cb756f4320",
      "timestamp": 1559570974642,
      "payload": {
        "my_custom_interaction_int_value": 98,
        "my_custom_interaction_name": "MyCoolInteraction",
        "thing_id": "63:64:78:26:b1:c7"
      }
    }
  ]
}

Thing Connected

Notifies Copilot.cx that a thing was connected.

Type: thing_connected
Payload fields:

Field	Type	Description	Mandatory
`thing_id`	String	Your unique identifier of the Thing on which an interaction occurred.	Y
`user_id`	String	Your unique identifier of the User of the Thing whose status changed, if known.

Example

{
  "events": [
    {
      "type": "thing_connected",
      "event_id": "d1d777e1-98f6-4b7d-998c-85cb756f4320",
      "timestamp": 1559570974642,
      "payload": {
        "thing_id": "63:64:78:26:b1:c7"
      }
    }
  ]
}

Consumable Usage

Trigger this event in case your product has a consumable element (paper, cartridge, razor, etc…) and a user consumes it. This will later be used to identify consumable usage patterns and deviations from these patterns.

Type: consumable_usage
Payload fields:

Field	Type	Description	Mandatory
`thing_id`	String	Your unique identifier of the Thing on which an interaction occurred.	Y
`consumable_type`	String	The types of consumables (e.g. paper/cartrige/razor etc.)
`user_id`	String	Your unique identifier of the User of the Thing whose status changed, if known.

Example

{
  "events": [
    {
      "type": "consumable_usage",
      "event_id": "d1d777e1-98f6-4b7d-998c-85cb756f4320",
      "timestamp": 1559570974642,
      "payload": {
        "thing_id": "63:64:78:26:b1:c7",
        "consumable_type": "CoffeePod"
      }
    }
  ]
}

Firmware Upgrade Started

Trigger this event at the beginning of a firmware upgrade process.

Type: firmware_upgrade_started
Payload fields:

Field	Type	Description	Mandatory
`thing_id`	String	Your unique identifier of the Thing on which an interaction occurred.	Y
`firmware_version`	String	The version of the new firmware
`user_id`	String	Your unique identifier of the User of the Thing whose status changed, if known.

Example

{
  "events": [
    {
      "type": "firmware_upgrade_started",
      "event_id": "d1d777e1-98f6-4b7d-998c-85cb756f4320",
      "timestamp": 1559570974642,
      "payload": {
        "thing_id": "63:64:78:26:b1:c7",
        "firmware_version": "17.52"
      }
    }
  ]
}

Firmware Upgrade Completed

Trigger upon firmware upgrade completion.

Type: firmware_upgrade_completed
Payload fields:

Field	Type	Description	Mandatory
`thing_id`	String	Your unique identifier of the Thing on which an interaction occurred.	Y
`firmware_version`	String	The version of the new firmware	Y
`result`	String	The resulting status of the firmware upgrade process : `success` / `device_unavailable` / `incomplete` / `failed`	Y
`user_id`	String	Your unique identifier of the User of the Thing whose status changed, if known.

Example

{
  "events": [
    {
      "type": "firmware_upgrade_completed",
      "event_id": "d1d777e1-98f6-4b7d-998c-85cb756f4320",
      "timestamp": 1559570974642,
      "payload": {
        "thing_id": "63:64:78:26:b1:c7",
        "firmware_version": "17.53",
        "result": "success"
      }
    }
  ]
}