Events

Events are custom names you assign to different actions a user may take in your application. Each action is an event that you can track.

Tracking an event means sending the event name and related data to Zendesk Connect for message campaigns. For example, each time a user renews their membership, your system could send an event named renewMembership with some related data to Connect. If your company created a campaign in Connect to respond to the renewMembership event, and the event identifies the user renewing her membership as Jane Doe, then Connect sends a predefined message to Jane Doe -- perhaps thanking her for renewing her membership. See Users.

You can send the event data to Connect using any of the following methods:

  • Use the Track Event endpoint in the Outbound REST API
  • Use the track() method in any of the Connect integration options

You can define an event name in Connect by simply sending an event with that name to Connect. See Event properties below. You can also define event names with the Events page (Settings > Events) in Connect before sending any events. If you define a name in Connect, make sure the name of the events you send later matches exactly the name defined in Connect.

Event properties

Events are represented by the following properties. Some Connect libraries may not implement all the properties or use slightly different names. For implementation details, see the docs for your library.

Name Type Mandatory Description
event string yes The name of the event. Should be a short name or description of the action taken, limited to 200 characters
user_id string yes The user's id. See Users
properties object no Custom properties associated with the event. See Properties below
timestamp timestamp no Unix timestamp for each event. See Timestamp below
Properties property

The team in your organization responsible for creating Connect campaigns may ask for additional information about an event so they can customize or personalize a message for each user. For example, after a user renews a membership, they might want to mention in the thank you message that the user's membership is valid until a certain date.

Use the properties property to provide more detail about the user's action. Example:

"properties": {
  "membership_valid": true,
  "membership_renewalDate": "2018-06-12"
}

The properties property is always an object, even if you only have one property:

"properties": {
  "membership_renewalDate": "2018-06-12"
}

You can nest properties:

eventProperties = {
  total: "45.00",
  membership: {
    valid: true,
    renewalDate: "2018-06-12"
  },
  items: 5
}

The team responsible for setting up campaigns can insert the example values in a message by selecting the membership.valid or membership.renewalDate property from the "@" variable list in the Connect message editor.

To view the existing properties for every event in Connect, open the Events page and click on the Plus (+) icon on the left side of an event's name.

image

Timestamp

You can specify your own time stamp for each event. The timestamp property should be a UNIX epoch time in seconds. Example:

"timestamp": 1529366403
JSON example

For other data formats, see the docs for your integration option.

{
  "event": "renewMembership",
  "user_id": "jdoe@example.com",
  "properties": {
    "membership_valid": true,
    "membership_renewalDate": "2018-06-12"
  },
  "timestamp": 1529366403
}