Web Chat Widget Guide

Set up browser-based chat for your website

Setup Time: ~2 minutes

Overview

Web channels enable AI agents to interact with customers through a chat widget embedded on your website. Supports text chat, voice, or both.

Key Features:

✅ Text chat with rich media
✅ Voice conversations (WebRTC)
✅ Customizable theming
✅ Mobile responsive
✅ Real-time messaging

Quick Start

Step 1: Create Web Channel

TypeScript
Python

import { WiilClient } from 'wiil-js';
import { DeploymentType, OttCommunicationType } from 'wiil-core-js';

const client = new WiilClient({ apiKey: process.env.WIIL_API_KEY! });

const webChannel = await client.deploymentChannels.create({
  deploymentType: DeploymentType.WEB,
  channelName: 'Website Live Chat',
  channelIdentifier: 'https://example.com',
  recordingEnabled: true,
  configuration: {
    communicationType: OttCommunicationType.UNIFIED,
    widgetConfiguration: {
      position: 'right'
    }
  }
});

console.log(`Channel ID: ${webChannel.id}`);

from wiil import WiilClient
from wiil.models.service_mgt import CreateDeploymentChannel
from wiil.types import DeploymentType, OttCommunicationType

client = WiilClient(api_key="YOUR_API_KEY")

channel = client.deployment_channels.create(
    CreateDeploymentChannel(
        deployment_type=DeploymentType.WEB,
        channel_name="Website Chat",
        channel_identifier="https://example.com",
        recording_enabled=True,
        configuration={
            "communicationType": OttCommunicationType.UNIFIED,
            "widgetConfiguration": {
                "position": "right",
            },
        },
    )
)

print("channel_id:", channel.id)

Step 2: Create Deployment

TypeScript
Python

import { DeploymentStatus, DeploymentProvisioningType } from 'wiil-core-js';

const deployment = await client.deploymentConfigs.create({
  projectId: 'YOUR_PROJECT_ID',
  deploymentChannelId: webChannel.id,
  agentConfigurationId: 'YOUR_AGENT_ID',
  instructionConfigurationId: 'YOUR_INSTRUCTION_ID',
  deploymentName: 'Website Chat',
  isActive: true,
  deploymentStatus: DeploymentStatus.PENDING,
  provisioningType: DeploymentProvisioningType.DIRECT
});

console.log(`Deployment ID: ${deployment.id}`);

from wiil import WiilClient
from wiil.models.service_mgt import CreateDeploymentConfiguration
from wiil.types import DeploymentProvisioningType, DeploymentStatus

client = WiilClient(api_key="YOUR_API_KEY")

deployment = client.deployment_configs.create(
    CreateDeploymentConfiguration(
        project_id="YOUR_PROJECT_ID",
        deployment_channel_id="YOUR_WEB_CHANNEL_ID",
        agent_configuration_id="YOUR_AGENT_CONFIG_ID",
        instruction_configuration_id="YOUR_INSTRUCTION_CONFIG_ID",
        deployment_name="Website Support",
        deployment_status=DeploymentStatus.PENDING,
        provisioning_type=DeploymentProvisioningType.DIRECT,
        is_active=True,
    )
)

print("deployment_id:", deployment.id)

TypeScript
Python

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <h1>Welcome!</h1>

  <!-- WIIL Widget -->
  <div
    id="wiil-widget"
    data-config-id="YOUR_DEPLOYMENT_ID"
    data-features="chat,voice"
  ></div>
  <script src="https://cdn.wiil.io/public/wiil-widget.js"></script>
  <script>WiilWidget.init();</script>
</body>
</html>

<div id="wiil-widget" data-config-id="YOUR_DEPLOYMENT_ID" data-features="chat,voice"></div>
<script src="https://cdn.wiil.io/public/wiil-widget.js"></script>
<script>WiilWidget.init();</script>

That's it! Your chat widget is now live.

Communication Types

Choose how customers interact:

TEXT - Text Chat Only

communicationType: OttCommunicationType.TEXT

Features:

Text messages
Rich media (images, files)
Typing indicators
Message history

Best for: Help centers, FAQ bots, support chat

VOICE - Voice Only

communicationType: OttCommunicationType.VOICE

Features:

Voice input/output
Speech recognition
Real-time audio (WebRTC)

Best for: Voice-first applications, accessibility

UNIFIED - Text + Voice

communicationType: OttCommunicationType.UNIFIED

Features:

All text features
All voice features
Seamless switching
Multi-modal conversations

Best for: Full-featured customer service (recommended)

Position

Control where the widget appears:

widgetConfiguration: {
  position: 'right'  // or 'left'
}

Complete Example

TypeScript
Python

import { WiilClient } from 'wiil-js';
import {
  DeploymentType,
  OttCommunicationType,
  DeploymentStatus,
  DeploymentProvisioningType
} from 'wiil-core-js';

