Zendesk Events API extension overview

Last update: 2023-12-06
  • Topics:
  • Tags
    View more on this topic
  • Created for:
  • Developer

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

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

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

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

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

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:

On this page