This article shows how to set up the Zendesk Agent Scripting app with Instant Notes. Go here if you want to learn more about the features and benefits of the app.

Getting Started

Here are the basic steps to get up and running:

1. Build an interactive decision tree script with Zingtree.
2. Install the Agent Scripting App into Zendesk.
3. Configure the Agent Scripting app within Zendesk.
4. If you want to enable Instant Notes, you’ll need to create one or more endpoint nodes with a “copy to ticket notes” button and content to copy as notes.
5. If you want to have your decision tree scripts update your  Zendesk tickets, you’ll need to add variables and/or tags to your Zingtree tree to match your Zendesk setup.
6. If you want to enable automatic script selection, you’ll need to add tags to your trees in Zingtree and configure the Zendesk Agent Scripting app properly.

Installing the Agent Scripting App into Zendesk

Download and configure the Zendesk Agent Scripting App like so:

1. Download the Agent Scripting app here. If you are updating to 19.6 from a previous version, delete the older version before installing. This will not be necessary going forward.
2. In Zendesk, click the Admin icon and go to Apps > Manage.
3. Click Upload Private App.

   

4. The Upload App page appears.

   

5. Enter “Agent Scripting” or something similar for the App Name.
6. For App File, locate the file zingtree-agent-scripting.zip you downloaded in step 1.
7. Click Upload, then confirm if necessary.

Configuring the App

Once you’ve uploaded the app, the configuration screen appears:

Here’s what each item does:

Tree ID: This is the default tree that appears when agents click “Open Script”.  (You should always have a default tree.)

Zingtree API key: Each organization in Zingtree has an API key, which is used to match scripts and track new tickets. Your API key can be found at zingtree.com under My Account, Organizations and Billing, API and Data.

Show Tree in Side Panel: Select this option if you want to display the entire tree in the right-hand sidebar when a ticket is open. Uncheck this to use pop-over mode instead.

In pop-over mode, you can also click the Zingtree icon in the top bar to launch a script. Like so:

Hide Integration Setup Info: When you are setting up Agent Scripting for the first time, you may need some information about your Zendesk setup to take advantage of automatically updating ticket fields. An “Integration Setup Info” link appears by default when you first install the app, and ticking this option hides it.

Display Half-Height: In Popover mode, the popup view will cover half the height of the screen. This has no effect when using Sidebar mode.

Match Tree Tags to Zendesk Brand: If this option is checked, the subdomain of the selected brand will be matched to a Zingtree tree tag.  Any matching tree or trees will appear. For example, if the brand subdomain is xyz.zendesk.com, any trees tagged as xyz (using the Zingtree Settings tool) will appear.

Match Tree Tags to Zendesk Ticket Tags: If checked, the values in the Zendesk ticket tags will be matched with your Zingtree tree tags (set via the Zingtree Settings tool) to show one or more matching scripts.

Match Tree Tags to values in a Custom field: If you want to use a custom field value to show matching scripts, enter the Zendesk custom field identifier here. The field name can be found using the Integration Setup Info link that first appears in the sidebar when you install the app.

Don’t share Zendesk Custom Fields with Zingtree: By default, the app sends custom field data from each Zendesk ticket to Zingtree so you can do more powerful automatic branching via Logic Nodes, as well as echoing customer information (like their name, for example). If your organization has data privacy concerns, you can check this option to disable data sharing.

IMPORTANT: Be sure to click Install or Update when finished with the app configuration.

Data Sent from Zendesk to Zingtree

Unless you select the Don’t share Zendesk Custom Fields with Zingtree configuration option, Zendesk will send the following variables to your Zingtree decision tree:

• requester_name – The customer’s full name.
• requester_email – The email of the customer.
• zendesk_tags – Any tags in the ticket.
• agent_tags – Any tags from the agent.
• agent – The Agent’s full name.
• agent_first_name – The Agent’s first name.
• zd_subject – The subject of the ticket.
• zd_type -The type of the ticket.
• zd_priority – The priority of the ticket.
• zd_status – The status of the ticket.
• Any custom fields.

To display one of these values, just surround the variable name with # characters. So to show the Agent’s first name in your script, enter #agent_first_name# in the content area of any node in your decision tree.

Tip: Add ##ALL DATA## to the content area of any node in your own tree to see all the variables sent to your script.

How to Update Ticket Data

As agents navigate through your trees, their use of the decision tree scripts you create can automatically update data in that ticket. This can be done in two ways:

• By clicking a button in a script
• By entering data into Zingtree data entry fields.

The Agent Scripting app can update basic ticket data by setting variables within the decision tree script. For example, if you set a Zingtree variable named zd_subject, it will change the subject of the ticket.

These Zingtree variables can update the ticket:

• zd_subject: Set this to change the subject or the title of the ticket.
• zd_priority: Change the priority of the ticket. Possible values: “urgent”, “high”, “normal”, “low”
• zd_type: Change the ticket type. Possible values: “problem”, “incident”, “question” or “task”
• zd_status: Update the ticket status. Possible values: “new”, “open”, “pending”, “hold”, “solved”, “closed”
• zd_comment: Add a new comment to the ticket.

How to Update Custom Fields

You can also set values of custom fields within the ticket. The key is to use variable names in your Zingtree that match the ones used in Zendesk.

