How to Hide the Markdown Toolbar in Amazon Connect Chat Widget While Maintaining Text Formatting Support

Problem Statement

Amazon Connect administrators implementing chat widgets may encounter a scenario where text containing periods (such as "ID.me" or "company.name") is automatically converted into clickable hyperlinks. This behavior occurs when the chat widget interprets text patterns as URLs, even when they are not intended to be links.

The standard solution involves adding 'text/markdown' to the supportedMessagingContentTypes array, which improves the widget's ability to distinguish between actual URLs and text that happens to match URL patterns. However, this configuration introduces a markdown formatting toolbar in the chat interface, displaying text styling options including Bold, Italic, and list formatting.

Organizations may need to:

• Prevent text with periods from being incorrectly converted to hyperlinks
• Maintain markdown support for proper URL handling
• Hide the formatting toolbar from the chat interface
• Apply consistent behavior for both agents and customers

Understanding how to configure both requirements simultaneously enables administrators to provide a clean chat interface while maintaining proper text parsing functionality.

Findings

Investigation of the Amazon Connect chat widget configuration options revealed the following:

Markdown Content Type Behavior: Including 'text/markdown' in the supportedMessagingContentTypes array enables enhanced text parsing that distinguishes between actual URLs and text containing periods. When only 'text/plain' is configured, the widget applies simpler pattern matching that may incorrectly identify non-URL text as hyperlinks.

Toolbar Display Mechanism: The markdown formatting toolbar appears automatically when 'text/markdown' is included in the supported content types. This toolbar provides text styling features such as Bold, Italic, and both bulleted and numbered list options, designed to give users access to formatting capabilities.

Configuration Option Available: Amazon Connect provides the alwaysHideToolbar configuration option within the customizationObject snippet field under the composer section. This option is documented in the AWS official documentation for supported snippet fields.

Composer Customization Capabilities: The composer section of the customizationObject supports multiple configuration options including alwaysHideToolbar, disableEmojiPicker, and disableCustomerAttachments, providing comprehensive control over the chat input interface.

No Functional Trade-offs: Both requirements can be achieved simultaneously—preventing false hyperlinks while hiding the toolbar—without compromising text parsing capabilities or URL functionality.

Solution

Prerequisites: Setting Up Amazon Connect Hosted Widget

Before implementing the HTML configuration, you need to create and configure a communication widget in Amazon Connect. This section provides the steps to set up the pre-built Amazon Connect hosted widget snippet.

Step 1: Create a Communication Widget

1. Log in to your Amazon Connect instance from the AWS console
2. Navigate to Channels > Communication Widgets
3. Click Add Widget
4. Provide a name (e.g., "ChatWidget") and description
5. For Communication Options, select Chat
6. Select the contact flow that will be triggered when the chat starts
7. Click Save and Continue

Step 2: Configure Domain & Security Settings

1. Under Domain & Security Settings, add your website domain
2. For Add Security for New Communication Widget Requests, select your security preference
3. Click Save and Continue
4. Copy the provided widget script snippet

For detailed step-by-step instructions with screenshots, refer to:

• Amazon Connect Chat UI Examples - Pre-built Hosted Widget
• AWS Workshop - Adding Chat to Your Website
• AWS Workshop - Basic Chat Implementation

Complete Implementation

Once you have created your communication widget and obtained the widget script, you can proceed with the configuration to hide the markdown toolbar while maintaining text formatting support.

To hide the markdown toolbar while maintaining text formatting support and preventing false URL detection, configure two key elements in your Amazon Connect chat widget script:

1. Include 'text/markdown' in the supportedMessagingContentTypes
2. Add the customizationObject with alwaysHideToolbar: true in the composer section

