ChatGridAI Setup Guide

Your goal: Get your team asking questions in Google Chat or Teams — and getting instant, accurate answers from your own company documents.

Here's everything you need to make that happen.

Before you start, make sure you have:

Here's exactly what you'll do:

Core Features

• Works in your existing chat: Google Chat or Teams — no new apps to learn
• Learns your company knowledge: Upload PDFs, Word docs, procedures — AI references them when answering
• You control costs: Use your own OpenAI API key — all AI costs billed directly to your OpenAI account
• Multi-group setup: Different teams get different AI configurations with separate knowledge bases

Pricing Model

You pay two separate things:

1. OpenAI API costs: Billed directly to your OpenAI account (~$0.15-$10 per 1M tokens depending on model)
2. ChatGridAI platform fee:
   • 14-day free trial (10 seats, no credit card required)
   • After trial: Minimum 20 seats ($100/month)
   • Sold in packs: 5 seats for $25/month (always $5 per seat)
   • Details: Section 7 — Billing

How It Works

Supported Platforms

• Google Chat: Direct messages, group chats, spaces (requires Google Workspace)
• Microsoft Teams: Direct messages, group chats, channels (requires Microsoft 365)

Security

• Your documents: Stored only in OpenAI Vector Stores, NOT on ChatGridAI servers
• Your conversations: Stored in OpenAI threads, NOT on ChatGridAI servers
• Your API key: Encrypted in HashiCorp Vault, never visible in full after setup
• Access control: Domain-verified users only, explicit group membership required

The dashboard is your management interface for ChatGridAI. Access it at /dashboard after logging in. The dashboard has a left sidebar with 5 sections:

The Team Members section shows all users in your workspace. View who's assigned to which groups, reassign users, and manage team access in one place.

What You See

Stats Cards (Top of Page)

• Total Members: All users across all groups
• Active Groups: Groups that have at least one member
• Unassigned: Users currently in "Unassigned" group only

Members Table

Table displays all users with these columns:

• Checkbox: Select individual users for bulk actions
• User: Email address (Google Workspace) or Display Name (Microsoft Teams). Admin users show "(Admin)" label.
• Delete: Button to permanently remove user from system (Enterprise/Professional plans only, 2 deletes per month for Professional). Cannot delete admin users.
• Current Group: Which group the user is currently assigned to
• Assign to Group: Dropdown to reassign user to different group

Search and Filter

Tools above the table:

• Search box: Type to filter by email/name. Updates table in real-time.
• Group filter dropdown: Show only members of specific group. Combines with search filter.
• Sort columns: Click "User" or "Current Group" column headers to sort ascending/descending. Arrow shows current sort direction.

Reassigning Users

Individual Reassign

Click dropdown in "Assign to Group" column → Select new group → User immediately moved to that group. Their chat thread stays intact.

Bulk Reassign

1. Check boxes next to users you want to move
2. Bulk actions bar appears showing "X selected"
3. Select target group from "Move to group..." dropdown
4. Click "Reassign Selected" button
5. Confirm in popup
6. All selected users moved to new group

Removing Users

Move to Unassigned (Free)

Select users → Bulk reassign dropdown → Choose "Unassigned" → Click "Reassign Selected". Users moved to Unassigned group. They cannot use the AI until reassigned to configured group.

Permanent Deletion (Paid Plans Only)

Delete Credits System:

When you purchase seats, you receive monthly delete credits equal to your seat count divided by 5 (rounded down):

• 20 seats (minimum) = 4 delete credits/month
• 25 seats = 5 delete credits/month
• 30 seats = 6 delete credits/month
• 50 seats = 10 delete credits/month
• Credits reset at start of each billing cycle
• Unused credits do NOT roll over

How to delete users:

1. Check boxes next to users
2. "Delete Selected" button appears (red)
3. Click "Delete Selected"
4. System shows remaining delete credits
5. Two confirmation popups (permanent action warning)
6. Users permanently removed from system
7. Delete credits deducted

Select All

Checkbox in table header (left side) → Selects/deselects all visible users in current filtered view. If you're filtered to specific group, only those users get selected.

Mobile View

Table converts to card layout on mobile devices. Each user = separate card showing all same information. All actions (reassign, delete, select) work identically.

View OpenAI token usage and estimated costs. All costs billed directly to your OpenAI account — ChatGridAI tracks and displays the data only.

Overview Stats (Last 30 Days)

• Total Tokens: Combined input and output tokens across all groups
• Total Cost: Estimated OpenAI costs in USD
• Active Groups: Groups with usage activity
• Avg Per Day: Average daily token consumption

Usage by Group Chart

