10

Zendesk Destination

About this integration

Zendesk is a customer service platform that helps you build better customer relationships. This integration helps you send data to Zendesk, helping you identify your users and enrich their profiles with data from your sources. This helps you provide your customers with better support.

Getting started

1. Go to the Data Pipelines tab and click Connections.

2. Click Add New under Destinations.

3. Select the Zendesk destination.

4. (Optional) Select the sources that you want to connect to this destination. You can always connect sources to your destination later. We’ll only show you eligible sources.

5. Configure your destination.

   1. Subdomain: The subdomain of your Zendesk instance. For example, if your Zendesk URL is https://example.zendesk.com, your subdomain is example.

   

   

6. Click Enable Destination.

Actions

When you’re done setting up your destination, you can go to the Actions tab to see how we map source events to your destination.

Identify Zendesk Users

When you call our identify API, we add or update a user record in Zendesk. To add people to Zendesk, your calls must include:

• traits.email—the email address of the person.
• A name or first_name and last_name traits. If the incoming calls includes a first_name and last_name, we parse it into the name field.

When updating user records in Zendesk, we match users based on their email address of a person you identify (typically $.traits.email) or their external_id (typically $.userId). A Zendesk profile can have multiple email addresses, but each address is unique to an individual user in your Zendesk instance.

{
  "action": "identify",
  "userId": "12345",
  "traits": {
    "name": "Homer Simpson",
    "email": "homer.simpson@example.com",
    "timezone": "America/Springfield",
    "organizationId": 6789,
    "phone": "555-555-1234"
  }
}

Mapping traits to Zendesk users

We map incoming traits from your sources to the following standard Zendesk user attributes.

To store other traits in Zendesk, you must first define them as User Fields. If your identify call sends a trait that you haven’t added to your Zendesk configuration, Zendesk will discard it.

You can add your custom traits in Zendesk under Admin Center > People > Configuration > User Fields.

When Customer.io sends data to Zendesk, you should see the populated attributes in the customer’s context. See Adding custom fields to users in Zendesk help for more information.

Adding or Removing Users to/from a Zendesk Organization

You can add a user to a Zendesk organization by passing traits.company.id in your identify calls. You can also remove people from an organization by setting traits.company.remove: true.

{
  "action": "identify",
  "userId": "12345",
  "traits": {
    "company": {
      "id": "6789"
    }
  }
}

{
  "action": "identify",
  "userId": "12345",
  "traits": {
    "company": {
      "id": "6789",
      "remove": true
    }
  }
}

Zendesk Verification Email at User Creation

By default, Zendesk sends a verification email to users when you create them.

You can prevent people you identify from receiving these verification emails by enabling the Skip Verify Email setting. The user’s email may still require verification if the “Create Users as Verified” option is false.

Create Users as Verified

By default all users are created as unverified and may receive a verification email (if the Skip Verify Email is false). If you have already verified your user’s email by other means you may wish to create them as verified in Zendesk.

To do so, set the Create Users as Verified setting to true on the default Create or Update User action on your Zendesk destination.

Track

A track call from your sourceA source is a website or server that you want to capture data from—it’s a source of data! represents an event—something someone does on your website or in your app that you want to report to destinations like Zendesk. When you make a track call, you’re sending information about a user’s activity to Zendesk.

Events must be associated with a user in Zendesk. If you provide a context.zendesk_user_id we will directly track the event under that ID.

Otherwise, if you provide an email and/or external_id we will search for the user and track the event with the found user. If no user is found an error will be returned.

{
  "action": "track",
  "userId": "1234",
  "event": "Article Read",
  "properties": {
    "title": "How to use Customer.io",
    "course": "Intro to Customer.io"
  }
}

Mapping track events to Zendesk Sunshine

If you want to map a track call to a Zendesk Sunshine event by email, you can set the user’s email address in as properties.email in your call. This helps Zendesk tie the event to a user. If your event does not include properties.email, we send the userId as external_id.

When your call includes an email address, a track call (from our JavaScript library) might look like this:

analytics.track('Article Read', {
  title: 'How to use Customer.io',
  course: 'Intro to Customer.io',
  properties: {
    email : 'person@example.com',
  }
});

Group

When you send a group call, we insert or update an organization in Zendesk. We use the groupId in your call to match organization records in Zendesk. If the groupId doesn’t exist, we create a new organization; if it exists, we update the existing organization.

{
  "action": "group",
  "groupId": "xyz999",
  "traits": {
    "name": "SF Giants",
    "url": "https://mlb.com/giants"
  }
}

{
  "action": "group",
  "groupId": "abc123",
  "userId": "1234",
  "traits": {
    "name": "SF Giants",
    "url": "https://mlb.com/giants"
  }
}

Organization attributes

Organizations in Zendesk have standard attributes. We map to the subset of these attributes listed below.

When you pass traits in your group calls, we’ll first try to map traits to known, existing fields in Zendesk—either the standard fields above or custom fields you’ve already created. If a custom field does not exist, we’ll create it.

We format incoming traits to camelCase or snake_case as necessary; if you don’t see custom fields populate in Zendesk, you may need to check the way you format traits in your group calls.