Building Custom Web Messaging Guest Attributes for Dynamic Routing

How-To-Articles
1

Building Custom Web Messaging Guest Attributes for Dynamic Routing

What This Guide Covers

  • Utilizing the Genesys Cloud Messenger JavaScript SDK to capture custom metadata from a website and pass it to Architect.
  • Implementing “Pre-Interaction” routing logic based on guest attributes (e.g., Cart Value, Account Tier, Current URL).
  • Surface guest attributes to agents within the Interaction Script for immediate context.

Prerequisites, Roles & Licensing

  • Licensing Tier: Genesys Cloud CX 1, 2, or 3.
  • Permissions: Messaging > Messenger > View, Architect > Flow > Edit, Conversation > Message > View.
  • Requirements: A deployed Genesys Cloud Web Messaging deployment and access to your website’s frontend code.

The Implementation Deep-Dive

1. Capturing and Setting Guest Attributes via SDK

The Genesys Cloud Messenger SDK allows you to set “Custom Attributes” before or during a conversation. These are key-value pairs that travel with the interaction.

  • The Code Pattern:
    Genesys("command", "Database.set", {
  messaging: {
    customAttributes: {
      customer_tier: "Platinum",
      current_page: window.location.href,
      cart_value: "1250.00",
      last_search: "return policy"
    }
  }
});
  • Execution Timing: This command must be executed before the customer starts the chat, or updated dynamically as the user navigates.
  • The Trap: “The Attribute Delay.” If you set attributes after the customer clicks the chat bubble but before the Genesys("command", "Messenger.open") call is processed, there is a race condition. If the interaction initializes before the database update is committed, Architect will receive null values. Always ensure Database.set is called on page load or as part of a pre-click validation hook.

2. Accessing Guest Attributes in Architect

Once attributes are sent from the browser, they are stored in the interaction’s Participant Data.

  • Architect Configuration: Use the Get Participant Data action at the start of your Inbound Message Flow.
  • Variable Mapping: The “Attribute Name” in Architect must exactly match the key used in the JavaScript snippet (e.g., customer_tier).
  • Dynamic Routing: Use a Switch or Decision block based on the retrieved variable. For example, if cart_value > 1000, route to the “High Value Support” queue; otherwise, route to “Standard Support.”
  • The Trap: “Case Sensitivity and Empty Strings.” Architect is strictly case-sensitive for attribute names. If you send Customer_Tier from JS but look for customer_tier in Architect, the action will fail. Always use lowercase snake_case for consistency and implement a “Fallback” branch in Architect for when attributes are missing or malformed.

3. Surfacing Context to Agents via Scripts

The most powerful use of guest attributes is reducing “Discovery Time” for agents.

  • Script Configuration: In your Interaction Script, create Variables that use the “Input” property. Link these variables to the context.customer_tier and context.cart_value fields.
  • The Process: When the agent accepts the chat, the script automatically populates with the data captured from the web session. The agent doesn’t have to ask, “What were you looking at?” - it’s already on their screen.
  • The Trap: “Data Privacy and Over-sharing.” Avoid passing sensitive data like Credit Card numbers or PII (Social Security Numbers) through Guest Attributes. These attributes are often logged in plain text within the conversation details and audit trails. Use a customer_id and perform a secure Data Action lookup within Architect to retrieve PII from your backend instead of passing it via client-side JavaScript.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Attributes Missing on “Re-Opened” Conversations

  • The Failure Condition: A customer returns to the site 2 hours later; the chat resumes, but the cart_value is now null or stale.
  • The Root Cause: Genesys Cloud Web Messaging is persistent. If the “Threading Timeline” has not expired, the customer is re-connected to the existing conversation. If your JS only sets attributes on the initial Messenger.ready event, they won’t be refreshed for the resume event.
  • The Solution: Use the MessagingService.started and MessagingService.restored event listeners in the SDK to re-apply Database.set whenever the session state changes.

Edge Case 2: URL Encoding Issues in Attributes

  • The Failure Condition: The current_page attribute looks like %20 and %3F gibberish in the agent script.
  • The Root Cause: Passing a raw window.location.href includes URL-encoded characters that Architect or the Scripting engine may not automatically decode.
  • The Solution: Use decodeURIComponent(window.location.href) in your JS before setting the attribute to ensure a human-readable string is passed to the platform.

Official References