Doughnut chart showing token distribution across groups. Only displays groups with usage activity (groups with zero tokens not shown). Click any segment to see user breakdown for that group in the chart below.

Top Users Chart

Bar chart showing top 8 users by token consumption within selected group. Displays username only (part before @ in email). Updates when you click different group in the doughnut chart above. Shows "No user activity yet" if group has no usage.

How Data is Tracked

Every time a user sends a message in Google Chat or Microsoft Teams:

Cost Calculation

Actual costs vary by model selected in group configuration:

Empty State

If no usage data exists yet, charts display "No usage data yet" or "No user activity yet". Start chatting with the AI in Google Chat or Microsoft Teams to generate analytics data.

Mobile View

Charts stack vertically on mobile devices. All data remains visible and interactive.

Pricing

Trial (14 days, free)

• 10 seats included
• No credit card required
• Unlimited groups
• Unlimited file uploads
• Full analytics access
• No delete credits (can only move users to Unassigned)

Paid Plan

Seat Packs: 5 seats for $25/month ($5 per seat)

• Minimum purchase: 4 packs (20 seats) = $100/month
• Each pack = 5 seats for $25
• Always exactly $5 per seat
• Scale up by purchasing additional packs as needed
• Billed monthly via Stripe
• Unlimited groups
• Unlimited file uploads
• Full analytics

Delete Credits

Monthly delete credits = your total seat count divided by 5 (rounded down)

• 20 seats (minimum) = 4 delete credits/month
• 25 seats = 5 delete credits/month
• 30 seats = 6 delete credits/month
• 50 seats = 10 delete credits/month

Current Subscription Card

Dashboard Billing section shows:

• Subscription Status: Active Trial, Active, Cancelling, Expired, or Inactive
• Total Seats: Your current seat count
• Delete Credits: Remaining credits this billing cycle / Monthly allowance
• Next Billing: Date and amount of next charge
• Billing Cycle: Monthly (annual not currently supported)

Upgrading from Trial

1. Click "Upgrade" button (appears in yellow trial banner or Billing section)
2. Redirected to Stripe Checkout (secure payment processor)
3. Enter payment details (credit/debit card)
4. Select quantity (minimum 4 packs = 20 seats = $100/month)
5. Confirm payment
6. Redirected back to dashboard
7. Subscription activated immediately
8. Trial banner disappears
9. Delete credits become available (4/month for minimum 20 seats)

Adding More Seats

When you have an active paid subscription:

1. Dashboard → Billing → Click "Add Seats" button
2. Redirected to Stripe Checkout
3. Adjust quantity (1–20 seat packs)
4. Each pack = 5 seats = $25/month
5. Confirm purchase
6. Seats added immediately
7. Delete credits recalculated automatically
8. Prorated charge for current billing period

Reducing Seats

Important: You must have fewer users than your new seat limit before reducing seats.

1. Dashboard → Billing → Click "Billing Portal"
2. Stripe customer portal opens
3. Click "Update plan" → Adjust seat pack quantity down
4. If current users > new seat limit: Change rejected
   • Warning: "You have X users but new limit is Y seats. Remove Z users first."
   • Go to Team Members → Move excess users to Unassigned or delete them
   • Try reducing seats again
5. If users ≤ new limit: Change scheduled for end of current billing period
6. Delete credits recalculated at next billing cycle

Delete Credits Explained

How it works: Your monthly delete credits equal your total seat count divided by 5 (rounded down).

Why Delete Credits Exist

Delete credits prevent abuse while allowing reasonable user turnover. When you remove a user, their seat becomes available for reassignment. Delete credits let you permanently remove users who have left your organization.

Credit Reset Schedule

• Credits reset at start of each billing cycle
• Unused credits do NOT roll over
• Reset date shown in Billing section
• If you add seats mid-cycle, credits recalculate immediately
• If you reduce seats, credits recalculate at next billing cycle

What If I Run Out of Credits?

Two options:

1. Wait until next billing cycle (credits reset automatically)
2. Buy more seats (adds more credits immediately via formula)

Alternative: Move users to "Unassigned" group (free, doesn't use credits, user can't access AI until reassigned)

Billing Portal

Click "Billing Portal" button to access Stripe customer portal where you can:

• Update payment method
• View payment history
• Download invoices
• Adjust seat pack quantity (add/remove seats)
• Cancel subscription

Cancellation

1. Click "Billing Portal"
2. Scroll to bottom → Click "Cancel subscription"
3. Confirm cancellation
4. Subscription marked "Cancelling"
5. Access continues until end of current billing period
6. No refunds for partial months
7. After period ends:
   • Cannot send messages in Google Chat or Microsoft Teams
   • Dashboard becomes read-only (view only, no edits)
   • All data preserved (groups, users, configuration, analytics)
   • Reactivate anytime by subscribing again

