Administrator Guide

Terminology used

The following terminology is used within this document.

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 false, a link to download the audio file (.wav) of the call recording and embedded player will NOT appear in the attached voice comment.	true	Does not have an app setting. Can only be set within a contact flow.	true; false
Call recording consent	call_recording_consent	Set this to false or optout when you’re not recording the conversation. Set it to true or optin when customer gave explicit consent to recording. Leaving it null (default) assumes recording is on without explicit consent.	null	Does not have an app setting. Can only be set within a contact flow.	optout, false; optin, true;
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 Dialed number system attribute. 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
Outbound CLI	outbound_cli	The number reported in tickets as the number that the agent dialled out from in outbound calls. This is usually set in contact flows from Queue Outbound Number system attribute. 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)
Conversation title	conversation_title	When set, the contents of this attribute will set the subject of a newly created ticket, instead of the usual “incoming/outgoing call …”. It will also set the title of the voice comment for calls.	null	Does not have an app setting. Can only be set within a contact flow.	Subject line, set by 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
Pause / resume recording	pause_recording	Allows the agent to pause and resume a call recording, assuming recording has been turned on.	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 the chat transcript between agent and customer will be attached to the ticket.	true	Does not have an app setting. Can only be set within a contact flow.	true; false
VoiceID enabled	voiceid_enabled	This flag is used to update a calling customer with their unique voice id and enrolment status (see detailed explanation in the VoiceID section below)	false	Does not have an app setting. Can only be set within a contact flow.	true; false
Zendesk user field for voice ID identifier	voiceid_field	Value of the field key of the Zendesk custom user field where the VoiceID unique id should be stored	voice_authentication_id	Does not have an app setting. Can only be set within a contact flow.	a valid Zendesk user field key
Zendesk user field for voice ID status	voiceid_status_field	Value of the field key of the Zendesk custom user field where the VoiceID status should be stored (status can be ENROLLED, OPTED_OUT or blank)	voice_authentication_status	Does not have an app setting. Can only be set within a contact flow.	a valid Zendesk user field key
VoiceID authentication mode	voiceid_auth_mode	Drives Voice authentication in connected state.	null	Does not have an app setting. Can only be set within a contact flow.	null, verify, re-verify

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:

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.

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.

VoiceID setup

Amazon Connect Voice ID, a feature of Amazon Connect, uses machine learning to provide real-time caller authentication and fraud risk detection to make voice interactions faster and more secure. You can read more about it here.

VoiceID is a feature of Amazon Connect which is independent from Zendesk connector app, in other words, it’s already implicitly supported by the app via the embedded CCP.

The Amazon Connect app for Zendesk ads some enhancements which will improve both customer and agent experience and also improve Zendesk reporting on the uptake of VoiceID.

First, as an admin, you will need to setup two custom Zendesk user fields with the following keys:

• voice_authentication_id: this will hold a unique id linked to customer's voiceprint

• voice_authentication_status: this will have the VoiceID enrolment status, which can be one of: blank (not enrolled), ENROLLED or OPTED_OUT

The above two field keys can be named differently if required. In such case you need to set these names in the respective contact flow as follows:

• for voice authentication id, set the field key in the voiceid_field contact attribute

• for voice authentication status, set the field key in the voiceid_status_field contact attribute

Second, you will need to install the Zendesk Search add-on from AWS Serverless application repository. This add-on will enable search and retrieval of the calling customer’s information, including the above listed user fields.

Third, you will need to construct a contact flow (sample available from our portal) in a certain way, to achieve the full benefit of these enhancements.

Customer and agent experience will be as follows:

1. A customer calls for the first time, or is not recognised, or is an existing customer but not yet enrolled or opted out (their VoiceID status is blank). A globally unique id is setup as their VoiceID identifier - the contact id can be used for that purpose. VoiceID session is initiated and contact attribute voiceid_enabled is set to true (used by the connector app at the end of the call).

2. The call is placed into a queue and routed to an agent, who accepts the call. The VoiceID UI is displayed to the agent where they can see that the customer is not yet enrolled. Agent can then suggest to the customer to be enrolled into VoiceID. If the customer accepts the agent can enrol them via VoiceID UI. If they decline the agent marks them as opted out (via the same VoiceID UI).

