Integrations

Zendesk

CategoriesAll

Event

Zendesk is a customer service platform. It’s designed for companies that want to create customer relationships that are more meaningful, personal, and productive. The Zendesk event integration supplements customer support by providing them additional context about their users; allowing them to provide a more personalized experience.

Prerequisites

The Zendesk integration uses the Sunshine Events API which is currently part of an Early Access Program to track events against a Sunshine profile. You need to ensure your Sunshine plan is properly configured to use the integration by selecting Admin > Settings > Subscription at https://your-zendesk-subdomain.zendesk.com/admin/billing/subscription.

The following items are required:

A Zendesk Account.
A Zendesk Sunshine Professional Plan or higher.
- Zendesk Sunshine Professional is the minimum required, but we recommend Enterprise or higher to avoid hitting Sunshine API limits.
- For more information check Plan Availability.
Account Verification.
- See verifying an end user’s email address for more details.
A Zendesk Sunshine API token.

Data Processing Notes

When you create a connection to Zendesk, forwarding for all existing data points will initially be set to off, and send new data points by default will be disabled. You must enable the specific data points that you wish to forward to Zendesk.

mParticle recommends working with your Zendesk account manager before forwarding all events to your Zendesk account in the event Filter. This will ensure that you have a sufficient plan to handle the additional events - check Zendesk rate limits.

mParticle will only forward events to Zendesk if:

An email address has been provided as identity in the event
The payload is less than ~2 Kilobytes - Event maximum payload
If a commerce payload is greater than ~2 Kilobytes, it will be split into separate requests for each product. The description property will contain information on the set it belongs to; e.g., 1 of N. Please see specific commerce event types to learn more.

Enabling User Profiles And Events In Zendesk

After you have finished configuring the integration in mParticle, and began forwarding events to Zendesk, you have to enable which of these user profiles and events that have already been forwarded will be visible in the customer context. To do this please follow the instructions on how to Add Sunshine user profiles and events to customer context in a ticket

Forwarded JSON Payload Example

This is an example of a JSON payload send to the Zendesk API with Event Source set to mParticle and Profile Type set to customer.

{
    "profile": {
        "source": "mParticle",
        "type": "customer",
        "identifiers": [{
                "type": "email",
                "value": "some@email.com"
            }
        ],
        "attributes": {
            "some_attribute_1": "some-attribute-value-1",
            "some_attribute_2": "some-attribute-value-2"
        }
    },
    "event": {
        "type": "some-app-event-name",
        "source": "mParticle",
        "properties": {
            "custom_attributes": {
                "some_attribute_name": "some-attribute-value"
            }
        }
    }
  }
}

Event Data Mapping

The following field mappings apply for all supported events.

Profile mappings

Parameter	Zendesk Field	mParticle Details
Event Source	profile.source	Taken from Configuration Settings, default is `mParticle`
Profile Type	profile.type	Taken from Configuration Settings, default is `customer`
user_attributes	profile.name	If `$FirstName` and `$LastName` attributes are defined, `name` attribute will be included
user_attributes	profile.attributes	Will include all defined attributes except `$FirstName` and `$LastName`
user_identities	profile.identifiers	Must include an email identity type

Event mappings

Parameter	Zendesk Field	mParticle Details
Event Source	event.source	Specified in Connection Settings
-	event.type	Check specific type of event for respective mapping of this field
custom_attributes	event.properties.custom_attributes	All attribute items will be added to custom_attributes property
-	event.description	Only set on commerce events that have been split into a set of events, it will contain a text describing the part of the set it belongs to; e.g., 1 of N.

The event.type is set based on the type of event:

mParticle Event Type	event.type
screen_view	Screen View
custom_event	The event_name specified in the custom event
commerce_event (Product Action)	eCommerce - product_action
commerce_event (Promotion Action)	eCommerce - Promotion promotion_action
commerce_event (Impression)	eCommerce - Impression

Screen View Events

The following field mappings apply for Screen View events.

Parameter	Zendesk Field	mParticle Details
-	event.type	`Screen View` string will be sent as value for this field
screen_name	event.properties.screen_name	The value sent in screen_name property in the event

Screen View (event) JSON Sample

{
    "type": "Screen View",
    "source": "mParticle",
    "properties": {
        "screen_name": "About",
        "custom_attributes": {
            "some_attribute_name": "some-attribute-value"
        }
    }
}

Custom Events

The following field mappings apply for Custom Events.

Parameter	Zendesk Field	mParticle Details
event_name	event.type	The event_name specified in the custom event
custom_event_type	event.properties.custom_event_type	The value sent in custom_event_type property in the event. e.g.: UserPreference, Navigation, ProductCheckout

Custom Event (event) JSON Sample

{
    "type": "custom event name",
    "source": "mParticle",
    "properties": {
        "custom_event_type": "Other",
        "custom_attributes": {
            "some_attribute_name": "some-attribute-value"
        }
    }
}

