The ChatShipper Developer Hub

Welcome to the ChatShipper developer hub. You'll find comprehensive guides and documentation to help you start working with ChatShipper as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Advanced metrics Quickstart

Making cube queries

  curl \
 -H "Authorization: EXAMPLE-API-TOKEN" \
 -G \
 --data-urlencode 'query={"measures":["Users.count"]}' \
 https://{{ api_server }}/v2/metrics/load

The following examples have the expanded js query for easy reading, when doing queries you can strip all whitespaces and pass them as query=$QUERY

Cube output format

Cube output format is quite verbose, it includes the query you sent
and the datastructure is closely related to the query, example output:

{
  "query": {
    "measures": [
      "Messages.count"
    ],
    "timeDimensions": [
      {
        "dimension": "Messages.createdat",
        "dateRange": [
          "2019-12-01T05:00:00.000Z",
          "2020-01-01T05:00:00.000Z"
        ],
        "granularity": "month"
      }
    ],
    "limit": 1,
    "rowLimit": 1,
    "timezone": "UTC",
    "filters": [],
    "dimensions": []
  },
  "data": [
    {
      "Messages.createdat": "2019-12-01T00:00:00.000",
      "Messages.count": 4469
    }
  ],
  "annotation": {
    "measures": {
      "Messages.count": {
        "title": "Messages Count",
        "shortTitle": "Count",
        "type": "number"
      }
    },
    "dimensions": {},
    "segments": {},
    "timeDimensions": {
      "Messages.createdat": {
        "title": "Messages Createdat",
        "shortTitle": "Createdat",
        "type": "time"
      }
    }
  }
}

Example extraction of this data, note that there is a single data point.

     resultSet.loadResponse.data[0][`${collection}.count`];

MongoBI vs BigQuery

We have implemented automated selection of the backend.

Parameters

Time

The following format for dates is accepted by cube:

   const start = `${year}-${month}-01 00:00:00`);
   const end = `${yearEnd}-${monthEnd}-01 00:00:00`);

All of the following examples use the granularity month. Supported granularities: hour, day, week, month.

Created

All examples are for created unless it says updated. Created can be
obtained by the collections records created at and will contain the
ACTUAL total. When obtaining the number of create events in a time
range use the Events collection and filter by verb equals create.

Totals

Totals can be obtained by removing the timeDimensions key from the queries.

Active

The events table records all the operations, currently we support
"view", "create", "update". You can count the number of objects,
operations based on the filtering.

When active is viewed + created + updated, you can drop the verb filtering.

Organization, Subsidiaries, All

Note: For any given user the API now restricts the possible results by adding
this filter to all queries which forces all the results to contain the
user selected organization in the orgpath:

You can add a organization specific filter entry with this:

 {
    "dimension" : `${collection}.organization`,
    "operator" : "equals",
    "values" : [ `${orgId}` ]
  }

Or use the "contains" operator to do fuzzy matching against a field, for example we want to get all the subdiaries use orgpath.

 {
    "dimension" : `${collection}.orgpath`,
    "operator" : "contains",
    "values" : [ `${orgId}` ]
  }

Multiple filters can be mixed for example to only get the information about the subsidiaries

{
   ...,
   filters : [
{
    "dimension" : `${collection}.organization`,
    "operator" : "notEquals",
    "values" : [ `${orgId}` ]
  },
 {
    "dimension" : `${collection}.orgpath`,
    "operator" : "contains",
    "values" : [ `${orgId}` ]
  }

]
}

CS Dashboard Queries

Organizations created in this period

Using the Events collection

