WebChat

Overview

The WebChat provider lets you embed a chat widget directly in your website. It supports:

• Real-time messaging
• Adaptive Cards
• File uploads
• Custom theming
• Mobile responsive
• OAuth/OIDC authentication (Google, Microsoft Entra ID, GitHub, custom OIDC)
• Built-in locale picker for language selection

Architecture

User's Browser
    │
    ▼ WebSocket
┌─────────────────────────────────────────┐
│          WebChat Widget (React)         │
│     (greentic-webchat component)        │
└─────────────────────────────────────────┘
    │
    ▼ Direct Line Protocol
┌─────────────────────────────────────────┐
│        Direct Line Server               │
│   (greentic-messaging-providers)        │
└─────────────────────────────────────────┘
    │
    ▼ NATS
┌─────────────────────────────────────────┐
│          Greentic Runner                │
└─────────────────────────────────────────┘

Setup

1. Configure Provider

   answers.json

   {
     "messaging-webchat": {
       "enabled": true,
       "public_base_url": "https://your-domain.com",
       "allowed_origins": ["https://yoursite.com"],
       "session_timeout": 1800
     }
   }

2. Run Setup

   gtc setup --answers answers.json ./my-bundle

3. Start Runtime

   gtc start ./my-bundle

4. Embed in Website

   Add the widget to your HTML:

   <script src="https://your-domain.com/webchat/widget.js"></script>
   <script>
     GreenticWebChat.init({
       directLine: {
         domain: 'https://your-domain.com/webchat',
         webSocket: true
       },
       tenant: 'demo',
       team: 'default',
       theme: {
         primaryColor: '#0078D4'
       }
     });
   </script>

Configuration Options

Option	Required	Description
enabled	Yes	Enable/disable provider
public_base_url	Yes	Base URL for Direct Line
allowed_origins	No	CORS allowed origins
session_timeout	No	Session timeout in seconds (default: 1800)
token_expiry	No	Token expiry in seconds (default: 3600)
oauth_enabled	No	Enable OAuth/OIDC login for WebChat (default: false)
oauth_provider	No	OAuth provider: google, microsoft, github, or oidc
oauth_client_id	No	OAuth client ID (required when oauth_enabled is true)
oauth_authority	No	OIDC authority/issuer URL (required for microsoft and oidc providers)
oauth_scopes	No	OAuth scopes to request (defaults vary by provider)

Widget Configuration

Basic Setup

<script src="https://your-domain.com/webchat/widget.js"></script>
<script>
  GreenticWebChat.init({
    directLine: {
      domain: 'https://your-domain.com/webchat'
    },
    tenant: 'demo',
    team: 'default'
  });
</script>

With Theming

<script>
  GreenticWebChat.init({
    directLine: {
      domain: 'https://your-domain.com/webchat'
    },
    tenant: 'demo',
    team: 'default',
    theme: {
      primaryColor: '#0078D4',
      backgroundColor: '#f5f5f5',
      bubbleBackground: '#ffffff',
      bubbleFromUserBackground: '#0078D4',
      bubbleTextColor: '#333333',
      bubbleFromUserTextColor: '#ffffff',
      sendBoxBackground: '#ffffff',
      sendBoxTextColor: '#333333'
    }
  });
</script>

With User Info

<script>
  GreenticWebChat.init({
    directLine: {
      domain: 'https://your-domain.com/webchat'
    },
    tenant: 'demo',
    team: 'default',
    user: {
      id: 'user-123',
      name: 'John Doe',
      email: 'john@example.com'
    }
  });
</script>

Minimized Start

<script>
  GreenticWebChat.init({
    directLine: {
      domain: 'https://your-domain.com/webchat'
    },
    tenant: 'demo',
    team: 'default',
    startMinimized: true,
    showToggleButton: true
  });
</script>

Features

Text Messages

- id: reply
  type: reply
  config:
    message: "Hello! How can I help you today?"

Adaptive Cards

WebChat has full Adaptive Card support:

- id: welcome_card
  type: adaptive-card
  config:
    card:
      type: AdaptiveCard
      version: "1.4"
      body:
        - type: TextBlock
          text: "Welcome!"
          size: Large
          weight: Bolder
        - type: TextBlock
          text: "I'm your virtual assistant. How can I help?"
        - type: ActionSet
          actions:
            - type: Action.Submit
              title: "Get Help"
              data:
                action: "help"
            - type: Action.Submit
              title: "Contact Support"
              data:
                action: "support"

Quick Replies (Suggested Actions)

- id: suggestions
  type: reply
  config:
    message: "What would you like to do?"
    suggested_actions:
      - "Check Order Status"
      - "Talk to Support"
      - "View FAQs"

File Uploads

Enable file uploads:

GreenticWebChat.init({
  // ... other config
  uploadEnabled: true,
  uploadAccept: '.pdf,.doc,.docx,.png,.jpg',
  uploadMaxSize: 10485760  // 10MB
});

Handle uploads in flow:

- id: handle_upload
  type: branch
  config:
    conditions:
      - expression: "attachments.length > 0"
        next: process_file
      default: normal_message

- id: process_file
  type: reply
  config:
    message: "Thanks! I've received your file: {{attachments[0].name}}"

Typing Indicator

- id: thinking
  type: reply
  config:
    typing: true
    typing_duration: 2000  # milliseconds
  next: actual_reply

- id: actual_reply
  type: reply
  config:
    message: "Here's what I found..."

API Integration

JavaScript API

// Get chat instance
const chat = GreenticWebChat.getInstance();

// Send message programmatically
chat.sendMessage('Hello from JS!');

// Minimize/maximize
chat.minimize();
chat.maximize();

// Clear conversation
chat.clear();

// End conversation
chat.end();

// Listen for events
chat.on('message', (event) => {
  console.log('New message:', event.text);
});

chat.on('conversationStarted', () => {
  console.log('Conversation started');
});

REST API

Direct Line REST API endpoints:

# Start conversation
POST /webchat/v3/directline/conversations
Authorization: Bearer <token>

# Send message
POST /webchat/v3/directline/conversations/{conversationId}/activities
Content-Type: application/json

{
  "type": "message",
  "text": "Hello!"
}

# Get messages
GET /webchat/v3/directline/conversations/{conversationId}/activities

Customization

Custom CSS

<style>
  .greentic-webchat {
    --primary-color: #0078D4;
    --background-color: #ffffff;
    --text-color: #333333;
    --border-radius: 8px;
    --font-family: 'Segoe UI', sans-serif;
  }

  .greentic-webchat .message-bubble {
    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
  }

  .greentic-webchat .send-button {
    background-color: var(--primary-color);
  }
</style>

Custom Avatar

GreenticWebChat.init({
  // ... other config
  botAvatar: 'https://example.com/bot-avatar.png',
  userAvatar: 'https://example.com/user-avatar.png',
  showAvatars: true
});

Custom Header

The header area can display a title, subtitle, and close button. When the locale picker is enabled, it appears in the header. When OAuth is enabled, a logout button is also rendered in the header next to the locale picker.

GreenticWebChat.init({
  // ... other config
  header: {
    title: 'Support Chat',
    subtitle: 'We usually reply within minutes',
    showCloseButton: true
  }
});

Multi-Language Support

The WebChat GUI includes a built-in locale picker that lets users switch languages at runtime. The locale picker appears in the chat header, allowing users to select their preferred language without reloading the page.

GreenticWebChat.init({
  // ... other config
  locale: 'es-ES',
  showLocalePicker: true,
  availableLocales: ['en-US', 'es-ES', 'fr-FR', 'de-DE', 'ja-JP'],
  strings: {
    'placeholder': 'Escribe un mensaje...',
    'send': 'Enviar',
    'connecting': 'Conectando...',
    'reconnecting': 'Reconectando...'
  }
});

When showLocalePicker is enabled, a language selector appears in the header next to the close button (and logout button, if OAuth is enabled). Changing the locale updates all UI strings and notifies the flow so responses can adapt to the selected language.

OAuth/OIDC Authentication

WebChat supports optional OAuth/OIDC authentication to require users to log in before accessing the chat. When enabled, a login overlay is displayed before the chat interface becomes available. The implementation uses a client-side PKCE (Proof Key for Code Exchange) flow for security.

Tip

OAuth authentication is entirely optional. If not configured, WebChat operates without any login requirement, as in previous versions.

Supported Providers

Provider	oauth_provider value	Notes
Google	google	Google OAuth 2.0 with Google Identity Services
Microsoft (Entra ID)	microsoft	Azure AD / Entra ID, requires oauth_authority
GitHub	github	GitHub OAuth Apps
Custom OIDC	oidc	Any OpenID Connect-compliant provider, requires oauth_authority

How It Works

1. User opens the WebChat widget
2. A login overlay is shown with a sign-in button for the configured provider
3. The user authenticates through the provider’s login flow (client-side PKCE)
4. On successful authentication, the overlay is dismissed and the chat becomes accessible
5. The authenticated user’s identity is passed to the flow as user context
6. A logout button appears in the header (next to the locale picker) for signing out

Provider Setup

Each provider is configured through the answers.json file or interactively via the QA-based setup wizard. The setup wizard uses conditional logic to guide you through only the fields required for your chosen provider.

Google

1. Create OAuth credentials in the Google Cloud Console

   • Create a new OAuth 2.0 Client ID
   • Set application type to “Web application”
   • Add your WebChat domain to “Authorized JavaScript origins”
   • Add https://your-domain.com/webchat/auth/callback to “Authorized redirect URIs”