Commerce Events

The following field mappings apply for Product Commerce Events.

Product-based

Parameter	Zendesk Field	mParticle Details
event_name	event.type	The value sent in event_name property in the event
action	event.properties.action	The value sent in action property of the product_action property in the event, e.g.: AddToCart, Checkout, RemoveFromWishlist
transaction_id	event.properties.transaction_id	The value sent in transaction_id property of the product_action property in the event
currency_code	event.properties.currency_code	The value sent in currency_code property in the event
total_amount	event.properties.total_amount	The value sent in total_amount property of the product_action property in the event
tax_amount	event.properties.tax_amount	The value sent in tax_amount property of the product_action property in the event
shipping_amount	event.properties.shipping_amount	The value sent in shipping_amount property of the product_action property in the event
coupon_code	event.properties.coupon_code	The value sent in coupon_code property of the product_action property in the event
timestamp_unixtime_ms	event.properties.timestamp_unixtime_ms	The value sent in timestamp_unixtime_ms property in the event
products	event.properties.products	The array of products sent in products property of the product_action property in the event

Product-Based JSON Sample

{
    "type": "eCommerce - AddToCart",
    "source": "mParticle",
    "properties": {
        "action": "AddToCart",
        "transaction_id": "some-transaction-id",
        "currency_code": "USD",
        "total_amount": "1.99",
        "tax_amount": "0.50",
        "shipping_amount": "1.00",
        "coupon_code": "some-coupon-code",
        "timestamp_unixtime_ms": "1605805232479",
        "products": [{
                "id": "some-product-id",
                "name": "some-product-name",
                "brand": "some-product-brand",
                "category": "some-product-category",
                "position": "1",
                "price": "1.99",
                "quantity": "1",
                "coupon_code": "some-product-coupon-code",
                "total_product_amount": "1.99",
                "product_attributes": {
                    "some_product_attribute_name": "some-product-attribute-value"
                }
            }
        ],
        "custom_attributes": {
            "some_attribute_name": "some-attribute-value"
        }
    }
}

Promotion-based

The following field mappings apply for Promotion Commerce Events.

Parameter	Zendesk Field	mParticle Details
event_name	event.type	The value sent in event_name property in the event
action	event.properties.action	The value sent in action property of the promotion_action property in the event, e.g.: PromotionView, PromotionClick
timestamp_unixtime_ms	event.properties.timestamp_unixtime_ms	The value sent in timestamp_unixtime_ms property in the event
promotions	event.properties.promotions	The array of promotions sent in promotions property of the promotion_action property in the event

Promotion-Based JSON Sample

{
    "type": "eCommerce - PromotionView",
    "source": "mParticle",
    "properties": {
        "action": "PromotionView",
        "promotions": [{
                "id": "some-promotion-id",
                "name": "some-promotion-name",
                "creative": "some-creative-name",
                "position": "some-position-value"
            }
        ],
        "custom_attributes": {
            "some_attribute_name": "some-attribute-value"
        }
    }
}

Impression-based

The following field mappings apply for Impression Commerce Events.

Parameter	Zendesk Field	mParticle Details
event_name	event.type	The value sent in event_name property in the event
product_impressions	event.properties.product_impressions	The array of product impressions sent in product_impressions property in the event

Impression-Based JSON Sample

{
    "type": "eCommerce - Impression",
    "source": "mParticle",
    "properties": {
        "product_impressions": [{
                "product_impression_list": "some-product-impresion-list-name",
                "products": [{
                        "id": "some-product-id",
                        "name": "some-product-name",
                        "brand": "some-product-brand",
                        "category": "some-product-category",
                        "position": "1",
                        "price": "1.99",
                        "quantity": "1",
                        "coupon_code": "some-product-coupon-code",
                        "total_product_amount": "1.99",
                        "product_attributes": {
                            "some_product_attribute_name": "some-product-attribute-value"
                        }
                    }
                ]
            }
        ],
        "custom_attributes": {
            "some_attribute_name": "some-attribute-value"
        }
    }
}

Configuration Settings

Setting Name	Data Type	Description
Authentication Email Address	`string`	Email address for API authentication
API Token	`string`	API tokens are auto-generated passwords in the Support admin interface on Zendesk platform
Subdomain	`string`	The subdomain can be identified from the Zendesk account’s URL. For example: if your URL is https://your-zendesk-subdomain.zendesk.com, then the subdomain value is `your-zendesk-subdomain`

Connection Settings

Setting Name	Data Type	Default Value	Platform	Description
Event Source	`string`	mParticle	All	Application which sent the event
Profile Type	`string`	customer	All	Is a user-defined name that lets you create different kinds of profiles for a given source. Example: “customer” for the customer profiles

Was this page helpful?