Complete HTML Implementation

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Chat Widget Example</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="text/javascript">
    (function(w, d, x, id){
      s=d.createElement('script');
      s.src='https://your-instance.my.connect.aws/connectwidget/static/amazon-connect-chat-interface-client.js';
      s.async=1;
      s.id=id;
      d.getElementsByTagName('head').appendChild(s);
      w[x] = w[x] || function() { (w[x].ac = w[x].ac || []).push(arguments) };
    })(window, document, 'amazon_connect', 'your-widget-id');
    
    amazon_connect('styles', { 
      iconType: 'CHAT', 
      openChat: { color: '#ffffff', backgroundColor: '#123456' }, 
      closeChat: { color: '#ffffff', backgroundColor: '#123456'} 
    });
    
    amazon_connect('snippetId', 'your-snippet-id');
    
    // Include text/markdown to prevent false URL detection
    amazon_connect('supportedMessagingContentTypes', [ 
      'text/plain', 
      'text/markdown', 
      'application/vnd.amazonaws.connect.message.interactive', 
      'application/vnd.amazonaws.connect.message.interactive.response' 
    ]);
    
    // Hide the toolbar while keeping markdown support
    amazon_connect('customizationObject', {
      composer: {
        alwaysHideToolbar: true
      }
    });
    </script>
  </body>
</html>

Key Configuration Elements

1. supportedMessagingContentTypes Configuration

amazon_connect('supportedMessagingContentTypes', [ 
  'text/plain', 
  'text/markdown',  // Required to prevent false URL detection
  'application/vnd.amazonaws.connect.message.interactive', 
  'application/vnd.amazonaws.connect.message.interactive.response' 
]);

The 'text/markdown' content type enables the chat widget to properly parse text and distinguish between actual URLs (like "www.example.com") and text that happens to contain periods (like "ID.me" or "company.name").

2. customizationObject Configuration

amazon_connect('customizationObject', {
  composer: {
    alwaysHideToolbar: true
  }
});

The alwaysHideToolbar flag hides the markdown formatting toolbar from the chat interface while maintaining all markdown processing capabilities in the background.

Configuration Order

The order of snippet field configurations matters. Always configure in this sequence:

1. Widget initialization function
2. styles configuration
3. snippetId configuration
4. supportedMessagingContentTypes configuration
5. customizationObject configuration

Deployment Steps for React Applications

If you're using a React application with Create React App:

Step 1: Update the HTML File

Modify the public/index.html file with the configuration shown above.

Step 2: Build the Application

npm run build

Step 3: Deploy to S3

aws s3 sync build/ s3://your-bucket-name --delete

Replace your-bucket-name with your actual S3 bucket name.

Step 4: Invalidate CloudFront Cache (if applicable)

If you're using CloudFront for distribution:

aws cloudfront create-invalidation --distribution-id YOUR_DISTRIBUTION_ID --paths "/*"

Verification Steps

After deployment, verify the configuration:

1. Navigate to your chat widget URL
2. Click the chat button to open the widget
3. Type text with periods (e.g., "ID.me" or "test.example")
4. Verify that the text does NOT become a clickable hyperlink
5. Verify that the markdown formatting toolbar is NOT visible
6. Type an actual URL (e.g., "www.example.com")
7. Verify that actual URLs still become clickable hyperlinks

What This Solution Achieves

✅ Prevents False Hyperlinks: Text like "ID.me" or "company.name" will not be converted to clickable links

✅ Hides the Toolbar: The markdown formatting toolbar will not appear in the chat interface

✅ Maintains URL Support: Actual URLs like "www.example.com" will still be properly converted to clickable hyperlinks

✅ Works for All Users: The configuration applies to both customer-facing chat widgets and agent interfaces

✅ No Performance Impact: The solution uses native configuration options with no additional processing overhead

Troubleshooting

Issue 1: Toolbar Still Appears After Configuration

Symptom: The markdown formatting toolbar is still visible in the chat widget despite adding alwaysHideToolbar: true.

Possible Causes:

• Configuration not properly deployed
• Browser cache showing old version
• Incorrect placement of customizationObject in script
• CloudFront cache not invalidated

Solution:

