Administrator Guide
Terminology used
The following terminology is used within this document.
attribute | An Amazon Connect custom attribute which, if set within a contact flow, will override the default configuration set within the app’s settings. |
pop / popped | To automatically open a new tab (or shift focus to an existing one) in Zendesk for a specific user or ticket. |
auto assignment | Setting where tickets are created and/or assigned to the call automatically based on conditions and rules described in this document (default behaviour). |
manual assignment | Setting where users or tickets are presented to the agent (popped), and then it’s up to the agent to either create a new ticket (and for which user), or select an existing ticket and attach the call to it. To enable manual assignment set the attribute |
recognised customer | A customer that was identified as an existing Zendesk user. |
unrecognised customer | A customer that could not be identified as an existing Zendesk user. |
anonymous customer | A customer whose CLI came across as “anonymous” or “private” and therefore could not be identified as an existing Zendesk user. |
user profile | A Zendesk user profile. |
contact flow | An Amazon Connect contact flow. |
app setting | The Amazon Connect app settings. To view or edit the app’s settings in Zendesk, go to admin, click on manage under apps and select the Amazon Connect app. |
Contact flow attributes
Contact attributes are used to set the behaviour of the app. Contact attributes can be set within your contact flows. An attribute can be set to the same desired value at the start of every contact flow, or can be set dynamically, based on the business logic of the containing flow.
Below is a list of the configuration settings for each contact attribute, each with its default setting and the name of the attribute that overrides that default, if set in the contact flow.
Any attributes set within a contact flow will override its corresponding app setting.
Setting name | Attribute name | Description | Default setting | App setting name | Attribute values |
---|---|---|---|---|---|
Recent ticket timeout | recent_ticket_timeout | This setting controls whether a recent ticket of a recognised caller should be opened instead of creating a new one. E.g. setting this to 15 means that a new ticket will be created if there hasn’t been a ticket created or updated in the last 15 minutes for that user. | 0 | Create ticket after minutes | numerical value (in minutes) |
Ticket assignment behaviour | ticket_assignment | Determines how tickets are created or assigned to a call. When set to auto a new ticket will be created for each call. When set to agent the agent will have control over the creation of new tickets or selecting from existing ones to attach the call to. | auto | Does not have an app setting. Can only be set within a contact flow. | auto; agent |
Pop customer or ticket details before accepting the call | pop_incoming | If this option is set to false then customer or ticket details will be displayed in Zendesk only after the agent accepts the incoming call. | true | Does not have an app setting. Can only be set within a contact flow. | true; false |
Insert call details with embedded call recording | voice_comment | When set to true, call details such as where the call originated from, who answered it, time and length of the conversation and audio recording of the call with embedded player will be attached to the ticket. | true | Does not have an app setting. Can only be set within a contact flow. | true; false |
Provide a link to download the call recording file | download_recording | When set to true, a link to download the audio file (.wav) of the call recording will be attached to the ticket. | true | Does not have an app setting. Can only be set within a contact flow. | true; false |
Dialled number | dialed_number | The number reported in tickets as the number that the caller dialled in inbound calls. This is usually set in contact flows from System.DialedNumber. If not set, the outbound CLI number specified in the app setting will be used. | null | Default entry point phone number | Phone number in E.164 format only |
Zendesk ticket number | zendesk_ticket | If this attribute is set in a contact flow the ticket number specified will be opened, instead of creating a new one. NOTE: the name of this attribute can be changed in the corresponding app setting. | null | Contact attribute name containing Zendesk Ticket Number. | Zendesk ticket number (entered by caller within IVR) |
Zendesk user ID | zendesk_user | The ID of an existing Zendesk user. If this is set in a contact flow the app will disregard the caller’s CLI and search for a user by this ID. | null | Does not have an app setting. Can only be set within a contact flow. | Zendesk user ID (entered by caller within IVR) |
Customer’s phone number | customer_number | Customer's phone number can be entered in the contact flow (using Store Customer Input block with phone number). If this is set in a contact flow the app will disregard the caller’s CLI and search for a user by this attribute. | null | Does not have an app setting. Can only be set within a contact flow. | Customer phone number (entered by caller within IVR) |
Customer’s name | customer_name | Although Zendesk may treat a customer as an unrecognised caller, their name could be obtained from another source, eg. sales database within the contact flow. Using this attribute that name would then be applied to the newly created Zendesk user instead of the CLI. | null | Does not have an app setting. Can only be set within a contact flow. | Customer’s name entered via chat or set in IVR |
Customer’s email | customer_email | When this attribute is present its value will be used to identify the customer when the contact type is chat and no zendesk_user attribute (see above) is present. | null | Does not have an app setting. Can only be set within a contact flow. | Customer’s email entered via chat or set in IVR |
Customer’s language | customer_language | A 2-letter language code, required for speech analysis. Supported language codes are: en, es, fr, de, it, pt, ar, hi, ja, ko, zh, and zh-TW. | en | Does not have an app setting. Can only be set within a contact flow. | 2-letter language code only |
Force ticket creation | force_ticket_creation | When the ticket assignment attribute is set to agent, this attribute will determine whether to force create a ticket after the call finishes, if the agent hasn't already created or assigned a ticket during the call. | true | Does not have an app setting. Can only be set within a contact flow. | true; false |
Advanced speech analysis | speech_analysis | Performs real-time transcription, text comprehension and sentiment analysis and allows you to attach results to Zendesk tickets. Can use any of the values | null | Does not have an app setting. Can only be set within a contact flow. | transcript; comprehend; sentiment |
Pause / resume recording | pause_recording | Allows the agent to pause and resume a call recording | null | Does not have an app setting. Can only be set within a contact flow. | true; false |
Create a ticket on every outbound call | all_outbound | By default, tickets will not be created for outbound calls to unknown numbers. When this attribute is set to true, a new user will be automatically created along with a new ticket. | false | Does not have an app setting. Can only be set within a contact flow. | true; false |
Chat transcript | chat_transcript | When set to | true | Does not have an app setting. Can only be set within a contact flow. | true; false |
App settings
The app’s settings are configured in Zendesk. To view/edit the app’s settings, go to your Zendesk instance. Click on the admin icon in the left navigation bar, and under apps select manage. Click on the Amazon Connect app.

