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.
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.
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.
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.
Under Zendesk Domain, enter the value for your Zendesk subdomain. Under Zendesk Token, select the secret you created earlier that contains the API token.
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.
When setting up the action configuration, you are prompted to assign data elements to the various properties that will be sent to Zendesk.
These data elements should be mapped as referenced below.
event
keysevent
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) |
Refer to the Zendesk Events API documentation for additional guidance on event properties.
profile
keysprofile
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. |
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:
Events:
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.
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"}]} |
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: