Collect API

Overview

The Collect API enables you to send Thing and User data from your server to Copilot.cx so that it appears in the Copilot.cx Web Portal and enables engagement functionality.

The Report endpoint sends an Events array containing one or more events. The following kinds of events can be sent:

• User events
• Thing events
• Custom events
• Other Misc. events
• Preexisting syne events

Common Collect API Fields

Each event in the Events array may contain the following common fields:

type

This is a mandatory field that defines the type of event. For example, user_created. Each type of event may have different mandatory and optional fields.

payload

Contains the primary content to be transferred by an event. The payload field contains one or more fields (some are mandatory and some optional). These fields are described in the tables below.

user_id and thing_id

Practices for your unique identifier for a User or for a Thing:

• Each User identifier must also be unique and persistent. Normally it would be the same UUID you would use in your user management system, so you can correlate the information from Copilot.cx and your own user management.

• Each Thing identifier must uniquely represent a specific physical device. Therefore, we recommend using an identifier that is uniquely embedded, printed on or associated with the physical device, such as a MAC address or serial number (as opposed to using identifiers that only exist in the data world).

• The User identifier (user_id) that is sent from a mobile device’s application using the Copilot.cx SDK should have the same user identifier as was used in the mobile device application and sent to the Copilot.cx cloud via Firebase™.

• Unique identifiers for Users and Things are required when reporting events so that the activity described in the event can be attributed to the relevant User or Thing.

• If an endpoint is received for a user_id or thing_id that was not previously created in Copilot, then Copilot.cx automatically creates it. For example, for user_updated, thing_update, user_thing_associated or thing_interaction.

• Copilot.cx retains the latest data for each entity. For example, if multiple user_updated endpoints are received specifying the same user_id, then the endpoint with the latest timestamp received by Copilot.cx overwrites and determines the User’s data, such as the User’s email. The same goes for Things (thing_id).

event_id

A unique identifier that you provide with each event sent to Copilot.cx Report. This ID enables tracking of the event for future reference, if needed. This event_id is particularly important when an invalid event message is returned by Copilot.cx Report. This unique event identifier enables you to analyze the problem and resend the event to Copilot, if necessary.

timestamp

UNIX EPOCH timestamps in milliseconds (starting from 01/01/1970 UTC).

Field validation constraints on the timestamp field:

• Must be in milliseconds.
• Must be during the last 30 days.
• Cannot be a future date.

custom_properties

A dictionary which contains all other properties and attributes for a user.
These properties can be used to target and segment the users later, through Copilot.CX system.
As a guideline - fast-changing (statues, is_switched_on) or high-variance (pet_name, uniqe_id) properites should not be sent here, but as a seperate event.
Field validation constraints on the custom_properties field:

• Values can be only primitive (string, float, boolean).
• Cannot have keys which can be sent as another defined field (timestamp, event_id, user_id, type, thing_id, payload, utc_offest)
  • Specifically in user events - first_name, last_name
  • Specifically in thing events - model, firmware_version

General Field Value Constraints

For the following fields ‒ event_id, user_id, thing_id, first_name, last_name and email:

• Maximum String Length ‒ 50
• Supported Characters ‒ Supports all Latin extended, including the following special characters: : - . _ + @
• The following characters are not supported: < > { } [ ] ; # & ( ) $ | ^ \ / , * = % ! ~ "

For the following fields ‒ status_name, status_value and sub_type:

• Maximum String Length ‒ 50

Request

• End point : https://report.<YOUR_ENVIRONMENT>.bycopilot.com/v2/collect
• HTTP Method : POST
• HTTP Headers:
  • Content-Type : application/json
  • Authorization: Basic $YOUR_AUTH_DATA_HERE$
• Example of HTTP Request:

  {
    "events": [
      {
        "type": "user_created",
        "event_id": "5139f606-a47b-45b9-8fa2-20d1576950be",
        "timestamp": 1559570628993,
        "payload": {
          "email": "juanita.pagac43@mailinator.com",
          "first_name": "Juanita",
          "last_name": "Pagac",
          "user_id": "325ca496-afe8-4f44-bd37-b0dc90bdfdea",
          "copilot_analysis_consent": true,
          "utc_offset": "-0500",
          "custom_properties": {
            "subscription": "premium",
            "is_user_external": true,
            "category": 5
          }
        }
      }
    ]
  }