Status Indicators

• Active: Subscription active, will auto-renew
• Cancelling: Subscription active until period end, will not renew
• Active Trial: In 14-day trial period
• Expired: Trial or subscription ended, access disabled until renewed
• Inactive: No active subscription or trial

Seat Management Best Practices

• Start small: Use trial to test with 10 users, buy seat packs as needed
• Monitor usage: Analytics section shows which users are active
• Plan for turnover: Delete credits = ~20% monthly turnover (2 deletions per 10 seats)
• Move vs Delete: Move inactive users to Unassigned (free, reversible) vs permanent deletion (uses credits)
• Timing matters: Add seats anytime (prorated), reduce at billing cycle end (avoid early removal)

Pricing Examples

Actions let employees submit structured requests directly from chat — without filling in forms or switching apps. The AI collects the details through conversation, shows the employee a summary to confirm, then fires a signed webhook to any external system you configure (Jira, ServiceNow, an HR platform, a custom API, etc.).

How It Works (Employee Perspective)

8.1 Enable Actions for a Group

Actions are configured per group. To enable them:

1. Open the dashboard and select your group
2. Go to the JSON Builder section in the sidebar
3. Create at least one template (see Section 8.2)
4. Go to the Webhooks section and enter your webhook URL
5. Toggle Actions enabled on

8.2 Creating Templates (JSON Builder)

A template defines two things: what fields the AI should collect from the employee, and what JSON payload gets sent to your webhook when they confirm.

Step 1 — Create a new template

In the JSON Builder, click + New. Give it a display name (e.g. "Vacation Request") and a slug is generated automatically (e.g. vacation_request). The slug is what the AI uses internally to identify the request type.

Step 2 — Define mandatory fields

Add the fields the AI needs to collect. Each field has a name and a collection mode:

• Required — AI will infer from context if possible, otherwise ask
• Always ask — AI must ask the employee explicitly, even if the answer seems obvious (use for dates, names, anything that must be confirmed)
• Ask if known — AI asks but proceeds if the employee doesn't know
• Auto-fill (name) — Automatically populated from the employee's display name. Never shown to or asked of the employee.

Example fields for a leave request:

• request_type — Required (annual, sick, unpaid)
• start_date — Always ask
• end_date — Always ask
• is_paid — Required
• employee_name — Auto-fill (name)

Step 3 — Build the payload

Use the Row Builder to define key/value pairs, or switch to Raw JSON to paste your own structure. Use {{mustache}} variables to inject values collected from the conversation.

Example payload for a Jira Service Management request:

{
  "summary": "{{title}}",
  "description": "{{description}}",
  "request_type": "{{fields.request_type}}",
  "start_date": "{{fields.start_date}}",
  "end_date": "{{fields.end_date}}",
  "is_paid": "{{fields.is_paid}}",
  "requested_by": "{{user.email}}",
  "source": "{{platform}}",
  "action_id": "{{action_id}}"
}

8.3 Variable Reference

The following variables are available in your JSON template. Empty optional fields are automatically stripped from the payload before delivery.

Variable	Value
{{event_type}}	Always action.created
{{action_id}}	Unique UUID for this submission (use for idempotency in your system)
{{timestamp}}	ISO 8601 UTC timestamp of submission
{{title}}	Short summary generated by the AI (e.g. "Annual Leave 14–18 April")
{{description}}	Full description of the request
{{intent}}	The template slug matched (e.g. vacation_request)
{{user.email}}	Employee email address (Google Chat). Empty on Teams.
{{user.name}}	Employee display name (Teams). Empty on Google Chat.
{{platform}}	teams or google_chat
{{group.name}}	Name of the group the employee belongs to
{{group.id}}	Numeric group ID
{{fields.FIELD_NAME}}	Any field collected during the conversation. Replace FIELD_NAME with your field name (e.g. {{fields.start_date}}).

8.4 Webhook Configuration

Go to the Webhooks section in the dashboard sidebar to configure delivery settings for the selected group.

Webhook URL

The HTTPS endpoint that receives the payload. Must return a 2xx status code to be considered a successful delivery. ChatGridAI retries up to 3 times on 5xx errors with exponential backoff before marking the delivery as failed.

Signing secret (recommended)

If provided, every request includes an X-ChatGridAI-Signature header containing an HMAC-SHA256 signature of the payload. Verify this on your server to confirm the request is genuine and hasn't been tampered with.

The signature is computed as:

HMAC-SHA256(secret, "{timestamp}.{body}")

Where timestamp is the value of the X-ChatGridAI-Timestamp header and body is the raw JSON string.

