Webchat Channel

We have developed a Webchat channel that allows users to embed their peers into their own systems using either a URL or a script. This provides a customizable chat experience that can be tailored through a user-friendly form interface.

1. Embed via Script

To embed the Webchat using a script, include the following code snippet in your website:

<script src="https://app.cognipeer.com/scripts/cognipeer.sdk.js"></script>
<script>
  window.cognipeer.chat({
    hookId: "HOOK_ID",
    contact: {
      name: "John",
      surname: "Doe"
    }
  });
</script>

2. Embed via URL

Alternatively, you can embed the Webchat directly using a URL:

https://app.cognipeer.com/webchat/HOOK_ID

This URL accepts three parameters: contact, params, and context as json string.

Integration Parameters

Contact

The contact parameter allows you to pass user-specific information to the Webchat. This helps in creating and tracking users on your end.

• name: The first name of the user.
• surname: The last name of the user.
• email: The user’s email address.
• integrationId: A unique identifier for the user within your system.

Example Usage:

<script>
  window.cognipeer.chat({
    hookId: "HOOK_ID",
    contact: {
      name: "Jane",
      surname: "Smith",
      email: "jane.smith@example.com",
      integrationId: "user_12345"
    }
  });
</script>

Params

The params parameter is used to pass additional data to the Webchat without sending it to the Language Learning Model (LLM). This is useful for tools and functionalities that require specific data.

Example Usage:

<script>
  window.cognipeer.chat({
    hookId: "HOOK_ID",
    params: {
      sessionId: "abcde12345",
      featureFlag: true
    }
  });
</script>

Context

The context parameter allows you to send contextual information about the current user directly into the prompt. This enhances the relevance and personalization of the chat interactions.

Example Usage:

<script>
  window.cognipeer.chat({
    hookId: "HOOK_ID",
    context: {
      currentUser: {
        id: "user_12345",
        role: "admin",
        preferences: {
          theme: "dark"
        }
      }
    }
  });
</script>

Complete Integration Example

<script src="https://app.cognipeer.com/scripts/cognipeer.sdk.js"></script>
<script>
  window.cognipeer.chat({
    hookId: "HOOK_ID",
    contact: {
      name: "Alice",
      surname: "Johnson",
      email: "alice.johnson@example.com",
      integrationId: "user_67890"
    },
    params: {
      sessionId: "xyz789",
      featureFlag: false
    },
    context: {
      currentUser: {
        id: "user_67890",
        role: "user",
        preferences: {
          language: "en",
          notifications: true
        }
      }
    }
  });
</script>

How to Customize Theme Settings

Go to Webchat channel details under Peer Details/Channels tab.

Logo Settings

• Logo Source (src): Enter the URL of your logo image.
• Logo Width (width): Specify the width of the logo in pixels.
• Logo Height (height): Specify the height of the logo in pixels.
• Logo Alt Text (alt): Provide alternative text for the logo.

Color Settings

• Primary Color (primary): Choose the primary color for your Webchat interface.
• Black Color (black): Select the shade of black for text and other elements.
• White Color (white): Select the shade of white for backgrounds and highlights.
• Header Background (headerBG): Choose the background color for the header.
• Main Background (mainBG): Choose the background color for the main chat area.
• Footer Background (footerBG): Choose the background color for the footer.

Theme Settings

• Font Family (fontFamily): Select the font family for the Webchat text.
• Border Radius (radius): Set the border radius for rounded corners in the Webchat elements.

---

Feedback Feature

The Webchat channel includes an optional feedback feature that allows users to rate AI responses with thumbs up/down buttons. This helps you gather insights on response quality and identify areas for improvement.

Enabling Feedback

To enable the feedback feature:

1. Navigate to Peer → Channels → Webchat
2. Open the Settings tab
3. Enable the Feedback toggle
4. Save your settings

How It Works

When enabled:

• Thumbs up/down buttons appear below each AI response
• Users can rate responses as helpful (👍) or not helpful (👎)
• Feedback is stored with the message for analytics
• Only AI messages show feedback buttons (not user messages)
• Each message can only be rated once per session

User Experience

The feedback buttons:

• Appear only for AI responses after they're fully rendered
• Are subtle and non-intrusive (appear on hover on desktop)
• Include accessibility labels for screen readers
• Use icon-only buttons to minimize visual clutter
• Disappear after feedback is given (or show selected state)

Accessing Feedback Data

Feedback data is stored with each message and can be accessed via:

1. Message API - Individual message feedback is included in message objects
2. Conversation Analytics - Aggregate feedback metrics by conversation
3. Peer Analytics - Overall feedback trends for the peer

Example Message Object with Feedback:

{
  "_id": "msg_123",
  "conversationId": "conv_456",
  "content": "Here's how to reset your password...",
  "type": "ai",
  "feedback": 1,  // 1 = positive, 0 = negative, null = no feedback
  "createdAt": "2025-10-21T10:30:00Z"
}

Feedback API

You can programmatically submit feedback via the Webchat hook API:

POST /api/v1/integration/webchat/:hookId/feedback

{
  "messageId": "msg_123",
  "feedback": 1  // 1 for thumbs up, 0 for thumbs down
}

Response:

{
  "success": true,
  "data": {
    "_id": "msg_123",
    "feedback": 1,
    "updatedAt": "2025-10-21T10:35:00Z"
  }
}

Analytics and Insights

Use feedback data to:

Identify Problem Areas:

• Questions that consistently receive negative feedback
• Topics where the AI struggles
• Response patterns that need improvement

Measure Quality:

• Overall satisfaction rate (positive feedback %)
• Feedback trends over time
• Comparison between different peers or topics

Improve Performance:

• Review negatively-rated responses
• Enhance knowledge base with missing information
• Refine prompts based on feedback patterns
• A/B test different peer configurations

Best Practices

1. Enable Selectively: Consider enabling feedback for customer-facing peers but maybe not for internal tools

2. Act on Feedback: Regularly review negative feedback and improve peer configuration accordingly

3. Combine with Evaluations: Use feedback data alongside formal evaluation runs for comprehensive quality assessment

4. Monitor Trends: Watch for patterns in feedback rather than individual ratings

5. Privacy Considerations: Feedback is anonymous by default; consider your privacy policy when collecting feedback

Configuration Options

Available settings in Webchat channel configuration:

{
  "feedback": true,           // Enable/disable feedback feature
  "anonymousUser": false,     // Allow guest users without contact info
  "allowAttachments": true,   // Allow file uploads
  "messageInputPlaceholder": "Type your message..."
}

Localization

Feedback buttons support multiple languages via localization strings:

• webchat.feedback.positive: "Thumbs up"
• webchat.feedback.negative: "Thumbs down"

These are automatically translated based on the user's language preference.

Troubleshooting

Feedback buttons not appearing:

• Verify feedback is enabled in channel settings
• Check that messages are of type "ai" (not "user")
• Ensure latest SDK version is loaded
• Confirm messages have finished rendering

Feedback not being saved:

• Verify messageId is correct
• Check webhook/API connectivity
• Review server logs for errors
• Ensure proper authentication for the webhook

---