Send query results to Zendesk

Zendesk is a service-first CRM company that builds software designed to improve customer relationships by providing support, chat, and community services that span channels.

Amperity may be configured to create or update user records in Zendesk by using the Zendesk Users API to create or update users . Use this connector to deliver a better customer support experience by pre-populating Zendesk user records with customer records from Amperity, including:

• Order history

• Loyalty status

• Satisfaction survey results

• Shopping preferences

• and more

Use this data to show customer support representatives information related to product recommendations, next best actions, and likelihood of churn.

Note

Creating or updating records are rate limited to a maximum of 100 users per second.

This topic describes the steps that are required to send customer data to Zendesk from Amperity:

1. Build a query

2. Add orchestration

3. Run orchestration

Note

Zendesk must be enabled before you can configure an orchestration to send query results.

Build query

Results that are sent to Zendesk must be correctly mapped to the following attributes, as required by the Zendesk Users API :

Zendesk Fields	Type	Description
email	String	Optional; may be used instead of external_id. The primary email address for the customer record. Zendesk uses the email field to identify users within Zendesk by default. You may use the external_id field to provide the Amperity ID to Zendesk, after which you may use the Amperity ID within Zendesk to identify a user. When the email field is present and external_id is not present, multiple records orchestrated with the same email address are treated as updates to the same user. Tip Use this field in conjunction with the verified field to define when email address updates are made to a customer’s primary or secondary email address.
external_id	String	Optional; should be used instead of email. This field should be associated with the Amperity ID. When external_id field is provided, it will take precedence over email and becomes the field Zendesk will use to identify users. After the creation of a user with a given external_id, subsequent requests with the same external_id are treated as updates and, in the presence of the same external_id and different email values, additional email addresses are added to the same user as secondary email addresses. Tip Zendesk requires one of email or external_id, but is designed to prefer the external_id when it is available.
name	String	Required. The full name of the customer. Warning A record without a name and one of email or external_id is filtered out, marked with an error, and is not submitted to Zendesk.
phone	String	Optional. The primary phone number associated with the customer record. Note The Zendesk User API requires phone numbers to be compliant with the E.164 format.
user_fields.[field]	String	Optional. The Zendesk User API contains 37 fields, most of which are not required. The Zendesk User API supports custom fields as long as they are prefixed with user_fields. in the field name. For example: user_fields.city. Note Fields submitted to Zendesk that are not built into the Zendesk User API or are not formatted as valid custom fields (including misspellings) will be ignored.

Use an attributes table

An attributes table consolidates a set of fields for use with a specific downstream workflow, and then assigns column names to each field that correctly maps to the naming patterns that are required by that workflow.

An attributes table can be configured to allow users of the Visual Segment Editor to build segments that send results to Zendesk.

Note

Fields in an attributes table are available to SQL editors in the Queries and Segments pages. An attributes table must be configured to be made available to the visual editors.

For example, to send results from Amperity to Zendesk you must associate a user’s full_name to name, you may associate the Amperity ID to external_id, and you may provide custom fields as long as they begin with user_fields.. When this table has been Made available to the Visual Segment Editor users will be able to build visual segments that use fields in the attributes table.

The following query will build an attributes table that maps the Amperity ID to the Zendesk external ID, and then map email addresses, full names, and phone numbers to the corresponding Zendesk attributes:

SELECT
  amperity_id
  ,amperity_id AS external_id
  ,email AS email
  ,LOWER(full_name) AS name
  ,phone AS phone
FROM Customer_360

Important

Only tables that contain the Amperity ID can be made available to the Visual Segment Editor. The first line in a SELECT statement that builds an attributes table must be amperity_id.

A user can build a visual query or visual segment by selecting fields from this attributes table, and then send the results to Zendesk with the correct mapping already applied.

Caution

You cannot build an attributes table that contains custom fields. A column name may only contain alphanumeric characters (a-Z), underscores (_), and must start with an alphanumeric character. Use a query for results that send custom fields to Zendesk.

Use a query

A query is SQL that is run from the Queries page against database tables in the Customer 360 page. A query returns a refined and filtered subset of useful customer data.

The following example is a query that contains only the fields that are required by Zendesk: a name, an email address, and the Amperity ID, which will be used to identify the users in Zendesk:

SELECT
  amperity_id AS external_id
  ,LOWER(full_name) AS name
  ,email AS email
FROM Customer_360

The following example is a query that sends additional contact information for customers that uses some of the fields that are built into the Zendesk User API along with a small set of custom fields for each customer’s location:

SELECT
  amperity_id AS external_id
  ,LOWER(full_name) AS name
  ,email AS email
  ,phone AS phone
  ,address AS "user_fields.address"
  ,address2 AS "user_fields.address2"
  ,city AS "user_fields.city"
  ,state AS "user_fields.state"
  ,postal AS "user_fields.postal"
FROM Customer_360

Build a query named “Zendesk - Users” to collect name and phone data from the customer 360 database, along with the Amperity ID and a custom field:

SELECT
  amperity_id AS external_id,
  lower(full_name) AS name,
  phone AS phone,
  city AS "user_fields.city"
FROM Customer_360

Add orchestration

An orchestration defines the relationship between query results and a destination, including the location to which those query results will be sent and the frequency at which the orchestration will be run.

To add an orchestration

1. From the Destinations tab, click Add Orchestration. This opens the Add Orchestration dialog box.

2. From the Object Type drop-down, select Query.

3. From the Object drop-down, select the query for which results will be sent to Zendesk.

4. From the Destination drop-down, select a destination that is configured for sending data to Zendesk.

5. From the Data Template drop-down, select a data template.

6. Verify all settings.

7. Set the workflow to Manual. (You can change this to automatic later, after verifying the end-to-end workflow.)

8. Click Save.

Run orchestration

Run the orchestration manually to validate that it works.

To run the orchestration

1. From the Destinations tab, under Orchestrations, open the    menu for the Zendesk orchestration, and then select Run.

2. The Status column for the orchestration will update to say “Waiting to start…”, after which the notifications pane will update to include a notification that shows the current status.

3. When the orchestration has run successfully, the status is updated to “Completed”.