How to pass CRM customer ID through the Web Messaging SDK startChat() method

What You Will Build

• You will configure a Genesys Cloud Web Chat client to inject a specific CRM customer identifier into the chat session before it connects to an agent.
• You will use the @genesys-cloud/web-chat-sdk to intercept the startChat flow and modify the attributes payload.
• You will use JavaScript/TypeScript in a standard web browser environment (Node.js is not supported for this SDK as it requires DOM access).

Prerequisites

• Genesys Cloud Organization: An active Genesys Cloud account with Web Chat enabled.
• Web Chat Configuration: A published Web Chat configuration ID (found in Admin > Omnichannel > Messaging > Web Chat > Configurations).
• SDK Version: @genesys-cloud/web-chat-sdk version 1.0.0 or later.
• Language/Runtime: JavaScript (ES6+) or TypeScript running in a browser environment.
• Dependencies:
  • @genesys-cloud/web-chat-sdk
  • @genesys-cloud/web-chat-elements (optional, for UI components)

Authentication Setup

The Web Chat SDK does not use standard OAuth2 client credentials flows for the end-user session. Instead, it uses a Web Chat Configuration ID to establish a session with the Genesys Cloud Messaging service. The “authentication” is the validation of the configuration ID against your organization’s domain.

You must obtain your Configuration ID from the Genesys Cloud Admin portal. This ID is a string that uniquely identifies the chat widget settings, including the outbound queue and messaging rules.

Critical Note: Do not expose your Admin API credentials (Client ID/Secret) in the browser. The Web Chat SDK handles its own token exchange via the Configuration ID. You are responsible for passing the user data (CRM ID) securely from your own application logic to the SDK.

Implementation

Step 1: Initialize the Web Chat Client

First, you must import the SDK and create an instance of the client. The client is the primary interface for controlling the chat lifecycle.

import { createClient } from '@genesys-cloud/web-chat-sdk';

// Replace with your actual Configuration ID from Genesys Cloud Admin
const CONFIGURATION_ID = 'your-configuration-id-here';

// Initialize the client
const client = createClient({
  configurationId: CONFIGURATION_ID,
});

export default client;

This code sets up the connection to the Genesys Cloud messaging infrastructure. At this stage, no chat session exists. The client is ready to receive commands to start a chat.

Step 2: Prepare the CRM Customer ID Payload

Before calling startChat, you must define the data you want to pass. Genesys Cloud Web Chat supports custom attributes in the startChat method. These attributes are attached to the conversation and are visible to agents and downstream integrations (such as CRM callbacks or Pure Cloud scripts).

The standard way to pass external identifiers is through the attributes object. You should use a reserved or custom namespace to avoid conflicts with internal Genesys Cloud attributes. A common pattern is to use externalId or a custom key like crmCustomerId.

// This function simulates retrieving the customer ID from your CRM system
function getCustomerContext() {
  // In a real app, this might come from a Redux store, Context API, or local storage
  return {
    crmCustomerId: 'CRM-12345-XYZ',
    customerEmail: 'john.doe@example.com',
    customerTier: 'Gold'
  };
}

// Prepare the attributes object for the SDK
const customerData = getCustomerContext();

const chatAttributes = {
  // Use a consistent key name that your backend integrations expect
  'externalId': customerData.crmCustomerId,
  'email': customerData.customerEmail,
  'tier': customerData.customerTier
};

Why use attributes?
The startChat method accepts an optional object parameter. This object is merged into the initial message payload sent to the Genesys Cloud messaging service. These attributes become part of the conversation metadata. Agents can see these in the Agent Desktop, and you can query them via the Analytics API later.

Step 3: Execute startChat with Attributes

Now you will call the startChat method on the client instance, passing the attributes object.

async function initiateChatWithCRMId() {
  try {
    // Ensure the client is initialized
    if (!client) {
      throw new Error('Web Chat Client not initialized');
    }

    // Define the attributes to pass
    const attributes = {
      'externalId': 'CRM-12345-XYZ',
      'customField_1': 'Value_A'
    };

    // Call startChat with the attributes object
    // The second argument is the options object, which includes 'attributes'
    await client.startChat({
      attributes: attributes
    });

    console.log('Chat started successfully with CRM ID attached.');

  } catch (error) {
    console.error('Failed to start chat:', error);
    
    // Handle specific errors
    if (error.message.includes('configuration')) {
      console.error('Invalid Configuration ID. Check your Genesys Cloud Admin settings.');
    } else if (error.message.includes('network')) {
      console.error('Network error. Check internet connection.');
    }
  }
}

Key Parameter Explanation:

• attributes: An object of key-value pairs. Keys must be strings. Values can be strings, numbers, or booleans. Complex objects (arrays, nested objects) are not guaranteed to be preserved or displayed correctly in all agent views. Keep it flat.

Step 4: Verify the Data in Genesys Cloud

To confirm the data was passed correctly, you do not need to wait for an agent. You can inspect the conversation in real-time using the Genesys Cloud API or by checking the network traffic in your browser’s developer tools.

Browser Network Tab Verification:

1. Open your browser’s Developer Tools (F12).
2. Go to the Network tab.
3. Trigger the startChat function.
4. Look for a POST request to a URL ending in /conversations/webchat.
5. Inspect the Payload or Request Body. You should see your attributes object inside the JSON payload.

API Verification (Post-Chat):
After the chat is complete, you can query the conversation details using the Analytics API or the Conversations API.

// This is a separate backend script to verify the data was stored
// Requires Genesys Cloud API Credentials (Client ID, Secret, Environment)

const axios = require('axios');

async function verifyConversationAttributes(conversationId) {
  const environment = 'mypurecloud.ie'; // Change to your region
  const clientId = 'YOUR_CLIENT_ID';
  const clientSecret = 'YOUR_CLIENT_SECRET';

  // 1. Get OAuth Token
  const tokenResponse = await axios.post(`https://${environment}/oauth/token`, {
    grant_type: 'client_credentials',
    client_id: clientId,
    client_secret: clientSecret
  });

  const accessToken = tokenResponse.data.access_token;

  // 2. Get