Documentation

Documentation

YourOwn SetupYourOwn SDKYourOwn API
Sphere SetupSphere SDKSphere API
  • Resources

›Collect payload

Introduction

  • Copilot.cx Server API

Reference

  • Collect API
  • Collect payload

    • User events
    • Thing events
    • Custom events
    • Misc. events
    • Preexisting sync events
  • Consent endpoint

Appendix

  • Releases

Custom events

In addition to Predefined events, Copilot.cx supports a variety of User and Thing events that have a predefined set of fields for you to use. Sending a custom event enables you to send additional information, specific to your product and use case that Copilot.cx will use for tracking User/Thing behavior/data so you can engage with users in a contextual way.

Custom events may consist of multiple fields of primitive data types ‒ String, Integer or Boolean. You can enter any value.

In order to so, set the event type to custom_event and add your own subtype to event's payload. Custom event can have custom payload. The example below demonstrates the payload of the collect API event item which is custom event called "sub_type_1" and have two custom properties:

  • my_boolean_property_sub_type1 - An exmaple of a custom property representing a boolean which is set to false.
  • my_int_property_sub_type1 - An exmaple of a custom property representing a integer (number) which is set to 6.

    my_boolean_property_sub_type1 (key & value) and my_int_property_sub_type1(key &value) and subtype (value) are just example of how you can use the custom payload fields for the custom events.

Please refer the user_id and thing_id best practices here.

Event structure

  • Type: custom_event

  • Payload fields:

FieldTypeDescriptionMandatory
subtypeStringrepresents your custom event name.Y
user_idStringYour unique identifier of the User relevant for this event, if known.
thing_idStringYour unique Thing identifier if known.
Any field nameString / Integer / BooleanDescription of the interaction that was performed. Multiple fields can be specified.

At least one field thing_id or user_id should exist in the custom event reporting. Otherwise it would be ignored.

  • Example
    {
      "events": [
        {
          "type": "custom_event",
          "event_id": "3d5a2d51-acf1-46d0-8808-3723c7fcdefb",
          "timestamp": 1559570980484,
          "payload": {
            "my_boolean_property_sub_type1": false,
            "my_int_property_sub_type1": 6,
            "user_id": "325ca496-afe8-4f44-bd37-b0dc90bdfdea",
            "thing_id": "63:64:78:26:b1:c7",
            "subtype": "sub_type_1"
          }
        }
      ]
    }
    
← Thing eventsMisc. events →
Copilot
Mail: hello@copilot.cx
Call: (212).398.0001
© Copilot.cx 2025