Bot users

Information about the users of a bot can be retrieved from the following endpoint:

Endpoint

GET <base URL>/projects/<project id>/users/properties

Parameters

The users can be filtert, sorted and paginated using the following parameters:

  • stageIds: A list of stage IDs as comma-separated string. Only the users of the given stages will be returned.
  • filters: A JSON-encoded array of filter definitions. A filter definition is an object with the following properties:

    • mode: "include" or "exclude" where "include" returns the users that match the filters and "exclude" those that don't.
    • field: The user property to filter for.
    • operator: The operator to use for comparison. Dependent on the datatype of the field. Look here for datatypes and available operators.)
    • value: The value to match.
  • sortBy: A list of properties to sort by, given as comma-separated string. Each property must be prefixed with either + or - for ascending or descending order, respectively.
  • startId: The user ID to start from.
  • limit: The maximal number of users to return (default is 50).

limit and startId can be used for paginating the results. An offset option cannot be offered for technical reasons.

An example:

{
  "stageIds": "a6819263-73f9-48db-969f-ee9d7241d7b6,0f954369-16e8-4d18-915a-7be2dc458714",
  "filters": "[{\"mode\": \"include\", \"field\": \"user.company\", \"operator\": \"=\", \"value\": \"Mercury.ai\"}]",
  "sortBy": "+user.lastName,+user.firstName",
  "startId": "db82a72a-8b47-4821-82e7-c948a786a686",
  "limit": 10
}

Response

The response is an object with the usual keys success and data, where data is an object with the list of users objects under the property items:

{
  "success": true,
  "data": {
    "items": [...]
  }
}

The user objects have the properties userId, firstName, lastName, lastInteractionTime and properties. The latter contains an object with the context parameters that are set for the user.

An example:

{
  "userId":"db72b72a-8b47-4801-82f7-c948a386a579",
  "firstName":"John",
  "lastName":"Doe",
  "lastInteractionTime":"2020-03-17 16:54:06.0",
  "properties":{
    "user.locale":"de",
    "user.firstName":"John",
    "user.lastName":"Doe",
    "user.company":"Mercury.ai"
  }
}