WebChat

Resumen

El provider WebChat te permite insertar un widget de chat directamente en tu sitio web. Soporta:

Mensajería en tiempo real
Adaptive Cards
Subida de archivos
Temas personalizados
Diseño responsive para móviles
Autenticación OAuth/OIDC (Google, Microsoft Entra ID, GitHub, OIDC personalizado)
Selector de locale integrado para selección de idioma

Arquitectura

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

Configuración

Configura el Provider

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

Ejecuta la configuración

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

Inicia el runtime
Ventana de terminal
```
gtc start ./my-bundle
```

Insértalo en el sitio web

Agrega el widget a tu 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>

Opciones de configuración

Opción	Requerido	Descripción
`enabled`	Sí	Habilita/deshabilita el provider
`public_base_url`	Sí	URL base para Direct Line
`allowed_origins`	No	Orígenes permitidos por CORS
`session_timeout`	No	Tiempo de espera de la sesión en segundos (por defecto: 1800)
`token_expiry`	No	Expiración del token en segundos (por defecto: 3600)
`oauth_enabled`	No	Habilita el login OAuth/OIDC para WebChat (por defecto: false)
`oauth_provider`	No	Provider OAuth: `google`, `microsoft`, `github`, o `oidc`
`oauth_client_id`	No	ID de cliente OAuth (requerido cuando `oauth_enabled` es `true`)
`oauth_authority`	No	URL de authority/issuer OIDC (requerida para los providers `microsoft` y `oidc`)
`oauth_scopes`	No	Scopes OAuth a solicitar (los valores por defecto varían según el provider)

Configuración básica

<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>

Con tematización

<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>

Con información del usuario

<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>

Inicio minimizado

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

Funcionalidades

Mensajes de texto

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

Adaptive Cards

WebChat tiene soporte completo para Adaptive Cards:

- 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"

Respuestas rápidas (acciones sugeridas)

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

Subida de archivos

Habilita la subida de archivos:

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

Maneja las subidas en un 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}}"

Indicador de escritura

- 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..."

Integración con APIs

API de JavaScript

// 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');
});

API REST

Endpoints de la API REST de Direct Line:

# 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

Personalización

CSS personalizado

<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>

Avatar personalizado

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

Header personalizado

El área del header puede mostrar un título, subtítulo y un botón de cierre. Cuando el selector de locale está habilitado, aparece en el header. Cuando OAuth está habilitado, también se renderiza un botón de logout en el header junto al selector de locale.

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

Soporte multilenguaje

La GUI de WebChat incluye un selector de locale integrado que permite a los usuarios cambiar de idioma en tiempo de ejecución. El selector de locale aparece en el header del chat, permitiendo elegir el idioma preferido sin recargar la página.

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...'
  }
});

Cuando showLocalePicker está habilitado, aparece un selector de idioma en el header junto al botón de cierre (y al botón de logout, si OAuth está habilitado). Cambiar el locale actualiza todos los strings de la UI y notifica al flow para que las respuestas puedan adaptarse al idioma seleccionado.

Autenticación OAuth/OIDC

WebChat soporta autenticación OAuth/OIDC opcional para requerir que los usuarios inicien sesión antes de acceder al chat. Cuando está habilitada, se muestra una superposición de inicio de sesión antes de que la interfaz de chat quede disponible. La implementación usa un flujo PKCE (Proof Key for Code Exchange) del lado del cliente por seguridad.

Providers soportados

Provider	Valor de `oauth_provider`	Notas
Google	`google`	Google OAuth 2.0 con Google Identity Services
Microsoft (Entra ID)	`microsoft`	Azure AD / Entra ID, requiere `oauth_authority`
GitHub	`github`	GitHub OAuth Apps
OIDC personalizado	`oidc`	Cualquier provider compatible con OpenID Connect, requiere `oauth_authority`

Cómo funciona

El usuario abre el widget WebChat
Se muestra una superposición de inicio de sesión con un botón para el provider configurado
El usuario se autentica mediante el flujo de login del provider (PKCE del lado del cliente)
Tras autenticarse correctamente, la superposición se cierra y el chat queda accesible
La identidad del usuario autenticado se pasa al flow como contexto de usuario
Aparece un botón de logout en el header (junto al selector de locale) para cerrar sesión

Configuración del provider

Cada provider se configura mediante el archivo answers.json o de forma interactiva con el asistente de configuración basado en QA. El asistente usa lógica condicional para guiarte solo por los campos requeridos para el provider elegido.

Google