3. At the end of the call, the app checks customer’s enrolment status and saves it into their voice authentication status Zendesk user field. It also saves the generated voice authentication id into respective Zendesk user field.

Later, when that same customer calls again and are identified by the Zendesk-Search add-on, the contact flow looks into their enrolment status and takes one of the two paths:

1. If the enrolment status is ENROLLED, the IVR asks the customer to speak for about 10 seconds, so that they can be verified by their voiceprint. VoiceID verifies them against the stored authentication id, retrieved from the respective Zendesk user field. If they are successfully authenticated, agent will see that immediately upon being connected. If they are not authenticated though or authentication result is inconclusive, the ticket_assignment contact attribute will be set to agent (manual), so that the call and the related Zendesk support ticket is not automatically attributed to a potentially wrong customer.

2. When the enrolment status is OPTED_OUT, the IVR will skip voice verification and will route the call to an agent who will be able to see that customer is not opted into the VoiceID.

Regardless of current enrolment status, customer can always request a change. So they can decide to opt out after being already enrolled, or the opposite - request to be enrolled after they’ve opted out. The connector app will store their updated status in the respective Zendesk user field.

Enhanced Monitoring and Multi-party Calls

Enhanced monitoring is Amazon Connect’s functionality for supervisors to either silently monitor agent calls, or barge-in to a call to assist the agent. This feature is enabled in Amazon Connect configuration together with Multi-party calls.

The act of monitoring (both legacy and enhanced) will have no effect on the ticket created by the agent. For the enhanced monitoring to work correctly the supervisor has to be in the Offline state. Upon connecting to an existing call for monitoring the ticket related to the monitored call will automatically display (pop) for the supervisor. Note that this feature applies only to the enhanced monitoring.

Multi-party calls will enable agents to add up to 4 additional participants (ie. 6 in total) to a call through either quick connects or the number pad. Agent’s Connect experience will be governed per the enhanced Contact Control Panel UI (described here).

Multi-party calls should not create multiple Zendesk tickets. Instead, all agent parties (legs) should be reported on the same ticket. This behaviour closely matches the current behaviour with transfers - for each added agent call leg, that agent’s connector app will search for a ticket with the original Contact ID. If found, it will automatically pop and the call leg details will be added to it. If not found, the agent will be automatically set into the manual ticket assignment mode, where they will have the ability to search for the ticket and then attach their call leg to it.

Sometimes, ticket can’t be found due to Zendesk indexing lag, or if the agent doesn’t have permission to view the ticket, for example if the ticket is assigned to a private group which the agent is not a member of.

It can also happen if the first agent hasn’t created a ticket yet because they were in manual assignment mode. After a ticket is created, the first agent can let other agents on the call know the ticket id, so other agents can then find it via Zendesk search and attach their call legs to it (assuming they have required permissions).

Note: At the moment Contact Lens are not supported with multi-party calls and monitoring barge-in. Although the transcript and sentiment analysis will still be added to the ticket, they may be of a degraded quality. (Applies only to clients who have enabled Contact Lens add-on functionality.)

Integration with Amazon Connect Tasks

You can can configure an integration of Zendesk support tickets with Amazon Connect tasks, so that certain ticket events (eg. create, update) automatically create a corresponding task in Amazon Connect which then routes it according to configured routing rules.

To achieve this you need to establish Zendesk → Amazon EventBridge integration and configure associated task creation rules. Zendesk and Amazon Web Services support the integration between platforms via Amazon EventBridge, where a Zendesk event, such as Support ticket creation, can be captured and processed in EventBridge. In our case that process is automatic Amazon Connect task creation on such event.

Note: you’ll need to have the Amazon EventBridge integration enabled by Zendesk first. Please get in touch with their support team.

Tasks that are created via such integration follow a naming convention where the task name field is in the format of Zendesk-nnnn where nnnn stands for Zendesk ticket number.

As such a task is routed to an agent, the connector app will offer it to the agent and automatically pop the related Zendesk ticket. If the agent accepts the task, it’s details will be added as a private note to that ticket, same as they would for accepted call.