# Create Contact Lens rules using the Amazon Connect admin website
Contact Lens rules allow you to automatically categorize contacts, receive alerts, or generate tasks based on keywords that are used during a call, chat, or email, sentiment scores, customer attributes, and other criteria.
This topic explains how to create rules using the Amazon Connect admin website. To create and manage rules programmatically, see [Rules actions](https://docs.aws.amazon.com/connect/latest/APIReference/rules-api.html) and the [Amazon Connect Rules Function language](https://docs.aws.amazon.com/connect/latest/APIReference/connect-rules-language.html) in the *Amazon Connect API Reference Guide*.
**Tip**
For a list of rules feature specifications (for example, how many rules you can create), see [Amazon Connect Rules feature specifications](feature-limits.md#rules-feature-specs).
## Step 1: Define rule conditions for conversational analytics
1. On the navigation menu, choose **Analytics and optimization**, **Rules**.
1. Select **Create a rule**, **Conversational analytics**.
1. Under **When**, use the dropdown list to choose **post-call analysis**, **real-time analysis**, **post-chat analysis**, or **email analysis**.
![\[The new rule page, the when dropdown menu.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rule-define-conditions.png)
1. Choose **Add condition**.
You can combine criteria from a large set of conditions to build very specific Contact Lens rules. Following are the available conditions:
+ **Words or phrases**: Choose from [Exact match, Pattern match, or Semantic match](exact-match-pattern-match-semantic-match.md) to trigger an alert or task when keywords are uttered.
+ **Natural Language - Semantic Match**: Provide a natural language statement (e.g., customer called to cancel their account) to match with conversation transcripts using generative AI, and take an action (for example, triggering a task, performing an evaluation, etc.) For more information, see [Generative AI-powered semantic match](natural-language-semantic-match.md)
+ **After contact work (ACW)**: Build rules to measure agent efficiency in completing after contact work.
+ **Agent hierarchy**: Build rules that run on a specific agent hierarchy. Agent hierarchies may represent geographical locations, departments, products, or teams.
To see list of agent hierarchies so you can add them to rules, you need the **Agent hierarchy - View** permission in your security profile.
+ **Agent**: Build rules that run on a subset of agents. For example, create a rule to ensure newly hired agents comply with company standards.
To see agent names so you can add them to rules, you need **Users - View** permissions in your security profile.
+ **AI agent**: Identify contacts where a particular Connect AI agent performed self-service or agent assistance. You can select multiple AI agents, or select a specific version of an agent.
To see AI agent names so you can add them to rules, you need **AI agents - View** permissions in your security profile.
+ **AI agent - Escalation**: Identify contacts when a Connect AI agent used for customer self-service escalated to a human.
To see AI agent names so you can add them to rules, you need **AI agents - View** permissions in your security profile.
+ **Agent interaction duration**: Build rules to identify contacts that had an agent interaction longer or shorter than what was expected. This feature applies to calls only.
+ **Contact segment attributes**: You can identify contacts within rules using custom contact segment attributes with values populated from other systems or using custom logic. You can [define an attribute](predefined-attributes.md#predefined-attributes-create-web-admin) and set its value in flows. Custom segment attributes are only present on that specific contact ID, and not the entire contact chain. For example, you can build a rule that identifies that contact was pre-authenticated in IVR, before being connected with the agent.
To see the list of contact segment attributes to add to a rule, you need **Predefined attributes - View** permissions.
+ **Disconnect reason**: Build rules that check for why a contact disconnected. For example, if the agent disconnected prior to the customer, or if the contact was transferred.
+ **Highest loudness score**: Build rules that check for the peak loudness score (in decibels) during the conversation for the agent or the customer. Higher loudness (for example, over 70Db) may be associated with excitement or anger, while speech below a certain loudness score (for example, 30Db or lower) might be hard to understand.
+ **Hold time**: Build rules to identify contacts that had unusual hold times to identify opportunities to handle contacts more efficiently. You can set rules using longest hold time, total hold time, and number of holds. You can also check for hold time as a percentage of the total time the customer was connected with the agent (customer hold time divided by agent interaction duration and customer hold time).
+ **Initiation method**: Build rules that check whether a contact was inbound, outbound, transferred, etc.
+ **Contact attributes**: Build rules that run on the values of custom [contact attributes](what-is-a-contact-attribute.md). For example, you can build rules specifically for a particular line of business or for specific customers, such as based on their membership level, their current country of residence, or if they have an outstanding order.
You can add up to five contact attributes to a rule.
+ **Sentiment - Time period**: Build rules that run on the sentiment analysis results (positive, negative, or neutral) over a trailing window of time.
For example, you can build a rule for when customer sentiment has remained negative for a set period of time. If the participant joined the contact later, the time period set here applies to when participant was present.
When rules are applied to contacts that don't have sentiment data, neutral sentiment is used.
+ **Sentiment - Entire contact**: Build rules that run on the value of sentiment scores over an entire contact. For example, you can build a rule when customer sentiment has remained low for the entire contact, you can create a task for a customer experience analyst to review the call transcript and follow-up.
When rules are applied to contacts that don't have sentiment data, neutral sentiment is used.
+ **Interruptions**: Build rules that detect when the agent has interrupted the customer for more than X times. This feature applies to calls only.
+ **Non-talk time**: Build rules that check for no speech detected. This may include periods of a customer being put on hold. You can check for total non-talk time, longest non-talk time period within a conversation, or percentage of non-talk time during the conversation. High non-talk time, such as a percentage of non-talk time exceeding 50 percent of the conversation, may indicate an opportunity to improve processes or agent coaching opportunities. This feature applies to calls only.
+ **Response time**: Build rules to identify contacts where the participant had a response time longer or shorter than what was expected: Average or Maximum.
For example, you can set a rule on the **Agent greeting time**, also known as **First response time**: after the agent joined the chat, how long until they sent the first greeting message. This will help you to identify when an agent took too long to engage with the customer.
+ **Potential disconnect issue**: Build rules that check for any technical issues (such as network connectivity, device problems). You can use this to exclude contacts from automated agent performance evaluations, where there were connectivity issues out of the agent’s control.
+ **Queues**: Build rules that run on a subset of queues or check if the contact was not queued. Often organizations use queues to indicate a line of business, topic, or domain. For example, you could build rules specifically for your sales queues, tracking the impact of a recent marketing campaign, or, alternatively, rules for your customer support queues, tracking overall sentiment. For self-service interactions, you can check if the contact was never queued, potentially indicating successful self-service with an AI agent.
To see queue names so you can add them to rules you need **Queues - View** permissions in your security profile.
+ **Routing profile**: Identify contacts handled by agents mapped to a specific routing profile. The routing profile may indicate agent department or skill proficiency. For example, you may perform automated evaluations of agents with the routing profile New hires, trained on basic troubleshooting using different evaluation criteria versus tenured multi-skilled agents.
To see the routing profiles so you can add them to rules, you need **Routing Profiles - View** permissions in your security profile.
+ **Talk time**: Build rules using threshold of absolute time spent talking by the agent or the customer. This can be used to identify where the customer did not speak at all, leading the agent to disconnect or where the agent exhibited call avoidance behaviors such as not speaking after picking up the phone.
+ **Agent interaction duration**: Build rules to identify contacts that had an agent interaction longer or shorter than what was expected. This feature applies to calls only.
The following image shows a sample rule with multiple conditions for a voice contact.
![\[A sample rule with multiple conditions for a voice contact.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-conditions.png)
The following image shows a sample rule with multiple conditions for a chat contact. The rule is triggered when the **First** response time is greater than or equal to 1 minute, and the agent did not mention any of the listed greeting words or phrases in their first response.
**First response time** = after the agent has joined the chat, how long until they sent the first message to the customer.
![\[A sample rule with multiple conditions for a chat contact.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-conditions-chat.png)
1. Choose **Next**.
## Step 2: Define rule actions
1. Choose **Add action**. You can choose the following actions:
+ [Create Task](contact-lens-rules-create-task.md): this option is not available for real-time chat
+ [Send email notification](contact-lens-rules-email.md)
+ [Generate an EventBridge event](contact-lens-rules-eventbridge-event.md)
![\[The add action dropdown menu, a list of actions.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-add-action-no-wisdom.png)
1. Choose **Next**.
1. Review and make any edits, then choose **Save**.
1. After you add rules, they are applied to new contacts that occur after the rule was added. Rules are applied when Amazon Connect conversational analytics analyzes conversations.
You cannot apply rules to past, stored conversations.
# Automatically categorize contacts by matching conversations with natural language statements, or specific words and phrases
Contact Lens conversational analytics enables you to automatically categorize contacts to identify top drivers, customer experience, and agent behavior for your contacts. On the **Contact details** page for a chat, categories appear above the transcript, as shown in the following image.
![\[The Contact details page, the Categories section.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-category-overview-chat2.png)
Following are some of the key things you can do when you categorize contacts:
+ With generative AI-powered contact categorization, you can provide criteria to categorize contacts in natural language (for example, did the customer try to make a payment on their balance?).
+ You can provide specific words or phrases spoken by agents or customers to match with a conversation. Contact Lens then automatically labels contacts that meet the match criteria, and provides relevant points from the conversation.
+ You can define actions to receive alerts and generate tasks on categorized contacts.
+ You can specify additional criteria to categorize contacts, such as customer sentiment score, queues, or any custom attributes that you have added to contacts, like customer loyalty information.
## When to use words or phrases
Using specific words or phrases is useful when there is a well-defined list of words or phrases that you wish to detect, for example, monitoring agent script adherence or assessing customer interest in a product.
## When to use natural language
Using natural language statements to match with contacts is useful when there are too many possible words or phrases or when you want to match with context-specific criteria, for example, "The customer wanted to make a change to their subscription plan.", "The agent resolved all of the customer's issues."
## Add rules to categorize contacts
In this section:
+ [Step 1: Define conditions](#add-category-rules-define-conditions)
+ [Step 2: Define actions](#add-category-rules-define-actions)
### Step 1: Define conditions
1. Log in to Amazon Connect with a user account that is assigned the **CallCenterManager** security profile, or that is enabled for **Rules** permissions.
1. On the navigation menu, choose **Analytics and optimization**, **Rules**.
1. Select **Create a rule**, **Conversational analytics**.
1. Assign a name to the rule.
1. Under **When**, use the dropdown list to choose **post-call analysis**, **real-time analysis**, **post-chat analysis**, **real-time chat analysis**, or **email analysis**.
![\[The new rule page, the When dropdown list.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rule-define-conditions.png)
1. Choose **Add condition**, and then choose the type of match:
+ **Words or Phrases - Exact Match**: Finds contacts that match with the exact words or phrases. Enter the words or phrases, separated by a comma.
+ **Words or Phrases Pattern Match**: Finds contacts by looking for a pattern of words or phrases. You can also specify the distance between words. For example, if you are looking for contacts where the word "credit" was mentioned but you do not want to see any mention of the words "credit card," you can define a pattern matching category to look for the word "credit" that is not within a one-word distance of "card."
+ **Natural Language - Semantic Match**: Use generative AI to find contacts that match the provided natural language statement. The statement should be answerable with a yes or no answer. Natural language - Semantic match is used when you want to match contacts with context-specific criteria or when there are too many possible words or phrases for matching. The following are examples:
+ "The customer wanted to make a change to their subscription plan."
+ "The customer indicated a desire to terminate their current services."
+ "The agent offered multiple payment options."
+ "The agent assured the customer that their call was important and requested additional waiting time."
+ "The agent resolved all of the customer's issues."
**Note**
Natural Language - Semantic Match conditions cannot be used for real-time analysis.
To create rules that use generative AI requires an additional permission: **Rules - Generative AI**.
**Pro Tip**:Use generative AI-powered **Natural language- Semantic match** if you previously used **Words or Phrases - Semantic Match**.
+ **Words or Phrases - Semantic Match**: Finds words that may be synonyms. For example, if you enter "upset" it can match "not happy," or "hardly acceptable" can match with "unacceptable," and "unsubscribe" can match with "cancel subscription." Similarly, it can semantically match phrases. For example, "thank you so much for helping me out," "thanks a lot and this is so helpful," and "I am so happy that you are able to help me."
This removes the need to define an exhaustive list of keywords while creating categories, and provides you the ability to cast a wider net for searching similar phrases that are important to you. For best semantic matching results, provide keywords or phrases with similar meaning within a semantic matching card. Currently, you can provide a maximum of four keywords and phrases per semantic matching card.
1. Using **Words or Phrases - Exact Match** as an example, enter the words or phrases, separated by a comma, that you want to highlight and choose **Add**. Each word or phrase separated by a comma gets its own line in the card.
![\[The new rules page, the Words or phrases - Exact match section.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-add-category-rules-script.png)
![\[The new rules page, the Words or phrases - Exact match section, the Add button.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-add-category-rules-script2.png)
The logic that Contact Lens uses to read these phrases is: (Hello AND thank AND you AND for AND calling AND Example AND Corp) OR (we AND value AND your AND business) OR (how AND may AND I AND assist AND you).
Alternatively, use a **Natural Language - Semantic Match** condition and enter a natural language statement in the textbox, that Generative AI should be able to evaluate as either True or False.
![\[The new rules page, the Natural language - Semantic match section.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-add-category-rules-natural-language-semantic.png)
1. To add more words or phrases, choose **Add group of words or phrases**. In the following image, the first group of words or phrases are what the agent might utter, and the second group is what the customer might utter.
![\[A Words or phrases - Exact match for agent, the word AND, a Words or phrases section for the customer.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-add-category-rules-script3.png)
1. The logic that Contact Lens uses to read these phrases is: (Hello AND thank AND you AND for AND calling AND Example AND Corp) OR (we AND value AND your AND business) OR (how AND may AND I AND assist AND you).
1. The two cards are connected with an AND. This means, one of the rows in the first card needs to be uttered AND then one of the phrases in the second card needs to be uttered.
The logic that Contact Lens uses to read the two cards of words or phrases is (card 1) AND (card 2).
1. Choose **Add condition** to apply the rules to:
+ Specific queues
+ When contact attributes have certain values
+ When sentiment scores have certain values
For example, the following image shows a rule that applies when an agent is working the BasicQueue or Billing and Payments queues, the customer is for auto insurance, and the agent is located in Seattle.
![\[A rule with multiple conditions.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-add-category-rules-3.png)
### Step 2: Define actions
In addition to categorizing a contact, you can define what actions Amazon Connect should take:
1. [Generate an EventBridge event](contact-lens-rules-eventbridge-event.md)
1. [Create Task](contact-lens-rules-create-task.md)
1. [Create Case](contact-lens-rules-create-case.md)
1. [Send email notifications](contact-lens-rules-email.md)
1. [Create a rule that submits an automated evaluation](contact-lens-rules-submit-automated-evaluation.md)
### Step 3: Review and save
1. When done, choose **Save**.
1. After you add rules, they are applied to new contacts that occur after the rule was added. Rules are applied when Amazon Connect conversational analytics analyzes conversations.
You cannot apply rules to past, stored conversations.
# When a rule or category fails to be evaluated by Amazon Connect Contact Lens
When Amazon Connect Contact Lens evaluates a rule or category during a post-contact analysis for a voice or chat contact, it is possible that the rule or category fails to evaluate.
Following are the possible category outcomes when a rule or category is evaluated during contact analysis:
1. **Successfully matched and applied to the contact**. When categories are displayed on the **Contact details** page, it indicates they were successfully matched and applied to the contact.
1. **Successfully evaluated and but they don't apply to the contact**. When categories are absent from the **Contact details** page, it indicates they don't apply to the contact but were successfully evaluated by Contact Lens rules.
1. **The contact analysis was completed but a specific category was not evaluated**. When a category fails to be evaluated, it doesn't mean the category doesn't apply to the contact (based on its criteria), but rather that Contact Lens completed the contact analysis without evaluating this specific category.
The following image shows that failed categories are denoted with their dashed borders, transparent backgrounds, error icons, and failed prefixes. When you hover over a failed category, details about why the category failed to evaluate are displayed.
![\[The failed categories on the Contact details page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/failed-categories1.png)
These failed categories only exist from rules with the semantic match condition. The two possible reasons are:
1. **Quota exceeded**: Your Gen AI actions limit was exceeded for that time span. You can request a quota increase through AWS Support.
1. **Failed safety guidelines**: Category processing failed because it did not satisfy security and quality guardrails.
We recommend adding more conditions to your semantic match rules to narrow down the number of contacts it may apply to. This will help avoid quota exceeded failures.
## Contact Lens post-contact analysis output customer S3 file
Failed categories appear in the analysis file under JobDetails > Skipped Analysis.
The `SkippedAnalysis` section shows contact analysis that was marked as 'Skipped', even though the analysis was completed for that contact. It contains the properties "Feature" and "ReasonCode". `POST_CONTACT_SUMMARY` is one of the existing features.
`CATEGORIZATION` is added as a new feature to skipped analysis. There is one unique categorization element in the `SkippedAnalysis` array for each unique `ReasonCode` that resulted in failed categorization. A new `SkippedEntities` property is introduced for each unique element, containing a list of all category names (and their associated rule IDs) that failed due to the associated reason code.
Following is an example of failed categories within `JobDetails`:
```
"JobDetails": {
"SkippedAnalysis": [
{
"Feature": "CATEGORIZATION",
"ReasonCode": "QUOTA_EXCEEDED",
"SkippedEntities": [
{
"CategoryName": "PotentialFraud"
"RuleId": "a1130485-9529-4249-a1d4-5738b4883748"
},
{
"CategoryName": "Refund"
"RuleId": "bbbbbbb-9529-4249-a1d4-5738b4883748"
}
]
},
{
"Feature": "CATEGORIZATION",
"ReasonCode": "FAILED_SAFETY_GUIDELINES",
"SkippedEntities": [
{
"CategoryName": "ManagerEscalation"
"RuleId": "cccccccc-9529-4249-a1d4-5738b4883748"
},
]
},
{
"Feature": "POST_CONTACT_SUMMARY",
"ReasonCode": "INSUFFICIENT_CONVERSATION_CONTENT"
}
]
},
```
For more information, see [Example Contact Lens conversational analytics output files for a call](contact-lens-example-output-files.md).
# Add real-time alerts to Contact Lens for supervisors based on keywords and phrases in a call
After you [enable real-time analytics](enable-analytics.md) in your flow, you can add rules that automatically alert supervisors when a customer experience issue occurs.
For example, Contact Lens can automatically send an alert when certain keywords or phrases are mentioned during the conversation, or when it detects other criteria. The supervisor sees the alert on the real-time metrics dashboard. From there, supervisors can listen in to the live call, and provide guidance to the agent over chat to help them resolve the issue faster.
The following image shows an example of what a supervisor would see on the real-time metrics report when they get an alert. In this case, Contact Lens has detected an angry customer situation.
![\[The real-time metrics page, an alert for an angry customer.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-real-time-metrics-alert2.png)
When the supervisor listens in to a live call, Contact Lens provides them with a real-time transcript and customer sentiment trend that helps them understand the situation and assess the appropriate action. The transcript also eliminates the need for customers to repeat themselves if they are transferred to another agent.
The following image shows a sample real-time transcript.
![\[A sample real-time transcript.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-real-time-transcript.png)
## Add rules for real-time alerts for calls
1. Log in to Amazon Connect with a user account that is assigned the **CallCenterManager** security profile, or that is enabled for **Rules** permissions.
1. On the navigation menu, choose **Analytics and optimization**, **Rules**.
1. Select **Create a rule**, **Conversational analytics**.
1. Assign a name to the rule.
1. Under **When**, use the dropdown list to choose **real-time analysis**.
1. Choose **Add condition**, and then choose the type of match:
+ **Exact Match**: Finds only the exact words or phrases.
+ **Pattern Match**: Finds matches that may be less than 100 percent exact. You can also specify the distance between words. For example, you might look for contacts where the word "credit" was mentioned, but you do not want to see any mention of the words "credit card." You can define a pattern matching category to look for the word "credit" that is not within a one-word distance of the word "card."
**Tip**
Semantic Match isn't available for real-time analysis.
1. Enter the words or phrases, separated by a comma, that you want to highlight. Real-time rules only support any keywords or phrases that **were mentioned**.
![\[A words and phrases rule.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-add-alert-rules-1.png)
1. Choose **Add**. Each word or phrase separated by a comma gets its own line.
![\[A words and phrases rule with multiple phrases, each on it's own line.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-add-alert-rules-2.png)
The logic that Contact Lens uses to read these words or phrases is: (Talk OR to OR your OR manager) OR (this OR is OR not OR helpful) OR (speak OR to OR your OR supervisor), etc.
1. To add more words or phrases, choose **Add group of words or phrases**. In the following image, the first group of words or phrases are what the agent might utter. The second group is what the customer might utter.
![\[A words and phrases rule with multiple phrases for customer and agent.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-add-category-rules-script3.png)
1. In this first card, Contact Lens reads each line as an OR. For example: (Hello) OR (thank OR you OR for OR calling OR Example OR Corp) OR (we OR value OR your OR business).
1. The two cards are connected with an AND. This means, one of the rows in the first card needs to be uttered AND then one of the phrases in the second card needs to be uttered.
The logic that Contact Lens uses to read the two cards of words or phrases is (card 1) AND (card 2).
1. Choose **Add condition** to apply the rules to:
+ Specific queues
+ When contact attributes have certain values
+ When sentiment scores have certain values
For example, the following image shows a rule that applies when an agent is working the BasicQueue or Billing and Payments queues, the customer is for auto insurance, and the agent is located in Seattle.
![\[A words and phrases rule with multiple conditions.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-add-category-rules-3.png)
1. When done, choose **Next**.
1. In the **Assign contact category** box, add a name for the category. For example, **Compliant** or **Not\$1Compliant**.
1. Choose **Next**, then choose **Save and publish**.
# Add real-time alerts to Contact Lens for supervisors based on keywords and phrases in a chat
After you [enable real-time analytics](enable-analytics.md) in your flow, you can add rules that automatically alert supervisors when a customer experience issue occurs.
For example, Contact Lens can automatically send an alert when certain keywords or phrases are mentioned during the chat, or when it detects other criteria. The supervisor can then view the **Contact details** page for a real-time chat to view the issue. From there, supervisors can join the chat, and provide guidance to the agent over chat to help them resolve the issue faster.
The following image shows an example of what a supervisor would see on the **Contact details** page when they get an alert for a real-time chat. In this case, Contact Lens has detected an angry customer situation.
![\[The contact details page, an alert for an angry real-time chat customer.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-realtime-alert-chat.png)
When the supervisor monitors a chat, Contact Lens provides them with a real-time transcript and customer sentiment trend that helps them understand the situation and assess the appropriate action. The transcript also eliminates the need for customers to repeat themselves if they are transferred to another agent.
## Add rules for real-time alerts for chats
1. Log in to Amazon Connect with a user account that is assigned the **CallCenterManager** security profile, or that is enabled for **Rules** permissions.
1. On the navigation menu, choose **Analytics and optimization**, **Rules**.
1. Select **Create a rule**, **Conversational analytics**.
1. Assign a name to the rule.
1. Under **When**, use the dropdown list to choose **real-time analysis**.
1. Choose **Add condition**, and then choose the type of match. The following image shows a rule configured for a **Sentiment - Time period** condition.
![\[The conditions for a real-time chat analysis rule.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-realtime-chat-rule2.png)
Choose from the following options:
+ **Exact Match**: Finds only the exact words or phrases.
+ **Pattern Match**: Finds matches that may be less than 100 percent exact. You can also specify the distance between words. For example, you might look for contacts where the word "credit" was mentioned, but you do not want to see any mention of the words "credit card." You can define a pattern matching category to look for the word "credit" that is not within a one-word distance of the word "card."
**Tip**
Semantic Match isn't available for real-time analysis.
1. Enter the words or phrases, separated by a comma, that you want to highlight. Real-time rules only support any keywords or phrases that **were mentioned**.
![\[A words and phrases rule.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-add-alert-rules-1.png)
1. Choose **Add**. Each word or phrase separated by a comma gets its own line.
![\[A words and phrases rule with multiple phrases, each on it's own line.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-add-alert-rules-2.png)
The logic that Contact Lens uses to read these words or phrases is: (Talk OR to OR your OR manager) OR (this OR is OR not OR helpful) OR (speak OR to OR your OR supervisor), etc.
1. To add more words or phrases, choose **Add group of words or phrases**. In the following image, the first group of words or phrases are what the agent might mention. The second group is what the customer might mention.
![\[A words and phrases rule with multiple phrases for customer and agent.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-add-category-rules-script3.png)
1. In this first card, Contact Lens reads each line as an OR. For example: (Hello) OR (thank OR you OR for OR calling OR Example OR Corp) OR (we OR value OR your OR business).
1. The two cards are connected with an AND. This means, one of the rows in the first card needs to be mentioned AND then one of the phrases in the second card needs to be mentioned.
The logic that Contact Lens uses to read the two cards of words or phrases is (card 1) AND (card 2).
1. Choose **Add condition** to apply the rules to:
+ Specific queues
+ When contact attributes have certain values
+ When sentiment scores have certain values
For example, the following image shows a rule that applies when an agent is working the BasicQueue or Billing and Payments queues, the customer is for auto insurance, and the agent is located in Seattle.
![\[A words and phrases rule with multiple conditions.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-add-category-rules-3.png)
1. When done, choose **Next**.
1. In the **Assign contact category** box, add a name for the category. For example, **Compliant** or **Not\$1Compliant**.
1. Choose **Add action** to specify what action Amazon Connect should take when the conditions are met. You can configure supervisor alerts by using email notifications or by developing a custom integration with EventBridge.
![\[The Generate an EventBridge event and Send email notification options.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-realtime-chat-rule3.png)
1. If you chose **Send email notification**, see [Create rules that send email notifications](contact-lens-rules-email.md) for more details about completing the page and for information about email limits.
If you chose **Generate an EventBridge event**, see [Create a rule that generates an EventBridge event](contact-lens-rules-eventbridge-event.md) for more details about completing the page and for information about subscribing to EventBridge event types.
# Create rules that send email notifications
You can create rules that send email notifications to people in your organization. This helps you to respond more expediently to potential issues in your contact center. For example, you can create a rule to notify:
+ A team supervisor when there is an account escalation or cancellation.
+ A group of people in your contact center as a result of certain words being mentioned during a conversation.
+ A designated person in your contact center when a disagreement occurs during the call.
+ An agent who had handled the contact that was analyzed or evaluated with Amazon Connect conversational analytics.
**Important**
All emails are sent from `no-reply@amazonconnect.com`.
SAML users don't have primary email addresses, they have username logins. A username login is typically an email address but it doesn't have to be. For these users the field label **Email address** is empty inside Amazon Connect. When email notifications are sent for SAML users, they must have a secondary email configured in order to get it. If a secondary email is not configured, the user won't receive the email.
**To create a rule that sends an email notification**
1. Log in to Amazon Connect with a user account that has the [required permissions](permissions-for-rules.md) to create rules.
1. Navigate to **Analytics and optimization**, **Rules**.
1. On the **Rules** page, choose **Create a rule**, and then from the dropdown list, choose **Conversational analytics** or **Evaluation forms**.
![\[The rules page, the create a rule dropdown list, the contact lens option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-create-rule.png)
1. On the **New rule** page, define the conditions for the rule. For more information, see:
+ [Define rule conditions for conversational analytics](build-rules-for-contact-lens.md#rule-conditions)
+ [Define rule conditions for evaluation forms](create-evaluation-rules.md#rule-conditions-eval).
1. When you define actions for the rule, choose **Send email notification** for the action.
![\[The new rule page, the add action dropdown list, the send email notification action.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-email-action.png)
1. In the **Send email notification** section, choose who is going to receive the email by using one of these options:
+ **Select recipients by login**: Routes the email to the specified user.
**Important**
SAML users must have a secondary email configured in order to get it. If a secondary email is not configured, the user won't receive the email.
+ **Select recipients by tags**. Routes the email dynamically based on the agent's tag values.
+ **Select the agent who handled the contact**. Routes the email to the agent who handled the contact.
In the following image, the rule sends a notification email to the agent who handled the contact.
![\[The Send email notification section, the Select the agent who handled the contact option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-email-tag.png)
1. In **Subject**, add the email subject. In **Body**, add the contents of the email notification.
Use **@ to add dynamic variables** that are populated during execution of the rule. For conversational analytics rules and evaluation forms rules, you can add **rule name, instance URL, contact, agent** and **queue** information for the contact that matched the rule. Evaluation forms rules additionally enable you to insert the **evaluation ID**.
![\[The body of the email, the list of available variables.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/rules-send-email-dynamic-variables.png)
**Note**
Other rule types support different variables:
Real-time metrics rules enable you to enter **rule name, instance URL** and list of **agents, queues, flows or routing profile** that breached the threshold to trigger the alert.
Rules for cases allow you to insert **rule name, instance URL** and **case ID**.
1. Choose **Next**. Review your selections, and then choose **Save**.
1. After you add rules, they are applied to new contacts that occur after the rule was added. Rules are applied when Amazon Connect conversational analytics analyzes conversations.
You cannot apply rules to past, stored conversations.
## Email limits
+ Amazon Connect has a default limit of 500 emails a day. When that limit is exceeded, the Amazon Connect instance is blocked for 24 hours from sending more email. This is because the emails are subject to bounce and complaint limits. For more information, see the **Bounce** and **Complaint** sections in [Understanding email deliverability in Amazon SES](https://docs.aws.amazon.com/ses/latest/dg/send-email-concepts-deliverability.html).
+ All emails are sent from `no-reply@amazonconnect.com`, which you cannot customize.
+ SAML users don't have primary email addresses, they have username logins. A username login is typically an email address but it doesn't have to be. For these users the field label **Email address** is empty inside Amazon Connect. When email notifications are sent for SAML users, they must have a secondary email configured in order to get it. If a secondary email is not configured, the user won't receive the email.
If the default option for sending emails does not meeting your requirements, please contact your Technical Account Manager or Support to discuss with the Amazon Connect service team.
# Create a rule that generates an EventBridge event
In real-time or post-call/chat, you can get events and use them to trigger subsequent notifications or alerts, or aggregate reports outside of Amazon Connect. There's a lot you can do with this data. For example:
+ Get real-time alerts in a QuickSight dashboard.
+ Create aggregated reported outside of Amazon Connect.
+ Join data with your CRM.
+ Connect your notification solution to EventBridge and make sure that by end of day, all of a certain type of events go to a certain inbox. The payload tells you the contact, agent, and queue.
**Note**
For real-time metrics rules, the resources triggering the rule will be listed under **resources**. For example, if you create a rule that alerts you on queue metrics such as avg. queue answer time, the list of queues that breached the threshold will be listed under resources.
**To create a rule that generates an EventBridge event**
1. When you create your rule, choose **Generate EventBridge event** for the action.
![\[The new rule page, the take these actions section, the add action dropdown list, the Generate an EventBridge event action.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-events-example1.png)
1. For **Action name**, enter the name for the event payload.
**Note**
The value you assign for **Action name** is visible in the EventBridge payload. When you aggregate events, the action name provides an additional dimension that you can use to process them. For example, you have 200 category names, but only 50 have a specific action name, such as NOTIFY\$1CUSTOMER\$1RETENTION.
![\[The take these actions section, the assign contact category section, the Generate an EventBridge event section.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-add-eb-action.png)
1. Choose **Next**. Review and then **Save**.
1. After you add rules, they are applied to new contacts that occur after the rule was added. Rules are applied when Amazon Connect conversational analytics analyzes conversations.
You cannot apply rules to past, stored conversations.
1. To leverage the EventBridge data, subscribe to the EventBridge event type. See the next procedure.
## Subscribe to EventBridge event types
To subscribe to EventBridge event types, create a custom EventBridge rule that matches the following:
+ "source" = "aws.connect"
+ "detail-type" = "Contact Lens Post Call Rules Matched" or one of the following:
+ **Contact Lens Realtime Rules Matched**
+ **Contact Lens Realtime Chat Rules Matched**
+ **Contact Lens Post Chat Rules Matched**
+ **Contact Lens Evaluation Rules Matched**
+ **Metrics Rules Matched**
The following image shows these settings in the Event pattern section of the new rule page.
![\[The Event pattern section of the new EventBridge rule page.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-eb-rules-events.png)
### Example EventBridge payloads
Following is an example of what the EventBridge payload looks like when **Contact Lens Post Call Rules Matched**.
```
{
"version": "0", // set by EventBridge
"id": "aaaaaaaa-bbbb-cccc-dddd-bf3703467718", // set by EventBridge
"source": "aws.connect",
"detail-type": "Contact Lens Post Call Rules Matched",
"account": "your AWS account ID",
"time": "2020-04-27T18:43:48Z",
"region": "us-east-1", // set by EventBridge
"resources": ["arn:aws:connect:us-east-1:your AWS account ID:instance/instance-ARN"],
"detail": {
"version": "1.0",
"ruleName": "ACCOUNT_CANCELLATION", // Rule name
"actionName": "NOTIFY_CUSTOMER_RETENTION",
"instanceArn": "arn:aws:connect:us-east-1:your AWS account ID:instance/instance-ARN",
"contactArn": "arn:aws:connect:us-east-1:your AWS account ID:instance/instance-ARN/contact/contact-ARN",
"agentArn": "arn:aws:connect:us-east-1:your AWS account ID:instance/instance-ARN/agent/agent-ARN",
"queueArn": "arn:aws:connect:us-east-1:your AWS account ID:instance/instance-ARN/queue/queue-ARN",
}
}
```
Following is an example of what the payload looks like when **Contact Lens Realtime Rules Matched**.
```
{
"version": "0", // set by EventBridge
"id": "aaaaaaaa-bbbb-cccc-dddd-bf3703467718", // set by EventBridge
"source": "aws.connect",
"detail-type": "Contact Lens Realtime Rules Matched",
"account": "your AWS account ID",
"time": "2020-04-27T18:43:48Z",
"region": "us-east-1", // set by EventBridge
"resources": ["arn:aws:connect:us-east-1:your AWS account ID:instance/instance-ARN"],
"detail": {
"version": "1.0",
"ruleName": "ACCOUNT_CANCELLATION", // Rule name
"actionName": "NOTIFY_CUSTOMER_RETENTION",
"instanceArn": "arn:aws:connect:us-east-1:your AWS account ID:instance/instance-ARN",
"contactArn": "arn:aws:connect:us-east-1:your AWS account ID:instance/instance-ARN/contact/contact-ARN",
"agentArn": "arn:aws:connect:us-east-1:your AWS account ID:instance/instance-ARN/agent/agent-ARN",
"queueArn": "arn:aws:connect:us-east-1:your AWS account ID:instance/instance-ARN/queue/queue-ARN",
}
}
```
# Create a rule that generates a task
Amazon Connect rules enables you to generate tasks. This helps you create traceable actions with owners and provides you visibility on task completion and productivity out the box.
Following are some examples:
+ Review a contact when the customer is fraudulent. For example, you can create a follow-up task when a customer utters words or phrases that makes them appear potentially fraudulent.
+ Follow up when the customer mentions specific topics that you want to later on upsell or provide additional support by reaching out.
+ Evaluate agent performance in specific scenarios, e.g. customer sentiment was very low during the conversation and the customer expressed frustration.
+ Take operational actions, such as assigning additional agents to queues on which avg. queue answer time in the last hour has exceeded acceptable thresholds.
**To create a rule that creates a task**
1. When you create your rule, choose **Create Task** for the action.
![\[The new rule page, the add action dropdown menu, the create task option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-add-task-example1.png)
1. Complete the task fields as follows:
![\[The new rule page, the assign contact category section, the Create task section.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-add-tasks-example2.png)
1. **Category name**: The category name appears in the contact record. Max length: 200 characters.
1. **Name**: The name appears in the agent's Contact Control Panel (CCP). Max length: 512 characters.
1. **Description**: The description appears in the agent's Contact Control Panel (CCP). Max length: 4096 characters.
**Note**
In Name and Description, use **@ to add dynamic variables** that are populated during execution of the rule. For conversational analytics rules and evaluation forms rules, you can add **rule name, instance URL, contact, agent** and **queue** information for the contact that matched the rule. Evaluation forms rules additionally enable you to insert the **evaluation ID**.
![\[The task action with dynamic variables.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/rules-create-task-dynamic-variables.png)
Other rule types support different variables::
Real-time metrics rules enable you to enter **rule name, instance URL and list of agents, queues, flows or routing profile** that breached the threshold to trigger the alert.
Rules for cases allow you to insert **rule name, instance URL** and **case ID**.
1. **Task reference name**: This is a default reference that automatically appears in the agent's CCP.
+ For real-time rules, the task reference links to the Real-time details page.
+ For post-call/chat rules, the task reference links to the **Contact details** page.
1. **Additional Reference name**: Max length: 4096 characters. You can add up to 25 references.
1. **Select a flow**: Choose the flow that is designed to route the task to the appropriate owner of the task. The flow must be saved and published for it to appear in your list of options in the dropdown.
1. The following image shows an example of how this information appears in the agent's CCP.
![\[A task in the agent's Contact Control Panel.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-add-tasks-ccp.png)
In this example, the agent sees the following values for **Name**, **Description**, and **Task reference name**:
1. **Name** = **Action-Required-Contact Lens- ba2cf8fe....**
1. **Description** = **Test**
1. **Task reference name** = taskRef and the URL to the Real-time details page
1. Choose **Next**. Review and then choose **Save** the task.
1. After you add rules, they are applied to new contacts that occur after the rule was added. Rules are applied when Amazon Connect conversational analytics analyzes conversations.
You cannot apply rules to past, stored conversations.
## Voice and task contact records are linked
When a rule creates a task, a contact record is automatically generated for the task. It's linked to the contact record of the voice call or chat that met the criteria for the rule to create the task.
For example, a call comes into your contact center and generates CTR1:
![\[Information on the initial contact record when a call comes in.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-attributes-example1.png)
The Rules engine generates a task. In the contact record for the task, the voice contact record appears as the **Previous contact ID**. In addition, the task contact record inherits contact attributes from the voice contact record, as illustrated in the following image:
![\[Contact record 2 for the task.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-attributes-example2.png)
## About dynamic values for ContactId, AgentId, QueueId, RuleName
The dynamic values in brackets [ ] are called [contact attributes](what-is-a-contact-attribute.md). Contact attributes enable you to store temporary information about the contact so you can use it in a flow.
When you add contact attributes in brackets [ ] — such as ContactId, AgentId, QueueId, or RuleName — the value is passed from one contact record to another. You can use contact attributes in your flow to branch and route the contact accordingly.
For more information, see [Use contact attributes](connect-contact-attributes.md).
# Create a rule in Contact Lens that ends associated tasks from a case
**To create a rule that ends associated tasks**
1. When you create your rule, choose **A new case is updated** as the event source.
![\[The new rule page, the add action dropdown menu, the a case is added option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-update-case-1.png)
1. When you create your rule, choose **End tasks** for the action.
![\[The new rule page, the add action dropdown menu, the end tasks option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-ends-tasks-2.png)
![\[The end tasks option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-ends-tasks-3.png)
1. Choose **Next**. Review and then choose **Save**.
1. After you add rules, they are applied to new contacts that occur after the rule was added. Rules are applied when Amazon Connect conversational analytics analyzes conversations.
You cannot apply rules to past, stored conversations.
# Create a rule in Contact Lens that creates a case
**To create a rule that creates a case**
1. When you create your rule, choose **Post-call analysis is available**, **Post-chat analysis is available**, or **Email analysis is available** as the event source.
![\[The define condition page, choose Post-call analysis is available, Post-chat analysis is available, or Email analysis is available as event source.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-create-case-1.png)
1. Choose **Next**
1. On the actions page, choose **Create case** for the action.
![\[The new rule page, the add action dropdown menu, the create case option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-create-case-2.png)
1. In the **Create case** card, select a **Case template**.
![\[In the Create case card, select a Case template.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-create-case-3.png)
1. Fill out the **required fields** and add **optional case fields** to populate case data.
**Note**
A customer profile must be associated with a contact for this action to work. For more information, see [Enable Cases](enable-cases.md).
![\[Fill out the required fields and add optional case fields to populate case data.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-create-case-4.png)
1. Choose **Next**. Review and then choose **Save**.
1. After you add rules, they are applied to new contacts that occur after the rule was added. Rules are applied when Amazon Connect conversational analytics analyzes conversations.
You cannot apply rules to past, stored conversations.
# Create a rule in Contact Lens that updates a case
**To create a rule that updates a case**
1. When you create your rule, choose **A case is updated** as the event source and choose **Next**.
![\[The new rule page, the add action dropdown menu, the a case is updated option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-update-case-1.png)
1. When you create your rule, choose **Update case** for the action.
![\[The new rule page, the add action dropdown menu, the update case option.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-update-case-2.png)
1. Select any case field that you want to update from the dropdown and define its new value.
![\[Select any case field that you want to update from the dropdown and define its new value.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-update-case-3.png)
![\[Select any case field that you want to update from the dropdown and define its new value.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-update-case-4.png)
1. Choose **Next**. Review and then choose **Save**.
1. After you add rules, they are applied to new contacts that occur after the rule was added. Rules are applied when Amazon Connect conversational analytics analyzes conversations.
You cannot apply rules to past, stored conversations.
# Create a rule in Contact Lens that submits an automated evaluation
Contact Lens enables you to automatically fill and submit evaluations by using insights and metrics from conversational analytics.
## Step 1: Configure automation on the evaluation form
Before you can create a rule that submits an automated evaluation, you need to configure automation on the evaluation form. For detailed instructions, see [Step 6: Enable automated evaluations](create-evaluation-forms.md#step-automate) in [Create an evaluation form](create-evaluation-forms.md).
Following is an overview of the steps:
1. Setup automation on every question in an evaluation form.
1. Turn on **Enable automated submission of evaluations** before activating the evaluation form.
1. When you activate the evaluation form with automation configured, a prompt is displayed for you to create a rule, as shown in the following image.
![\[A prompt to create a rule.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/create-a-rule-to-submit-automated-evaluations-1.png)
1. Choose **Create a rule**.
1. On the **Rules** page, define a rule that specifies which contacts are automatically evaluated using the selected evaluation form. The following procedure provides instructions.
## Step 2: Define a rule that specifies which contacts are automatically evaluated
You can trigger automated evaluations with two types of rules:
+ A **Conversational analytics** rule that automatically evaluates the contact after Contact Lens completes its analysis.
+ An **Evaluation forms** rule that can be used to trigger a situation-specific evaluation form as an outcome of a generic evaluation form. For example, if the answer to the evaluation question *Was the customer interested in purchasing a product* is *Yes*, then you can trigger another evaluation form measuring *Agent sales performance*.
### Trigger automated evaluations with a conversational analytics rule
This is the default rule type that is selected when you create a rule to submit an automated evaluation during form activation. You can also create such a rule by selecting **Create a rule**, **Conversational analytics** on the **Rules** page.
1. Choose **A Contact Lens post-call analysis is available** or **A Contact Lens post-chat analysis is available** as the event source. These two options are highlighted in the following image.
![\[The post-call analysis and post-chat analysis options.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/defined-conditions-evaluations.png)
1. Define conditions to identity contacts to be automatically evaluated, and then choose **Next**.
Example conditions that you can use to identify the specific set of agents or contacts on which the evaluation form is applicable are:
+ Agents
+ Agent hierarchy
+ AI agent
+ Queues
+ Initiation method
In addition, you can exclude contacts that may have ended prematurely due to connectivity or other issues using conditions such as:
+ Interaction duration (for example, over 30 seconds)
+ Talk time (for example, the customer speaks for over 10 seconds)
+ Potential disconnect issue when the issue does not exist or there is no known connectivity or device issue during the conversation
1. On the **Define actions** page provide a category name to identify the rule.
1. Choose **Add action**, select **Submit automated evaluation**, and select the form that you want to use for automatically submitting an evaluation. (This action is already selected on the page if you created the rule when you activate the form.)
1. Choose **Next**. Review and then choose **Save and Publish**.
After you add rules, they are applied to new contacts that occur after the rule was added. Rules are applied when Amazon Connect conversational analytics analyzes conversations.
**Important**
You cannot apply rules to past, stored conversations.
### Trigger automated evaluations with an evaluation forms rule
1. Go to the **Rules** page. Select **Create a rule**, **Evaluation forms**.
1. Under **When**, select the event source as **A Contact Lens evaluation result is available**.
1. Choose **Add condition** to trigger a situation-specific evaluation. For example:
+ A specific answer on another evaluation, shown in the following image.
![\[A specific answer on another evaluation.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/add-condition-1.png)
+ The score of another evaluation form, shown in the following image.
![\[The score of another evaluation form.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/add-condition-2.png)
1. Choose **Add action**, select **Submit automated evaluation**, and select the form that you want to use for automatically submitting an evaluation.
1. Choose **Next**. Review and then choose **Save and Publish**.
## Frequently Asked Questions (FAQ)
1. **Can an automated evaluation override an evaluation that has been manually submitted?**
No, an automated evaluation cannot override a manually submitted evaluation. If an evaluation already exists, then the automated evaluation will fail for that contact and account administrators can see such failure notifications within CloudWatch.
1. **How do I identify automated evaluations?**
If an evaluation is automatically submitted, it is marked as "submitted by Contact Lens automation" on the **Contact details** page. If an automated evaluation is edited and re-submitted by an evaluator, the "submitted by" contains the name of the evaluator.
1. **Can I automatically evaluate a contact using multiple evaluation forms?**
Yes, you can automatically submit evaluations on a contact using multiple evaluation forms. You need to create multiple rules to submit automated evaluations using the different evaluation forms.
# Use a Word or phrase condition in a Contact Lens rule
Within Contact Lens **conversational analytics** rule, you have the option to specify a Words or phrases condition. You can choose Exact Match, Semantic Match, or Pattern Match for the words or phrases. This topic explains each type of match.
**Note**
All three match types are not case sensitive, for example, if you have specified the word as "billing", it will also match with the transcript containing the word "Billing".
## How to use exact match
**Exact Match** is an exact word match, which can be either singular or plural.
You can add the keywords or phrases by using either of the following methods:
+ Selecting **Enter keywords or phrases** and entering values manually in the text box. Multiple values can be separated by a comma.
![\[Enter keywords or phrases option in the UI.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/exact-match-1.png)
+ Selecting **Import from word collection** to import pre-defined words and phrases from word collections.
![\[Import from word collection option in the UI.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/exact-match-2.png)
Word collections can be categorized into two types: user word collections and system word collections. System word collections are pre-defined by Amazon Connect, which are non-editable to users. A user word collection can be created, read, updated, and deleted (CRUD) by users. For more information, see [Manage word collections when you create conversational analytics rules in Contact Lens](manage-word-collections.md).
## How to use pattern match
If you want to match related words, append an asterisk (\$1) to the criteria. For example, if you want to match on all variations of "neighbor" (neighbors, neighborhood) you would type **neighbo\$1**.
With **Pattern Match** you can specify the following:
+ **List of values**: This is useful when you want to build expressions with interchangeable values. For example, the expression might be:
*I'm calling about a power outage in ["Beijing" or "London" or "New York" or "Paris" or "Tokyo"]*
Then in your list of values you would add the cities: Beijing, London, New York, Paris, Tokyo.
The advantage of using values is that you can create one expression, instead of multiple. This reduces the number of cards that you need to create.
+ **Number**: This option is used most frequently in compliance scripts, or if you're looking for a context when you know somewhere in between there's a number (in digits [0-9]). This way you can put all of your criteria into one expression instead of two. For example, an agent compliance script might say:
*I have been in this industry for [num] years and would like to discuss this topic with you.*
Or a customer might say:
*I have been a member for [num] years.*
**Note**
When extracting numbers from chat or audio transcripts, only numerical digits (0-9) are recognized.
For voice contacts, certain languages may not convert spoken numbers into digital format during [number transcription](https://docs.aws.amazon.com/transcribe/latest/dg/how-numbers.html). This means number pattern matching might not work in these cases. For a list of which languages support number transcription, see [Supported languages and language-specific features](https://docs.aws.amazon.com/transcribe/latest/dg/supported-languages.html) in the *Amazon Transcribe Developer Guide*.
+ **Proximity definition**: Finds matches that may be less than 100 percent exact. You can also specify the distance between words. For example, if you are looking for contacts where the word "credit" was mentioned but you do not want to see any mention of the words "credit card," you can define a pattern matching category to look for the word "credit" that is not within a one-word distance of "card."
For example, a proximity definition might be:
*credit [is not within 1 word from] card*
**Tip**
For a list of languages supported by pattern match, see [AI features](supported-languages.md#supported-languages-contact-lens).
## How to use semantic match
Semantic matching is supported only for post-call/chat analysis.
+ An "intent" is an example of utterance. It can be a phrase or a sentence.
+ You can enter up to four intents in one card (group).
+ We recommend using semantically similar intents within one card to get the best results. For example, there's category for "politeness." It includes two intents: "greetings" and "goodbye". We recommend separating these intents into two cards:
+ Card 1: "How are you today" and "How’s everything going". They are semantically similar greetings.
+ Card 2: "Thanks for contacting us" and "Thank you for being our customer." They are semantically similar goodbyes.
Separating the intents into two cards provides more accuracy than putting them all into one card.
# Use Generative AI to semantically match contacts with natural language statements
Within a Contact Lens **conversational analytics** rule, you have the option to specify a **Natural language - semantic match** condition that uses generative AI to find contacts that match a natural language statement. Natural language - Semantic match is used when you want to match contacts with context-specific criteria (for example, the customer’s issue was resolved during the call) or when there are too many possible words or phrases to use the **Words or phrases** conditions.
Pro Tip: Use generative AI-powered Natural language- Semantic match if you previously used Words or Phrases - Semantic Match.
## How to use Natural language - semantic match
****
1. Log in to Amazon Connect with a user that has permissions **Rules** and **Rules - Generative AI** permissions.
1. On the navigation menu, choose **Analytics and optimization**, and then **Rules**.
1. Then select **Create a Rule** and choose **Conversational analytics**.
![\[Import from word collection option in the UI.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/create-natural-semantic-match-rule.png)
1. Select either "A Contact Lens post-call analysis is available" or "A Contact Lens post-chat analysis is available".
1. Select **Add condition** and then choose **Natural language - semantic match**.
![\[Import from word collection option in the UI.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/choose-natural-semantic-match.png)
1. Enter a natural language statement that can be evaluated by Generative AI as true or false by matching with the conversation transcript.
![\[Import from word collection option in the UI.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/enter-natural-language-statement.png)
1. Add any additional conditions, for example, queues, custom contact attributes, etc.
1. Choose **Next** and provide a category name (with no spaces) that would be used to label contacts with the natural language statement, for example, **CustomerAddressChange**.
1. You can specify additional actions, such as [generating tasks](contact-lens-rules-create-task.md), [sending email notifications](contact-lens-rules-email.md), [automatically submit evaluations](contact-lens-rules-submit-automated-evaluation.md), among others.
1. Choose **Next** to review the rule before you **Save and Publish** the rule. If you are not ready to publish the rule, you can also **Save as draft**.
## Guidelines to use semantic-match
The following list details how to best use semantic-match:
+ The statement should be something that can be evaluated as true or false.
+ Natural language - semantic match only uses the transcript of the conversation. If you want to use other contact attributes (for example, queues) in your match criteria, then those need to be specified as separate conditions within the rule.
+ If possible, use the term 'agent' instead of terms like 'colleague', 'employee', 'representative', 'advocate', or 'associate'. Similarly use the term 'customer', instead of terms like 'member', 'caller', 'guest', or 'subscriber'.
+ Only use double quotes if you want to check for exact words being spoken by the agent or the customer. For example, If the instruction is to check for the agent saying "Have a nice day", then the generative AI will not detect "Have a nice afternoon". Instead the natural language statement should say "The agent wished the customer a nice day".
**Example statements to use with semantic-match **
+ The customer wanted to make a change to their subscription plan.
+ The customer conveyed gratitude towards the agent's support.
+ The customer indicated a desire to terminate their current services.
+ The customer requested a subsequent interaction.
+ The customer asked the agent to repeat information, indicating a lack of understanding.
+ The customer asked to talk to the agent’s manager.
+ The agent asked the customer for additional information or validation before providing a definitive answer.
+ The agent offered multiple payment options
+ The agent assured the customer that their call was important and requested additional waiting time.
+ The agent resolved all of the customer’s issues.
# Manage word collections when you create conversational analytics rules in Contact Lens
A *word collection* is a set of pre-built words and phrases that you can use to define the exact match condition when you create conversational analytics rules. When you add exact match conditions to a rule, you can choose a list of words and phrases from a dropdown menu.
## Required permissions
Contact Lens Rules - Word Collections uses the same set of security profile permissions as Contact Lens Rules. For more information, see [Security profile permissions for Contact Lens rules](permissions-for-rules.md).
## How to access the word collection management page
1. When you create or update a conversational analytics rule, choose the gear icon on top right of the **Exact match** condition card, as shown in the following image.
![\[Enter keywords or phrases option in the UI.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/word-collections-permissions-how-to-access-1.png)
1. On the **Word collections** management page, you can view existing word collections and create new word collections.
![\[Enter keywords or phrases option in the UI.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/word-collections-permissions-how-to-access-2.png)
## How to create a user word collection
****
1. On the **Word collections** management page, choose **Create a word collection**.
![\[Enter keywords or phrases option in the UI.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/create-user-word-collections-1.png)
1. Enter the name of the word collection, add words and phrases, then choose **Save**.
![\[Enter keywords or phrases option in the UI.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/create-user-word-collections-2.png)
## Word collection limits
+ Amazon Connect has a default limit of 100 user word collections per instance.
+ Each word collection can have a maximum of 100 words or phrases.
+ Each word or phrase is limited to no more than 512 characters.
+ You can manage only user word collections. You can not manage or edit system word collections.
# Enter a script in a Contact Lens rule for agents to follow
Enter a script in a Contact Lens rule when you need agents to use exact wording in customer calls.
To enter a script in a rule, enter phrases. For example, if you want to highlight when agents say *Thank you for being a member. We appreciate your business*, enter two phrases:
+ Thank you for being a member.
+ We appreciate your business.
To apply the rule to certain lines of businesses, add a condition for which queues it applies to, or contact attributes. For example, the following image shows a rule that applies when an agent is working the BasicQueue or Billing and Payments queues, the customer is for auto insurance, and the agent is located in Seattle.
![\[The new rule page, the Words or phrases - Exact match section, multiple conditions.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-add-category-rules-3.png)
# Security profile permissions for Contact Lens rules
To view, edit, or add rules for automatic categorization, you must be assigned to a security profile that has **Analytics and Optimization: Rules** permissions.
To view, edit, or add rule that use generative AI (using the **Natural language - semantic match** condition), your security profile must additionally be assigned the **Analytics and Optimization: Rules - Generative AI** permission.
To see agent names so you can add them to rules, you need **Users and permissions: Users - View** permissions in your security profile.
To see the queue names so you can add them to rules, you need **Routing: Queues - View** permissions in your security profile.
For more information, see [Assign permissions to use Contact Lens conversational analytics in Amazon Connect](permissions-for-contact-lens.md).
# Design a flow to use contact attributes in a rule in Contact Lens
You can have up to 5 contact attributes in a rule.
Contact attributes are retrieved at the beginning of the real-time contact analysis session and whatever is retrieved at that time is used for rule evaluation during the whole session. Any contact attribute update after the session started isn't picked up.
You can design flows to use the contact attributes you specify in a rule, and then route the task accordingly. For example, a call or chat arrives in your contact center. When Contact Lens analyzes the call or chat, it gets a hit on the **Compliance** rule. The contact record that's created for the call, for example, includes information similar to the following image. It shows the **Category** = **Compliance**, and it has two custom contact attributes: **CustomerType** = **VIP**, **AgentLocation** = **NYC**.
![\[The contact record when the Compliance rule is triggered.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-attributes-example1.png)
The Rules engine generates a task. The contact record for the task inherits the contact attributes from the voice contact record, as illustrated in the following image.
![\[The contact record for the task, the custom contact attributes.\]](http://docs.aws.amazon.com/connect/latest/adminguide/images/contact-lens-rules-attributes-example2.png)
The voice contact record appears as the **Previous contact ID**.
The flow that you specify in the rule should be designed to use the contact attributes and route the task to the appropriate owner. For example, you may want to route tasks where **CustomerType = VIP** to a specific agent.
For more information, see [Use contact attributes](connect-contact-attributes.md).
# Rules are applied to new contacts when Contact Lens analyzes conversations
After you add rules, they are applied to new contacts that occur after the rule was added. Rules are applied when Amazon Connect conversational analytics analyzes conversations.
You cannot apply rules to past, stored conversations.
# Error notifications: When Contact Lens can't analyze a contact
It's possible that Contact Lens can't analyze a contact file, even though analysis is enabled on the flow. When this happens, Contact Lens sends error notifications using Amazon EventBridge events.
Events are emitted on a [best effort](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html) basis.
## Subscribe to EventBridge notifications
To subscribe to these notifications, create a custom EventBridge rule that matches the following:
+ "source" = "aws.connect"
+ "detail-type" = "Contact Lens Analysis State Change"
You can also add to the pattern to be notified when a specific event code occurs. For more information, see [Event Patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/filtering-examples-structure.html) in the *Amazon EventBridge User Guide*.
The format of a notification looks like the following sample:
```
{
"version": "0", // set by CloudWatch Events
"id": "55555555-1111-1111-1111-111111111111", // set by CloudWatch Events
"source": "aws.connect",
"detail-type": "Contact Lens Analysis State Change",
"account": "111122223333",
"time": "2020-04-27T18:43:48Z",
"region": "us-east-1", // set by CloudWatch Events
"resources": [
"arn:aws:connect:us-east-1:111122223333:instance/abcd1234-defg-5678-h9j0-7c822889931e",
"arn:aws:connect:us-east-1:111122223333:instance/abcd1234-defg-5678-h9j0-7c822889931e/contact/efgh4567-pqrs-5678-t9c0-111111111111"
],
"detail": {
"instance": "arn:aws:connect:us-east-1:111122223333:instance/abcd1234-defg-5678-h9j0-7c822889931e",
"contact": "arn:aws:connect:us-east-1:111122223333:instance/abcd1234-defg-5678-h9j0-7c822889931e/contact/efgh4567-pqrs-5678-t9c0-111111111111",
"channel": "VOICE",
"state": "FAILED",
"reasonCode": "RECORDING_FILE_CANNOT_BE_READ"
}
}
```
## Event codes
The following table lists the event codes that may result when Contact Lens can't analyze a contact.
| Event reason code | Description |
| --- | --- |
| INVALID\$1ANALYSIS\$1CONFIGURATION | Contact Lens received invalid values when the flow was initiated, such as an unsupported or invalid language code, or an unsupported value for redaction behavior. |
| RECORDING\$1FILE\$1CANNOT\$1BE\$1READ | Contact Lens can't get the recording file. This might be because file isn't present in the S3 bucket, or there are problems with permissions. |
| RECORDING\$1FILE\$1TOO\$1SMALL | The recording file is too small for analysis (less than 105 ms). If file doesn’t have expected format, an INVALID error occurs. Empty JSON is also an unexpected object. |
| RECORDING\$1FILE\$1TOO\$1LARGE | The recording file exceeds the duration limit for analysis. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/connect/latest/adminguide/contact-lens-error-notifications.html) |
| RECORDING\$1FILE\$1INVALID | The recording file is invalid. |
| RECORDING\$1FILE\$1CANNOT\$1BE\$1READ | An error occurred when Contact Lens tried to read the recording file. |
| RECORDING\$1FILE\$1EMPTY | The recording file is empty. |
| RECORDING\$1SAMPLE\$1RATE\$1NOT\$1SUPPORTED | The sample rate of the audio file is not supported. Contact Lens currently supports audio files with an 8kHz sample rate. That is the sample rate for Amazon Connect recordings. |
# Error notifications when an Amazon Connect rule fails to run
It's important to know when a specific rule action has failed in a production environment, and what caused the failure. Then you can proactively mitigate such failures in future.
To get real-time insights on the actions that failed to run, you integrate Amazon Connect Rules with Amazon EventBridge events. This enables you to be notified when, for example, the "Create task" action failed to run because the maximum number of **Concurrent active tasks per instance** reached the service quota. When this happens, Amazon Connect sends error notifications using Amazon EventBridge events.
Events are emitted on a [best effort](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html) basis.
## Subscribe to EventBridge notifications
To subscribe to these notifications, create a custom EventBridge rule that matches the following:
+ "source" = "aws.connect"
+ "detail-type" = "Contact Lens Rules Action Execution Failed"
You can also add to the pattern to be notified when a specific event code occurs. For more information, see [Event Patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/filtering-examples-structure.html) in the *Amazon EventBridge User Guide*.
The format of a notification looks like the following sample:
```
{
"version": "0",
"id": "8d122163-6c07-f8cb-06e7-373a1bcf8fc6",
"source": "aws.connect",
"detail-type": "Amazon Connect Rules Action Execution Failed",
"account": "123456789012",
"time": "2022-01-05T01:30:42Z",
"region": "us-east-1",
"resources": ["arn:aws:connect:us-east-1:123456789012:instance/cb54730f-5aac-4376-b2f4-7c822889931e"],
"detail": {
"ruleId": "7410c94b-21c2-4db0-a707-c6d751edbe8f",
"actionType": "CREATE_TASK",
"triggerEvent": "THIRD_PARTY",
"instanceArn": "arn:aws:connect:us-east-1:123456789012:instance/cb54730f-5aac-4376-b2f4-7c822889931e",
"reasonCode": "ResourceNotFoundException",
"error": "ContactFlowId provided does not belong to connect instance",
"additionalInfo": "{\n \"message\": \"Not Found\",\n \"code\": \"ResourceNotFoundException\",\n \"statusCode\": 404,\n \"time\": \"2022-01-03T20:23:07.073Z\",\n \"requestId\": \"048e4403-71c1-47d6-96fc-825744f518e7\",\n \"retryable\": false,\n \"retryDelay\": 28.217537834500316\n}"
}
}
```
## Supported action types
+ `CREATE_TASK`
+ `GENERATE_EVENTBRIDGE_EVENT`
+ `SEND_NOTIFICATION`
For information about `ASSIGN_CONTACT_CATEGORY`, see [Error notifications: When Contact Lens can't analyze a contact Troubleshoot](contact-lens-error-notifications.md).
## Supported trigger events
+ `REAL_TIME_CALL`
+ `REAL_TIME_CHAT`
+ `POST_CALL`
+ `POST_CHAT`
+ `THIRD_PARTY`
## Reason codes for failed actions
When an action fails, the error notification service collects the reason codes from the supported actions. For more information about the reason codes for Task and EventBridge action failures, see the following topics:
+ For reason codes for Task action failures, see [Errors](https://docs.aws.amazon.com/connect/latest/APIReference/API_StartTaskContact.html#API_StartTaskContact_Errors) in the **StartTaskContact** API topic in the *Amazon Connect API Reference Guide*.
+ For reason codes for EventBridge action failures, see [Errors](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html#API_PutEvents_Errors) in the **PutEvents** API topic in the *Amazon EventBridge API Reference Guide*.
# Specify variables for certain parameters when creating or managing rules using Amazon Connect APIs
When you create or manage rules programmatically using Amazon Connect APIs (such as [CreateRule](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateRule.html) or [UpdateRule](https://docs.aws.amazon.com/connect/latest/APIReference/API_UpdateRule.html)), you can specify variables for certain parameters. The variables are resolved at runtime when the action is triggered, based on the value of the [EventSourceName](https://docs.aws.amazon.com/connect/latest/APIReference/API_RuleTriggerEventSource.html) parameter.
For example, let's say you're setting up a task action and you want to add more context. Following is an example of how you could use variable injections to include the ID of the contact and the ID of the agent in the `Description` field of the task:
+ Customer is unhappy about the phone call. A swear word was detected during the conversation with agent `$.ContactLens.PostCall.Agent.AgentId` in the contact `$.ContactLens.PostCall.ContactId`
When the action is triggered, his string would resolve to "Customer is unhappy about the phone call. A swear word was detected during a conversation with agent 12345678-1234-1234-1234-EXAMPLEID012 in the contact 87654321-1234-1234-1234-EXAMPLEID345"
The following table lists each event source, and the JSONPath to use for fields that support variable injection.
| EventSourceName | JSONPath Reference |
| --- | --- |
| OnPostCallAnalysisAvailable | \$1.ContactLens.PostCall.ContactId \$1.ContactLens.PostCall.Agent.AgentId \$1.ContactLens.PostCall.Queue.QueueId |
| OnRealTimeCallAnalysisAvailable | \$1.ContactLens.RealTimeCall.ContactId \$1.ContactLens.RealTimeCall.Agent.AgentId \$1.ContactLens.RealTimeCall.Queue.QueueId |
| OnPostChatAnalysisAvailable | \$1.ContactLens.PostChat.ContactId \$1.ContactLens.PostChat.Agent.AgentId \$1.ContactLens.PostChat.Queue.QueueId |
| OnSalesforceCaseCreate | \$1.ThirdParty.Salesforce.CaseCreate.CaseNumber \$1.ThirdParty.Salesforce.CaseCreate.Name \$1.ThirdParty.Salesforce.CaseCreate.Email \$1.ThirdParty.Salesforce.CaseCreate.Phone \$1.ThirdParty.Salesforce.CaseCreate.Company \$1.ThirdParty.Salesforce.CaseCreate.Type \$1.ThirdParty.Salesforce.CaseCreate.Reason \$1.ThirdParty.Salesforce.CaseCreate.Origin \$1.ThirdParty.Salesforce.CaseCreate.Subject \$1.ThirdParty.Salesforce.CaseCreate.Priority \$1.ThirdParty.Salesforce.CaseCreate.CreatedDate \$1.ThirdParty.Salesforce.CaseCreate.Description |
| OnZendeskTicketCreate | \$1.ThirdParty.Zendesk.TicketCreate.Id \$1.ThirdParty.Zendesk.TicketCreate.Priority \$1.ThirdParty.Zendesk.TicketCreate.CreatedAt |
| OnZendeskTicketStatusUpdate | \$1.ThirdParty.Zendesk.TicketStatusUpdate.Id \$1.ThirdParty.Zendesk.TicketStatusUpdate.Priority \$1.ThirdParty.Zendesk.TicketStatusUpdate.CreatedAt |