Response

Success response

Success:

{
  "invalid_events": []
}

Error response

Failure (in case of missing a mandatory property):

• Case of missing "timestamp" property:

{
  "invalid_events": [
    {
      "event_id": "f6a1c1d2-7932-414b-a480-31ea08d97200",
      "index": 0,
      "error": "Event missing field: timestamp."
    }
  ]
}

• Case of unrecognized event type:

{
  "invalid_events": [
    {
      "event_id": "d459b177-9afc-498c-984e-4ba6fb0aa249",
      "index": 0,
      "error": "Event type not recognized."
    }
  ]
}

Error response general structure

{
    "reason": enum,
    "error_message": string
}

Possible errors:

• HTTP code: 405

{
    "reason": "COMMON.INVALID_METHOD"
}

• HTTP code: 400

{
    "reason": "COMMON.REQUEST_VALIDATION",
    "error_message": "Request missing field: 'events'."
}

• HTTP code: 400

{
    "reason": "COMMON.REQUEST_VALIDATION",
    "error_message": "The field 'events' must be an array."
}

• HTTP code: 400

{
    "reason": "COMMON.REQUEST_VALIDATION",
    "error_message": "The field 'events' must be an array containing between 1-200."
}

• HTTP code: 400

{
    "reason": "COMMON.REQUEST_VALIDATION",
    "error_message": "The header 'content-type' must be 'application/json'."
}

• Not bearer or basic token - HTTP code: 401

{
    "reason": "AUTH.UNAUTHORIZED"
}

• Invalid token - HTTP code: 401

{
    "reason": "AUTH.UNAUTHORIZED"
}

• Token expired - HTTP code: 401

{
    "reason": "AUTH.UNAUTHORIZED"
}

• Invalid user role - HTTP code: 403

{
    "reason": "AUTH.INVALID_PERMISSIONS"
}

Success response structure:

HTTP code: 200

{
  "Invalid_events": Array<InvalidEvent>
}

• Invalid event structure:

If event id exists:

{
    "event_id": string,
    "index": number, // index in the original array
    "error": string
}

If event id doesn’t exists:

{
    "index": number, // index in the original array
    "error": string
}

Error handling

Possible errors due to invalid events:

• "Event missing field: {field_name}"

• "Payload missing field: {field_name}"

• "Payload has unknown fields. (note: {field_name})"

• "Payload should not have more than 20 keys."

• "Payload must be an object."

• "Event structure is invalid."

• "Event type not recognized."

• "Event timestamp must be a number. (note: timestamp must be in ms)"

• "Event timestamp must be a positive number. (note: timestamp must be in ms)"

• "Event timestamp invalid. (note: timestamp must be in ms)"

• "Event timestamp cannot be more than 30 days ago. (note: timestamp must be in ms)"

• "Event timestamp cannot be in the future. (note: timestamp must be in ms)"

• "status_date must be a number. (note: timestamp must be in ms)"

• "status_date must be a positive number. (note: timestamp must be in ms)"

• "status_date invalid. (note: timestamp must be in ms)"

• "Event cannot be null."

• "Event must be an object."

• "{field_name} contains invalid characters. (note: specials characters are limited to: [':', '-', '.', '_', '+', '@'])"

• "{field_name} length invalid. (note: 0-50)"

• "custom_properties cannot have objects or arrays as values."

Field validation

Field name	Valid string	Valid string length	Valid character	Valid timestamp	Valid dictionary
thing_id	V	V	V	X	X
user_id	V	V	V	X	X
firmware_version	V	X	X	X	X
model	V	X	X	X	X
status_key	V	V	X	X	X
status_value	V	V	X	X	X
status_date	X	X	X	V	X
first_name	V	V	V	X	X
last_name	V	V	V	X	X
email	V	V	V	X	X
subtype	V	V	X	X	X
utc_offset	V	V	V	X	X
custom_properties	X	X	X	X	V