1. Verify Script Placement: Ensure the customizationObject is placed AFTER the supportedMessagingContentTypes configuration:

// Correct order
amazon_connect('supportedMessagingContentTypes', [...]);
amazon_connect('customizationObject', {
  composer: {
    alwaysHideToolbar: true
  }
});

2. Clear Browser Cache: Hard refresh the page (Ctrl+F5 on Windows, Cmd+Shift+R on Mac) or open in incognito mode.

3. Verify Deployment: Check that the updated HTML file was properly uploaded to your hosting environment.

4. Invalidate CloudFront: If using CloudFront, create an invalidation:

aws cloudfront create-invalidation --distribution-id YOUR_DISTRIBUTION_ID --paths "/index.html"

5. Check Browser Console: Open browser developer tools (F12) and check for JavaScript errors that might prevent the configuration from loading.

---

Issue 2: Text with Periods Still Becoming Hyperlinks

Symptom: Text like "ID.me" or "company.name" is still being converted to clickable hyperlinks.

Possible Causes:

• 'text/markdown' not included in supportedMessagingContentTypes
• Typo in the content type string
• Configuration not loaded properly

Solution:

1. Verify Content Types: Check that 'text/markdown' is correctly spelled and included:

amazon_connect('supportedMessagingContentTypes', [ 
  'text/plain', 
  'text/markdown',  // Must be exactly this string
  'application/vnd.amazonaws.connect.message.interactive', 
  'application/vnd.amazonaws.connect.message.interactive.response' 
]);

2. Check for Typos: Common mistakes include:

   • 'text/mark-down' (incorrect hyphen)
   • 'text/Markdown' (incorrect capitalization)
   • 'markdown' (missing 'text/' prefix)

3. Verify Script Loading: Check browser console for errors indicating the chat widget script failed to load.

4. Test with Different Text Patterns: Try various patterns to confirm behavior:

   • "ID.me" (should NOT be a link)
   • "test.example" (should NOT be a link)
   • "www.example.com" (SHOULD be a link)
   • "https://example.com" (SHOULD be a link)

---

Issue 3: Actual URLs Not Becoming Clickable

Symptom: Legitimate URLs like "www.example.com" are not being converted to clickable hyperlinks.

Possible Causes:

• 'text/markdown' removed from supportedMessagingContentTypes
• Only 'text/plain' is configured
• URL format not recognized by markdown parser

Solution:

1. Ensure Markdown Support: Verify 'text/markdown' is included in the configuration.

2. Use Proper URL Format: Ensure URLs include proper prefixes:

   • ✅ "www.example.com"
   • ✅ "https://example.com"
   • ✅ "http://example.com"
   • ❌ "example.com" (may not be recognized without www or protocol)

3. Test URL Patterns: Different URL formats may behave differently. Test common patterns in your chat widget to verify expected behavior.

---

Issue 4: Configuration Not Taking Effect

Symptom: Changes to the chat widget configuration don't appear to have any effect.

Possible Causes:

• Aggressive browser caching
• CloudFront caching old version
• Wrong file being edited
• Build process not including changes

Solution:

1. Verify File Location: Ensure you're editing the correct HTML file:

   • For React apps: public/index.html (NOT build/index.html)
   • The build folder is generated and should not be edited directly

2. Rebuild Application: After making changes, always rebuild:

npm run build

3. Verify Build Output: Check that changes appear in the built HTML file.

4. Force Upload: Use cache-control headers when uploading:

aws s3 sync build/ s3://your-bucket-name --delete --cache-control "max-age=0"

5. Create CloudFront Invalidation: Invalidate all paths:

aws cloudfront create-invalidation --distribution-id YOUR_DISTRIBUTION_ID --paths "/*"

6. Test in Incognito Mode: Open the chat widget in a private/incognito browser window to bypass all caching.

---

Issue 5: JavaScript Errors in Browser Console

Symptom: Browser console shows errors related to amazon_connect or chat widget initialization.

Possible Causes:

• Syntax error in configuration
• Missing comma or bracket
• Invalid JSON structure in customizationObject
• Chat widget script failed to load

Solution:

1. Validate JavaScript Syntax: Check for common syntax errors:

// ❌ Incorrect - missing semicolon
amazon_connect('supportedMessagingContentTypes', [ 'text/plain', 'text/markdown' ])
amazon_connect('customizationObject', { ... });

// ✅ Correct - includes semicolon
amazon_connect('supportedMessagingContentTypes', [ 'text/plain', 'text/markdown' ]);
amazon_connect('customizationObject', { ... });

2. Verify Object Structure: Ensure proper nesting:

// ✅ Correct structure
amazon_connect('customizationObject', {
  composer: {
    alwaysHideToolbar: true
  }
});

// ❌ Incorrect - missing composer wrapper
amazon_connect('customizationObject', {
  alwaysHideToolbar: true
});

3. Check Script Loading: Verify the chat widget script URL is correct and accessible.

4. Use Browser Console: Open developer tools (F12) and check for specific error messages that indicate the problem.

5. Test with Minimal Configuration: Start with a minimal configuration and add options incrementally to identify which specific configuration causes issues.

---

Issue 6: Different Behavior Between Environments

Symptom: Configuration works in development but not in production, or vice versa.

Possible Causes:

• Different Amazon Connect instances
• Different widget IDs or snippet IDs
• Environment-specific caching policies
• Different CloudFront configurations

Solution:

1. Verify Instance URLs: Ensure the correct Amazon Connect instance URL is used for each environment.

2. Check Widget and Snippet IDs: Verify you're using the correct IDs for each environment.

3. Compare Configurations: Use a diff tool to compare the HTML files between environments.

4. Check CloudFront Settings: Verify caching policies are consistent:

   • Cache-Control headers
   • Default TTL settings
   • Invalidation patterns

5. Test Directly from Origin: Bypass CloudFront by testing directly from the origin (S3 or web server) to isolate caching issues.

---

Debugging Best Practices

Enable Console Logging:

Add console logging to track configuration loading:

console.log('Loading Amazon Connect chat widget...');
amazon_connect('supportedMessagingContentTypes', [ 'text/plain', 'text/markdown' ]);
console.log('Content types configured');
amazon_connect('customizationObject', {
  composer: {
    alwaysHideToolbar: true
  }
});
console.log('Customization object configured');

Monitor Network Requests:

Use browser developer tools Network tab to verify:

• Chat widget script loads successfully (200 status)
• No CORS errors
• Correct instance URL is being called

Test Incrementally:

1. Start with default configuration (no customizations)
2. Add 'text/markdown' only
3. Add alwaysHideToolbar only
4. Combine both configurations
5. Add additional customizations

This approach helps identify which specific configuration causes issues.

Summary

Amazon Connect chat widgets can be configured to prevent false URL detection while hiding the markdown formatting toolbar by combining two key configurations: including 'text/markdown' in the supportedMessagingContentTypes array and setting alwaysHideToolbar: true within the customizationObject composer section. The 'text/markdown' content type enables proper text parsing to distinguish between actual URLs and text containing periods, while the alwaysHideToolbar flag hides the formatting toolbar from the user interface. This solution works for both customer-facing widgets and agent interfaces, requires no performance trade-offs, and can be deployed through standard web hosting workflows including S3 and CloudFront. Common issues include caching problems, syntax errors, and incorrect configuration placement, all of which can be resolved through proper verification and deployment procedures.

References

• Amazon Connect - Supported Widget Snippet Fields
• Amazon Connect - Additional Customizations for Chat Widget
• Amazon Connect - Add Chat to Your Website
• Amazon Connect - Communications Widgets
• Amazon Connect Chat UI Examples - GitHub
• Amazon Connect Chat UI Examples - Pre-built Hosted Widget
• AWS Workshop - Adding Chat to Your Website
• AWS Workshop - Basic Chat Implementation

---