Default settings and assumptions
The default settings specify the behaviour of the app if no contact attributes have been set within your contact flows. Default settings for the app are as follows:
Setting name | Default setting | Default description |
---|---|---|
Recent ticket timeout | not set | |
Ticket assignment behaviour | auto | By default, a new ticket is created for each call. |
Pop customer or ticket details before accepting the call | true | By default, customer or ticket details will pop for the agent before they accept a call. |
Insert call details with embedded call recording | true | By default, call details with embedded call recording will be attached to every call. |
Provide a link to download the call recording file | true | By default, a link to download the call recording file will be attached to every call. |
Force ticket creation | true | By default, a ticket will be automatically created after the call finishes, if the agent hasn't already created or assigned a ticket during the call. Note this only applies when the ticket assignment attribute is set to agent. |
Dialled number | not set | |
Zendesk ticket number | not set | |
Zendesk user ID | not set | |
Customer’s phone number | not set | |
Customer’s name | not set | |
Customer’s language | en | By default, the language for speech analysis is set to english. |
Advanced speech analysis | not set | |
Create a ticket on every outbound call | false | By default, tickets will not be created for outbound calls to unknown numbers. |
Chat transcript | true | By default, the chat transcript will be attached to a ticket after the end of a chat. |
Customer identification for chats
Recognising a customer from a chat involves using a Lex bot to extract identifying details from the customer and calling the Zendesk search API (which is available as an existing add-on). In the end, the resulting customer ID should be put in the zendesk_user
custom attribute within your contact flow which is then used in the app to uniquely identify the customer..
Alternatively, if the Zendesk search API is not used and your LEX bot just retrieves the customer’s name, this can be used to search for the customer as well. To do this, pass through the customer’s name through the custom attribute customer_name
. If a single customer match is found, that customer’s user profile will pop for the agent. If there are multiple matches with the same name or email, the app will change its ticket assignment behaviour to agent
and a notification message will pop, suggesting to the agent to do a search within Zendesk and select the appropriate user profile.
If a customer cannot be identified the app will change its ticket assignment behaviour to agent
and the agent can create a new user and then click on the create ticket
button to create a new ticket attached to this user.
Alternatively, the agent can first identify the customer and if they are an existing user the agent can navigate to the existing user’s profile and click on the create ticket
button to create a ticket for that user.
The agent may also establish if the chat relates to one of the user’s existing tickets and attach the chat to it by opening the ticket and then clicking on the attach to current
button.
Attaching chat transcript
When either party ends the conversation an additional private comment is added to the ticket containing the chat transcript. The chat transcript contains messaging between the agent and the customer but also status messaging, such as when either party joins or leaves the conversation and chat messages from the chat bot (Connect system messages).
The custom attribute chat_transcript
controls whether the transcript gets attached to the ticket or not (default is true
). This way the you can choose to not include it by setting the attribute in the contact flow to false
.
Single concurrent chat
The latest version of the app only supports an agent being offered one chat at the time. Routing profiles in the related Connect instance should be configured accordingly.
If they’re not and a second chat comes in, the app will display an error message to the agent and will not create a ticket.
Enabling media-less mode
Media-less mode detaches the audio channel from the embedded Connect softphone within your Zendesk instance. The embedded softphone continues to function in all other aspects, such as accepting the call, creating and/or attaching call details to a Zendesk Support ticket, transferring a call to another agent, etc. The audio channel on the other hand needs to be handled by a separate instance of your Contact Control Panel (CCP), which must be launched before the agent starts receiving calls in the connector app.
Virtual Device Infrastructure (VDI) environments
The main purpose of media-less mode is to facilitate the use of the connector app in Virtual Device Infrastructure (VDI) environments where the standard embedded softphone won’t work.
Page and app refreshes
Another use of media-less mode is to bridge the otherwise interrupted audio channel when an agent reloads the Zendesk browser tab.
Normally, when a reload (or refresh) happens, the standard embedded softphone CCP reinitialises and therefore breaks the audio connection with the other party (e.g. customer). In media-less mode it is the external CCP that is open in a seperate tab that caries the audio connection which is unaffected by the reload of the embedded softphone within Zendesk.
This enhancement enabled us to refactor the embedded softphone in such a way that it seamlessly “survives” page reloads and apps refreshes. Call processing and ticket assignment logic continues as if the reload didn’t happen.
Multi-tab handling
This enhancement addresses a number of issues that may arise when handling a call while having the Zendesk Support app open in multiple tabs/windows simultaneously.
Previously, each instance of the Zendesk app would have its own embedded CCP (softphone), unaware of potential other instances, thus duplicating the processing logic. This would at times result in duplicated tickets, users and ticket comments.
With the latest upgrade (v2.2) only the instance (window/tab) that first received (or initiated) the call will be processing it. All others will ignore any further events related to that call. If the call processing tab is duplicated it’s treated as a new tab and the call will continue to be processed in the original one. It’s important not to close the call processing tab or its window. If this happens, try to reopen it (eg. CTRL
+SHIFT
+T
/ CTRL
+SHIFT
+N
in Chrome).