2. Configure the provider

   answers.json

   {
     "messaging-webchat": {
       "enabled": true,
       "public_base_url": "https://your-domain.com",
       "oauth_enabled": true,
       "oauth_provider": "google",
       "oauth_client_id": "123456789.apps.googleusercontent.com",
       "oauth_scopes": "openid profile email"
     }
   }

3. Run setup and start

   gtc setup --answers answers.json ./my-bundle
   gtc start ./my-bundle

Microsoft (Entra ID)

1. Register an application in the Azure Portal

   • Register a new application under “App registrations”
   • Set the redirect URI to https://your-domain.com/webchat/auth/callback (type: SPA)
   • Under “Authentication”, enable “Access tokens” and “ID tokens” for implicit grant
   • Note your Application (client) ID and Directory (tenant) ID

2. Configure the provider

   answers.json

   {
     "messaging-webchat": {
       "enabled": true,
       "public_base_url": "https://your-domain.com",
       "oauth_enabled": true,
       "oauth_provider": "microsoft",
       "oauth_client_id": "your-application-client-id",
       "oauth_authority": "https://login.microsoftonline.com/your-tenant-id/v2.0",
       "oauth_scopes": "openid profile email User.Read"
     }
   }

3. Run setup and start

   gtc setup --answers answers.json ./my-bundle
   gtc start ./my-bundle

GitHub

1. Create an OAuth App in GitHub Developer Settings

   • Go to “OAuth Apps” and create a new application
   • Set the “Authorization callback URL” to https://your-domain.com/webchat/auth/callback
   • Note the Client ID

2. Configure the provider

   answers.json

   {
     "messaging-webchat": {
       "enabled": true,
       "public_base_url": "https://your-domain.com",
       "oauth_enabled": true,
       "oauth_provider": "github",
       "oauth_client_id": "your-github-client-id",
       "oauth_scopes": "read:user user:email"
     }
   }

3. Run setup and start

   gtc setup --answers answers.json ./my-bundle
   gtc start ./my-bundle

Custom OIDC Provider

1. Register a client with your OIDC provider

   • Set the redirect URI to https://your-domain.com/webchat/auth/callback
   • Ensure your provider supports PKCE
   • Note the client ID and the issuer/authority URL

2. Configure the provider

   answers.json

   {
     "messaging-webchat": {
       "enabled": true,
       "public_base_url": "https://your-domain.com",
       "oauth_enabled": true,
       "oauth_provider": "oidc",
       "oauth_client_id": "your-client-id",
       "oauth_authority": "https://your-oidc-provider.com",
       "oauth_scopes": "openid profile email"
     }
   }

   The oauth_authority must point to the issuer URL where /.well-known/openid-configuration is available.

3. Run setup and start

   gtc setup --answers answers.json ./my-bundle
   gtc start ./my-bundle

Widget Configuration with OAuth

When OAuth is enabled on the server side, the widget automatically shows the login overlay. No additional client-side configuration is needed. The authenticated user’s identity is available in flows via the user context:

GreenticWebChat.init({
  directLine: {
    domain: 'https://your-domain.com/webchat'
  },
  tenant: 'demo',
  team: 'default'
  // OAuth login overlay is shown automatically when oauth_enabled is true
});

After authentication, the header displays a logout button next to the locale picker. Clicking it clears the session and returns the user to the login overlay.

Interactive Setup via QA Wizard

Instead of manually writing answers.json, you can use the interactive setup wizard which guides you through provider-specific configuration with conditional logic:

gtc setup ./my-bundle

The wizard detects when oauth_enabled is set to true and presents follow-up questions only for the selected oauth_provider, so you only see fields relevant to your chosen identity provider.

Security

Caution

Always configure allowed_origins in production to prevent unauthorized embedding.

Token Security

• Tokens are short-lived (1 hour default)
• Tokens are scoped to conversation
• Refresh tokens are not exposed to client

OAuth/OIDC Security

When OAuth is enabled:

• Authentication uses the PKCE flow, which does not require a client secret on the frontend
• Tokens are validated server-side before granting chat access
• The login overlay blocks all chat interaction until authentication succeeds
• Session logout clears tokens from the client and invalidates the server-side session

CORS Configuration

{
  "messaging-webchat": {
    "allowed_origins": [
      "https://www.example.com",
      "https://app.example.com"
    ]
  }
}

Troubleshooting

Widget Not Loading

1. Check console for JavaScript errors
2. Verify script URL is correct
3. Check CORS configuration

Connection Failed

1. Verify Direct Line endpoint is accessible
2. Check WebSocket support
3. Review firewall settings

Messages Not Sending

1. Check conversation is active
2. Verify token hasn’t expired
3. Review browser console for errors

Next Steps

• Adaptive Cards - Create rich cards
• Theming Guide - Advanced customization
• Flows Guide - Build conversation flows