async function setupWebChat() {
  const client = new WiilClient({ apiKey: process.env.WIIL_API_KEY! });

  // Get prerequisites
  const project = await client.projects.getDefault();
  const agentConfig = await client.agentConfigs.get('YOUR_AGENT_ID');
  const instructionConfig = await client.instructionConfigs.get('YOUR_INSTRUCTION_ID');

  // Create web channel with custom theme
  const webChannel = await client.deploymentChannels.create({
    deploymentType: DeploymentType.WEB,
    channelName: 'E-commerce Support Chat',
    channelIdentifier: 'https://shop.example.com',
    recordingEnabled: true,
    configuration: {
      communicationType: OttCommunicationType.UNIFIED,
      widgetConfiguration: {
        position: 'right'
      }
    }
  });

  // Create deployment
  const deployment = await client.deploymentConfigs.create({
    projectId: project.id,
    deploymentChannelId: webChannel.id,
    agentConfigurationId: agentConfig.id,
    instructionConfigurationId: instructionConfig.id,
    deploymentName: 'E-commerce Support',
    isActive: true,
    deploymentStatus: DeploymentStatus.PENDING,
    provisioningType: DeploymentProvisioningType.DIRECT
  });

  console.log('✓ Setup complete!');
  console.log(`\nAdd this to your website:\n`);
  console.log(`<div id="wiil-widget" data-config-id="${deployment.id}" data-features="chat,voice"></div>`);
  console.log(`<script src="https://cdn.wiil.io/public/wiil-widget.js"></script>`);
  console.log(`<script>WiilWidget.init();</script>`);

  return { webChannel, deployment };
}

setupWebChat().catch(console.error);

from wiil import WiilClient
from wiil.models.service_mgt import UpdateDeploymentChannel
from wiil.types import OttCommunicationType

client = WiilClient(api_key="YOUR_API_KEY")

updated = client.deployment_channels.update(
    UpdateDeploymentChannel(
        id="YOUR_WEB_CHANNEL_ID",
        configuration={
            "communicationType": OttCommunicationType.TEXT,
            "widgetConfiguration": {"position": "left"},
        },
    )
)

print(updated.configuration)

React Integration

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    // Create widget container
    const widgetDiv = document.createElement('div');
    widgetDiv.id = 'wiil-widget';
    widgetDiv.setAttribute('data-config-id', 'YOUR_DEPLOYMENT_ID');
    widgetDiv.setAttribute('data-features', 'chat,voice');
    document.body.appendChild(widgetDiv);

    // Load widget script
    const script = document.createElement('script');
    script.src = 'https://cdn.wiil.io/public/wiil-widget.js';
    script.async = true;
    script.onload = () => {
      window.WiilWidget.init();
    };
    document.body.appendChild(script);

    // Cleanup
    return () => {
      document.body.removeChild(widgetDiv);
      document.body.removeChild(script);
    };
  }, []);

  return (
    <div className="App">
      <h1>My App</h1>
    </div>
  );
}

Environment-Specific Setup

Use different URLs for dev/staging/production:

const channelIdentifier = process.env.NODE_ENV === 'production'
  ? 'https://example.com'
  : process.env.NODE_ENV === 'staging'
  ? 'https://staging.example.com'
  : 'http://localhost:3000';

const webChannel = await client.deploymentChannels.create({
  deploymentType: DeploymentType.WEB,
  channelIdentifier,
  // ... rest of config
});

Attribute	Required	Description	Example
`id`	✅ Yes	Must be "wiil-widget"	`id="wiil-widget"`
`data-config-id`	✅ Yes	Deployment ID	`data-config-id="abc123"`
`data-features`	✅ Yes	Features to enable	`data-features="chat,voice"`

Feature Options:

"chat" - Text chat only
"voice" - Voice only
"chat,voice" - Both (recommended)

Troubleshooting

✅ Verify deployment ID is correct
✅ Check deployment isActive: true
✅ Ensure script URL is correct
✅ Check browser console for errors
✅ Clear browser cache

Voice not working

✅ Set communicationType: UNIFIED or VOICE
✅ Check browser microphone permissions
✅ Use HTTPS (required for microphone access)
✅ Test in supported browser (Chrome, Firefox, Safari)

Next Steps

Learn Channel Types: Understanding Channels
Troubleshooting: Troubleshooting Guide

← Back to Channels Home

Web Chat Widget Guide

Overview

Quick Start

Step 1: Create Web Channel

Step 2: Create Deployment

Step 3: Add Widget to Website

Communication Types

TEXT - Text Chat Only

VOICE - Voice Only

UNIFIED - Text + Voice

Widget Configuration

Position

Complete Example

React Integration

Environment-Specific Setup

Widget Data Attributes

Troubleshooting

Widget not appearing

Voice not working

Next Steps

Overview​

Quick Start​

Step 1: Create Web Channel​

Step 2: Create Deployment​

Step 3: Add Widget to Website​

Communication Types​

TEXT - Text Chat Only​

VOICE - Voice Only​

UNIFIED - Text + Voice​

Widget Configuration​

Position​

Complete Example​

React Integration​

Environment-Specific Setup​

Widget Data Attributes​

Troubleshooting​

Widget not appearing​

Voice not working​

Next Steps​

Overview

Quick Start

Step 1: Create Web Channel

Step 2: Create Deployment

Step 3: Add Widget to Website

Communication Types

TEXT - Text Chat Only

VOICE - Voice Only

UNIFIED - Text + Voice

Widget Configuration

Position

Complete Example

React Integration

Environment-Specific Setup

Widget Data Attributes

Troubleshooting

Widget not appearing

Voice not working

Next Steps