Zendesk

Step-by-step guide to set up Zendesk as a destination in RudderStack.

Zendesk is a popular CRM and customer support service suite that ensures cutting-edge sales and support across various business domains. It allows you to tend to your customers in the best way possible and satisfactorily resolve all their queries and concerns. Zendesk also offers features such as live chat, call center software capabilities, and a smart knowledge base for your executives to quickly solve any customer query at hand.

RudderStack supports Zendesk as a destination to which you can seamlessly send your customer data.

Find the open-source transformer code for this destination in our GitHub repo.

Getting started

Before configuring Zendesk as a destination in RudderStack, make sure that Zendesk supports the source platform from which you are sending the events, by referring to the following table:

Connection Mode	Web	Mobile	Server
Device mode	-	-	-
Cloud mode	Supported	Supported	Supported

To know more about the difference between Cloud mode and Device mode in RudderStack, read the RudderStack connection modes guide.

Once you have verified that the source platform supports sending events to Zendesk, perform the steps below:

• From your RudderStack dashboard, add the source. From the list of destinations, select Zendesk.

• Assign a name to the destination and click on Next. You should then see the following screen:

Connection Settings

Connection settings

To set up the Zendesk destination in RudderStack, the following settings need to be configured:

• Email: This is a mandatory field. Enter the email you use to log into your Zendesk dashboard.

• API Token: This is a mandatory field. Enter the Zendesk API token that will be used to authenticate the request. To create an API token, check this Zendesk support article.

• Zendesk Subdomain: Enter your Zendesk subdomain (not including .zendesk.com).

• Create users as verified: Enabling this setting will create users as verified (the email verification is skipped). RudderStack sends verified as true if this setting is enabled.

• Send Group calls without a User ID: Enable this setting if you don't want to associate the user with a group. If this setting is enabled, only the group will be created or updated if userId is not present in the payload.

Once you've entered all the required settings, click on Next to finish the configuration. Zendesk should now be added and enabled as a destination in RudderStack.

Identify

The identify call creates or updates a user in Zendesk. RudderStack uses the email in traits for these actions. Hence, we highly recommend including the user's email address in the identify call.

rudderanalytics.identify("12345678", {
  name: "John Wick",
  email: "[e-mail]",
  country: "UK",
});

Standard mapping

RudderStack maps the properties to a subset of the standard Zendesk user attributes and creates a new custom field for the unmapped attributes. The mapping is shown in the following table:

RudderStack	Zendesk
email	email
name	name
organizationId	organization_id
timezone	time_zone
phone	phone
userId	user_id
userId	external_id

The organization_id corresponds to the organization ID assigned by Zendesk.

Verifying users at creation

You can use the Create users as verified dashboard setting in RudderStack to create and register the users as verified. Zendesk skips the email verification for these users.

Removing users from an organization membership

Enable the Enable Removing Users from Organizations setting in the dashboard to use this feature.

The following payload fields under context.traits are mandatory for this action:

• company.id

• company.remove (should be set to true)

RudderStack assumes a valid Zendesk organization_id in the company.id field. Then, it finds the organization corresponding to that ID and performs the action.

A sample identify call for this action is shown below:

rudderanalytics.identify("12345678",{
  name: "John Wick",
  email: "[e-mail]",
  country: "UK",
  company:{
    id: 900001329943,
    remove: true
  }
});

The above identify call updates the user as well as removes them from the organization associated with the ID 900001329943.

Track

Zendesk expects an userId for every track call. You can set the userId by making an identify call before sending any track event. RudderStack persists the user details from the identify call to all the subsequent calls.

A sample track call is as shown:

rudderanalytics.track("Track me", {
  category: "category",
  label: "label",
  value: "value",
});

RudderStack uses the Zendesk Sunshine Events API for the track calls. To successfully send track calls to Zendesk, the following criteria should be met:

• You need to have signed up for the Events API early access program.

• A userId needs to be passed along with the track call.

Group

You can use the group call to create or update an organization in Zendesk. RudderStack uses the groupId to do so.

A sample group call is shown below:

rudderanalytics.group("123456789", {
  name: "Softworks",
  country: "UK",
  group_plan: "trial",
});

The group call associates the user to the organization. You can disable this feature by disabling the Send Group Calls without User ID dashboard setting in RudderStack. In this case, RudderStack will create or update the organization even if no user is associated with the event.

Standard mapping

RudderStack maps the group traits to a subset of the standard Zendesk organization attributes of Zendesk. It creates a new custom field for any unmapped attributes.

The current mapping is shown in the following table:

RudderStack	Zendesk
name	name
domainNames	domain_names
tags	tags
groupId	external_id
url	url
deleted	deleted

RudderStack assumes that an identify call is made before any group call with the userId.

If groupId and userId both are present in the group event payload, then RudderStack will find the user with email present in the traits. If it is not present, RudderStack will create the user. It will also find the organization associated with the groupId present in the payload. If groupId is not present, RudderStack creates that too and then does the user-group association.

If a user already exists, the organizationId will be attached to the user and all the user information will be sent for this call.

The above discussion can be summarized as follows:

• New groupId and new email (No Zendesk user ID associated with the email): RudderStack creates the user and the organization and associates them.

• New groupId and existing email (Zendesk user already exists): RudderStack creates a new organization and associates the existing user with it.

• Old groupId and new email (Organization already exists in Zendesk, but not user): RudderStack creates a new user with the email and associated them with the organization.

Note that traits contain the relevant group-specific information, whereas the context.traits contains all the user-related information.

Contact us

If you come across any issues while configuring Zendesk with RudderStack, feel free to contact us or start a conversation in our Slack community.