> For the complete documentation index, see [llms.txt](https://rudderlabs.gitbook.io/rudderlabs-1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rudderlabs.gitbook.io/rudderlabs-1/docs/destinations/crm/zendesk.md).

# Zendesk

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

[**Zendesk**](https://www.zendesk.com/) 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**](https://github.com/rudderlabs/rudder-transformer/tree/master/v0/destinations/zendesk).

## 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**](https://rudderstack.com/docs/rudderstack-cloud/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**](https://app.rudderstack.com/), 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:

![](https://user-images.githubusercontent.com/59817155/136159593-9a019f5b-1f0b-4009-afba-d767bc93dc97.png)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**](https://support.zendesk.com/hc/en-us/articles/226022787-Generating-a-new-API-token-).
* **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.

```javascript
rudderanalytics.identify("12345678", {
  name: "John Wick",
  email: "johnwick@example.com",
  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:

```javascript
rudderanalytics.identify("12345678",{
  name: "John Wick",
  email: "johnwick@example.com",
  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:

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

RudderStack uses the [**Zendesk Sunshine Events API**](https://developer.zendesk.com/rest_api/docs/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:

```javascript
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**](mailto:%20docs@rudderstack.com) or start a conversation in our [**Slack**](https://rudderstack.com/join-rudderstack-slack-community) community.