Webchat Setup

Webchat v3 Setup Guide

What is Webchat v3?

Webchat v3 is Cognigy's embeddable chat widget for websites. It connects to a Webchat v3 Endpoint, which links a Flow to the widget and holds all appearance/behavior configuration.

Quick Start — Minimal Webchat

1. Ensure an agent + flow exist: create_ai_agent { name: "My Agent" }
2. Create a webchat endpoint: manage_webchat { projectId: "...", flowId: "...", name: "My Webchat" }
3. The response includes demoWebchatUrl — open it in a browser to test immediately.
4. Always show demoWebchatUrl to the user by default. Only provide configUrl/embeddingSnippet when asked about embedding or production deployment.

Quick Start — Update Existing Webchat

manage_webchat { endpointId: "...", layout: { colors: { primaryColor: "#0052cc" } }, behavior: { renderMarkdown: true } }

CREATE vs UPDATE:

• To create: omit endpointId and provide projectId + flowId. A new webchat3 endpoint is always created.
• To update: provide endpointId. Only the specified fields are changed; everything else is preserved.
• The tool never auto-detects or modifies existing endpoints. To update, first find the endpointId using list_resources { resourceType: "endpoint", projectId }.

Style Presets

Use stylePreset to apply a predefined look in one call:

manage_webchat { endpointId: "...", stylePreset: "modern" }

classic (default)

• Chat window: 460px, bot output max-width: 73%, bot output border: on
• Agent message bg: #ffffff, always scroll, no streaming collation, no progressive rendering, markdown on

modern

• Chat window: 900px, bot output max-width: 100%, bot output border: off
• Agent message bg: #ffffff, scroll to last input, streaming collation on, progressive rendering on, markdown on, input collation on

slick

• Chat window: 600px, bot output max-width: 100%, bot output border: off
• Agent message bg: #cccccc, scroll to last input, streaming collation on, progressive rendering off, markdown on, input collation on

Presets set layout + behavior fields. You can override individual fields after applying a preset by including them in the same call.

Settings Reference

layout

layout.colors

behavior

startBehavior

homeScreen

homeScreen.previousConversations

teaserMessage

chatOptions

chatOptions.quickReplies

chatOptions.textToSpeech

chatOptions.rating

chatOptions.footer

privacyNotice

businessHours

unreadMessages

maintenance

watermark

persistentMenu

attachmentUpload

webchatIcon

customJson

Type: string (raw JSON). Escape-hatch for advanced Webchat Custom Settings not covered above. Example: manage_webchat { endpointId: "...", customJson: "{"colors":{"primaryColor":"red"},"customTranslations":{"network_error":"Netzwerkfehler"}}" }

Common Recipes

Branded Webchat

manage_webchat { projectId: "...", flowId: "...", name: "Support Chat", layout: { title: "Acme Support", logoUrl: "https://acme.com/logo.png", colors: { primaryColor: "#0052cc", userMessageBg: "#e3f2fd" } } }

Modern Streaming Chat

manage_webchat { endpointId: "...", stylePreset: "modern", behavior: { enableTypingIndicator: true } }

Support Bot with Business Hours

manage_webchat { endpointId: "...", businessHours: { enabled: true, mode: "inform", timezone: "America/New_York", informationText: "We're available Mon-Fri 9-5 ET.", schedule: [ { dayOfWeek: "Monday", startTime: "09:00", endTime: "17:00" }, { dayOfWeek: "Tuesday", startTime: "09:00", endTime: "17:00" }, { dayOfWeek: "Wednesday", startTime: "09:00", endTime: "17:00" }, { dayOfWeek: "Thursday", startTime: "09:00", endTime: "17:00" }, { dayOfWeek: "Friday", startTime: "09:00", endTime: "17:00" } ] }, chatOptions: { enabled: true, rating: { enabled: true } }, privacyNotice: { enabled: true, policyLinkUrl: "https://acme.com/privacy" } }

Home Screen with Conversation Starters

manage_webchat { endpointId: "...", homeScreen: { enabled: true, welcomeText: "Hi! What can I help you with?", conversationStarters: [ { title: "Track my order", type: "postback", value: "track order" }, { title: "Return an item", type: "postback", value: "return item" }, { title: "Help Center", type: "url", value: "https://acme.com/help" } ] } }

Testing

The manage_webchat response includes demoWebchatUrl — a direct browser link to the Cognigy Demo Webchat page where the user can interact with the configured widget immediately. Always present this URL to the user by default.

You can also append query parameters for testing:

• ?user=testuser — set a specific user ID
• ?user=testuser&sessionId=mysession — set user and session

Embedding (Production)

When the user asks about deploying to their website, use the configUrl and embeddingSnippet from the response:

<script src="https://github.com/Cognigy/Webchat/releases/latest/download/webchat.js"></script>
<script>
  window.cognigyWebchat.open({
    configUrl: "CONFIG_URL_HERE"
  });
</script>

Replace CONFIG_URL_HERE with the configUrl from the manage_webchat response.

Prerequisites

• A Flow must exist (from create_ai_agent or manual creation)
• An LLM must be configured in the project for the agent to generate responses
• Use list_resources { resourceType: "endpoint", projectId } to find existing webchat endpoints