Skip to main content

​
Widget Authentication

Secure your embedded chat widget with flexible token-based authentication. ChatterMate supports both public and authenticated access modes to fit your application’s needs.

​
Authentication Modes

ChatterMate offers two authentication modes for your widget:

​
Public Access Mode

The default mode allows anonymous visitors to start conversations without authentication.How it works:
  • Token is automatically generated when the widget initializes
  • Visitors can chat immediately without signing in
  • Email collection is optional (based on chat style settings)
  • Conversation history is linked to the generated token
Best for:
  • Public support websites
  • Documentation assistants
  • General Q&A interfaces
  • Lead generation chatbots

​
How Token Authentication Works

​
Token Structure

ChatterMate uses JWT (JSON Web Token) for secure widget authentication. Each token contains:
FieldDescription
widget_idUnique identifier for the widget
org_idOrganization identifier
customer_idCustomer/user identifier
sourceOptional tracking source
expToken expiration timestamp

​
Token Flow

1

Token Generation

When a user visits your site, generate a token server-side using your secret key.
2

Widget Initialization

Pass the token to the widget during initialization.
3

Token Validation

ChatterMate validates the token on each request, verifying the signature and organization context.
4

Session Management

Valid tokens maintain conversation continuity across sessions and devices.

​
Implementation

​
Server-Side Token Generation

Generate tokens on your backend to securely identify users: 
const jwt = require('jsonwebtoken');

function generateWidgetToken(userId, email) {
  const payload = {
    widget_id: 'YOUR_WIDGET_ID',
    org_id: 'YOUR_ORG_ID',
    customer_id: userId,
    email: email,
    source: 'web_app'
  };

  return jwt.sign(payload, process.env.CONVERSATION_SECRET_KEY, {
    expiresIn: '24h'
  });
}

​
Client-Side Token Usage

Pass the token when initializing the widget: 
<script>
  window.chattermateId = 'YOUR_WIDGET_ID';
  window.chattermateToken = 'GENERATED_JWT_TOKEN';
</script>
<script src="https://app.chattermate.chat/webclient/chattermate.min.js"></script>

​
API Authentication

For direct API calls, include the token in headers: 
curl -X POST https://api.chattermate.chat/api/v1/chat \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

​
Security Features

Organization Isolation

Tokens are scoped to your organization. Cross-organization access is prevented.

Signature Verification

All tokens are cryptographically signed and verified on each request.

Widget Binding

Tokens are bound to specific widgets, preventing cross-widget token reuse.

Encrypted Storage

Tokens are stored securely with encryption at rest.
Never expose your CONVERSATION_SECRET_KEY in client-side code. Always generate tokens on your backend server.

​
Best Practices

  1. Token Expiration
    • Set appropriate expiration times (recommended: 24 hours)
    • Implement token refresh for long sessions
    • Handle expired token errors gracefully
  2. Secure Generation
    • Generate tokens server-side only
    • Use environment variables for secret keys
    • Rotate secrets periodically
  3. User Context
    • Include user identifiers for conversation continuity
    • Add email for customer identification
    • Use source tracking for analytics

​
Troubleshooting

  • Verify your CONVERSATION_SECRET_KEY matches between token generation and ChatterMate config
  • Check token hasn’t expired
  • Ensure widget_id in token matches the widget being used
  • Confirm token is set before the widget script loads
  • Check browser console for JavaScript errors
  • Verify token format is valid JWT
  • Ensure customer_id is consistent for the same user
  • Check organization ID matches
  • Verify token hasn’t been regenerated with different customer ID

​
What’s Next?

After configuring authentication:
  1. Set up your widget integration
  2. Configure chat customization options
  3. Test with authenticated and anonymous users

Widget Integration

Learn how to integrate the widget into your website