Zendesk Search for Connect with the help of the Zendesk Support API

Upgrading the SAR application? Please read https://help.voicefoundry.cloud/zendesk/add-on-features for important notes before doing so.

Introduction

Zendesk Search for Amazon Connect is an optional add-on to the Amazon Connect app for Zendesk. It enables driving the business logic of either DTMF driven (classic IVR) or conversation driven (LEX bot) contact flows, based on query results from the Zendesk Support API.

The following types of searches are supported:

search for user by user ID
search for user by caller’s phone number (CLI)
search for user by custom Zendesk user fields
search for ticket by ticket ID
search for most recent open ticket of an identified user
templated searches for other queries supported by the Zendesk API

The search is performed within a contact flow by calling a lambda function which is installed as part of the corresponding serverless application within the AWS Serverless Application Repository. This lambda in turn calls the Zendesk Support API with a specific search query, based on parameters passed from the contact flow.

Lambda functions called from Amazon Connect follow a simple interface - accepting a key/value map of arguments and returning another key/value map as a response. In the contact flow, values are then extracted from the map as contact flow attributes of type External and using the key as the attribute name or directly as $.External.<key> (see this AWS documentation for more in-depth information).

Search Parameters

To tell the lambda which of the above search types to use, we pass the parameter search_by with one of the following values zendesk_user, calling_user, custom_field, zendesk_ticket, most_recent_ticket or template, followed by none, one or more additional parameters:

`search_by` type	Additional parameter(s)	Comments
`zendesk_user`	`zendesk_user`: Zendesk user ID	Looks for exact match
`calling_user`	None	Will use detected calling number (CLI) and return the user that has this number as a direct line (not shared)
`custom_field`	`<custom field name>`: <value>	Looks for a Zendesk user matching the custom field value. (See an example below)
`zendesk_ticket`	`zendesk_ticket`: Zendesk ticket ID	Looks for exact match
`most_recent_ticket`	`zendesk_user`: Zendesk user ID, `recent_hours`: time range	The most recent open ticket for the specified user within a given time range is returned. If the `recent_hours` is omitted it will default to the value entered at installation.
`template`	`search_template`: search query with placeholders for parameter values, `<parameter x name>`: <value x>	The search template is populated with parameter values and then passed onto Zendesk API. (See detailed discussion below)

Below is an example of configuring the lambda call block in a contact flow, where we want to search for a Zendesk support ticket by its number captured in a previous prompt:

For search_by types that return complex information instead of a simple key-value map, make sure to select JSON as Response validation type in Lambda invocation block:

This way you can access nested values by using dot notation, eg. $.External.user_fields.member_since

Return Status

Depending on the search type, the response from lambda will have different fields in the key/value map. All responses will have a status field, which can have one of the following values:

ok: the search was successful, we have found at least one matching user or ticket
not found: the search couldn’t find any user or ticket based on given parameters
bad request: some parameters are missing or invalid
server error: there was a networking error or some other technical issue

Here’s a cut-out from a contact flow depicting how we may branch based on the status value returned from the lambda:

Common Fields

Apart from the status field, each response also contains some common fields, depending on what we’re searching for (i.e. a user or a ticket):

Common user fields

Field name	Zendesk API property	Field value
*`zendesk_user`	id	Unique user ID within the Zendesk system.
*`customer_name`	name	User’s full name as stored in Zendesk
*`customer_number`	phone	User’s primary phone number
`external_id`	external_id	A unique identifier from another system, eg. accounts
`user_name`	N/A	User’s first name (extracted from full name)
`user_email`	email	User’s email address
`user_role`	role	User's role. Possible values are `end-user`, `agent`, or `admin`
`user_locale`	locale	User’s locale, eg. `en-AU`
`time_zone`	iana_time_zone	User’s time zone, eg. `Australia/Sydney`
`organization`	organization_id	The id of the user's organisation - see Zendesk documentation for more information
`suspended`	suspended	Whether the user is suspended
`user_fields`	user_fields	Custom defined user fields. This can be accessed using dot notation, eg. `user_fields.account_status` where account_status is a custom Zendesk user field.

^{* These value are usually stored in custom attributes with the same name and passed to the Amazon Connect app forZendesk.}
For more details on the Zendesk API user properties please check this documentation.

Common ticket fields

Field name	Zendesk API property	Field value
*`zendesk_ticket`	id	Unique ticket ID within Zendesk system.
*`zendesk_user`	requester_id	The ID of the user who requested this ticket
`ticket_subject`	subject	The value of the subject field for this ticket
`ticket_status`	status	Current ticket status. Can be `new`, `open`, `pending`, `hold`, `solved`, or `closed`.
`ticket_brand`	brand_id	The ID of the brand this ticket is associated with

^{* These value are usually stored in} ^{custom attributes with the same name and passed to the Zendesk Connect app.}
For more details on Zendesk API ticket properties please check this documentation.

This returned fields can then be used to further drive business logic within the contact flow. For example user_locale can be used to play prompts in the customer’s native language, brand_id and organization can determine routing to appropriate queue or another contact flow, etc.

Search by Custom Fields

Within Zendesk we can create our own custom user fields to store various data about our customers. We can then use the name of such custom fields in our search.

Let’s say for example that we’ve added a field to store a customer’s account number:

When we added this field we had to specify a unique Field key. We will use this field key as the parameter name in our lambda call, like this:

Note, to search by custom ticket fields we need to use templates. See an example of searching by order number in the Templates section below.

Templates

Searching with a template provides the greatest power and flexibility but is more complex and requires some upfront preparation. To be productive with this type of search one needs to be familiar with the Zendesk Support search reference.

This type of search requires four groups of parameters to be passed to the lambda:

template string with placeholders, eg. search_template = type:user email:{user_email}
placeholder values, eg. user_email = mary.smith@widgets.biz
(optional) ordering parameters sort_by and sort_order
(optional) list of return fields, eg. details, notes

As a simple example let’s say we’re searching for a ticket that contains an order number in a custom field. For this we would need to set the following three lambda parameters:

search_by = template
search_template = type:ticket custom_field_3600456789:{order_number}
order_number = 8765

assuming the order number we’re searching for is 8765 and our order number custom ticket field has a field ID of 3600456789.

Let’s have a closer look at each of parameter groups.

Template string (`search_template`) and placeholder values

A search string, formatted according to the Zendesk search syntax, except that the values are expressed as placeholders - parameter names inside braces, eg. {zendesk_ticket}. Before the search string is submitted to the Zendesk Support API, all placeholders are replaced with values of corresponding parameters.

For example, say we pass 83217 as zendesk user and 48 as recent_hours, then this template
type:ticket requester:{zendesk_user} -status:closed -status:solved created>{recent_hours}hours
becomes:
type:ticket requester:83217 -status:closed -status:solved created>48hours

Ordering parameters `sort_by` and `sort_order`

Searching via templates often returns a list of several items. The lambda function however, can only return a single one back to the contact flow. As a rule, this is the first item in the list. That’s why it may be important to sort the result set in a certain way so that the desired item is at the start of the list.

Parameter sort_by contains the name of the Zendesk API property we want the returned results to be ordered by.
Parameter sort_order can be either asc or desc and specifies either ascending or descending sort.

Following the above template example we would set the sort_by parameter to updated_at and sort_order to desc, so that we get the most recently updated open ticket as the first item in the result set.

List of return fields (`return_fields`)

This parameter contains a comma separated list of fields from the result set that should be included in the lambda response, in addition to common fields (as mentioned earlier in this document) that are always returned. Common fields set is determined by the type search attribute at the start of the search template, so it’s always a good idea to include it when searching for either tickets or users.

For example, a search template starting with type:ticket will return all the common ticket fields listed above, plus any additional fields listed in the return_fields parameter.

All responses from a templated search will also return one more property - count. This reflects the number of results found by the search and can be used in driving the contact flow logic.

The carry-on (`carry_on`) facility

When using Zendesk search within our contact flows we often need to make consecutive lambda calls and sometimes there’s a need to keep values returned from one call in the next call’s response. In this scenario the carry-on facility comes handy. When doing the second lambda call we can use a parameter called carry_on containing a (comma separated) list of fields returned from the first call and then add individual fields as parameters with their values. Then the response from the second call will contain also those fields.

For example, if we first searched for a user and then for the most recent ticket for that user we may want to carry on certain user fields, such as the user’s first name in the ticket response:

We can then use both a ticket field and the carried over user_name field in a prompt:

Installation guide

To enable this feature you will need to install a serverless application within the AWS Serverless Application Repository.

Sign in to your AWS account, then search for and select the Serverless Application Repository service.

Make sure you are in the same region as your Connect instance.

Click on Available applications.

Under Public applications, select the checkbox Show apps that create custom IAM roles or resource policies.

Search for and select Zendesk-search-for-Connect-contact-flows.

Scroll down to Application settings and enter the following information:

Application name

Leave this as is.

TargetEnvironment

This is the name of your target environment (dev, UAT, prod etc). If unsure, just leave as prod.

RecentTicketsHours

This applies for one of the search options to look for the most recent ticket to open for a user. Set the time frame in hours within which to search for the most recently updated open ticket for a user (defaults to 72 if not specified here).

ZendeskEmailID

Enter the verified email address of a Zendesk user for your Zendesk instance. It’s advisable to create a dedicated Zendesk user for this integration so the functionality is not broken when a Zendesk user is removed (eg. if the related person leaves the company).

ZendeskToken

Sign in to your Zendesk instance. Click on Admin within the left hand navigation bar, and under Channels select API.

Click on Add API token.

Click on Copy. Paste the API token into the ZendeskToken field.

ZendeskURL

Enter the URL of your Zendesk instance. Ensure the URL begins with https:// and do not include / at the end of the URL or the stack will fail.

Select the checkbox to create custom IAM roles and click on Deploy.

Once your stack has been successfully created, scroll down and take note of the lambda name.

In your AWS account, search for and select Amazon Connect. Click on your Amazon Connect instance.

Click on Contact flows.

Under AWS lambda, click on the Function dropdown and select the lambda that was created during the stack.

Click on Add lambda function.

Once you have added the lambda to your Connect instance, you will then need to add the lambda to your contact flows. To get an understanding of how to configure your contact flow with this lambda, view the sample contact flow below.

Using the sample contact flow

We have provided a sample contact flow that showcases some of the potential searches you can perform within your own contact flows.

NOTE: You will need to update the lambdas in the sample contact flow with the lambda you added to your Connect instance.