Crea credenciales OAuth en la Google Cloud Console
- Crea un nuevo OAuth 2.0 Client ID
- Establece el tipo de aplicación como “Web application”
- Agrega tu dominio de WebChat a “Authorized JavaScript origins”
- Agrega https://your-domain.com/webchat/auth/callback a “Authorized redirect URIs”

Configura el provider

{
  "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"
  }
}

Ejecuta la configuración e inicia

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

Microsoft (Entra ID)

Registra una aplicación en el Azure Portal
- Registra una nueva aplicación en “App registrations”
- Establece la redirect URI en https://your-domain.com/webchat/auth/callback (tipo: SPA)
- En “Authentication”, habilita “Access tokens” e “ID tokens” para implicit grant
- Toma nota de tu Application (client) ID y Directory (tenant) ID

Configura el provider

{
  "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"
  }
}

Ejecuta la configuración e inicia

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

GitHub

Crea una OAuth App en GitHub Developer Settings
- Ve a “OAuth Apps” y crea una nueva aplicación
- Establece “Authorization callback URL” en https://your-domain.com/webchat/auth/callback
- Toma nota del Client ID

Configura el provider

{
  "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"
  }
}

Ejecuta la configuración e inicia

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

Provider OIDC personalizado

Registra un cliente con tu provider OIDC
- Establece la redirect URI en https://your-domain.com/webchat/auth/callback
- Asegúrate de que tu provider soporte PKCE
- Toma nota del client ID y de la URL de issuer/authority

Configura el provider

{
  "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"
  }
}

oauth_authority debe apuntar a la URL del issuer donde /.well-known/openid-configuration esté disponible.

Ejecuta la configuración e inicia

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

Cuando OAuth está habilitado del lado del servidor, el widget muestra automáticamente la superposición de inicio de sesión. No se necesita configuración adicional del lado del cliente. La identidad del usuario autenticado está disponible en los flows mediante el contexto de usuario:

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

Después de autenticarse, el header muestra un botón de logout junto al selector de locale. Al hacer clic, se limpia la sesión y el usuario vuelve a la superposición de inicio de sesión.

Configuración interactiva con el asistente QA

En lugar de escribir answers.json manualmente, puedes usar el asistente de configuración interactivo, que te guía por la configuración específica del provider con lógica condicional:

gtc setup ./my-bundle

El asistente detecta cuando oauth_enabled se establece en true y presenta preguntas de seguimiento solo para el oauth_provider seleccionado, de modo que solo veas los campos relevantes para tu provider de identidad.

Seguridad

Seguridad de tokens

Los tokens tienen una vida corta (1 hora por defecto)
Los tokens están limitados al alcance de la conversación
Los refresh tokens no se exponen al cliente

Seguridad OAuth/OIDC

Cuando OAuth está habilitado:

La autenticación usa el flujo PKCE, que no requiere un client secret en el frontend
Los tokens se validan del lado del servidor antes de conceder acceso al chat
La superposición de login bloquea toda interacción con el chat hasta que la autenticación se complete correctamente
El logout de la sesión elimina los tokens del cliente e invalida la sesión del lado del servidor

Configuración de CORS

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

Solución de problemas

Revisa la consola en busca de errores de JavaScript
Verifica que la URL del script sea correcta
Revisa la configuración de CORS

Conexión fallida

Verifica que el endpoint de Direct Line sea accesible
Comprueba el soporte de WebSocket
Revisa la configuración del firewall

Los mensajes no se envían

Comprueba que la conversación esté activa
Verifica que el token no haya expirado
Revisa la consola del navegador en busca de errores

Próximos pasos

Adaptive Cards - Crea cards enriquecidas
Guía de tematización - Personalización avanzada
Guía de Flows - Construye flows conversacionales

WebChat

Resumen

Arquitectura

Configuración

Opciones de configuración

Configuración del widget

Configuración básica

Con tematización

Con información del usuario

Inicio minimizado

Funcionalidades

Mensajes de texto

Adaptive Cards

Respuestas rápidas (acciones sugeridas)

Subida de archivos

Indicador de escritura

Integración con APIs

API de JavaScript

API REST

Personalización

CSS personalizado

Avatar personalizado

Header personalizado

Soporte multilenguaje

Autenticación OAuth/OIDC

Providers soportados

Cómo funciona

Configuración del provider

Google

Microsoft (Entra ID)

GitHub

Provider OIDC personalizado

Configuración del widget con OAuth

Configuración interactiva con el asistente QA

Seguridad

Seguridad de tokens

Seguridad OAuth/OIDC

Configuración de CORS

Solución de problemas

El widget no carga

Conexión fallida

Los mensajes no se envían

Próximos pasos