{
        "measures" : ["Events.directobjects"],
        "filters" :  [{
            "dimension" : "Event.verb",
            "operator" : "equals",
            "values" : ["created"]
        },
        {
            "dimension" : "Event.directobjecttype",
            "operator" : "equals",
            "values" : ["organization"]
        }],
        "timeDimensions" : [{
            "dimension" : "Events.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1
}

Alternative using the Organization collection:

{
        "measures" : ["Organization.count"],
        "timeDimensions" : [{
            "dimension" : "Organization.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1
}

Users created this period

Mongo

{
        "measures" : ["Events.count"],
        "filters" : [
        {
            "dimension" : "Events.verb",
            "operator" : "equals",
            "values" : [ "created"]
        },
        {
            "dimension" : "Events.directobjecttype",
            "operator" : "equals",
            "values" : [ "user"]
        }
        ],
        "timeDimensions" : [{
            "dimension" : "Events.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1
};

Or using the Users collection:

{
        "measures" : ["Users.count"],
        "timeDimensions" : [{
            "dimension" : "Users.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1
}

Bots created this period

Using the events collection:

{
        "measures" : ["Events.directobjects"],
        "filters" : [
        {
            "dimension" : "Events.verb",
            "operator" : "equals",
            "values" : [ "created"]
        },
        {
            "dimension" : "Events.inddirectobjecttype",
            "operator" : "equals",
            "values" : [ "bot"]
        }
        ],
        "timeDimensions" : [{
            "dimension" : "Events.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1
};

An alternative way to get this information:

{
    "measures": [
        "Users.count"
    ],
    "filters": [
        {
            "dimension": "UsersOrganizations.organizationsOrganization",
            "operator": "equals",
            "values": [
                "${organizationId}"
            ]
        },
        {
            "dimension": "UsersOrganizations.organizationsRole",
            "operator": "equals",
            "values": [
                "bot"
            ]
        }
    ],
    "timeDimensions": [
        {
            "dimension": "Users.createdat",
            "dateRange": [
                "2019-12-1 00:00:00",
                "2020-1-1 00:00:00"
            ],
            "granularity": "month"
        }
    ]
}

Integrations created this period

{
        "measures" : ["Events.directobjects"],
        "filters" :  [{
            "dimension" : "Event.verb",
            "operator" : "equals",
            "values" : ["created"]
        },
        {
            "dimension" : "Event.directobjecttype",
            "operator" : "equals",
            "values" : ["service"]
        }],
        "timeDimensions" : [{
            "dimension" : "Events.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1
}
{
        "measures" : ["Services.count"],
        "timeDimensions" : [{
            "dimension" : "Users.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1
};

Service collection, by type:

{
    "measures" : ["Services.count"],
    "timeDimensions" : [{
            "dimension" : "Users.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
    }],
    "dimensions" : ["Services.type" ]
}

Events collection

{
        "measures" : ["Events.directobjects"],
        "filters" : [
        {
            "dimension" : "Events.verb",
            "operator" : "equals",
            "values" : [ "created"]
        },
        {
            "dimension" : "Events.directobjecttype",
            "operator" : "equals",
            "values" : [ "service"]
        }
        ],
        "timeDimensions" : [{
            "dimension" : "Events.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1
};

To collect by type, add this dimensions statement to the above query:

{
   "dimensions" : [ "Events.prepObjectType"]
}

Integrations active this period

This will give you all the service ids that have messages created on
the given [start, end] range, with a message count for each one.

{
        "measures" : ["Messages.count"],
        "dimensions" : [ "Message.service"]
        "timeDimensions" : [{
            "dimension" : "Messages.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }]
}

Forms, Results and other message types

This will give a count of each message type:

{
        "measures" : ["Messages.count"],
        "dimensions" : [ "Messages.type"],
        "timeDimensions" : [{
            "dimension" : "Messages.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }]
}

If you want to query a single type

{
        "measures" : ["Messages.count"],
        "filters" : [
            {
                "dimension" : "Mesages.type",
                "operator" : "equals",
                "values" : [ "form"]
            }
        ],
        "timeDimensions" : [{
            "dimension" : "Messages.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1
}

Articles

Using the Events collection:

Verb matching

  • create : created
  • update : active
  • view: active
{
        "measures" : ["Events.directobjects"],
        "filters" : [
        {
            "dimension" : "Events.verb",
            "operator" : "equals",
            "values" : [ "created"]
        },
        {
            "dimension" : "Events.directobjecttype",
            "operator" : "equals",
            "values" : [ "article"]
        }
        ],
        "timeDimensions" : [{
            "dimension" : "Events.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1
};

Created, using Articles collection

{
        "measures" : ["Articles.count"],
        "timeDimensions" : [{
            "dimension" : "Articles.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1
}

Updated, using the Articles collection

{
        "measures" : ["Articles.count"],
        "filters" : [ {
            "dimension" : "Articles.createdat",
            "operator" : "lt",
            "values" : [ start ]
        }],
        "timeDimensions" : [{
            "dimension" : "Articles.updatedat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1

}

Contacts

Created

{
        "measures" : ["Contacts.count"],
        "timeDimensions" : [{
            "dimension" : "Contacts.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1
}

Updated

{
        "measures" : ["Contacts.count"],
        "filters" : [ {
            "dimension" : "Contacts.createdat",
            "operator" : "lt",
            "values" : [ start ]
        }],
        "timeDimensions" : [{
            "dimension" : "Contacts.updatedat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1

}

Using the events collection

Verb matching

  • create : created
  • update : active
  • view: active
{
        "measures" : ["Events.directobjects"],
        "filters" : [
        {
            "dimension" : "Events.verb",
            "operator" : "equals",
            "values" : [ "created"]
        },
        {
            "dimension" : "Events.directobjecttype",
            "operator" : "equals",
            "values" : [ "article"]
        }
        ],
        "timeDimensions" : [{
            "dimension" : "Events.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1
};

Conversations

Created

{
        "measures" : ["Conversations.count"],
        "timeDimensions" : [{
            "dimension" : "Conversations.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1
}

Type

{
        "measures" : ["Conversations.count"],
        "dimensions" : [ "Conversations.type"],
        "timeDimensions" : [{
            "dimension" : "Conversations.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }]
}

Updated

{
        "measures" : ["Conversations.count"],
        "filters" : [ {
            "dimension" : "Conversations.createdat",
            "operator" : "lt",
            "values" : [ start ]
        }],
        "timeDimensions" : [{
            "dimension" : "Conversations.updatedat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1

}

BQ

Verb matching

  • create : created
  • update : active
  • view: active
{
        "measures" : ["Events.directobjects"],
        "filters" : [
        {
            "dimension" : "Events.verb",
            "operator" : "equals",
            "values" : [ "created"]
        },
        {
            "dimension" : "Events.directobjecttype",
            "operator" : "equals",
            "values" : [ "article"]
        }
        ],
        "timeDimensions" : [{
            "dimension" : "Events.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1
};

Messages

Total

{
        "measures" : ["Messages.count"],
        "timeDimensions" : [{
            "dimension" : "Messages.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }],
        "limit" : 1
}

Roles

{
        "measures" : ["Messages.count"],
        "dimensions" : [ "Messages.role"]
        "timeDimensions" : [{
            "dimension" : "Messages.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }]
}

Touchpoints

{
        "measures" : ["Messages.count"],
        "dimensions" : [ "Messages.touchpoint"]
        "timeDimensions" : [{
            "dimension" : "Messages.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }]
}

Results

Results by name(label)

{
  "measures": [
    "Results.count"
  ],
  "dimensions": [
    "Results.name",
  ],
  "timeDimensions" : [{
            "dimension" : "Messages.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }]
}

Results by type

{
  "measures": [
    "Results.count"
  ],
  "dimensions": [
    "Results.type",
  ],
  "timeDimensions" : [{
            "dimension" : "Messages.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }]
}

Results by role

{
  "measures": [
    "Results.count"
  ],
  "dimensions": [
    "Results.posterrole",
  ],
  "timeDimensions" : [{
            "dimension" : "Messages.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }]
}

Results by category

{
  "measures": [
    "Results.count"
  ],
  "dimensions": [
    "Results.category",
  ],
  "timeDimensions" : [{
            "dimension" : "Messages.createdat"
            "dateRange" : [start, end],
            "granularity" : "month"
        }]
}

Updated about a month ago

Advanced metrics Quickstart


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.