Overview
Team Common Ground provides tools to integrate with your website, allowing your customers to communicate with your business directly from your site.
Available Integrations
Chat
A floating chat button for your website that expands into a full messaging interface. Your customers can:
- Start new conversations
- View their message history
- Send messages, report issues, or provide feedback
Scheduler
A floating booking button for your website that expands into an appointment scheduling interface. Your customers can:
- Browse available time slots
- Select a service type
- Book appointments directly from your site
Domain Verification
Before using any website integration, you must verify ownership of your domain. This ensures only authorized websites can interact with your business.
Getting Started
To set up website integrations, you'll verify your domain, configure your settings, and add the embed code to your site. Each integration is covered in the sections below.
Domain Verification
Domain verification ensures that only authorized websites can embed the chat for your business. This prevents unauthorized sites from impersonating your business or sending fake messages on behalf of your customers.
Verification Methods
There are two ways to verify your domain. Choose whichever works best for your setup.
Option 1: File-Based Verification
Host a verification file on your website at a specific path. This is the simplest method if you have access to your web server.
Verification File Path
The verification file must be hosted at:
https://your-domain.com/.well-known/teamcommonground.json
File Format
Single environment:
{
"verification": {
"key": "your_verification_key_here"
}
}
Multiple environments (e.g., local dev and production):
{
"verification": {
"keys": [
"local_dev_key_here",
"production_key_here"
]
}
}
Option 2: DNS TXT Record
Add a TXT record to your domain's DNS settings. This is ideal if you don't have direct access to your web server or prefer not to host files.
Record Details
| Field | Value |
|---|---|
| Type | TXT |
| Host / Name | _teamcommonground-verify.your-domain.com |
| Value | teamcommonground-verify=your_verification_key |
Steps
- Go to your domain's DNS settings (usually in your domain registrar or hosting provider).
- Add a new TXT record with the host and value shown in your integration settings.
- Wait for DNS propagation (can take a few minutes to 48 hours depending on your provider).
- Click Verify in the integration settings.
Note: DNS propagation times vary. If verification fails, wait a few minutes and try again.
Common Issues
| Issue | Solution |
|---|---|
| "File not found" | Ensure the file is at /.well-known/teamcommonground.json (note the dot in .well-known) |
| "Invalid key" | Re-download the verification file and try again |
| "CORS error" | Ensure your server allows requests to the .well-known directory |
| "No TXT record found" | Double-check the record name and value, and allow time for DNS propagation |
| "DNS lookup timed out" | Wait a few minutes and try again — propagation may still be in progress |
Local Development
For local development, you can verify localhost:3000 (or your local port) using file-based verification. This allows testing the chat during development.
Note: Local development domains should not be used in production.
Chat
The Chat is a floating chat button that you add to your website. When clicked, it expands into a full messaging interface where your customers can communicate with your business.
Features
- Floating Button - A customizable chat button fixed in the corner of the screen
- Expandable Interface - Opens a full chat window without leaving the page
- Conversation History - Logged-in users can view and continue previous conversations
- Activity Types - Users can send messages, report issues, or provide feedback
- Real-time Updates - Messages appear instantly for both parties
- Mobile Friendly - Works on all screen sizes with a responsive fullscreen layout on mobile
Requirements
- Verified Domain - Your website domain must be verified (see )
- Business ID - Available in your integration settings
Embed Code
Add the loader script and chat component to your website:
<!-- Load the widget script -->
<script src="https://www.teamcommonground.com/widget/loader.js" async></script>
<!-- Add the widget -->
<tcg-chat-widget business-id="YOUR_BUSINESS_ID"></tcg-chat-widget>
Replace YOUR_BUSINESS_ID with your actual Business ID from the integration settings.
Complete Example
<!DOCTYPE html>
<html>
<head>
<title>My Website</title>
</head>
<body>
<!-- Your website content -->
<!-- Team Common Ground Chat Widget -->
<script src="https://www.teamcommonground.com/widget/loader.js" async></script>
<tcg-chat-widget business-id="YOUR_BUSINESS_ID"></tcg-chat-widget>
</body>
</html>
Embed Attributes
| Attribute | Description | Required |
|---|---|---|
business-id | Your Business ID | Yes |
Custom Triggers
Instead of the floating launcher, you can use your own inline buttons to open the chat. Use <tcg-chat-button> with a business-id — no <tcg-chat-widget> element is needed.
Button Component
<tcg-chat-button business-id="YOUR_BUSINESS_ID">Chat with us</tcg-chat-button>
Use your own element (image, icon, etc.):
<tcg-chat-button business-id="YOUR_BUSINESS_ID" auto-hide>
<img src="/chat-icon.png" alt="Chat" />
</tcg-chat-button>
Button Attributes
| Attribute | Description | Default |
|---|---|---|
business-id | Your Business ID (required when no <tcg-chat-widget> is on the page) | — |
variant | Button style: solid, ghost, or outline | ghost |
color | Accent color (hex without #) | 3B82F6 |
auto-hide | Hide when chat is open | (not set) |
page | Page to open: message, issue, feedback, help, history | (home) |
context | JSON string with context data | (none) |
JavaScript API
Control the chat programmatically:
// Open the widget
TCGWidget.open();
// Open to a specific page
TCGWidget.open('message'); // 'help', 'message', 'issue', 'feedback', 'history'
// Close the widget
TCGWidget.close();
// Check if widget is open
if (TCGWidget.isOpen) {
// widget is currently open
}
Passing Context Data
Pass context data when opening the chat for product pages, order support, etc.:
<tcg-chat-button
page="message"
context='{"title":"Blue Widget Pro","description":"SKU: BWP-123","entityId":"prod_123","entityType":"product"}'
>
Ask about this product
</tcg-chat-button>
Or via JavaScript:
TCGWidget.open('message', {
title: 'Blue Widget Pro',
description: 'SKU: BWP-123 | $49.99',
imageUrl: 'https://example.com/product.jpg',
entityId: 'prod_123',
entityType: 'product'
});
Context Schema:
| Property | Type | Description |
|---|---|---|
title | string | Required. Main display title |
description | string | Additional details |
imageUrl | string | Product/entity image URL |
url | string | Link back to the source page |
entityId | string | Product/entity ID for tracking |
entityType | string | Type hint (e.g., "product", "order") |
metadata | object | Custom key-value pairs |
name | string | Pre-fill guest name for guest sign up |
email | string | Pre-fill guest email for guest sign up |
Customization
Appearance and behavior are configured in the chat integration settings. Changes take effect immediately without updating your embed code.
Available Settings
- Primary Color - Brand color for the floating button, send button, and outgoing message bubbles
- Position - Bottom Right (default) or Bottom Left
- Theme - Light, Dark, or System (matches user's system preference)
- Greeting Message - Welcome message shown to new users
- Action Buttons - Configure which action types appear (Message, Issue, Feedback, Help) with custom titles, subtitles, and colors
Z-Index
The chat uses z-index: 2147483647. If other elements cover it, adjust their z-index values.
FAQ / Help Center
The FAQ feature adds a searchable help center to your chat. Customers can browse help articles organized into collections, search across all content, and provide feedback on articles — all without leaving your site.
Enabling FAQ
FAQ is enabled in the editor under the FAQ section in the sidebar. When enabled, an action button labeled Browse help articles (customizable) appears on the home screen alongside your other action buttons.
You can customize:
- FAQ Title — The heading shown in the FAQ view (e.g., "Help Center", "FAQs")
- Button Label — The text on the home screen action button (e.g., "Browse help articles")
Collections & Articles
FAQ content is organized into collections and articles.
Collections
Collections are groups of related articles (e.g., "Getting Started", "Billing", "Account"). Each collection has:
| Field | Description |
|---|---|
| Name | Display name for the collection |
| Description | Optional summary shown below the name |
| Order | Controls the display order |
| Active | Toggle visibility in the chat |
Articles
Articles are individual help entries. Each article has:
| Field | Description |
|---|---|
| Question | The title displayed in the article list |
| Type | inline (markdown content displayed inline) or external (links to an external URL) |
| Content | Markdown body for inline articles |
| External URL | Destination URL for external articles |
| Collection | Optional — assign to a collection, or leave uncategorized |
| Order | Controls the display order within its collection |
Inline articles render markdown content directly inside the chat, with a "Was this helpful?" feedback prompt at the bottom.
External articles open in a new browser tab when clicked.
Managing FAQ Content
In the editor, the FAQ sidebar section provides controls to:
- Create a collection — Add a new collection with a name and optional description
- Create an article — Add an inline or external article, assign it to a collection, and write markdown content
- Reorder — Use the up/down arrows to reorder collections and articles
- Edit — Click any article or collection to edit its details
- Delete — Remove articles or collections
- Import from URL — Bulk import collections and articles from an external JSON endpoint
Import from URL
The Import from URL feature lets you bulk import FAQ content from a JSON endpoint hosted on your verified domain. This is useful for syncing help content from an existing knowledge base or CMS.
How It Works
- Click the cloud icon in the FAQ section toolbar to reveal the import panel
- Enter the URL of your JSON endpoint (e.g.,
https://yourdomain.com/api/faqs.json) - Click Import — the system fetches and validates the response
- A preview shows all collections and articles found, with checkboxes to select which items to import
- Items that already exist (matching IDs) are labeled as updates; new items are labeled as new
- Click Confirm Import to save the selected items
Requirements
| Requirement | Details |
|---|---|
| HTTPS | The URL must use HTTPS (except localhost for development) |
| Verified domain | The URL's domain must be verified for your business (see ) |
| Content-Type | Response must have Content-Type: application/json |
| Response size | Maximum 1 MB |
| Timeout | The endpoint must respond within 10 seconds |
| No redirects | Redirects are not followed (for security) |
Response Schema
Your endpoint must return JSON matching the ExternalFAQResponse schema:
{
"version": "1.0",
"collections": [
{
"id": "getting-started",
"name": "Getting Started",
"description": "Learn the basics of our platform",
"icon": "rocket",
"order": 0
}
],
"articles": [
{
"id": "create-account",
"collectionId": "getting-started",
"question": "How do I create an account?",
"type": "inline",
"content": "## Creating an Account\n\nVisit our signup page and...",
"order": 0
},
{
"id": "api-reference",
"collectionId": "getting-started",
"question": "API Reference",
"type": "external",
"externalUrl": "https://yourdomain.com/docs/api",
"order": 1
}
],
"metadata": {
"lastUpdated": "2025-01-15T10:30:00Z",
"cacheMaxAge": 300
}
}
Schema Reference
Root object:
| Field | Type | Required | Description |
|---|---|---|---|
version | string | Yes | Must be "1.0" |
collections | array | Yes | Array of collection objects (max 50) |
articles | array | Yes | Array of article objects (max 500) |
metadata | object | No | Optional metadata |
Collection object:
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Unique identifier |
name | string | Yes | Display name |
description | string | No | Short description |
icon | string | No | Icon identifier |
order | number | Yes | Sort order |
Article object:
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Unique identifier |
collectionId | string | No | Collection to group into (omit for uncategorized) |
question | string | Yes | Article title |
type | string | Yes | "inline" or "external" |
content | string | No | Markdown content (for inline type) |
externalUrl | string | No | Destination URL (for external type) |
order | number | Yes | Sort order within its collection |
Metadata object:
| Field | Type | Description |
|---|---|---|
lastUpdated | string | ISO 8601 timestamp |
cacheMaxAge | number | Suggested cache TTL in seconds |
Limits
| Limit | Value |
|---|---|
| Max collections per import | 50 |
| Max articles per import | 500 |
| Max response size | 1 MB |
| Request timeout | 10 seconds |
User-Agent
Requests are made with the User-Agent header TeamCommonGround-WidgetFAQ/1.0.
How Customers Use FAQ
When a customer clicks the help action button in the chat:
- Browse — Collections are listed with article counts. Uncategorized articles appear at the top level.
- Search — A search bar filters articles by question title and content in real time.
- Read — Clicking an inline article opens its markdown content in the chat. External articles open in a new tab.
- Feedback — After reading an inline article, customers can rate it as helpful or not helpful.
View counts and feedback counts are tracked per article and visible in the editor.
Scheduler
The Scheduler is a floating booking button that you add to your website. When clicked, it expands into an appointment scheduling interface where your customers can browse available time slots and book appointments.
Features
- Floating Button - A customizable calendar button fixed in the corner of the screen
- Expandable Calendar - Opens a date and time picker without leaving the page
- Service Type Selection - Optionally let clients choose a service type before booking
- Guest Booking - Visitors can book without creating an account
- Mobile Friendly - Works on all screen sizes with automatic fullscreen on mobile
Requirements
- Verified Domain - Your website domain must be verified (see )
- Business ID - Available in your integration settings
- Availability Configured - Set your weekly schedule and slot duration in the editor
Embed Code
Add the loader script and scheduler component to your website:
<!-- Load the widget script -->
<script src="https://www.teamcommonground.com/widget/loader.js"></script>
<!-- Add the widget -->
<tcg-scheduler-widget business-id="YOUR_BUSINESS_ID"></tcg-scheduler-widget>
Replace YOUR_BUSINESS_ID with your actual Business ID from the integration settings.
Complete Example
<!DOCTYPE html>
<html>
<head>
<title>My Website</title>
</head>
<body>
<!-- Your website content -->
<!-- Team Common Ground Scheduler Widget -->
<script src="https://www.teamcommonground.com/widget/loader.js"></script>
<tcg-scheduler-widget business-id="YOUR_BUSINESS_ID"></tcg-scheduler-widget>
</body>
</html>
Embed Attributes
| Attribute | Description | Required |
|---|---|---|
business-id | Your Business ID | Yes |
color | Accent color (hex without #, e.g. 8B5CF6) | No |
position | bottom-right (default) or bottom-left | No |
theme | light (default) or dark | No |
Custom Triggers
Instead of the floating launcher, you can use your own inline buttons to open the scheduler. Use <tcg-scheduler-button> with a business-id — no <tcg-scheduler-widget> element is needed.
Button Component
<tcg-scheduler-button business-id="YOUR_BUSINESS_ID">Book an Appointment</tcg-scheduler-button>
Style it with the variant attribute:
<tcg-scheduler-button business-id="YOUR_BUSINESS_ID" variant="solid" color="8B5CF6">Schedule Now</tcg-scheduler-button>
Use your own element (image, icon, etc.):
<tcg-scheduler-button business-id="YOUR_BUSINESS_ID" auto-hide>
<img src="/calendar-icon.png" alt="Book" />
</tcg-scheduler-button>
Button Attributes
| Attribute | Description | Default |
|---|---|---|
business-id | Your Business ID (required when no <tcg-scheduler-widget> is on the page) | — |
variant | Button style: solid, ghost, or outline | ghost |
color | Accent color (hex without #) | 8B5CF6 |
auto-hide | Hide when scheduler is open | (not set) |
JavaScript API
Control the scheduler programmatically:
// Open the widget
TCGSchedulerWidget.open();
// Close the widget
TCGSchedulerWidget.close();
// Check if widget is open
if (TCGSchedulerWidget.isOpen) {
// widget is currently open
}
Customization
Appearance and booking options are configured in the scheduler editor. Changes take effect immediately without updating your embed code.
Available Settings
- Accent Color - Brand color for the floating button and UI accents
- Position - Bottom Right (default) or Bottom Left
- Heading / Subheading - Customize the header text
- Service Types - Show or hide service type selection
- Guest Booking - Allow or require sign-in before booking
Availability Settings
Configure your weekly schedule, appointment duration, buffer time between slots, and advance booking limits directly from the editor.
Z-Index
The scheduler uses z-index: 2147483647. If other elements cover it, adjust their z-index values.
Troubleshooting
Not Appearing
| Cause | Solution |
|---|---|
| Domain not verified | Ensure your domain shows "Verified" status in the integration settings |
| Wrong Business ID | Verify the business-id attribute matches your business |
| Z-index conflicts | Other elements may be covering it — adjust their z-index |
| Content Security Policy | If your site has strict CSP, add teamcommonground.com to frame-src |
Shows Error
If it shows a red exclamation mark:
| Cause | Solution |
|---|---|
| Domain verification failed | The URL's referer must match a verified domain. Check the browser console for details |
| Business not found | Double-check the Business ID |
Users Can't Sign In
| Cause | Solution |
|---|---|
| Pop-up blocked | The sign-in flow may open in a new tab — ensure pop-ups are allowed for your domain |
| Cookies disabled | Firebase Auth requires cookies — ensure third-party cookies are enabled |
Messages Not Sending
| Cause | Solution |
|---|---|
| Authentication expired | User may need to sign in again — they will be prompted for re-authentication |
| Network issues | Check the browser console for API errors and verify internet connectivity |
Getting Help
If you're still having issues, check the browser console for error messages, verify your domain is correctly verified, and test with a fresh incognito window. Contact support with your Business ID and error details if the problem persists.