Skip to main content
Skip table of contents

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

Upgrading the SAR application? Please read for important notes before doing so.


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)



zendesk_user: Zendesk user ID

Looks for exact match



Will use detected calling number (CLI) and return the user that has this number as a direct line (not shared)


<custom field name>: <value>

Looks for a Zendesk user matching the custom field value. (See an example below)


zendesk_ticket: Zendesk ticket ID

Looks for exact match


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.


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



Unique user ID within the Zendesk system.



User’s full name as stored in Zendesk



User’s primary phone number



A unique identifier from another system, eg. accounts



User’s first name (extracted from full name)



User’s email address



User's role. Possible values are end-user, agent, or admin



User’s locale, eg. en-AU



User’s time zone, eg. Australia/Sydney



The id of the user's organisation - see Zendesk documentation for more information



Whether the user is suspended



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



Unique ticket ID within Zendesk system.



The ID of the user who requested this ticket



The value of the subject field for this ticket



Current ticket status. Can be new, open, pending, hold, solved, or closed.



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.


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 =

  • (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
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.


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


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).


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).


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.


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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.