Bearer token (optional)

If your endpoint requires authentication, enter a token here. It is sent as Authorization: Bearer <token> on every request.

Custom headers (optional)

Add any additional HTTP headers your endpoint requires (e.g. X-Api-Key). Values are stored encrypted and never shown in full after saving.

8.5 Testing & Delivery Logs

Test button

Use Send test event in the Webhooks section to fire a sample payload to your endpoint immediately. The response status code and body are shown inline so you can confirm delivery before going live.

Delivery history

The Webhooks section shows the last 50 deliveries across all groups — timestamp, group, request title, HTTP status, and success/failure status. Use this to diagnose failed deliveries without needing server-side logging.

8.6 End-to-End Example — Leave Request to Jira Service Management

This example walks through a complete setup connecting an HR leave request to Jira Service Management.

1. Create the template in JSON Builder

• Display name: Leave Request
• Slug: leave_request (auto-generated)
• Fields: request_type (Required), start_date (Always ask), end_date (Always ask), is_paid (Required), employee_name (Auto-fill name)

2. Build the JSON payload

{
  "fields": {
    "project": { "key": "HR" },
    "issuetype": { "name": "Leave Request" },
    "summary": "{{title}}",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [{
        "type": "paragraph",
        "content": [{ "type": "text", "text": "{{description}}" }]
      }]
    },
    "customfield_10001": "{{fields.request_type}}",
    "customfield_10002": "{{fields.start_date}}",
    "customfield_10003": "{{fields.end_date}}",
    "customfield_10004": "{{fields.is_paid}}",
    "customfield_10005": "{{fields.employee_name}}",
    "reporter": { "emailAddress": "{{user.email}}" }
  }
}

3. Configure the webhook

• URL: https://your-domain.atlassian.net/rest/api/3/issue
• Bearer token: Your Jira API token (Base64 encoded email:token)
• Custom header: X-Atlassian-Token: no-check

4. Send a test event, then go live

Click Send test event and confirm a 201 response from Jira. Enable Actions for the group. Employees can now submit leave requests directly from Teams or Google Chat.

8.7 Example — IT Request to ServiceNow

This example creates an incident in ServiceNow when an employee reports an IT issue.

1. Create the template

• Display name: IT Support Request
• Slug: it_request
• Fields: issue_description (Always ask), urgency (Required — low / medium / high), affected_system (Ask if known), employee_name (Auto-fill name)

2. JSON payload

{
  "records": [{
    "short_description": "{{title}}",
    "description": "{{description}}\n\nIssue: {{fields.issue_description}}\nAffected system: {{fields.affected_system}}",
    "urgency": "{{fields.urgency}}",
    "caller_id": "{{user.email}}",
    "category": "software",
    "subcategory": "{{intent}}",
    "u_source": "ChatGridAI ({{platform}})",
    "u_chatgridai_id": "{{action_id}}"
  }]
}

3. Configure the webhook

• URL: https://your-instance.service-now.com/api/now/table/incident
• Bearer token: ServiceNow Basic Auth token (Base64 user:password) or OAuth token
• Custom headers: Accept: application/json and Content-Type: application/json

8.8 Example — Generic REST API / Custom Endpoint

If you have your own internal system or want to use a middleware like Zapier, Make, or n8n, use a generic webhook setup. This is the most flexible option.

1. Create the template

Define whatever fields make sense for your use case. The JSON payload can be any valid JSON structure — nested objects, arrays, flat key/value pairs.

2. Minimal payload (everything available)

{
  "event": "{{event_type}}",
  "id": "{{action_id}}",
  "submitted_at": "{{timestamp}}",
  "platform": "{{platform}}",
  "group": "{{group.name}}",
  "user": {
    "email": "{{user.email}}",
    "name": "{{user.name}}"
  },
  "request": {
    "type": "{{intent}}",
    "title": "{{title}}",
    "description": "{{description}}",
    "fields": {
      "field_one": "{{fields.field_one}}",
      "field_two": "{{fields.field_two}}"
    }
  }
}

3. Using with Zapier / Make / n8n

Point the webhook URL at your Zapier Catch Hook, Make webhook module, or n8n Webhook node. ChatGridAI sends the payload; your automation tool handles routing it to Slack, email, Google Sheets, or any downstream system. Use the signing secret to verify requests are genuine before processing them.

4. Verifying the signature (Node.js example)

const crypto = require('crypto');

function verifySignature(req, secret) {
  const timestamp = req.headers['x-chatgridai-timestamp'];
  const signature = req.headers['x-chatgridai-signature'];
  const body = req.rawBody; // raw string, not parsed

  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${body}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}