First of all, determine the names of the variables in Zendesk by clicking the Integration Setup Info link in the Agent Scripting app. You’ll see something like this:

You’ll see the label for the field as it appears in Zendesk’s ticket form and the Zendesk variable next to it. In the above example, the Product custom field variable is custom_field_22899289. This is a drop-down selector, and the Zendesk values for the field options are astrology and insurance. For the rest of this example, we’ll use custom_field_22899289 as the custom field variable. To make a button selection update a custom field, you’ll set it up in your Zingtree as follows:

• Go to the Overview tool, and edit the node whose button selections will update the ticket.
• Click Edit Buttons (or Add Buttons if you don’t have any buttons defined). The button editor appears:

  

• Make sure Variable(s) to Set on Button Click is checked. This makes the other options appear.
• For the Button Click Variable, enter your custom field variable from Zendesk (custom_field_22899289 in the example).
• For each button option, enter the value of the variable under Score/Value. If this is a drop-down list in your Zendesk ticket, you’ll need to make sure the Score/Value entered matches one of the drop-down option values as shown in the Integration Setup Info.

How to Set Ticket Tags

If you’ve tagged a node in your tree, those tags will automatically transfer to Zendesk when the node appears. Here’s how it’s set up in the node editor in the section titled Internal Tags and Notes :

Button clicks can also add tags to a ticket. Just add two colons and the tag name to the button text.

In the above example, hello or goodbye will be added as a ticket tag. Agents won’t see the ::hello or ::goodbye text.

How to Configure Instant Notes

At the end of a decision tree session, you can make a node with the contents of notes that can be copied into the Internal Notes part of the ticket with a single click. This is a huge timesaver for agents, as you can pre-populate notes they might otherwise be typing into Zendesk. Instead, notes are copied over, and the agent can modify or enhance them as needed.  

To set up Instant Notes in your tree:

1. Make the content of the node appear as you want the notes to appear in Zendesk.
2. Surround the area to be copied with [[COPY-AREA]] and [[/COPY-AREA]], like this. You can drop in those opening and closing copy area tags from the templates button in the toolbar.

   

3. Add a “Copy Notes to Ticket Notes”  button below [[/COPY-AREA]]. You can do this from the Templates button in the node editor like this:

   

When the agent clicks the Copy to Ticket Notes button, the entire content between [[COPY-AREA]] and [[/COPY-AREA]] is copied.

Tip: Add ##TRANSCRIPT## into the copy area to include the full transcript of the session.

Using Zingtree Data Entry Fields to Update Tickets

Just like the above example, you can also use Zingtree for data entry and have that data automatically transferred to your ticket. The key is to use the same variable name in Zingtree as you used in Zendesk. The Integration Setup Info link in the sidebar will give you those Zendesk variable names.

Example: If you have a text entry field in Zingtree you want to update into the Zendesk field custom_field_1234, you would set up the variable name as follows:

Using Zingtree’s Zendesk CSS Theme

For the best user experience, we recommend using the Zendesk Apps theme in your trees that display inside of Zendesk. This will give you more room for your content (since the fonts are smaller), and also match the look and feel of the rest of the Zendesk experience.

To include the Zendesk Agent Scripting App theme in your trees, do the following:

• In Zingtree, open the Settings tool for your tree.
• Click the Display tab.
• Choose either Buttons or Panels as the Default Display Style.
• Click Pick a Color Theme.
• Choose Zendesk Agent Scripting as the theme.
• Click Save Theme and Colors.
• Click Update Settings.

Enabling Automatic Script Selection

Automatic Script Selection works by matching tree tags you set in Zingtree to values in the Brand, Tags, or a custom field in a Zendesk ticket. For example, if a tree is tagged with “astrology”, and the ticket tags include “astrology”, then that tree appears. If several trees match, then they will all appear, and the agent can choose one.

To open a script based on Brand:

• Add tags to your trees for each brand you want to match. So if one of your brands is xyz.zendesk.com, use xyz as a tree tag in Zingtree for all the trees you want to show.
• Make sure Match Tree Tags to Zendesk Brand is checked in the App Configuration.

To open a script based upon Zendesk ticket tags:

• Add tags to your trees for each tag you want to match. So if one of your ticket tag possibilities is “billing”, use billing as a tree tag in Zingtree for all the trees you want to show.
• Make sure Match Tree Tags to Zendesk Ticket Tags is checked in the App Configuration.

To open a script based upon a custom field:

• Add tags to your trees for each possible custom field value you want to match. So if one of your custom field values is “billing”, use billing as a tree tag in Zingtree for all the trees you want to show.
• Make sure the proper Zendesk field variable name is entered for  Match Tree Tags to values in a Custom Field in the App Configuration.

Adding tags to a tree in Zingtree is done like this:

1. Select a tree from My Trees.
2. Go to the Settings tool.
3. Click the Tags tab.
4. Enter or select a tag from the Tree Tags field.

   

Version 19.6 Release Notes:

• Sending blank values if variable value is null (Empty text fields in Zendesk populating Zingtree fields as NULL).
• Verifying string variables and removing whitespace from both sides.
• Sending variables with spaces causing issues with numbers, the server adding negative (-).
• Sending variables with spaces causing issues with strings.
• The configuration variables are renamed to lowercase for the naming consistency.

• Zendesk App: Agent Scripting with Instant Notes - Overview and Benefits