Zendesk Events API extension overview

Zendesk is a customer service solution and sales tool. The Zendesk event forwarding extension leverages the Zendesk Events API to send events from the Adobe Experience Platform Edge Network to Zendesk for further processing. You can use the extension to collect customer profile interactions for use in downstream analysis and action.

This document covers how to install and configure the extension in the UI.

Prerequisites

You must have a Zendesk account to use this extension. You can register for a Zendesk account on the Zendesk website.

You must also gather the following details for your Zendesk configuration:

Key type
Description
Example
Subdomain
During the registration process, a unique subdomain is created specific to the account. Refer to the Zendesk documentation for more information.
xxxxx.zendesk.com (where xxxxx is the value that was provided during the account creation)
API token
Zendesk uses bearer tokens as an authentication mechanism to communicate with the Zendesk API. After logging in to the Zendesk portal, generate an API token. Refer to the Zendesk documentation for more information.
cwWyOtHAv12w4dhpiulfe9BdZFTz3OKaTSzn2QvV

Finally, you must create an event forwarding secret for the API token. Set the secret type to Token, and set the value to the API token you gathered from your Zendesk configuration. Refer to the documentation on secrets in event forwarding for more details on configuring secrets.

Install the extension install

To install the Zendesk extension in the UI, navigate to Event Forwarding and select a property to add the extension to, or create a new property instead.

Once you have selected or created the desired property, navigate to Extensions > Catalog. Search for “Zendesk”, and then select Install on the Zendesk Extension.

Install button for the Zendesk extension being selected in the UI

Configure the extension configure

IMPORTANT
Depending on your implementation needs, you may need to create create a schema, data elements, and a dataset before configuring the extension. Please review all the configuration steps before starting in order to determine which entities you need to set up for your use case.

Select Extensions in the left navigation. Under Installed, select Configure on the Zendesk extension.

Configure button for the Zendesk extension being selected in the UI

Under Zendesk Domain, enter the value for your Zendesk subdomain. Under Zendesk Token, select the secret you created earlier that contains the API token.

Configuration options filled out in the UI

Configure an event forwarding rule

Start creating a new event forwarding rule rule and configure its conditions as desired. When selecting the actions for the rule, select the Zendesk extension, then select the Create Event action type.

Define Rule

When setting up the action configuration, you are prompted to assign data elements to the various properties that will be sent to Zendesk.

Define Action Configuration

These data elements should be mapped as referenced below.

event keys

event is a JSON object that represents the event triggered by the user. Refer to the Zendesk document on the anatomy of an event for details on the properties captured by the event object.

The following keys can be referenced within the event object when mapping to data elements:

event key
Type
Platform path
Description
Mandatory
Limits
source
String
arc.event.xdm._extconndev.event_source
The application which sent the event.
Yes
Do not use Zendesk as a value as it is a protected source name for Zendesk standard events. Attempts to use it will result in an error.
Value length must not exceed 40 characters.
type
String
arc.event.xdm._extconndev.event_type
A name for the event type. You can use this field to denote different kinds of events for a given source. For example, you can create one set of events for user logins and another for shopping carts.
Yes
Value length must not exceed 40 characters.
description
String
arc.event.xdm._extconndev.description
A description for the event.
No
(N/A)
created_at
String
arc.event.xdm.timestamp
An ISO-8601 timestamp reflecting the time the event was created.
No
(N/A)
properties
Object
arc.event.xdm._extconndev.EventProperties
A custom JSON object with details about the event.
Yes
(N/A)
NOTE
Refer to the Zendesk Events API documentation for additional guidance on event properties.

profile keys

profile is a JSON object that represents the user that triggered the event. Refer to the Zendesk document on the anatomy of a profile for details on the properties captured by the profile object.

The following keys can be referenced within the profile object when mapping to data elements:

profile key
Type
Platform path
Description
Mandatory
Limits
source
String
arc.event.xdm._extconndev.profile_source
The product or service associated with the profile, such as Support, CompanyName, or Chat.
Yes
(N/A)
type
String
arc.event.xdm._extconndev.profile_type
A name for the profile type. You can use this field to create different kinds of profiles for a given source. For example, you can create one set of company profiles for customers and another for employees.
Yes
Profile type length must not exceed 40 characters.
name
String
arc.event.xdm._extconndev.name
The name of the person from the profile
No
(N/A)
user_id
String
arc.event.xdm._extconndev.user_id
The person’s user ID in Zendesk.
No
(N/A)
identifiers
Array
arc.event.xdm._extconndev.identifiers
An array containing at least one identifier. Each identifier consists of a type and a value.
Yes
Refer to the Zendesk documentation for more information on the identifiers array. All fields and values must be unique.
attributes
Object
arc.event.xdm._extconndev.attrbutes
An object containing user-defined properties about the person.
No
Refer to the Zendesk documentation for more information on profile attributes.

Validate data within Zendesk validate

If the event collection and Adobe Experience Platform integration are successful, then the events within the Zendesk console should appear as shown below. This indicates a successful integration.

Profiles:

Zendesk Profiles page

Events:

Zendesk Events page

Request limits limits

Based on the account type, the Zendesk Events API can handle the following number of requests per minute:

Account Type
Requests per minute
Team
250
Growth
250
Professional
500
Enterprise
750
Enterprise Plus
1000

Refer to the Zendesk documentation for more information on these limits.

Errors and troubleshooting errors-and-troubleshooting

While using or configuring the extension, the errors below might be returned by the Zendesk Events API:

Error Code
Description
Resolution
Example
400
Invalid profile length: This error occurs when the length of a profile attribute contains more than 40 characters.
Limit the length of the profile attribute data to a maximum of 40 characters.
{"error": [{"code":"InvalidProfileTypeLength","title": "Profile type length > 40 chars"}]}
401
Route not found: This error occurs when an invalid domain has been supplied.
Verify that a valid domain is supplied in the following format: {subdomain}.zendesk.com
{"error": [{"description": "No route found for host {subdomain}.zendesk.com","title": "RouteNotFound"}]}
401
Invalid or Missing Authentication: This error occurs when access the token is invalid, missing, or expired.
Verify that access token is valid and has not expired.
{"error": [{"code":"MissingOrInvalidAuthentication","title": "Invalid or Missing Authentication"}]}
403
Insufficient permissions: This error occurs when sufficient permissions to access the resource are not provided.
Validate that the required permissions have been provided.
{"error": [{"code":"PermissionDenied","title": "Insufficient permisssions to perform operation"}]}
429
Too Many Requests: This error occurs when the endpoint object record limit has been exceeded.
Refer to the section above on request limits for details on per-limit thresholds.
{"error": [{"code":"TooManyRequests","title": "Too Many Requests"}]}

Next steps

This document covered how to install and configure the Zendesk event forwarding extension in the UI. For more information on collecting event data in Zendesk, refer to the official documentation:

recommendation-more-help
12b4e4a9-5028-4d88-8ce6-64a580811743