# ConnectGain Documentation — full corpus
> Machine-readable concatenation of every page on https://docs.connectgain.cloud/ for LLM / AI-assistant ingestion. Curated index: https://docs.connectgain.cloud/llms.txt


---

# ConnectGain Documentation — Omnichannel Inbox, CRM & Automation

Source: https://docs.connectgain.cloud/

# ConnectGain Documentation

**ConnectGain** unifies every customer conversation — WhatsApp, Messenger, Instagram, Telegram, TikTok, LinkedIn, Shopify Inbox and Email — into a single inbox, with a full CRM, sales pipeline, project management, visual [bot flows](https://docs.connectgain.cloud/02-user-guide/bot-flows.md), drip sequences, AI automation, call intelligence, scheduling and analytics on top.

This is the official documentation: how to **use**, **administer**, **integrate** and **build on** the platform.

<div class="cg-hero-actions" markdown="1">

[Open the app:material-arrow-top-right:](https://dashboard.connectgain.cloud){.md-button target="_blank" rel="noopener" }
[Quick Start:material-rocket-launch:](https://docs.connectgain.cloud/01-getting-started/quick-start.md){.md-button }
[REST API:material-api:](https://docs.connectgain.cloud/07-api/README.md){.md-button }

</div>

---

## Start here

<div class="cg-start-cards" markdown="1">
-:material-rocket-launch: **[Getting Started](https://docs.connectgain.cloud/01-getting-started/README.md)** — First steps, product tour, and onboarding for new accounts

-:material-book-open-variant: **[User Guide](https://docs.connectgain.cloud/02-user-guide/README.md)** — Inbox, Contacts, Deals, Tasks, Campaigns, Bot Flows, Sequences, AI Re-Engagement, Call Intelligence and more

-:material-shield-account: **[Admin Guide](https://docs.connectgain.cloud/03-admin-guide/README.md)** — Settings, team management, permissions, invitations, authentication and billing

-:material-lightbulb-on: **[Use Cases](https://docs.connectgain.cloud/04-use-cases/README.md)** — Industry scenarios, the feature fact sheet, and automation recipes

-:material-connection: **[Integrations](https://docs.connectgain.cloud/05-integrations/README.md)** — WhatsApp, Messenger, Instagram, Telegram, TikTok, LinkedIn, Shopify, Email and Zoom

-:material-api: **[REST API](https://docs.connectgain.cloud/07-api/README.md)** — API keys, complete REST reference, Mobile & Bot Control APIs, Postman collection

-:material-webhook: **[Webhooks](https://docs.connectgain.cloud/08-webhooks/overview.md)** — Outbound HMAC-signed events for conversations, contacts, deals and more
</div>

---

## What ConnectGain does

| Area | Capabilities |
|---|---|
| **Conversations** | Unified inbox, message templates, channel management across 9 messaging channels + push |
| **CRM** | Contacts, companies, deals (kanban pipeline), tasks, notes, activity timelines |
| **Marketing** | Broadcast campaigns, drip sequences, social media planner |
| **Automation & AI** | Visual bot flows, rule-based automations, AI re-engagement, RAG chatbot, intent classification |
| **Telephony** | SIP softphone, AI call intelligence (transcription, diarization, sentiment, compliance, QA) |
| **Scheduling** | Calendar, bookings, Google Calendar & Zoom sync |
| **Insights** | Dashboards, analytics, sales reports |
| **Operations** | Projects, support tickets, attendance |
| **Developer** | REST API, outbound webhooks, API keys |

---

## Popular pages

- [Feature Fact Sheet](https://docs.connectgain.cloud/04-use-cases/marketing-fact-sheet.md) — the canonical list of everything ConnectGain does
- [Connect a channel](https://docs.connectgain.cloud/05-integrations/channels.md)
- [Live pricing on connectgain.cloud](https://connectgain.cloud/en/pricing)
- [API authentication](https://docs.connectgain.cloud/07-api/api-key-authentication.md) · [Webhooks overview](https://docs.connectgain.cloud/08-webhooks/overview.md)
- [Postman collection](https://docs.connectgain.cloud/07-api/postman.md)
- [FAQ](https://docs.connectgain.cloud/09-reference/faq.md) · [Glossary](https://docs.connectgain.cloud/09-reference/glossary.md) · [Troubleshooting](https://docs.connectgain.cloud/09-reference/troubleshooting.md)

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud)*

---

# Getting Started with ConnectGain – First Steps Guide

Source: https://docs.connectgain.cloud/01-getting-started/

# Getting Started

Welcome to ConnectGain! Read these in order.

1. **[Quick Start](https://docs.connectgain.cloud/01-getting-started/quick-start.md)** — sign up and send your first message.
2. **[Onboarding walkthrough](https://docs.connectgain.cloud/01-getting-started/onboarding.md)** — the in-app guided tour.

Looking for *what ConnectGain does*? See the canonical [Feature Fact Sheet](https://docs.connectgain.cloud/04-use-cases/marketing-fact-sheet.md) — every feature in one place.

Next: head to the [User Guide](https://docs.connectgain.cloud/02-user-guide/README.md) to learn each feature in depth.

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/index.md)*

---

# ConnectGain Onboarding Wizard – Account Setup Steps

Source: https://docs.connectgain.cloud/01-getting-started/onboarding/

# Onboarding Feature

## Overview

The Onboarding feature (`/onboarding`) provides a guided setup wizard for new users to configure their ConnectGain account. It ensures users complete essential setup steps including email verification, subscription selection, and optional channel configuration before accessing the platform. The onboarding process includes visual progress tracking and allows users to skip optional steps.

---

## Features

### 1. Onboarding Steps

**Step 1: Email Verification**
- Verify email address
- Email verification check
- Verification status indicator
- Verification instructions
- Cannot proceed without verification

**Step 2: Subscription**
- Choose subscription plan
- Plan selection
- Trial period information
- Plan comparison
- Subscribe button
- Redirect to Stripe checkout

**Step 3: Channel Setup**
- Connect messaging channels
- Channel connection
- Channel configuration
- Skip option available
- Optional step

### 2. Progress Tracking

**Visual Progress:**
- Progress indicators
- Step completion checkmarks
- Current step highlighting
- Progress bar

**Step Status:**
- Completed steps (green checkmark)
- Current step (blue circle)
- Pending steps (gray circle)

### 3. Email Verification Step

**Verification Features:**
- Email verification required
- Cannot proceed without verification
- Verification email sent automatically
- Resend verification option
- Verification status tracking

**Verification Process:**
1. User signs up
2. Verification email sent
3. User clicks verification link
4. Email verified
5. Can proceed to next step

### 4. Subscription Step

**Subscription Features:**
- Redirected to subscription plan selection
- Must select subscription plan
- Trial period available
- Cannot proceed without subscription
- Subscription activation required

**Subscription Process:**
1. After email verification
2. Redirected to subscription plan selection
3. Select plan
4. Complete checkout
5. Subscription activated
6. Can proceed to next step

### 5. Channel Setup

**Connected Channels:**
- Display connected channels
- Channel cards
- Channel status
- Channel actions (toggle, delete)

**Add Channels:**
- Connect new channels
- Add channel dialog
- Channel type selection
- Channel configuration
- OAuth integration (Facebook, Instagram)
- QR code authentication ([WhatsApp Lite](https://docs.connectgain.cloud/01-getting-started/05-integrations/whatsapp-lite-api.md))

**Skip Option:**
- Skip channel setup
- Skip button
- Optional step indication
- Continue without channels
- Can add channels later in Settings

### 6. Onboarding Completion

**Finish Setup:**
- Complete onboarding
- Finish button
- Onboarding completion tracking
- Redirect to dashboard

**Skip for Now:**
- Skip remaining steps
- Skip button
- Later completion option
- Access platform immediately

---

## Use Cases

### Use Case 1: New User Onboarding

**Scenario:**
New user signs up and completes onboarding.

**Steps:**
1. User signs up with email
2. Receives verification email
3. Clicks verification link
4. Email verified
5. Redirected to subscription plan selection
6. Selects subscription plan
7. Completes checkout
8. Redirected to onboarding page
9. Optionally connects channel
10. Clicks "Skip" or "Finish"
11. Access to platform granted

**Expected Outcome:**
User successfully onboarded and can access platform.

### Use Case 2: Skip Channel Setup

**Scenario:**
User wants to skip channel setup and add later.

**Steps:**
1. Complete email verification
2. Complete subscription
3. Reach channel setup step
4. Click "Skip for Now"
5. Onboarding marked complete
6. Access to platform granted
7. Can add channels later in Settings

**Expected Outcome:**
Onboarding completed without channels, can add later.

### Use Case 3: Connect Channel During Onboarding

**Scenario:**
User wants to connect channel immediately.

**Steps:**
1. Complete email verification
2. Complete subscription
3. Reach channel setup step
4. Click "Add Channel"
5. Select channel type
6. Complete channel configuration
7. Channel connected
8. Click "Finish"
9. Access to platform granted

**Expected Outcome:**
Channel connected and onboarding completed.

---

## API Integration

### Check Onboarding Status

**Endpoint:** `GET /rest/v1/profiles?id=eq.{user_id}`

**Response:**
```json
{
 "id": "user-uuid",
 "onboarding_completed": false,
 "email_confirmed": true
}
```

### Mark Onboarding Complete

**Endpoint:** `PATCH /rest/v1/profiles?id=eq.{user_id}`

**Request:**
```json
{
 "onboarding_completed": true
}
```

### Get Onboarding Progress

**Endpoint:** Custom logic based on:
- Email verification status
- Subscription status
- Channel count

---

## Best Practices

1. **Email Verification**
 - Verify email promptly
 - Check spam folder
 - Use accessible email
 - Resend if needed

2. **Subscription Selection**
 - Choose appropriate plan
 - Start with trial if available
 - Understand plan features
 - Can upgrade later

3. **Channel Setup**
 - Connect at least one channel
 - Use channels you'll actually use
 - Can add more later
 - Test channel connection

4. **Onboarding Completion**
 - Complete all steps
 - Don't skip unless necessary
 - Review setup before finishing
 - Access platform after completion

---

## Troubleshooting

### Email Verification Not Received

**Issue:** Verification email not arriving

**Solutions:**
- Check spam folder
- Verify email address correct
- Resend verification email
- Check email server status

### Cannot Proceed Past Verification

**Issue:** Stuck on verification step

**Solutions:**
- Verify email clicked
- Check verification status
- Refresh page
- Contact support

### Subscription Step Not Showing

**Issue:** Subscription step not appearing after email verification

**Solutions:**
- Verify email confirmed
- Check subscription status
- Refresh page
- Contact support if the subscription step still does not load

### Channel Setup Not Appearing

**Issue:** Channel step not showing

**Solutions:**
- Verify subscription active
- Check onboarding status
- Refresh page
- Verify step sequence

---

## Related Documentation

- [Quick Start](https://docs.connectgain.cloud/01-getting-started/onboarding/quick-start.md)
- [Profile management](https://docs.connectgain.cloud/01-getting-started/03-admin-guide/profile.md) — subscription tab and billing portal
- [Channels Feature](https://docs.connectgain.cloud/01-getting-started/05-integrations/channels.md)
- [Settings Feature](https://docs.connectgain.cloud/01-getting-started/03-admin-guide/settings.md)
- [API Documentation](https://docs.connectgain.cloud/01-getting-started/07-api/complete-api.md)

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/01-getting-started/index.md)*

---

# ConnectGain Quick Start – Send Your First Message in 5 Minutes

Source: https://docs.connectgain.cloud/01-getting-started/quick-start/

# Getting Started with ConnectGain

Welcome to ConnectGain! This guide will help you get up and running quickly.

---

## Table of Contents

1. [What is ConnectGain?](#what-is-connectgain)
2. [Quick Start (5 Minutes)](#quick-start-5-minutes)
3. [Setting Up Your Account](#setting-up-your-account)
4. [Connecting Your First Channel](#connecting-your-first-channel)
5. [Importing Contacts](#importing-contacts)
6. [Sending Your First Message](#sending-your-first-message)
7. [Next Steps](#next-steps)

---

## What is ConnectGain?

ConnectGain is a comprehensive customer engagement platform that:

- **Unifies messaging** across 9 channels — [WhatsApp Lite](https://docs.connectgain.cloud/01-getting-started/05-integrations/whatsapp-lite-api.md), WhatsApp Cloud, Facebook Messenger, Instagram, Telegram, TikTok, Shopify Inbox, LinkedIn, and Email (SMS is available for broadcasts and sequences)
- **Manages customer relationships** with a complete CRM (contacts, companies, deals, tasks)
- **Automates workflows** with bot flows and automation rules
- **Runs campaigns** with broadcast messaging and scheduling
- **Provides analytics** with real-time metrics and insights
- **Enables team collaboration** with role-based access control

---

## Quick Start (5 Minutes)

### Step 1: Sign Up

1. Navigate to the ConnectGain sign-up page
2. Enter your email address and create a password
3. Verify your email address
4. Complete the onboarding flow

### Step 2: Create Your Organization

1. Enter your organization name
2. Select your timezone
3. Choose your currency
4. Complete the setup

### Step 3: Connect a Channel

**For WhatsApp Lite (Recommended for Quick Start):**

1. Go to Settings → Channels
2. Click "Add Channel" → "WhatsApp Lite"
3. Follow the connection wizard
4. Click "Connect"

**For Other Channels:**

1. Go to Settings → Channels
2. Select your channel (Messenger, Instagram, etc.)
3. Follow the OAuth flow
4. Authorize ConnectGain

### Step 4: Import Contacts

**Option A: CSV Import**

1. Go to Contacts → Import
2. Download the CSV template
3. Fill in your contact data
4. Upload the CSV file
5. Review and confirm import

**Option B: Manual Entry**

1. Go to Contacts
2. Click "New Contact"
3. Fill in contact details
4. Save

### Step 5: Send Your First Message

1. Go to Inbox
2. Select a conversation or create a new one
3. Type your message
4. Click "Send"

**Congratulations!** You're now using ConnectGain.

---

## Setting Up Your Account

### Profile Setup

1. **Go to Profile** (top right → Your Name → Profile)
2. **Update your information:**
 - First Name
 - Last Name
 - Avatar (optional)
 - Timezone
 - Language preferences

### Organization Settings

1. **Go to Settings → Organization**
2. **Configure:**
 - Organization name
 - Default timezone
 - Default currency
 - Business hours
 - Notification preferences

### Team Setup (Optional)

1. **Go to Settings → Team**
2. **Invite team members:**
 - Enter email addresses
 - Assign roles (OWNER, ADMIN, AGENT, PROJECT_MANAGER, TEAM_ADMIN)
 - Send invitations
3. **Set permissions** for each role

---

## Connecting Your First Channel

### WhatsApp Lite (AppGain)

**Prerequisites:**
- AppGain account (ConnectGain provisions credentials automatically when you connect)

**Steps:**

1. Go to **Settings → Channels**
2. Click **"Add Channel"**
3. Select **"WhatsApp Lite"**
4. Follow the connection wizard and scan the QR code when prompted
5. Verify connection status (should show "Connected")

**Testing:**

1. Send a test message to your WhatsApp number
2. Check the Inbox - you should see the message appear
3. Reply from ConnectGain - the message should be delivered

### WhatsApp Cloud (Meta)

**Prerequisites:**
- Meta Business Account
- WhatsApp Business API access
- Access Token and Phone Number ID

**Steps:**

1. Go to **Settings → Channels**
2. Click **"Add Channel"**
3. Select **"[WhatsApp Cloud](https://docs.connectgain.cloud/01-getting-started/05-integrations/whatsapp-cloud-system-user.md)"**
4. Enter:
 - Access Token
 - Phone Number ID
 - Business Account ID (optional)
5. Click **"Connect"**
6. Configure webhook URL in Meta Developer Console

**Webhook Setup:**

1. Copy webhook URL: `https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-cloud-webhook`
2. Go to Meta Developer Console → Webhooks
3. Paste webhook URL
4. Subscribe to `messages` events
5. Verify webhook

### Facebook Messenger

**Steps:**

1. Go to **Settings → Channels**
2. Click **"Add Channel"**
3. Select **"Facebook Messenger"**
4. Click **"Connect with Facebook"**
5. Authorize ConnectGain
6. Select your Facebook Page
7. Complete setup

### Instagram Direct Messages

**Steps:**

1. Go to **Settings → Channels**
2. Click **"Add Channel"**
3. Select **"Instagram"**
4. Click **"Connect with Facebook"** (Instagram uses Facebook OAuth)
5. Authorize ConnectGain
6. Select your Instagram Business Account
7. Complete setup

### Telegram

**Steps:**

1. Create a Telegram Bot via @BotFather
2. Get your Bot Token
3. Go to **Settings → Channels**
4. Click **"Add Channel"**
5. Select **"Telegram"**
6. Enter your Bot Token
7. Click **"Connect"**
8. Configure webhook URL

---

## Importing Contacts

### CSV Import

**Supported Fields:**

- First Name, Last Name
- Email, Phone Number, Mobile Phone Number
- Company Name, Job Title
- Address (Street, City, State, Postal Code, Country)
- Lead Status, Lifecycle Stage
- Custom Fields

**Steps:**

1. Go to **Contacts → Import**
2. Click **"Import Contacts"**
3. Download CSV template (optional)
4. Prepare your CSV file with contact data
5. Upload CSV file
6. Map columns (if needed)
7. Review preview
8. Click **"Import"**
9. Review import results

**CSV Format Example:**

```csv
First Name,Last Name,Email,Phone Number,Company name,City,Country/Region
John,Doe,john@example.com,+1234567890,Acme Inc,New York,US
Jane,Smith,jane@example.com,+1987654321,Tech Corp,San Francisco,US
```

### Kommo CRM Import

**Steps:**

1. Go to **Contacts → Import**
2. Click **"Import from Kommo"**
3. Upload Kommo export CSV
4. Map fields
5. Review and import

### Manual Entry

**Steps:**

1. Go to **Contacts**
2. Click **"New Contact"**
3. Fill in:
 - Name (First, Last)
 - Phone numbers
 - Email addresses
 - Company (optional)
 - Tags (optional)
 - Custom fields (optional)
4. Click **"Save"**

### Bulk Actions

After importing, you can:

- **Tag contacts** - Select multiple contacts and add tags
- **Assign contacts** - Assign to team members
- **Create deals** - Convert contacts to deals
- **Export contacts** - Download as CSV

---

## Sending Your First Message

### From Inbox

1. **Go to Inbox**
2. **Select a conversation** or click "New Conversation"
3. **If new conversation:**
 - Select a contact
 - Select a channel
 - Start typing
4. **Type your message**
5. **Optional:**
 - Add emoji
 - Attach file/image
 - Use quick reply template
6. **Click "Send"**

### From Contact Details

1. **Go to Contacts**
2. **Click on a contact**
3. **Click "Send Message"**
4. **Select channel**
5. **Type and send**

### Using Templates

1. **Go to Templates**
2. **Create a template** or use existing
3. **Go to Inbox**
4. **Select conversation**
5. **Click "Templates"**
6. **Select template**
7. **Customize variables** (if any)
8. **Send**

### Quick Replies

1. **Go to Settings → Quick Replies**
2. **Create quick reply templates**
3. **In Inbox:**
 - Type `/` to see quick replies
 - Select a quick reply
 - Customize and send

---

## Next Steps

### 1. Explore Features

- **[Dashboard](https://docs.connectgain.cloud/01-getting-started/02-user-guide/dashboard.md)** - View metrics and insights
- **[Contacts](https://docs.connectgain.cloud/01-getting-started/02-user-guide/contacts.md)** - Manage your contact database
- **[Deals](https://docs.connectgain.cloud/01-getting-started/02-user-guide/deals.md)** - Track sales pipeline
- **[Tasks](https://docs.connectgain.cloud/01-getting-started/02-user-guide/tasks.md)** - Manage tasks and reminders

### 2. Set Up Automation

- **[Bot Flows](https://docs.connectgain.cloud/01-getting-started/02-user-guide/bot-flows.md)** - Create automated chatbots
- **[Automation Rules](https://docs.connectgain.cloud/01-getting-started/02-user-guide/automations.md)** - Set up workflow automation

### 3. Launch Campaigns

- **[Campaigns](https://docs.connectgain.cloud/01-getting-started/02-user-guide/campaigns.md)** - Create broadcast campaigns
- **[Templates](https://docs.connectgain.cloud/01-getting-started/02-user-guide/templates.md)** - Create message templates

### 4. Configure Settings

- **[Channels](https://docs.connectgain.cloud/01-getting-started/05-integrations/channels.md)** - Manage channel connections
- **[Team](https://docs.connectgain.cloud/01-getting-started/03-admin-guide/team.md)** - Invite team members
- **[Webhooks](https://docs.connectgain.cloud/01-getting-started/08-webhooks/README.md)** - Set up integrations

### 5. Learn More

- **[Use Cases](https://docs.connectgain.cloud/01-getting-started/04-use-cases/README.md)** - Real-world examples
- **[API Documentation](https://docs.connectgain.cloud/01-getting-started/07-api/complete-api.md)** - Integrate via API
- **[API Overview](https://docs.connectgain.cloud/01-getting-started/07-api/overview.md)** - How the REST API is organized

---

## Common Tasks

### Daily Operations

- **Check Inbox** - Respond to customer messages
- **Update Deals** - Move deals through pipeline
- **Complete Tasks** - Mark tasks as done
- **Add Notes** - Document customer interactions

### Weekly Tasks

- **Review Analytics** - Check dashboard metrics
- **Update Contacts** - Keep contact data current
- **Review Campaigns** - Check campaign performance
- **Team Sync** - Review team activity

### Monthly Tasks

- **Export Reports** - Download analytics reports
- **Review Automation** - Optimize bot flows and rules
- **Update Templates** - Refresh message templates
- **Team Review** - Review team performance

---

## Need Help?

- **Documentation:** Browse this documentation site
- **FAQ:** Check [Frequently Asked Questions](https://docs.connectgain.cloud/01-getting-started/09-reference/faq.md)
- **Troubleshooting:** See [Troubleshooting Guide](https://docs.connectgain.cloud/01-getting-started/09-reference/troubleshooting.md)
- **Support:** Contact support team

---

**Ready to explore?** → [User Guide](https://docs.connectgain.cloud/01-getting-started/02-user-guide/README.md)

## On the website

- [Channels on connectgain.cloud](https://connectgain.cloud/en/channels) — feature overview on the ConnectGain website

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/01-getting-started/index.md)*

---

# ConnectGain User Guide – Inbox, CRM & Automation

Source: https://docs.connectgain.cloud/02-user-guide/

# User Guide

Daily-use guides for everyone working in ConnectGain. One page per feature.

## 💬 Conversations

- [Inbox](https://docs.connectgain.cloud/02-user-guide/inbox.md) — unified inbox across all channels
- [Messages](https://docs.connectgain.cloud/02-user-guide/messages.md) — sending, templates, media, replies
- [Templates](https://docs.connectgain.cloud/02-user-guide/templates.md) — saved replies and WhatsApp templates

## 👥 CRM

- [Contacts](https://docs.connectgain.cloud/02-user-guide/contacts.md) — contact database, tags, import, merge
- [Companies](https://docs.connectgain.cloud/02-user-guide/companies.md) — B2B company records linked to contacts and deals
- [Deals](https://docs.connectgain.cloud/02-user-guide/deals.md) — pipeline, drag-and-drop, ownership
- [Tasks](https://docs.connectgain.cloud/02-user-guide/tasks.md) — to-dos with due dates, priorities and calendar view

## 🤖 Automation & AI

- [Bot Flows](https://docs.connectgain.cloud/02-user-guide/bot-flows.md) — visual bot builder: every node, trigger & scenario
- [Multilingual Bot Flows](https://docs.connectgain.cloud/02-user-guide/multilingual-flows.md) — answer each customer in their language
- [Automations](https://docs.connectgain.cloud/02-user-guide/automations.md) — rule-based triggers
- [Sequences](https://docs.connectgain.cloud/02-user-guide/sequences.md) — drip campaigns
- [Campaigns](https://docs.connectgain.cloud/02-user-guide/campaigns.md) — broadcasts
- [AI Re-Engagement](https://docs.connectgain.cloud/02-user-guide/ai-reengagement.md) — bring stale chats back to life
- [Call Intelligence](https://docs.connectgain.cloud/02-user-guide/call-intelligence.md) — AI call analysis

## 📅 Scheduling

- [Scheduling](https://docs.connectgain.cloud/02-user-guide/scheduling.md) — event types, availability and calendar sync
- [Bookings](https://docs.connectgain.cloud/02-user-guide/bookings.md) — customer-facing booking pages and appointments

## 📊 Insights

- [Dashboard](https://docs.connectgain.cloud/02-user-guide/dashboard.md) — real-time widgets and performance metrics
- [Analytics](https://docs.connectgain.cloud/02-user-guide/analytics.md) — cross-feature reporting and trends
- [Sales Report](https://docs.connectgain.cloud/02-user-guide/sales-report.md) — pipeline and revenue reporting

## 🛠 Operations

- [Projects](https://docs.connectgain.cloud/02-user-guide/projects.md) — projects, milestones, deliverables and timelines
- [Support Tickets](https://docs.connectgain.cloud/02-user-guide/support-tickets.md) — Issues & Fixes inside Support projects
- [Attendance](https://docs.connectgain.cloud/02-user-guide/attendance.md) — work schedules and attendance tracking
- [Social Media Planner](https://docs.connectgain.cloud/02-user-guide/social-media-planner.md) — schedule posts across social channels

Admin-only topics (settings, team, permissions) live in the [Admin Guide](https://docs.connectgain.cloud/03-admin-guide/README.md).

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/index.md)*

---

# AI Re-Engagement for Messenger & Instagram – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/ai-reengagement/

# AI Re-Engagement Feature

## Overview

AI Re-Engagement uses AI to automatically re-open Messenger and Instagram conversations **before** Meta's 24-hour customer-service window closes. The system generates personalised, context-aware nudge messages that drive customer replies and keep conversations active.

- **Re-engagement monitor:** `/reengagement` — shows recent nudges sent, timestamps, reasons, and status.
- **Settings:** Settings → AI & Automation → **AI Re-Engagement** tab.

**Contents:** [Features](#features) · [Use Cases](#use-cases) · [Test Cases](#test-cases) · [Related Documentation](#related-documentation)

---

## Features

### 1. AI-Powered Nudge Generation

**Smart Drafting:**
- AI analyses conversation context, contact history, deal stage, and tags
- Generates personalised nudge messages per conversation
- Adapts tone based on settings (Friendly / Formal / Casual)
- References prior messages, products discussed, and open deals

**Context Awareness:**
- Reads last 10 messages for context
- Considers contact tags (e.g., `hot_lead`, `awaiting_customer`)
- Checks associated deal stage and value
- Incorporates contact name and preferences

### 2. Channel Support

**Supported Channels:**
- Facebook Messenger
- Instagram Direct

**Not Supported:**
- WhatsApp (uses approved templates separately)
- Telegram
- TikTok
- LinkedIn
- Email

### 3. Trigger Configuration

**Timing Controls:**
- Default trigger: 20 hours after customer's last message
- Configurable range: 12–23 hours
- Hard stop: never sends after `last_user_message_at + 24h`
- Respects Meta's 24-hour customer-service window

**Channel Selection:**
- Enable per channel (Messenger, Instagram, or both)
- Independent toggle per channel

### 4. Safety & Limits

**Rate Limiting:**
- Maximum 1 nudge per 24-hour window per conversation (DB-enforced)
- 3 consecutive unanswered nudges auto-disable re-engagement on that conversation
- Customer reply resets the counter and marks open nudges as `user_replied`
- Per-conversation kill switch in the inbox UI

**Opt-Out Compliance:**
- Automatically honours customer opt-outs
- Unsubscribe status checked before sending
- All nudges logged as `AI_REENGAGEMENT_SENT` activity events

### 5. Approval Mode

**Agent Review Workflow:**
- Optional **Require agent approval** setting
- AI drafts appear in inbox as review cards
- Actions per draft:
 - **Approve** — sends the AI-generated message
 - **Edit** — modify text before sending
 - **Skip** — reject draft, prevent another nudge for that window
- Editing replaces AI text and sends immediately

### 6. AI Provider Options

**ConnectGain AI (Default):**
- Powered by Gemini 2.5 Flash via Lovable AI Gateway

**BYOK — Bring Your Own Gemini Key (Free):**
- Use your own Google AI Studio [API key](https://docs.connectgain.cloud/02-user-guide/07-api/api-key-authentication.md)
- Key encrypted at rest, never returned to the browser
- Scope selection:
 - **All AI features** — chatbots, classification, translations, drafts, summaries, and re-engagement
 - **Re-engagement only**
- Fallback toggle: temporarily use ConnectGain AI if your key fails

### 7. Access Control

**Admin Controls:**
- OWNER / ADMIN: enable, configure, set BYOK
- AGENT: approve / edit / skip drafts (when approval mode is on)

### 8. Activity Logging

**Audit Trail:**
- Every nudge logged as `AI_REENGAGEMENT_SENT` activity event
- Draft status tracked: `draft`, `sent`, `user_replied`, `skipped`, `failed`
- Nudge drafts and outcomes retained 90 days, then anonymised
- PII scrubbed from Sentry breadcrumbs

---

## Use Cases

### Use Case 1: Abandoned Cart Recovery on Messenger

**Scenario:**
Online shopper asked about a product, was sent options, then went quiet.

**Setup:**
1. Go to Settings → AI & Automation → AI Re-Engagement
2. Toggle **Enable**
3. Set threshold to 20 hours
4. Enable Messenger channel
5. Set tone to **Friendly**
6. Save

**Expected Outcome:**
20 hours after the customer's last message, AI sends a personalised nudge like:
> Hi Sara — still thinking about the navy linen dress? I can hold your size for the next few hours if you'd like. Want me to send the checkout link?

**Expected Uplift:** +15–25% recovered carts on Meta DMs.

---

### Use Case 2: Instagram Lead Follow-Up

**Scenario:**
IG follower DM'd "info?" on a sponsored post but never replied after the agent answered.

**Setup:**
1. Enable AI Re-Engagement
2. Set threshold to 18 hours
3. Enable Instagram channel
4. Set tone to **Casual**
5. Turn on **Require agent approval** (for high-value leads)

**Expected Outcome:**
AI drafts a follow-up message:
> Hey Jamal 👋 just wanted to make sure you saw the pricing I sent. Happy to set up a quick call or share the demo link — whichever works?

Agent reviews and approves. Message sent before 24h window closes.

**Expected Uplift:** +30% qualified-lead conversion.

---

### Use Case 3: Real-Estate Inquiry Rescue

**Scenario:**
Buyer asked about a listing on Messenger then went silent. Conversation tagged `hot_lead`.

**Setup:**
1. Enable AI Re-Engagement
2. Set threshold to 22 hours
3. Enable Messenger
4. Set tone to **Formal**

**Expected Outcome:**
> Hi Ahmed — the 3-bedroom in Sheikh Zayed is still available, and there's a viewing slot tomorrow at 5pm. Want me to book it for you?

**Expected Uplift:** +20% viewing bookings.

---

### Use Case 4: Support Warm Reminder Before SLA Breach

**Scenario:**
Customer reported an issue, support replied, customer never confirmed resolution.

**Setup:**
1. Enable AI Re-Engagement
2. Set threshold to 21 hours
3. Tag conversation `awaiting_customer`
4. Set tone to **Friendly**

**Expected Outcome:**
> Hi Lina, just checking in — did the reset link I sent earlier solve the login issue? If not, I can hop on a quick call.

**Expected Uplift:** Fewer reopened tickets, higher CSAT.

---

### Use Case 5: Sequence Safety-Net on Meta

**Scenario:**
Contact mid-way through a Messenger drip sequence who stopped responding.

**Setup:**
1. Enable AI Re-Engagement alongside Sequences
2. Set threshold to 20 hours
3. Enable Messenger

**Expected Outcome:**
> Hey Omar — wanted to circle back on what we discussed. Any questions I can answer before our next step?

**Expected Uplift:** Recovers ~12% of dropped sequences without breaking Meta policy.

---

## Test Cases

### Test Case 1: Enable AI Re-Engagement

**Test:** Verify activation and first nudge

**Steps:**
1. Go to Settings → AI & Automation → AI Re-Engagement
2. Toggle **Enable**
3. Set threshold to 20 hours
4. Select Messenger channel
5. Choose Friendly tone
6. Save settings
7. Create a test conversation on Messenger
8. Wait 20 hours (or trigger test mode)
9. Verify AI nudge draft generated
10. Verify nudge sent (or appears for approval)

**Expected Result:**
AI Re-Engagement active; nudge generated and sent within configured window.

---

### Test Case 2: Agent Approval Workflow

**Test:** Verify approval mode

**Steps:**
1. Enable **Require agent approval**
2. Trigger a re-engagement scenario
3. Verify draft card appears in inbox
4. Click **Edit**, modify message text
5. Click **Send**
6. Verify custom message delivered
7. Trigger another scenario
8. Click **Skip**
9. Verify no nudge sent and window blocked

**Expected Result:**
Agent can edit, approve, or skip drafts. Skipped conversations blocked for that window.

---

### Test Case 3: BYOK Configuration

**Test:** Verify BYOK setup

**Steps:**
1. Get a key from Google AI Studio
2. Go to Settings → AI → AI Provider
3. Select **My Google Gemini key (BYOK)**
4. Paste key, pick model
5. Click **Test**
6. Set scope to **Re-engagement only**
7. Save
8. Trigger re-engagement
9. Verify nudge uses BYOK key

**Expected Result:**
BYOK configured; re-engagement uses org's own Gemini key.

---

### Test Case 4: 3-Strike Auto-Disable

**Test:** Verify safety limit

**Steps:**
1. Enable AI Re-Engagement
2. Find a conversation with 3 consecutive unanswered nudges
3. Verify conversation auto-paused (re-engagement disabled)
4. Verify manual re-enable required in inbox

**Expected Result:**
After 3 unanswered nudges, re-engagement auto-disabled on that conversation.

---

### Test Case 5: 24h Window Compliance

**Test:** Verify Meta policy compliance

**Steps:**
1. Create a Messenger conversation
2. Send customer message
3. Wait until 24h+1 minute after last customer message
4. Verify AI Re-Engagement does NOT send nudge
5. Verify log shows "Window expired"

**Expected Result:**
No nudge sent after 24-hour window. Compliance enforced.

---

## Related Documentation

- [AI Re-Engagement Fact Sheet](https://docs.connectgain.cloud/02-user-guide/04-use-cases/marketing-fact-sheet.md)
- [AI Re-Engagement Use Cases](https://docs.connectgain.cloud/02-user-guide/04-use-cases/ai-reengagement-use-cases.md)
- [AI Re-Engagement In-App Help](https://docs.connectgain.cloud/02-user-guide/04-use-cases/ai-reengagement-in-app-help.md)
- [Automation Rules](https://docs.connectgain.cloud/02-user-guide/ai-reengagement/automations.md)
- [Bot Flows](https://docs.connectgain.cloud/02-user-guide/ai-reengagement/bot-flows.md)
- [Inbox](https://docs.connectgain.cloud/02-user-guide/ai-reengagement/inbox.md)
- [ConnectGain AI chatbot overview](https://connectgain.cloud/en/ai-chatbot) — AI capabilities on the website
- [AI Re-Engagement on connectgain.cloud](https://connectgain.cloud/en/ai-reengagement) — feature overview on the ConnectGain website

---

**Document Version:** 1.0.0
**Last Updated:** June 2026

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Analytics & Reporting Dashboard – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/analytics/

# Analytics & Reporting Feature

## Overview

Analytics (`/analytics`) provides a reporting dashboard for performance insights. It offers metrics across inbox performance, [sales pipeline](https://docs.connectgain.cloud/02-user-guide/analytics/deals.md), contact growth, and team performance, with a time range selector (7 / 30 / 90 days).

**Contents:** [Features](#features) · [Use Cases](#use-cases) · [API Integration](#api-integration) · [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting)

---

## Features

### 1. Overview Metrics

> Note: Each overview card shows a small "% from last period" caption. This caption is a static placeholder label — it is not a computed period-over-period comparison, and there are no live trend arrows.

**Total Messages:**
- Message volume tracking for the selected period
- Large-number metric card display

**Average Response Time:**
- Team response performance tracking
- Hours format display (e.g. `2.5h`)
- Calculated from inbound→outbound message pairs

**SLA Compliance:**
- Service level agreement tracking
- Compliance percentage calculation
- Progress bar visualization

**Total Contacts:**
- Contact database size
- Metric card display

### 2. Time Range Selection

**Available Periods:**
- Last 7 days
- Last 30 days
- Last 90 days

(There is no custom date range picker.) Changing the range re-fetches and recalculates all metrics.

### 3. Tabbed Analytics

#### Inbox Tab

**Response Metrics:**
- Average response time
 - Calculated across all conversations
 - Team-wide average
 - Individual agent breakdown (if applicable)
- SLA compliance percentage
 - Target response time vs actual
 - Compliance rate calculation
 - Progress bars showing compliance level

**Conversation Status:**
- Resolved conversations count
 - Successfully closed conversations
 - Resolution rate
- Unassigned messages count
 - Messages awaiting assignment
 - Urgency indicators
- Overdue conversations count
 - Conversations past SLA deadline
 - Priority indicators
- Status indicators
 - Color-coded status badges
 - Visual status representation

#### Deals Tab

The Deals tab embeds the Sales Report (pipeline) view:
- Sales pipeline table with deals by stage
- Pipeline value and stage breakdown

There is no separate conversion-rate metric or funnel visualization on this tab.

#### Contacts Tab

**Contact Growth:**
- Total contacts in the database
- Large-number metric card

**Engagement Rate:**
- Contact engagement percentage display

> The "% change" caption shown here is a static placeholder, not a computed period-over-period value.

#### Performance Tab

**Task Completion:**
- Completed tasks count
 - Tasks finished in period
 - Completion rate tracking
- Total tasks count
 - All tasks in period
 - Task volume tracking
- Completion rate percentage
 - Overall completion rate
 - Per-assignee completion rates
- Progress bars
 - Visual completion indicators
 - Progress tracking

**Overall Performance:**
- Displays an overall grade label. This is a static label, not a computed multi-metric efficiency score.

### 4. Visual Analytics

**Progress Bars:**
- Visual progress indicators
- SLA compliance visualization
- Task completion visualization
- Color-coded progress (green/yellow/red)

**Metric Cards:**
- Key metric display
- Large numbers for readability
- Static "% from last period" caption (placeholder text, not a computed value)

**Status Indicators:**
- Visual status display
- Color-coded statuses
 - Green: Good performance
 - Yellow: Warning
 - Red: Critical
- Icon indicators
- Badge displays

### 5. Data Refresh

- Metrics are recalculated whenever the time range is changed or the page is reloaded.
- Data is not streamed in real time; there is no live cross-device synchronization on this page.

---

## Use Cases

### Use Case 1: Weekly Performance Review

**Scenario:**
Manager wants to review team performance for the past week.

**Steps:**
1. Navigate to Analytics page
2. Select "Last 7 days" time range
3. Review overview metrics:
 - Total messages received
 - Average response time
 - SLA compliance percentage
 - Contact growth
4. Check Inbox tab:
 - Review response metrics
 - Check conversation status
 - Identify overdue conversations
5. Review Deals tab:
 - Check the sales pipeline table
 - Review pipeline value and stage breakdown
6. Review Performance tab:
 - Check task completion rates
7. Identify areas for improvement

**Expected Outcome:**
Manager has comprehensive view of team performance and can identify improvement areas.

### Use Case 2: Monthly Business Review

**Scenario:**
Executive needs monthly business metrics for board meeting.

**Steps:**
1. Navigate to Analytics page
2. Select "Last 30 days" time range
3. Review all metrics across tabs
4. Prepare presentation with key insights

**Expected Outcome:**
Executive has all necessary metrics for business review presentation.

### Use Case 3: SLA Monitoring

**Scenario:**
Support manager monitors SLA compliance (refreshed on each visit / range change).

**Steps:**
1. Navigate to Analytics page
2. Select "Last 7 days" time range
3. Focus on Inbox tab
4. Monitor SLA compliance percentage
5. Check overdue conversations count
6. Review average response time
7. Take action on overdue items
8. Track improvement over time

**Expected Outcome:**
Support manager maintains SLA compliance and improves response times.

---

## API Integration

### Get Analytics Metrics

**Endpoint:** `GET /rest/v1/analytics/metrics`

**Query Parameters:**
- `organization_id` - Filter by organization
- `start_date` - Start date for period
- `end_date` - End date for period
- `metric_type` - Type of metric (messages, response_time, sla, contacts)

**Response:**
```json
{
 "metrics": {
 "total_messages": 1250,
 "average_response_time": "2.5 hours",
 "sla_compliance": 95.5,
 "total_contacts": 5420,
 "period_comparison": {
 "messages_change": 12.5,
 "response_time_change": -5.2,
 "sla_change": 2.1,
 "contacts_change": 8.3
 }
 }
}
```

### Get Inbox Analytics

**Endpoint:** `GET /rest/v1/analytics/inbox`

**Query Parameters:**
- `organization_id` - Filter by organization
- `start_date` - Start date
- `end_date` - End date

**Response:**
```json
{
 "inbox_metrics": {
 "average_response_time": "2.5 hours",
 "sla_compliance": 95.5,
 "resolved_conversations": 450,
 "unassigned_messages": 12,
 "overdue_conversations": 5
 }
}
```

### Get Deals Analytics

**Endpoint:** `GET /rest/v1/analytics/deals`

**Query Parameters:**
- `organization_id` - Filter by organization
- `start_date` - Start date
- `end_date` - End date

**Response:**
```json
{
 "deals_metrics": {
 "active_deals_count": 125,
 "pipeline_value": 2500000,
 "conversion_rate": 25.5,
 "stage_distribution": {
 "lead": 30,
 "qualified": 25,
 "proposal": 20,
 "negotiation": 15,
 "closed_won": 35
 }
 }
}
```

---

## Best Practices

1. **Regular Monitoring**
 - Check analytics daily for key metrics
 - Review weekly for trends
 - Analyze monthly for strategic insights

2. **Compare Ranges Manually**
 - Switch between 7 / 30 / 90-day ranges to spot trends
 - Look at absolute numbers across ranges (the on-card "% change" caption is a placeholder)

3. **Action-Oriented**
 - Use analytics to drive actions
 - Set targets based on metrics
 - Track progress toward goals

4. **Team Performance**
 - Review individual performance metrics
 - Provide feedback based on data
 - Recognize top performers

5. **SLA Management**
 - Monitor SLA compliance closely
 - Address overdue conversations immediately
 - Set realistic SLA targets

---

## Troubleshooting

### Metrics Not Updating

**Issue:** Analytics metrics not reflecting latest data

**Solutions:**
- Refresh the page
- Check date range selection
- Verify data exists for selected period
- Check organization filter

### Incorrect Calculations

**Issue:** Metrics showing incorrect values

**Solutions:**
- Verify date range is correct
- Check organization filter
- Review source data
- Contact support if issue persists

### Performance Issues

**Issue:** Analytics page loads slowly

**Solutions:**
- Reduce date range
- Check internet connection
- Clear browser cache
- Try different browser

---

## Related Documentation

- [Dashboard Feature](https://docs.connectgain.cloud/02-user-guide/analytics/dashboard.md)
- [API Documentation](https://docs.connectgain.cloud/02-user-guide/07-api/complete-api.md)
- [Developer Guide](https://docs.connectgain.cloud/02-user-guide/07-api/README.md)
- [Analytics on connectgain.cloud](https://connectgain.cloud/en/analytics) — feature overview on the ConnectGain website

---

**Last Updated:** February 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Agent Attendance Tracking & Online Status – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/attendance/

# Attendance Tracking Feature

## Overview

The Attendance feature (`/attendance`) provides comprehensive tracking of agent attendance, online status, and clock in/out times. This feature is essential for team management, ensuring proper coverage, and monitoring agent availability.

**Access Level:** Admin/Owner only

**Status:** Production Ready

**Last Updated:** January 2025

---

## Features

### 1. Online Agents Panel

**Real-Time Online Status:**
- Live tracking of all online agents in the organization
- Online agent count badge
- Real-time updates via WebSocket subscriptions
- Automatic refresh every 60 seconds
- Debounced updates to prevent excessive queries

**Agent Information Display:**
- Agent name and email
- Profile avatars with initials fallback
- Green status indicators for online agents
- Time-ago formatting for last seen timestamps
- Visual online status indicators

**Performance Optimizations:**
- Throttled fetching (max once per 5 seconds)
- Debounced real-time updates (2 second delay)
- Efficient database queries
- Optimized for large teams

### 2. Attendance History Table

**Comprehensive Attendance Records:**
- Complete clock in/out tracking
- Hours worked calculation
- Status indicators (ACTIVE/COMPLETED)
- Agent information display
- Timestamp formatting

**Advanced Filtering:**
- Search by agent name or email
- Filter by status (All, Active, Completed)
- Date range filtering:
 - Today
 - Last 7 days
 - Last 30 days
 - Last 90 days
- Real-time search functionality

**History Layout:**
- Collapsible tree grouped by agent → day → session (expand to drill in)
- No page-based navigation; the tree loads the filtered range

**Bulk Delete:**
- "Clear Records" / "Delete Filtered" to remove attendance records (cannot be undone)

**Data Display:**
- Formatted dates (MMM d, yyyy)
- Formatted times (HH:mm)
- Duration in hours and minutes
- Status badges with color coding
- Agent contact information

### 3. Automatic Tracking

**Clock In/Out Automation:**
- Automatic clock in on user login
- Automatic clock out on user logout
- No manual intervention required
- Duration calculation automatic
- Status updates in real-time

**Database Integration:**
- Attendance logs stored in `attendance_logs` table
- Online status tracked in `profiles` table
- Last seen timestamp updates
- Automatic duration calculations

### 4. Access Control

**Role-Based Access:**
- Only ADMIN and OWNER roles can access
- Automatic redirect for unauthorized users
- Role-based permission checking
- Secure data isolation via RLS policies

**Organization-Level Data:**
- Only shows attendance for organization members
- Secure data isolation
- Multi-tenant support
- Privacy protection

---

## Database Schema

### attendance_logs Table

```sql
- id: UUID (primary key)
- user_id: UUID (foreign key to auth.users)
- organization_id: UUID (foreign key to organizations)
- clock_in_at: TIMESTAMP WITH TIME ZONE
- clock_out_at: TIMESTAMP WITH TIME ZONE (nullable)
- created_at: TIMESTAMP WITH TIME ZONE
- updated_at: TIMESTAMP WITH TIME ZONE
```

### profiles Table (Extended)

```sql
- is_online: BOOLEAN (default: false)
- last_seen_at: TIMESTAMP WITH TIME ZONE
```

### attendance_summary View

Provides easy access to attendance data with calculated fields:
- Hours worked calculation
- Status determination (ACTIVE/COMPLETED)
- Agent information join
- Optimized for reporting

---

## Usage

### Viewing Attendance

1. Navigate to **Attendance** in the sidebar (Admin/Owner only)
2. View **Online Agents Panel** on the left:
 - See all currently online agents
 - Monitor real-time status
 - View last seen timestamps
3. View **Attendance History Table** on the right:
 - Browse attendance records
 - Filter by date range
 - Search by agent name
 - Filter by status

### Filtering Attendance Records

1. **Search:** Enter agent name or email in search box
2. **Status Filter:** Select status (All, Active, Completed)
3. **Date Range:** Select period (Today, Last 7/30/90 days)
4. **Refresh:** Click refresh button to update data

### Understanding Status

- **ACTIVE:** Agent is currently clocked in (no clock_out_at)
- **COMPLETED:** Agent has clocked out (clock_out_at exists)

---

## Security

### Row Level Security (RLS)

- Agents can view their own attendance logs
- Admins/Owners can view all attendance logs in organization
- Service role has full access for automation
- Secure data isolation per organization

### Privacy

- Attendance data is organization-scoped
- No cross-organization data access
- Secure authentication required
- Audit trail maintained

---

## Benefits

1. **Automatic Tracking:** No manual entry required
2. **Real-Time Visibility:** See who's online instantly
3. **Historical Reporting:** Complete attendance history
4. **Manager Oversight:** Track team attendance patterns
5. **Compliance:** Maintain accurate attendance records
6. **Performance Insights:** Analyze attendance patterns

---

## Best Practices

1. **Regular Monitoring:** Check attendance dashboard daily
2. **Filter Usage:** Use date range filters for specific periods
3. **Status Checks:** Monitor active sessions regularly
4. **Export Data:** Use attendance data for payroll/HR systems
5. **Team Communication:** Share attendance insights with team

---

## Troubleshooting

**"No attendance records showing"**
- Check date range filter
- Verify user has clocked in
- Ensure correct organization selected

**"Online status not updating"**
- Check real-time subscription
- Refresh the page
- Verify user is logged in

**"Can't access attendance page"**
- Verify user has ADMIN or OWNER role
- Check organization permissions
- Contact system administrator

---

## Related Documentation

- [Team Management](https://docs.connectgain.cloud/02-user-guide/03-admin-guide/team.md)
- [Settings](https://docs.connectgain.cloud/02-user-guide/03-admin-guide/settings.md)
- [Dashboard](https://docs.connectgain.cloud/02-user-guide/attendance/dashboard.md)
- [Attendance on connectgain.cloud](https://connectgain.cloud/en/attendance) — feature overview on the ConnectGain website

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Automation Rules – Trigger-Based Workflows – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/automations/

# Automation Rules Feature

## Overview

Automation Rules (`/automations`) enable businesses to automate workflows based on triggers and conditions. This rule-based automation system triggers actions based on events and conditions, allowing businesses to streamline operations and improve efficiency.

**Contents:**

- [Features](#features) — rules, trigger events, management, execution
- [Conditional Logic Details](#conditional-logic-details) — fields, operators, actions
- [Use Cases](#use-cases)
- [Test Cases](#test-cases)
- [API Integration](#api-integration)
- [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting)

---

## Features

### 1. Automation Rules

**Create Automations:**
- Build automation rules with:
 - Rule name
 - Description
 - Trigger event
 - Conditions
 - Actions
 - Active/inactive status

**Edit Automations:**
- Update automation rules

**Delete Automations:**
- Remove automation rules

**Enable/Disable:**
- Toggle automation status
- Active automations run automatically
- Inactive automations are paused

### 2. Trigger Events

**Message Events:**
- Message received
- Message sent
- Message failed

**Contact Events:**
- Contact created
- Contact updated
- Contact tag updated
- Contact lifecycle updated
- Contact assigned

**Deal Events:**
- Deal created
- Deal updated
- Deal stage changed
- Deal assigned

**Conversation Events:**
- Conversation created
- Conversation assigned
- Conversation status changed

**Task Events:**
- Task created
- Task completed
- Task overdue

**Broadcast & Social Events:**
- Broadcast response
- Comment added
- Facebook comment received

**Call & Meeting Events:**
- Call ended
- Zoom recording completed

### 3. Automation Management

**Rule List:**
- View all automation rules
- Table view (desktop)
- Card view (mobile)
- Status indicators
- Trigger icons
- Action counts

**Rule Details:**
- View rule configuration
- Full rule definition
- Execution history
- Success/failure rates

**Bulk Operations:**
- Manage multiple rules
- Bulk enable/disable
- Bulk delete

### 4. Automation Execution

**Real-Time Execution:**
- Immediate rule execution
- Event-driven triggers
- Instant action execution

**Execution Logging:**
- Track rule executions
- Execution history
- Success/failure tracking
- Error messages

**Error Handling:**
- Handle execution errors
- Error notifications
- Retry logic
- Fallback actions

### 5. Pagination

**50 Automations Per Page:**
- Efficient loading
- Page navigation

---

## Conditional Logic Details

**Condition Fields:**

**Message Fields:**
- Message content
- Contact ID
- Channel type (WHATSAPP_LITE, WHATSAPP_CLOUD, FB_MESSENGER, INSTAGRAM, TELEGRAM, TIKTOK, SHOPIFY_INBOX, BULK_EMAIL, LINKEDIN)
- Channel name (specific channel account)

**Contact Fields:**
- First name
- Last name
- Email addresses
- Phone numbers

**Deal Fields:**
- Deal title
- Deal stage
- Deal value
- Old stage (for stage changes)
- New stage (for stage changes)

**Conversation Fields:**
- Conversation status
- Contact ID
- Channel type
- Channel name

**Time Fields:**
- Organization time (with timezone)
- Time-based conditions (before, after, between)
- Days of week selection (Sunday-Saturday)

**Operators:**

**Text Operators:**
- Equals
- Contains
- Starts with
- Ends with
- Not equals

**Numeric Operators:**
- Equals
- Greater than
- Less than
- Not equals

**Time Operators:**
- Between (time range)
- Before (specific time)
- After (specific time)

**Special Operators:**
- Channel type selection (dropdown)
- Channel name selection (dropdown)
- Days of week (multi-select checkboxes)

**Time Conditions:**
- Time-based conditions
- Days of week selection
- Time range filtering

### 1. Conditions

**Field Conditions:**
- Check field values
- Equals, Contains, Starts with, Ends with
- Not equals, Greater than, Less than

**Time Conditions:**
- Time-based conditions
- Current time (organization timezone)
- Between times, Before time, After time
- Days of week selection

**Channel Conditions:**
- Channel-specific conditions
- Channel type matching
- Channel name matching

**Multiple Conditions:**
- Combine conditions
- AND logic, OR logic
- Complex condition groups

### 2. Actions

**Create Task:**
- Automatically create tasks
- Task title, description
- Priority (Low, Medium, High)
- Assignee (optional, auto-assign available)
- Due date (optional)

**Auto Assign Conversation:**
- Auto-assign conversations
- Round-robin assignment
- Availability-based assignment

**Auto Assign Task:**
- Auto-assign tasks
- Round-robin assignment
- Availability-based assignment

**Assign Conversation:**
- Assign to specific user
- User selection

**Add Tag:**
- Add tags to contacts
- Tag name
- Multiple tags

**Reply with Message:**
- Send automated replies
- Text message
- Quick reply template
- Variable substitution

**FB: Reply to Comment + Send DM (FB_COMMENT_REPLY_AND_DM):**
- Available on the "Facebook Comment Received" trigger
- Public reply to the comment
- Private DM to the commenter
- Optional @mention of the commenter

**HTTP Request:**
- Call external APIs
- GET, POST, PUT, PATCH, DELETE
- URL configuration
- Headers configuration
- Body configuration
- Response handling

### 3. Task Creation Action

**Task Configuration:**
- Task title (required)
- Task description
- Priority (LOW, MEDIUM, HIGH)
- Assignee selection
- Due date setting

### 4. Message Reply Action

**Reply Options:**
- **Text Message** - Send plain text message
- **Quick Reply Template** - Use pre-configured quick reply template
- Variable substitution support
- Template selection from available templates

**Reply Configuration:**
- Choose message type (text or template)
- Select quick reply template (if using template)
- Enter message text (if using text)
- Message sent automatically when trigger fires

### 5. HTTP Request Action

**HTTP Configuration:**
- URL (required)
- Method (GET, POST, PUT, PATCH, DELETE)
- Headers (key-value pairs)
- Body (key-value pairs)

### 6. Automation Management

**Management Features:**
- Create automation rules
- Edit existing rules (via edit dialog)
- Delete rules
- Enable/disable rules (toggle switch)
- View automation list
- Pagination support (50 items per page)
- Mobile-responsive table/card views
- Search and filter capabilities

**Automation List Views:**
- **Desktop View** - Table format with all details
- **Mobile View** - Card format optimized for mobile
- Status badges (Active/Paused)
- Trigger icons for visual identification
- Quick actions (Edit, Delete, Toggle)

### 7. Rule Status

**Status Types:**
- **Active** - Rule enabled and running
- **Inactive** - Rule disabled

---

## Use Cases

### Use Case 1: Auto-Assign New Conversations

**Scenario:**
Business wants to automatically assign new conversations to available agents.

**Steps:**
1. Go to Automations
2. Click "Create Automation"
3. Set trigger: "conversation.created"
4. Add action: "AUTO_ASSIGN_CONVERSATION"
5. Activate automation
6. Test by creating conversation
7. Verify conversation assigned

**Expected Outcome:**
New conversations automatically assigned to available agents.

### Use Case 2: Create Task on Deal Stage Change

**Scenario:**
Sales team wants task created when deal moves to "Negotiation" stage.

**Steps:**
1. Create automation
2. Set trigger: "deal.stage.changed"
3. Add condition: new_stage equals "Negotiation"
4. Add action: CREATE_TASK
5. Configure task:
 - Title: "Follow up on negotiation"
 - Priority: HIGH
 - Assignee: Sales Manager
6. Activate automation
7. Test by changing deal stage

**Expected Outcome:**
Task created automatically when deal reaches negotiation stage.

### Use Case 3: Auto-Reply to Messages

**Scenario:**
Business wants to send automatic reply to messages received outside business hours.

**Steps:**
1. Create automation
2. Set trigger: "message.received"
3. Add condition: org_time between 18:00 and 09:00
4. Add condition: days_of_week (Monday-Friday) - select checkboxes
5. Add action: REPLY_MESSAGE
6. Choose message type: Text Message
7. Configure message: "Thank you for your message. We'll respond during business hours."
8. Activate automation
9. Test by sending message outside hours

**Expected Outcome:**
Automatic reply sent to messages received outside business hours.

### Use Case 4: Reply with Quick Reply Template

**Scenario:**
Business wants to send automated reply using a quick reply template.

**Steps:**
1. Create automation
2. Set trigger: "message.received"
3. Add condition: content contains "hello"
4. Add action: REPLY_MESSAGE
5. Choose message type: Quick Reply Template
6. Select template from dropdown
7. Activate automation
8. Test by sending "hello" message

**Expected Outcome:**
Quick reply template sent automatically when "hello" detected.

### Use Case 5: Filter by Channel Type

**Scenario:**
Business wants different automations for different channels.

**Steps:**
1. Create automation for WhatsApp
2. Set trigger: "message.received"
3. Add condition: channel_type equals "WHATSAPP_LITE"
4. Add action: CREATE_TASK
5. Configure task for WhatsApp messages
6. Create separate automation for Messenger
7. Set condition: channel_type equals "FB_MESSENGER"
8. Configure different actions for Messenger

**Expected Outcome:**
Channel-specific automations working correctly.

### Use Case 6: Tag Contacts Based on Message Content

**Scenario:**
Business wants to tag contacts mentioning "complaint" as "Needs Attention".

**Steps:**
1. Create automation
2. Set trigger: "message.received"
3. Add condition: content contains "complaint"
4. Add action: ADD_TAG
5. Configure tag: "Needs Attention"
6. Activate automation

**Expected Outcome:**
Contacts automatically tagged when complaint mentioned.

### Use Case 7: Webhook Integration

**Scenario:**
Business wants to notify external system when high-value deal created.

**Steps:**
1. Create automation
2. Set trigger: "deal.created"
3. Add condition: value greater than 10000
4. Add action: HTTP_REQUEST
5. Configure:
 - URL: https://api.example.com/webhook
 - Method: POST
 - Headers: Authorization: Bearer token
 - Body: deal_id, value, contact_name
6. Activate automation

**Expected Outcome:**
External system notified when high-value deal created.

---

## Test Cases

### Test Case 1: Create Automation

**Test:** Verify automation creation

**Steps:**
1. Go to Automations
2. Click "Create Automation"
3. Enter rule name
4. Select trigger
5. Add action
6. Configure action
7. Activate automation
8. Save automation
9. Verify automation appears in list

**Expected Result:**
Automation created successfully

### Test Case 2: Conditional Logic

**Test:** Verify condition matching

**Steps:**
1. Create automation with condition
2. Set condition: message content contains "help"
3. Add action: CREATE_TASK
4. Activate automation
5. Send message with "help"
6. Verify task created
7. Send message without "help"
8. Verify task not created

**Expected Result:**
Conditions match correctly

### Test Case 3: Multiple Actions

**Test:** Verify multiple actions execution

**Steps:**
1. Create automation
2. Add multiple actions:
 - CREATE_TASK
 - ADD_TAG
 - REPLY_MESSAGE
3. Activate automation
4. Trigger automation
5. Verify all actions executed

**Expected Result:**
All actions executed in sequence

### Test Case 4: Time-Based Conditions

**Test:** Verify time condition matching

**Steps:**
1. Create automation
2. Set trigger: message.received
3. Add condition: org_time between 18:00 and 09:00
4. Add condition: days_of_week (Monday-Friday)
5. Add action: REPLY_MESSAGE
6. Activate automation
7. Test during specified time
8. Test outside specified time
9. Verify correct behavior

**Expected Result:**
Time conditions work correctly

### Test Case 5: Enable/Disable Automation

**Test:** Verify automation toggle

**Steps:**
1. Create active automation
2. Disable automation
3. Verify status changed
4. Trigger event
5. Verify automation not executed
6. Enable automation
7. Trigger event
8. Verify automation executed

**Expected Result:**
Enable/disable toggle works correctly

---

## API Integration

### Create Automation

**Endpoint:** `POST /rest/v1/automation_rules`

**Request:**
```json
{
 "organization_id": "org-uuid",
 "name": "Auto Assign Conversations",
 "trigger_type": "conversation.created",
 "conditions": [],
 "actions": [
 {
 "type": "AUTO_ASSIGN_CONVERSATION"
 }
 ],
 "is_active": true
}
```

### Update Automation

**Endpoint:** `PATCH /rest/v1/automation_rules/{id}`

**Request:**
```json
{
 "is_active": false
}
```

---

## Best Practices

1. **Automation Design**
 - Keep automations focused
 - Use clear naming
 - Test before activating
 - Document automation purpose

2. **Condition Logic**
 - Use specific conditions
 - Avoid overly broad conditions
 - Test condition matching
 - Use time conditions wisely

3. **Action Selection**
 - Choose appropriate actions
 - Configure actions completely
 - Test action execution
 - Monitor automation performance

4. **Performance**
 - Limit automation complexity
 - Use efficient conditions
 - Monitor execution time
 - Review automation logs

5. **Maintenance**
 - Review automations regularly
 - Update outdated automations
 - Disable unused automations
 - Monitor automation success rates

---

## Troubleshooting

### Automation Not Triggering

**Issue:** Automation not executing

**Solutions:**
- Check automation status (must be active)
- Verify trigger type matches event
- Check condition matching
- Review automation logs

### Actions Not Executing

**Issue:** Actions not performing

**Solutions:**
- Verify action configuration
- Check action requirements
- Review error logs
- Test actions individually

---

## Related Documentation

- [Bot Flows Feature](https://docs.connectgain.cloud/02-user-guide/automations/bot-flows.md)
- [Sequences (Drip Campaigns)](https://docs.connectgain.cloud/02-user-guide/automations/sequences.md)
- [Webhooks Feature](https://docs.connectgain.cloud/02-user-guide/08-webhooks/README.md)
- [API Documentation](https://docs.connectgain.cloud/02-user-guide/07-api/complete-api.md)
- [Automation on connectgain.cloud](https://connectgain.cloud/en/automation) — feature overview on the ConnectGain website

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Bookings Management & Calendar Sync – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/bookings/

# Bookings Management Feature

## Overview

The Bookings feature (`/bookings`) provides centralized management for appointments, meetings, and events with Google Calendar integration. This feature helps teams coordinate schedules, manage client appointments, and ensure proper calendar synchronization.

**Access Level:** All authenticated users

**Status:** Production Ready

**Last Updated:** January 2025

**Contents:** [Features](#features) · [Usage](#usage) · [Status Workflow](#status-workflow) · [Benefits](#benefits) · [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting)

---

## Features

### 1. Booking Creation

**Create New Bookings:**
- Title and description
- Contact association (from CRM)
- User assignment (team member)
- Start and end time selection
- Timezone support
- Location details
- Meeting link (Zoom, Google Meet, etc.)
- Status selection (scheduled, confirmed, cancelled, completed)

**Booking Form:**
- Date and time pickers
- Contact search and selection
- User dropdown
- Location input
- Meeting link input
- Status selector
- Validation and error handling

### 2. Booking Management

**Edit Bookings:**
- Update all booking fields
- Modify date and time
- Change contact assignment
- Update status
- Edit location and meeting links
- Save changes

**Delete Bookings:**
- Confirmation dialog
- Permanent deletion
- Calendar sync removal
- Contact notification (if applicable)

**Status Management:**
- Scheduled (default)
- Confirmed
- Rescheduled
- Cancelled
- Completed

### 3. Booking List View

**Comprehensive Table Display:**
- All bookings in organization
- Searchable content
- Filterable by status
- Responsive design

**Booking Information:**
- Title
- Contact name and email
- Date and time (formatted)
- Location
- Status badge
- Action menu

**Status Indicators:**
- Scheduled (outline badge)
- Confirmed (green badge)
- Rescheduled (yellow badge)
- Cancelled (red badge)
- Completed (secondary badge)

### 4. Search and Filtering

**Search Functionality:**
- Search by title
- Search by description
- Search by contact name
- Real-time filtering
- Case-insensitive search

**Status Filtering:**
- All statuses
- Scheduled only
- Confirmed only
- Cancelled only
- Completed only

**Date Filtering:**
- Upcoming bookings
- Past bookings
- Date range selection (future enhancement)

### 5. Google Calendar Integration

**Calendar Event Sync:**
- Automatic event creation
- Event updates on booking changes
- Event deletion on booking cancellation
- Google Calendar event ID tracking

**Quick Actions:**
- Open in Google Calendar (direct link)
- Join meeting (meeting link)
- View event details
- Sync status indicator

**Calendar Features:**
- Guest added as attendee
- Meeting link in description
- Reminders configured
- Timezone handling

### 6. Contact Integration

**Contact Association:**
- Link bookings to CRM contacts
- Contact picker with search
- Contact information display
- Contact name formatting
- Quick contact access

**Contact Benefits:**
- Unified contact view
- Booking history per contact
- Contact timeline integration
- Deal association (future)

### 7. User Assignment

**Team Member Assignment:**
- Assign bookings to users
- User selection dropdown
- User information display
- Multi-user support (future)
- Availability checking (future)

---

## Usage

### Creating a Booking

1. Navigate to **Bookings** page
2. Click **Create Booking** button
3. Fill in booking form:
 - Enter title and description
 - Select contact (optional)
 - Assign to team member
 - Set date and time
 - Add location or meeting link
 - Select status
4. Click **Save**
5. Booking created and calendar synced (if Google Calendar connected)

### Managing Bookings

1. **View Bookings:** Browse all bookings in table
2. **Search:** Use search box to find specific bookings
3. **Filter:** Filter by status using dropdown
4. **Edit:** Click action menu > Edit
5. **Delete:** Click action menu > Delete (with confirmation)
6. **View Calendar:** Click "Open in Google Calendar" (if synced)

### Google Calendar Actions

1. **Open Event:** Click "Open in Google Calendar" from action menu
2. **Join Meeting:** Click "Join Meeting" if meeting link exists
3. **Sync Status:** Check if booking has calendar event ID

---

## Status Workflow

### Scheduled → Confirmed
- Booking is confirmed
- Calendar event updated
- Contact notified (if applicable)

### Confirmed → Completed
- Meeting completed
- Status updated
- Notes can be added
- Follow-up tasks created

### Any Status → Cancelled
- Booking cancelled
- Calendar event removed/updated
- Contact notified
- Slot freed up

---

## Benefits

1. **Centralized Management:** All bookings in one place
2. **Calendar Sync:** Automatic Google Calendar integration
3. **Contact Integration:** Link bookings to CRM contacts
4. **Status Tracking:** Monitor booking lifecycle
5. **Team Coordination:** Assign bookings to team members
6. **Conflict Prevention:** See all bookings at once

---

## Best Practices

1. **Consistent Naming:** Use clear, descriptive titles
2. **Contact Association:** Always link to contacts when possible
3. **Status Updates:** Keep status current
4. **Calendar Sync:** Ensure Google Calendar is connected
5. **Meeting Links:** Add meeting links for virtual meetings
6. **Regular Review:** Check bookings regularly

---

## Troubleshooting

**"Booking not syncing to Google Calendar"**
- Verify Google Calendar connection
- Check calendar permissions
- Re-authorize calendar access
- Check for error messages

**"Can't find contact"**
- Verify contact exists in CRM
- Check contact search
- Ensure correct organization
- Create contact if needed

**"Booking not showing"**
- Check status filter
- Verify date range
- Check search terms
- Refresh the page

---

## Related Documentation

- [Scheduling](https://docs.connectgain.cloud/02-user-guide/bookings/scheduling.md) - Public booking pages
- [Contacts](https://docs.connectgain.cloud/02-user-guide/bookings/contacts.md) - Contact management
- [Settings](https://docs.connectgain.cloud/02-user-guide/03-admin-guide/settings.md) - Calendar integration setup
- [Bookings on connectgain.cloud](https://connectgain.cloud/en/bookings) — feature overview on the ConnectGain website

---

## Future Enhancements

- Recurring bookings
- Group bookings
- Booking reminders
- SMS notifications
- Payment integration
- Booking analytics
- Availability checking
- Conflict detection

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Bot Flows & Bot Builder – Visual Chatbot Builder – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/bot-flows/

# Bot Flows — Visual Chatbot Builder

Bot Flows (`/flows`) is ConnectGain's visual **bot builder**: a drag-and-drop canvas for automated conversation flows across WhatsApp and every other channel. With 37+ node types and a rich set of triggers, flows can answer inquiries, collect information, create deals and tasks, move contacts through lifecycle stages, call external APIs, run AI/RAG answering, log to spreadsheets, and hand off to a human agent when needed.

> New here? Skim **[Concepts](#concepts)** → **[The builder UI](#the-builder-ui)** → **[Triggers](#triggers--starting-a-flow)**, then jump to the node you need or to **[End-to-end scenarios](#end-to-end-scenarios)**.

> **Parity + backward-compatibility.** ConnectGain's builder covers every node, trigger, and use case offered by respond.io's Workflows — and adds deals, tasks, RAG, voice, multi-LLM, and cross-turn merge on top. The builder is also versioned **additively**: new nodes, triggers, and fields are always optional, so **flows built in older versions keep running unchanged**.

## Contents

1. [Concepts](#concepts)
2. [The builder UI](#the-builder-ui)
3. [Triggers — starting a flow](#triggers--starting-a-flow)
4. [Variables & dynamic text](#variables--dynamic-text)
5. [Pause / resume (waiting for the user)](#pause--resume-waiting-for-the-user)
6. [Node reference](#node-reference)
7. [Multilingual flows](#multilingual-flows)
8. [Deploying, activating & publishing](#deploying-activating--publishing)
9. [Testing & debugging](#testing--debugging)
10. [Flow analytics](#flow-analytics)
11. [API integration](#api-integration)
12. [End-to-end scenarios](#end-to-end-scenarios)
13. [Best practices](#best-practices)
14. [Troubleshooting](#troubleshooting)

---

## Concepts

| Term | Meaning |
|---|---|
| **Flow** | A chatbot/automation graph. Lives in `bot_flows`; has a status of **Draft** or **Published**. |
| **Node** | One step (send a message, branch, call an API, create a deal…). 37 types across 6 categories. |
| **Edge** | A connection from one node's output handle to another node's input. Defines execution order/branches. |
| **Trigger node** | The required entry point. Defines *what event* starts the flow and *which channel* it listens to. |
| **Session** | Per-conversation state (`bot_sessions`) holding **variables** and the current pause point. |
| **Variable** | A named value in the session (`{{name}}`). Set by inputs, API calls, AI, or Set Variable. |
| **Deployment** | Publishing compiles the flow to an **n8n workflow** and activates its webhook. The runtime is n8n. |

**How a flow actually runs:** an inbound message hits a **channel webhook** (WhatsApp, Messenger, …) → ConnectGain POSTs the event to the flow's n8n webhook → n8n executes node-by-node → node actions (sending messages, CRM writes) call back into ConnectGain edge functions. A flow only runs when it is **Published *and* its n8n workflow is active**.

---

## The builder UI

- **Canvas** — drag-and-drop, zoom/pan, snap-to-grid. Connect nodes by dragging from a node's output handle to another node's input.
- **Add-node palette** — grouped by category (Triggers, Messaging, AI & RAG, Logic, Data, CRM). Each node shows an icon + one-line description.
- **Node inspector** — click a node to configure it. The inspector also lists **available variables** from upstream nodes (computed by walking the edge graph backwards).
- **Node search / jump** — quickly find and focus a node in large flows.
- **Flow settings** — name, description, status.
- **Deploy / Publish** — compiles to n8n and activates. **Undeploy** removes it from n8n.
- **Test** — sample-webhook tester + preview.
- Flows list paginates at **50 per page**.

---

## Triggers — starting a flow

Every flow needs at least one **Trigger** node. Configure its **event** and (for message events) a **channel** filter.

### Trigger events

**Conversation & messaging**

- `message.received` — inbound customer message (the most common trigger)
- `message.sent` — an outbound message was sent
- `conversation.created` / `conversation.assigned` / `conversation.status.changed`
- **Broadcast Response** (`broadcast.response`) — the contact replied within 72h of receiving a [campaign](https://docs.connectgain.cloud/02-user-guide/bot-flows/campaigns.md). Payload carries `campaign_id`, `campaign_name`.
- **Manual Shortcut** (`manual.shortcut`) — an agent launches the flow from the [inbox](https://docs.connectgain.cloud/02-user-guide/bot-flows/inbox.md) **⚡ Shortcuts** menu.

**Contact**

- `contact.created` / `contact.assigned`
- `contact.updated` — any contact edit. Set the optional **Field to watch** (e.g. `lead_score`) to fire **only** when that field changes (*Field Updated*).
- **Tag Updated** (`contact.tag.updated`) — contact tags changed.
- **Lifecycle Updated** (`contact.lifecycle.updated`) — the contact's lifecycle stage changed.

**Deals & tasks**

- `deal.created` / `deal.stage.changed` / `deal.updated` / `deal.assigned`
- `task.created` / `task.updated` / `task.completed` / `task.overdue`

**Other**

- **Call Ended** (`call.ended`) — a call recording arrived (carries call id, contact, duration).
- Incoming Webhook (HTTP POST) · Zoom Recording Completed (`zoom.recording.completed`)

### Channel filtering (message triggers)

- **Channel** — `all`, or one of `WHATSAPP_LITE, WHATSAPP_CLOUD, FB_MESSENGER, INSTAGRAM, TELEGRAM, TIKTOK, SHOPIFY_INBOX, BULK_EMAIL, LINKEDIN`.
- **Channel account** — pin to one connected account (e.g. only your main WhatsApp Cloud number), or `all`. Prevents a flow meant for one number firing on another.

### Multiple triggers in one flow

Add several Trigger nodes to a single flow and each starts its own branch from the same webhook; events are routed to the matching branch by event type. Use this to share setup (variables, lookups) across related events.

### Inbox Shortcuts (agent-launched)

Build a flow with a **Manual Shortcut** trigger and publish it. A **⚡ Shortcuts** menu appears in the inbox conversation header; selecting your flow runs it for the current conversation, passing the conversation/contact context. The webhook URL is never exposed to the browser — launches go through the org-validated `trigger-shortcut-flow` endpoint.

---

## Variables & dynamic text

Reference any session value in **any text field** with handlebars: `{{variable}}` or dot-paths `{{contact.first_name}}`.

**Where variables come from**

- The trigger payload: `{{message.text}}`, `{{contact.id}}`, `{{contact.first_name}}`, `{{contact.phone}}`, `{{conversation.id}}`
- **Collect Input** / **Quick Reply** (collect mode) — the user's answer
- **Set Variable**, **HTTP Request** (`responseVariable`), **Database Query**/**Memory** (`outputVariable`), **AI Response** (`response`), **AI Agent** (`agentResponse`)

**Rules to remember**

- Missing variable → the literal `{{token}}` is left **unchanged** (never blanked). This is what makes interpolation safe to add to old flows.
- Dot-paths are **static** — `{{order.id}}` works; **nested/dynamic keys like `{{texts.{{lang}}.greeting}}` do not.** Compute the final flat value first (Set Variable / Database Query), then reference it.
- Numeric helper: `{{counter}} + 1` increments in text fields.
- Store user input, API responses, and computed values, then reuse them in conditions and in [message templates](https://docs.connectgain.cloud/02-user-guide/bot-flows/templates.md).

### Dates & the current time

There is **no generic `{{now}}` text variable** — flows can't stamp the current date into an arbitrary message field. Use one of these instead:

- **Resolve relative dates from what the user says → use the AI Agent.** The AI Agent (and RAG agent) are automatically given the real current date/time at run time, so "book me in **tomorrow at 3 PM**", "**next Monday**", "**this Friday at 10 AM**" resolve to a correct absolute **ISO 8601** datetime you can pass to the **Scheduler**. Set the agent's **Timezone (for dates)** field to your local IANA zone (e.g. `Africa/Cairo`) so relative dates land on the correct local day. This is injected at **Publish** time — **re-publish** a flow after changing the timezone or after this feature was deployed. (See [UC-FLOW-019](https://docs.connectgain.cloud/02-user-guide/04-use-cases/bot-flow-automation-recipes.md#uc-flow-019-book-appointments-from-relative-dates).)
- **Branch on the current time → use the Date & Time node.** It evaluates *now* (in a chosen timezone) against business-hours windows and takes the **In hours** / **Out of hours** output. Use it for open/closed routing, not for emitting a date string.
- **Compute a date server-side → use the Scheduler node.** It returns real, bookable slots (`available_slots`) computed from your availability rules — no date maths in the flow.

---

## Pause / resume (waiting for the user)

Two nodes pause the flow and wait for the next inbound message: **Quick Reply** and **Collect Input**. This is fundamental to conversational bots.

- When a pause node runs, the session stores `current_node_id` and what it's awaiting (`awaiting_buttons` / `awaiting_input_variable`).
- The customer's **next message** resumes the flow at that exact point — Quick Reply matches a button (by number `1`/`2`, exact title, payload, or `btn_0` id), Collect Input captures free text into the variable.
- If a reply doesn't match any button, the flow **restarts** from the trigger (so a stray "hi" re-greets rather than dead-ends).
- Bot flows pause for the user automatically; they only **stop** on an explicit human **handoff** (`ai_handoff_at`).

> **Chaining tip:** enable **Collect into variable** on Quick Reply to collapse its many per-button outputs into a single "answered" output. You can chain several Quick Replies and send one summary at the end, instead of 15-edge spaghetti.

---

## Node reference

Each node lists its purpose, key config, the variables it outputs, and notes. Configure everything in the node inspector. All text fields accept `{{variables}}`.

### Messaging nodes

#### Send Message

Sends a text/template message on the chosen channel.

- **Key config:** `channelAccountId`, `message` (supports `{{vars}}`), `messageSource` = `custom | freeformOrTemplate | quickReply | waCloudTemplate | llm`. For multilingual templates: `templateNameBase` + `localizedBodies` (see [Multilingual](#multilingual-flows)).
- **Outputs:** `messageId`, `status` (`sent`/`failed`).
- **Notes:** `freeformOrTemplate` smart-send picks freeform inside the 24h window, else a Meta template. Respects the WhatsApp 24-hour customer-service window.

#### Send Media

Sends an image, video, audio, or document.

- **Key config:** `mediaType` (`image | video | audio | document`), `mediaUrl` (URL or `{{var}}`), `caption`.
- **Outputs:** `messageId`.
- **Notes:** provider media URLs expire — prefer re-hosted/Storage URLs.

#### Quick Reply

Sends a prompt with tappable buttons.

- **Key config:** `message`, `buttons[]` (`title`, `payload`), and optionally **Collect into variable** (`collectAsVariable`, `variableName`, `saveMode` = `index | title | payload`). Per-language **localized** message + button labels are supported.
- **Outputs:** the chosen button as `{variableName}` (collect mode), or `selectedValue`/`selectedLabel`; one output handle per button otherwise.
- **Notes:** WhatsApp Cloud renders ≤3 as buttons, 4–10 as a list, more as numbered text. Other channels use numbered text. **Pauses** the flow. See [Multilingual](#multilingual-flows).

#### Collect Input

Prompts the user and waits for a validated reply.

- **Key config:** `inputType` (`text | number | email | phone | date | choice`), `prompt`, `variableName`.
- **Outputs:** `{variableName}` (validated/coerced).
- **Notes:** **Pauses** the flow until the user replies.

### Logic nodes

#### If Condition

Branches on one or more comparisons.

- **Key config:** `field` (or `{{var}}`), `conditions[]` of `{ operator, value }`, `combinator` = `and | or`.
- **Operators:** equals, not equals, contains, does not contain, starts with, ends with, regex, `>`, `>=`, `<`, `<=`, is empty, is not empty.
- **Outputs:** `true` / `false` handle.

#### Switch

Multi-way branch — one handle per case + default.

- **Key config:** `inputVariable` (e.g. `{{intent}}` or `{{lang}}`), `cases[]` of `{ value, label }`.
- **Outputs:** the matched case, or `default`.

#### Loop

Iterates over an array with index tracking.

- **Key config:** the array variable to iterate; body runs per item.

#### Delay

Waits before continuing.

- **Key config:** duration (seconds/minutes/hours/days).

#### Date & Time

Branches on whether *now* is inside configured **business-hours** windows.

- **Key config:** `timezone` (IANA), `businessHours[]` of `{ day, startTime, endTime }`.
- **Outputs:** **In hours** / **Out of hours**. An empty schedule always takes *In hours*.

#### Merge

Waits for multiple branches and combines them.

- **Key config:** `inputCount` (2–6), `mode` = `combineAll | combineByPosition | append`.
- **Outputs:** `merged` payload with fields from every branch. Use after a fan-out so downstream sees all results together.

#### Jump To

Redirects execution to another node (loops, skip-ahead, reusable sections).

- **Key config:** `targetNodeId`.
- **Notes:** transparent at deploy time (compiles away); cycle-guarded. Great for converging language/branch paths back to a shared tail.

#### Trigger Flow (Sub-flow)

Starts another published flow for the same contact.

- **Key config:** `targetFlowId`, `passVariables` (default on), `waitForCompletion`.
- **Notes:** build reusable sub-flows (e.g. a Booking flow) once and call them from many parents.

#### Error Handler

Catches errors from upstream nodes.

- **Key config:** `fallbackMessage`.
- **Outputs:** `errorMessage`, and an `error` / `success` branch.

#### End Flow

Terminates the flow. Optional final `message`.

### AI & RAG nodes

> All LLM nodes need an **LLM API key**. Enter it in the node, or rely on a platform key / an existing n8n credential. **An AI node with no resolvable key blocks n8n activation** — the deploy fails with a clear message instead of silently killing the trigger. Google's *AI Response* node can run key-in-URL, but the *AI Agent* node needs a real credential.

#### AI Response

Calls an LLM with a system prompt + user input, returns text.

- **Key config:** `llmProvider` (`openai | google | anthropic | groq | deepseek | mistral | ollama`), `model`, `prompt` (supports `{{vars}}`), `userInput` (e.g. `{{message.text}}`), `temperature`.
- **Outputs:** `response`, `tokensUsed`.

#### AI Agent

A LangChain tools-agent that autonomously picks tools to answer.

- **Key config:** `llmProvider`/`llmModel`, `systemPrompt`, `temperature`, `memoryEnabled` + `memoryWindowSize` (1–50), **Timezone (for dates)**, and **tools**: `databaseQuery`, `updateContact`, `createDeal`, `addTag`, `httpRequest` (give the HTTP tool a base URL + description).
- **Outputs:** `agentResponse`.
- **Current date awareness:** the agent is automatically told the current date/time at run time (see [Dates & the current time](#dates--the-current-time)), so it resolves "tomorrow at 3 PM" / "next Monday" correctly and outputs ISO 8601. Set **Timezone** to your local IANA zone (e.g. `Africa/Cairo`).
- **Notes:** its system prompt interpolates `{{variables}}`. Keeps per-conversation chat memory. Tools call back into ConnectGain securely.

#### Classify Intent

AI intent detection — usually feeding a **Switch**.

- **Key config:** the input text + the candidate intents.
- **Outputs:** the detected intent (switch on `{{intent}}`).

#### RAG System

Full Retrieval-Augmented Generation: agent + embeddings + vector retriever + an upload pipeline for your knowledge files.

- **Key config:** LLM + embedding providers/models, knowledge base, uploaded files (ingested to the vector store on deploy).
- **Notes:** zero-hallucination answering grounded in your documents.

#### Voice Agent

Hands a call to an ElevenLabs voice agent.

- **Key config:** `agentId`, `prompt`, `voice`.
- **Outputs:** `transcript`, `summary`.

### Data nodes

#### Set Variable / Get Variable

Store / read a value in flow- or global-scoped state.

- **Set:** `variableName`, `value` (supports `{{vars}}`), `scope` (`flow | global`).
- **Get:** `variableName` → value into context.

#### Transform Data

Runs a JS expression and stores the result.

- **Key config:** `inputVariable`, `expression` (e.g. `input.toUpperCase`), `outputVariable`.

#### HTTP Request

Calls an external API and stores the response.

- **Key config:** `url` (supports `{{vars}}`), `method`, `headers` (JSON), `body` (JSON), `responseVariable`.
- **Outputs:** `{responseVariable}.status`, `{responseVariable}.body`.

#### Database Query

Runs a parameterised query against an **allow-listed** table and stores rows.

- **Key config:** table/operation, `filters`/`data` (JSON, support `{{vars}}`), `columns`, `limit` (≤500), `outputVariable`.
- **Allow-listed tables:** `contacts, deals, tasks, conversations, messages, bot_sessions, companies, notes, products`.

#### Memory

Per-session / per-contact / org key-value memory, or CRUD on allow-listed tables.

- **Key config:** `mode` (`memory | database`); memory mode: `operation` (`set/get/append/delete/clear`), `scope` (`session/contact/org`), `key`, `value`, `ttlSeconds`; database mode mirrors Database Query.
- **Outputs:** `{outputVariable}`, `success`.

#### Google Sheets

Appends a row to a Google Sheet.

- **Key config:** spreadsheet id or URL + tab name, ordered cell values (each supports `{{var}}`).
- **Notes:** uses the organization's connected Google account (reconnect Google once to grant Sheets access).

### CRM & conversation nodes

#### Update Contact

Sets fields on the current [contact](https://docs.connectgain.cloud/02-user-guide/bot-flows/contacts.md). **Key config:** `fields`.

#### Add Tag

Adds **or removes** a tag on the contact. **Key config:** `tags`, `mode` = `add | remove` (supports `{{vars}}`).

#### Update Lifecycle

Moves the contact to a **lifecycle stage** and fires the *Lifecycle Updated* event. **Key config:** `stageId`. Stages are defined in **Settings → Lifecycle Stages**.

#### Create Deal / Update Deal

Create a [deal](https://docs.connectgain.cloud/02-user-guide/bot-flows/deals.md) (`title`, `value`, `stageId`) → `dealId`; or update an existing deal (`dealId`, `fields`).

#### Create Task / Auto Assign Task

Create a [task](https://docs.connectgain.cloud/02-user-guide/bot-flows/tasks.md) (`title`, `assigneeId?`, `dueDate?`) → `taskId`; or auto-assign by availability/round-robin (respects `can_be_auto_assigned_tasks`).

#### Assign Conversation

Assigns the conversation to an agent (specific, round-robin, or availability-based; respects `can_be_auto_assigned_conversations`).

#### Add Comment

Adds an **internal note** to the contact's activity timeline (not sent to the customer). Supports `{{vars}}`.

#### Close Conversation / Open Conversation

Mark the conversation closed, or reopen it (e.g. close after resolution; reopen when the customer replies).

#### Handoff to Agent

Transfers the conversation to a human, preserves context, and **stops the bot** for that conversation (sets the handoff flag) so the bot won't talk over the agent.

---

## Multilingual flows

One flow can answer each customer in their own language. The short version:

1. Capture the language into a **`lang`** session variable (a Quick Reply language-picker with *Save = payload*, or a Set Variable from `{{contact.language}}`).
2. Author **localized** Quick Reply bodies + button labels (per-language editor in the node). Default content is the fallback.
3. For template sends, use **Send Message** `templateNameBase` + `localizedBodies`.
4. Need different *paths* per language (not just text)? **Switch** on `{{lang}}` and converge with **Jump To**.

Full step-by-step, data shapes, and fallback rules: **[Building Multilingual Bot Flows](https://docs.connectgain.cloud/02-user-guide/bot-flows/multilingual-flows.md)**.

---

## Deploying, activating & publishing

A flow's status is **Draft** (in development), **Published** (active and running), or **Archived** (disabled).

1. Add a **Trigger** node and **save** the flow (deploy refuses without a trigger).
2. Click **Deploy / Publish**. ConnectGain compiles the graph to an n8n workflow via the `n8n-deploy-flow` edge function, (re)creates it, and **activates** it.
3. On success the flow is **Published** and its webhook is live; on failure the toast shows the reason.

**What activation means:** n8n only serves a flow's production webhook while the workflow is **active**. If a node is invalid (classically, an AI node with no LLM key), n8n refuses to activate — and the deploy **surfaces that error** and leaves the flow **Draft** instead of pretending success. Fix the named node and redeploy.

**Undeploy** removes the workflow from n8n and returns the flow to Draft.

---

## Testing & debugging

- **Sample-webhook tester** — fire a representative event into the flow without a real customer message.
- **n8n executions** — each run appears in n8n; open one to see node-by-node inputs/outputs and errors.
- **Quick activation check** — POST to the flow's webhook URL:

 ```bash
 curl -i -X POST "<flow n8n_webhook_url>" -H "Content-Type: application/json" -d '{}'
 ```

 `404` → workflow inactive (activation failed); `200` → active.
- **Session inspection** — `bot_sessions` holds the live `variables` and `current_node_id` for a conversation; useful when a pause/resume misbehaves.

---

## Flow analytics

Track how flows perform in aggregate and per node.

**Flow performance:** execution count, success rate, average completion time, drop-off points, and user-engagement metrics.

**Node analytics:** per-node execution count, success/failure rates, average processing time, and bottleneck identification.

---

## API integration

Flows are stored in the `bot_flows` table and can be managed through the REST API (see the [Complete API Reference](https://docs.connectgain.cloud/02-user-guide/07-api/complete-api.md)).

### Create a flow

**Endpoint:** `POST /rest/v1/bot_flows`

```json
{
 "organization_id": "org-uuid",
 "name": "Welcome Flow",
 "description": "Welcome new customers",
 "status": "DRAFT",
 "nodes": [
 { "id": "start-1", "type": "START", "position": { "x": 100, "y": 100 } },
 { "id": "text-1", "type": "TEXT", "message": "Hello!", "position": { "x": 200, "y": 100 } }
 ],
 "edges": [
 { "source": "start-1", "target": "text-1" }
 ]
}
```

### Publish a flow

**Endpoint:** `PATCH /rest/v1/bot_flows/{id}`

```json
{ "status": "PUBLISHED" }
```

To pause or resume a bot on a live conversation programmatically, use the [Bot Control API](https://docs.connectgain.cloud/02-user-guide/07-api/bot-control-api.md).

---

## End-to-end scenarios

### A. Welcome + route

Trigger `message.received` (channel `all`) → Send "Hi {{contact.first_name}}! How can we help?" → Quick Reply [Sales, Support, Hours] (collect into `topic`) → Switch on `{{topic}}` → Sales path / Support path / Date & Time (hours) path.

### B. FAQ deflection with auto-close

Trigger → Classify Intent → Switch on `{{intent}}` → Send the matching answer → Quick Reply "Did that help? Yes/No" (collect `resolved`) → If `resolved` contains "yes" → Add Comment "Auto-resolved" → **Close Conversation**; else **Handoff to Agent**.

### C. Lead capture → deal

Trigger → Collect Input name → Collect Input email → **Update Contact** (`fields` from the answers) → **Create Deal** ("New web lead", stage = New) → **Google Sheets** append row → Send confirmation.

### D. Business-hours routing

Trigger → **Date & Time** (Mon–Fri 09:00–17:00, `Africa/Cairo`): *In hours* → **Assign Conversation** + "An agent will be right with you"; *Out of hours* → "We're closed, we'll reply at 9 AM" → Collect Input (their question) → Add Comment.

### E. Multilingual support bot

Trigger → Quick Reply language picker (save payload → `lang`) → localized Quick Reply menu (one node, per-language body + buttons) → Switch on the choice → localized answers. See [Multilingual](https://docs.connectgain.cloud/02-user-guide/bot-flows/multilingual-flows.md).

### F. Campaign reply engagement

Trigger **Broadcast Response** → Add Tag "Campaign Engaged" → Send "Thanks for replying to {{campaign_name}}!" → Quick Reply "Book a demo? Yes/No" → on Yes, **Trigger Flow** → Booking sub-flow.

### G. Post-call follow-up

Trigger **Call Ended** → Send "Thanks for the call!" → **Add Comment** "Follow-up sent after {{duration_seconds}}s" → **Create Task** "Send proposal" (due +2 days).

### H. Lifecycle onboarding

Trigger **Lifecycle Updated** → If `lifecycle_stage` equals "Customer" → Send onboarding checklist → **Create Task** "Onboarding call".

### I. AI knowledge agent

Trigger → **RAG System** (your docs) answers grounded questions; fall back to **Handoff to Agent** when confidence is low or the user asks for a human.

### J. Agent one-click playbook

Trigger **Manual Shortcut** → Send pricing pack → Add Tag "Pricing Sent" → **Update Lifecycle** → Opportunity. Launch it from the inbox **⚡ Shortcuts** menu.

More ready-to-build recipes: [Bot Flow Automation Recipes](https://docs.connectgain.cloud/02-user-guide/04-use-cases/bot-flow-automation-recipes.md).

---

## Best practices

- **Always offer an exit to a human** (Handoff) on any branch a bot can't resolve.
- **Keep flows focused.** Extract reusable pieces into sub-flows and call them with **Trigger Flow**.
- **Name variables clearly** (`rating_call`, `lead_score`) and prefer collecting into variables over wide button fan-outs.
- **Use Jump To to converge** branch/language tails instead of duplicating nodes.
- **Pin the channel/account** on triggers when a flow is meant for one number, so it doesn't fire elsewhere.
- **Test after every deploy** — confirm the workflow activated (toast or curl check) before relying on it.
- **Localize content, branch only on flow shape** — most multilingual needs are content, handled in-node.

---

## Troubleshooting

| Symptom | Likely cause / fix |
|---|---|
| **No executions in n8n** for a message | Workflow not active. The trigger is a channel POST to the n8n webhook; n8n only serves it while active. Redeploy and read the toast; `curl` the webhook (404 = inactive). |
| **"Deploy failed: AI Agent node is missing the LLM API key…"** | Enter the LLM key in the AI Agent node (or set the platform key). Google AI Agent needs a real credential, not key-in-URL. |
| **Deploy reports success but bot never replies** | The flow may be Draft after a failed activation — check status and the deploy toast for the blocking node. |
| **Flow re-greets instead of resuming** | The user's reply didn't match any awaiting button — check button titles/payloads, or use Collect-into-variable. |
| **`{{var}}` shows literally in a message** | The variable wasn't set upstream (missing tokens are left as-is by design). Verify the producing node ran and the name matches. |
| **Wrong language sent** | Ensure a `lang`/`language` variable is set before the localized node; missing/blank translations fall back to Default. |
| **Bot talks over a human agent** | A Handoff sets the stop flag; ensure your handoff path runs before further bot messages. |

---

## See also

- [Building Multilingual Bot Flows](https://docs.connectgain.cloud/02-user-guide/bot-flows/multilingual-flows.md) — per-language content
- [Bot Flow Automation Recipes](https://docs.connectgain.cloud/02-user-guide/04-use-cases/bot-flow-automation-recipes.md) — ready-to-build use cases
- [Automations](https://docs.connectgain.cloud/02-user-guide/bot-flows/automations.md) · [Templates](https://docs.connectgain.cloud/02-user-guide/bot-flows/templates.md) · [Sequences](https://docs.connectgain.cloud/02-user-guide/bot-flows/sequences.md)
- [Inbox](https://docs.connectgain.cloud/02-user-guide/bot-flows/inbox.md) · [Complete API Reference](https://docs.connectgain.cloud/02-user-guide/07-api/complete-api.md) · [Bot Control API](https://docs.connectgain.cloud/02-user-guide/07-api/bot-control-api.md)
- [ConnectGain AI chatbot overview](https://connectgain.cloud/en/ai-chatbot) · [Bot Flows](https://connectgain.cloud/en/bot-flows) · [AI Agent](https://connectgain.cloud/en/ai-agent) — feature overviews on the ConnectGain website

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# AI Call Intelligence & Transcription – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/call-intelligence/

# Call Intelligence Feature

## Overview

Call Intelligence (`/call-intelligence`) provides AI-powered analysis of phone calls, meeting recordings, and call recordings. It automatically transcribes calls (Arabic and English), analyses sentiment, extracts action items, detects keywords, and generates AI summaries — powered by Google Gemini 2.5 Flash by default, with multi-vendor AI support. The feature includes a comprehensive analytics dashboard, agent performance tracking, and call minutes quota management.

## Table of Contents

1. [Features](#features)
2. [Use Cases](#use-cases)
3. [Test Cases](#test-cases)
4. [Related Documentation](#related-documentation)

---

## Features

### 1. Call Records Management

**Record Upload:**
- In-app upload via drag-and-drop or file picker
- Webhook upload for external systems
- Mobile API upload (multipart, up to 50 MB)
- Automatic call logging from SIP softphone
- Supported formats: MP3, WAV, OGG, M4A, WebM

**Record Metadata:**
- Caller / callee identification
- Phone number linking to contacts
- Call duration and timestamp
- Channel source (SIP, mobile, Zoom, webhook)
- Recording file and transcript storage

**Call Outcome Tracking:**
- Outcome labels: Answered, No Answer, Busy, Voicemail, Callback Requested, Not Interested, Follow-up Scheduled, Deal Closed, Wrong Number, Other
- Notes and follow-up flags
- Linked deals and tasks

### 2. AI Transcription

**Automatic Transcription:**
- Arabic and English language support
- Speaker diarisation (who said what)
- Timestamped segments
- Multi-vendor AI support with Gemini fallback for audio
- Silence detection — skips AI processing on empty recordings

**Transcript View:**
- Searchable transcript text
- Speaker labels (Agent / Customer / Unknown)
- Segment timestamps
- Inline playback sync

### 3. AI Analysis

**Sentiment Analysis:**
- Overall call sentiment: Positive, Neutral, Negative
- Sentiment distribution charts
- Sentiment trends over time
- Per-segment sentiment scoring

**AI Summary:**
- Automated call summary generation
- Key topics identified
- Conversation highlights
- One-click summary view per call record

**Action Item Extraction:**
- Automatic detection of follow-up tasks
- Assignee suggestions
- Due date inference
- One-click task creation from action items

**Keyword Detection:**
- Configurable keyword lists per organization
- Keyword frequency tracking
- Keyword trend analysis over time
- Call classification by keyword presence

**Call Classification:**
- Auto-categorised call types: Sales, Support, Complaint, Inquiry, Follow-up, General
- Classification confidence score
- Manual override capability

### 4. Analytics Dashboard

**Call Volume Charts:**
- Calls over time (daily, weekly, monthly)
- Total calls, total duration, average duration
- Channel breakdown (SIP, mobile, Zoom, webhook)
- Peak calling hours

**Sentiment Distribution:**
- Pie/bar chart of positive / neutral / negative calls
- Trend line over selected period
- Agent-level sentiment breakdown

**Agent Performance Leaderboard:**
- Calls handled per agent
- Average call duration
- Sentiment score per agent
- Conversion correlation (calls vs deals closed)
- Response time metrics

**Keyword Trends:**
- Most frequent keywords over time
- Keyword cloud / tag cloud
- Emerging keyword alerts

**Minutes Quota Tracking:**
- Monthly call minutes allowance
- Minutes used vs remaining
- Quota exhaustion alerts
- Admin top-up capability

**AI Token Usage Monitoring:**
- Tokens consumed per transcription / analysis
- Cost tracking for BYOK users
- Usage trends and forecasting

### 5. Multi-Vendor AI Support

**AI Vendor Selection:**
- Organization-level AI vendor configuration
- Supported vendors: ConnectGain AI (Gemini, default), OpenAI, Anthropic Claude, Google Gemini, Ollama, and GLM/Z.ai — plus BYOK (Bring Your Own Key) Gemini
- Vendor-specific model selection
- Automatic fallback on vendor failure

**Gemini Audio Fallback:**
- If primary vendor fails or doesn't support audio, falls back to Gemini 2.5 Flash
- Ensures transcription availability regardless of vendor status

### 6. Call Recording & Storage

**Recording Persistence:**
- All recordings stored in Supabase Storage
- Appgain CDN routing for fast playback
- Access-controlled playback (organization-scoped)
- Download capability for authorised users

**Mobile Call Recorder:**
- Native mobile app records calls
- Multipart upload via `/call-recording` edge function (up to 50 MB)
- Automatic contact matching by phone number
- Automatic outcome capture

### 7. Integration Points

**Zoom Integration:**
- Cloud recording sync via webhooks
- Google Calendar polling for missed webhooks
- Automatic import of Zoom meeting recordings
- Recording linked to scheduled events

**SIP Softphone:**
- WebRTC-based softphone using sip.js
- Automatic call logging on dial / hang-up
- Real-time call status in UI widget
- One-click recording attachment

**Contact Timeline:**
- Call records appear in contact activity timeline
- Unified view of messages, calls, tasks, notes, deals
- Click-through to full call analysis

### 8. Permissions & Access

**Role-Based Access:**
- `can_access_call_intelligence` permission required
- `can_see_all_call_records` — view all org calls vs own calls only
- `can_manage_call_settings` — configure AI vendor, quotas, keywords
- OWNER / ADMIN have full access

**View-Only Demo Mode:**
- Demo mode displays sample call data with AI analysis
- Read-only for prospective customers
- No real recordings processed

---

## Use Cases

### Use Case 1: Sales Call Analysis

**Scenario:**
Sales manager wants to understand why deals are won or lost by reviewing call patterns.

**Steps:**
1. Upload or record sales calls
2. AI transcribes and analyses each call
3. View sentiment trends — are closing calls more positive?
4. Check keyword trends — which objections come up most?
5. Review action items — are follow-ups being completed?
6. Compare top performers' call patterns in leaderboard

**Expected Outcome:**
Identify winning call patterns, common objections, and coaching opportunities.

---

### Use Case 2: Support Quality Monitoring

**Scenario:**
Support manager needs to monitor call quality and customer satisfaction.

**Steps:**
1. All support calls automatically recorded and transcribed
2. Filter calls by sentiment = Negative
3. Review transcripts for coaching moments
4. Check action items for missed follow-ups
5. Track average sentiment score per agent

**Expected Outcome:**
Proactive quality assurance, faster agent coaching, improved CSAT.

---

### Use Case 3: Compliance & Documentation

**Scenario:**
Financial services firm needs documented records of all client phone conversations.

**Steps:**
1. Enable automatic recording for all SIP calls
2. All recordings transcribed and stored securely
3. Searchable archive by contact, date, or keyword
4. Export transcripts for audit requests
5. Retention policies enforced (90-day default)

**Expected Outcome:**
Complete, searchable, auditable call documentation.

---

### Use Case 4: Meeting Recording Analysis

**Scenario:**
Project manager wants AI summaries of weekly client meetings.

**Steps:**
1. Sync Zoom cloud recordings
2. AI transcribes and summarises each meeting
3. Action items extracted and converted to tasks
4. Keywords tracked (e.g., "deadline", "budget", "blocker")
5. Team reviews summaries instead of re-listening

**Expected Outcome:**
Save hours per week on meeting review; nothing falls through cracks.

---

## Test Cases

### Test Case 1: Upload and Transcribe

**Test:** Verify call upload and AI transcription

**Steps:**
1. Go to Call Intelligence
2. Click **Upload Recording**
3. Select an MP3/WAV file
4. Enter caller and callee details
5. Save
6. Wait for AI processing
7. Verify transcript appears
8. Verify sentiment and summary generated

**Expected Result:**
Recording uploaded, transcribed, and analysed successfully.

---

### Test Case 2: Analytics Dashboard

**Test:** Verify dashboard metrics

**Steps:**
1. Upload multiple call recordings
2. Go to Call Intelligence → Dashboard
3. Verify call volume chart populated
4. Verify sentiment distribution accurate
5. Verify agent leaderboard shows correct data
6. Verify keyword trends visible

**Expected Result:**
All dashboard widgets populated with correct data.

---

### Test Case 3: BYOK Configuration

**Test:** Verify custom AI vendor setup

**Steps:**
1. Go to Settings → Call Intelligence
2. Select AI vendor and model
3. Enter [API key](https://docs.connectgain.cloud/02-user-guide/07-api/api-key-authentication.md) (if BYOK)
4. Save settings
5. Upload test recording
6. Verify transcription uses selected vendor
7. Verify fallback to Gemini on failure

**Expected Result:**
Custom vendor used; fallback works on failure.

---

### Test Case 4: Minutes Quota

**Test:** Verify quota tracking

**Steps:**
1. Check current minutes quota in settings
2. Upload a 5-minute recording
3. Verify quota decrements by ~5 minutes
4. Attempt upload when quota exhausted
5. Verify quota-exceeded message

**Expected Result:**
Quota tracked accurately; upload blocked when exceeded.

---

### Test Case 5: Contact Timeline Integration

**Test:** Verify call record in contact timeline

**Steps:**
1. Upload recording linked to a known contact
2. Go to Contacts → select that contact
3. Open Activity Timeline
4. Verify call record appears
5. Click call record
6. Verify navigates to full call analysis

**Expected Result:**
Call record visible in contact timeline with link to analysis.

---

## Related Documentation

- [BYOK Gemini Setup](https://docs.connectgain.cloud/02-user-guide/05-integrations/ai-byok-gemini.md)
- [Analytics](https://docs.connectgain.cloud/02-user-guide/call-intelligence/analytics.md)
- [Contacts](https://docs.connectgain.cloud/02-user-guide/call-intelligence/contacts.md)
- [Deals](https://docs.connectgain.cloud/02-user-guide/call-intelligence/deals.md)
- [Call Intelligence on connectgain.cloud](https://connectgain.cloud/en/call-intelligence) — feature overview on the ConnectGain website
- [Call Tracking on connectgain.cloud](https://connectgain.cloud/en/call-tracking) — feature overview on the ConnectGain website
- [SIP Softphone on connectgain.cloud](https://connectgain.cloud/en/sip-softphone) — feature overview on the ConnectGain website

---

**Document Version:** 1.0.0
**Last Updated:** June 2026

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Broadcast Campaigns for WhatsApp, SMS & Email – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/campaigns/

# Campaign Management (Broadcast) Feature

## Overview

Broadcast (`/broadcast`) enables businesses to create and manage bulk messaging campaigns across SMS, WhatsApp Business, [WhatsApp Lite](https://docs.connectgain.cloud/02-user-guide/05-integrations/whatsapp-lite-api.md), and Email. It provides targeting options, scheduling capabilities, message composition tools, and delivery tracking for campaign performance.

The Broadcast page is organized into tabs: **SMS**, **WhatsApp Business**, **WhatsApp Lite**, **Email**, and **Notification Logs**. There is no separate "Campaigns" page — everything lives under `/broadcast`.

**On this page:** [Features](#features) · [Use Cases](#use-cases) · [Test Cases](#test-cases) · [API Integration](#api-integration) · [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting)

---

## Features

### 1. Campaign Types

**SMS Campaigns:** *(via Appgain Notify / VictoryLink provider)*
- Text message campaigns
- Character limit: 160 (standard) or 1600 (concatenated)
- Delivery tracking
- Link shortening (optional)

**WhatsApp Lite Campaigns:**
- WhatsApp Lite messaging
- Media support (images, videos, documents)
- Delivery and read receipts
- Template support
- Link shortening (optional)

**WhatsApp Business Campaigns:**
- Meta WhatsApp Business API
- Approved templates required
- Rich media support
- Interactive buttons
- Template variables

**Email Campaigns:**
- Bulk email via a connected Bulk Email channel
- Email composer with subject line and body
- Variable substitution ({{name}}, {{company}}, etc.)
- Delivery tracking via Notification Logs

### 2. Campaign Creation

**Campaign Setup:**
- Campaign name
- Description
- Campaign type selection
- Channel selection

**Message Composition:**
- Text editor
- Character counter
- Variable substitution ({{name}}, {{company}}, etc.)
- Emoji picker
- Link shortening toggle
- Image upload
- Message preview

**Template Selection:**
- Use WhatsApp Business templates
- Template browser
- Template variables
- Variable filling
- Template preview

### 3. Targeting Options

**Target All Contacts:**
- Send to all contacts
- Organization-wide broadcast
- Optional filters

**Target by Tags:**
- Send to tagged contacts
- Multiple tag selection
- AND/OR logic
- Tag search

**Target Individual Contacts:**
- Select specific contacts
- Contact picker
- Contact search
- Multiple selection
- Contact list import

### 4. Campaign Scheduling

**Send Immediately:**
- Send right away
- Instant sending
- Queue management

**Schedule for Later:**
- Schedule future sending
- Date picker
- Time picker
- Timezone selection
- Organization timezone support

**Recipient Count:**
- Preview recipient count
- Real-time calculation
- Filter-based counting
- Tag-based counting

### 5. Campaign Management

**Campaign List:**
- View all campaigns
- Tabbed view (SMS, WhatsApp Business, WhatsApp Lite, Email, Notification Logs)
- Campaign status indicators
- Success ratio display
- Target information
- Created date
- Sent date
- Scheduled date

**Campaign Status:**
- DRAFT - Not sent
- SCHEDULED - Scheduled for future
- SENDING - Currently sending
- SENT - Finished sending
- FAILED - Sending failed
- CANCELLED - Cancelled before sending

**Campaign Actions:**
- View campaign details
- Edit campaign (draft only)
- Delete campaign (if DRAFT or SENT)
- Send campaign
- Schedule campaign
- Cancel scheduled campaign (if SCHEDULED)
- View delivery logs

### 6. Campaign Analytics

**Delivery Statistics:**
- Track message delivery
- Total sent
- Successfully delivered
- Failed deliveries
- Success ratio percentage

**Read Receipts:**
- Track message reads (WhatsApp)
- Read count
- Read rate

**Notification Logs:**
- Detailed delivery logs
- Per-recipient status
- Delivery timestamps
- Error messages
- Retry attempts

**Campaign Performance:**
- Overall campaign metrics
- Delivery rate
- Read rate
- Cost analysis
- ROI calculation

### 7. Campaign Testing

**Test Campaign:**
- Send test message
- Test phone number input
- Test message preview
- Test sending
- Test delivery verification

### 8. WhatsApp Warming

**Warming Campaigns:**
- Warm up WhatsApp numbers
- Warming dialog
- Warming progress tracking
- Warming recommendations
- Channel health monitoring

### 9. Table Features

**Sortable Columns:**
- Sort by any column
- Created date
- Sent date
- Scheduled date

**Column Visibility:**
- Show/hide columns
- Customizable table
- Saved preferences

**Filtering:**
- Filter campaigns
- By status
- By type
- By date range

**Bulk Selection:**
- Select multiple campaigns
- Bulk actions
- Bulk delete

### 10. Pagination

**50 Campaigns Per Page:**
- Efficient loading
- Page navigation

### 11. Delivery Tracking

**Notification Logs:**
- Message delivery status
- Sent count
- Delivered count
- Failed count
- Read count (if supported)

**Delivery Status:**
- PENDING - Queued for sending
- SENT - Sent to gateway
- DELIVERED - Delivered to recipient
- FAILED - Delivery failed
- READ - Read by recipient (if supported)

**Analytics:**
- Delivery rate
- Read rate
- Failure rate
- Cost tracking
- Performance metrics

### 12. Campaign Preview

**Preview Features:**
- Preview message content
- Test variable substitution
- Preview on different devices
- Check media rendering
- Validate template format

---

## Use Cases

### Use Case 1: Product Launch Announcement

**Scenario:**
Company launching new product, wants to notify all customers via WhatsApp.

**Steps:**
1. Create WhatsApp Lite campaign
2. Set name: "New Product Launch"
3. Compose message with product details and image
4. Target: All contacts with tag "Customer"
5. Schedule for launch date
6. Preview campaign
7. Send campaign
8. Monitor delivery
9. Track engagement
10. Follow up with interested customers

**Expected Outcome:**
All customers notified, engagement tracked, leads generated.

### Use Case 2: Promotional SMS Campaign

**Scenario:**
Retail store wants to send promotional SMS to customers.

**Steps:**
1. Create SMS campaign
2. Compose promotional message
3. Target contacts by location tag
4. Schedule for business hours
5. Set character limit
6. Send campaign
7. Track delivery
8. Monitor response rate
9. Analyze performance

**Expected Outcome:**
Promotional message delivered, responses tracked.

### Use Case 3: Birthday Campaign

**Scenario:**
Automated birthday wishes to customers.

**Steps:**
1. Create recurring WhatsApp campaign
2. Use template with {{name}} variable
3. Target contacts with birthday in current month
4. Schedule for morning delivery
5. Set up automation rule for monthly trigger
6. Monitor delivery
7. Track engagement

**Expected Outcome:**
Automated birthday wishes sent monthly.

### Use Case 4: Email Newsletter

**Scenario:**
Marketing team wants to send an email newsletter to a segment of contacts.

**Steps:**
1. Open the **Email** tab in Broadcast.
2. Click "New Campaign".
3. Enter a subject line and compose the email body (with variables such as {{name}}).
4. Choose a connected Bulk Email channel to send from.
5. Target by tags or all contacts.
6. Send now or schedule for later.
7. Track delivery in Notification Logs.

**Expected Outcome:**
Email newsletter delivered to the targeted contacts, with delivery status tracked.

---

## Test Cases

### TC-CAMP-001: Create SMS Campaign

**Test:** Verify SMS campaign creation

**Steps:**
1. Navigate to Broadcast → SMS tab
2. Click "New Campaign"
3. Select type: "SMS"
4. Enter name: "Test SMS Campaign"
5. Compose message (under 160 characters)
6. Select target: "ALL"
7. Click "Save"
8. Verify campaign created
9. Verify status: "DRAFT"
10. Open campaign details
11. Verify all data saved

**Expected Result:** SMS campaign created successfully

**Test Data:**
- Message: "Hello! This is a test SMS campaign."
- Target: All contacts

---

### TC-CAMP-002: Create WhatsApp Campaign with Media

**Test:** Verify WhatsApp campaign with image

**Steps:**
1. Navigate to Broadcast → WhatsApp Lite tab
2. Click "New Campaign"
3. Select type: "WHATSAPP_LITE"
4. Enter name: "Test WhatsApp Campaign"
5. Compose message
6. Upload image attachment
7. Select target: Tags ["VIP"]
8. Schedule for future time
9. Save campaign
10. Verify campaign created
11. Verify image attached
12. Verify scheduling set

**Expected Result:** WhatsApp campaign with media created and scheduled

---

### TC-CAMP-003: Send Campaign Immediately

**Test:** Verify immediate campaign sending

**Steps:**
1. Create campaign (DRAFT status)
2. Open campaign details
3. Click "Send Now"
4. Confirm sending
5. Verify status changes to "SENDING"
6. Monitor sending progress
7. Wait for completion
8. Verify status: "SENT"
9. Check notification logs
10. Verify messages sent

**Expected Result:** Campaign sent successfully to all targets

---

### TC-CAMP-004: Schedule Campaign

**Test:** Verify campaign scheduling

**Steps:**
1. Create campaign
2. Click "Schedule"
3. Select date and time (future)
4. Select timezone
5. Confirm schedule
6. Verify status: "SCHEDULED"
7. Verify scheduled time displayed
8. Wait for scheduled time
9. Verify campaign sends automatically
10. Verify status: "SENT"

**Expected Result:** Campaign scheduled and sent at specified time

---

### TC-CAMP-005: Target Campaign by Tags

**Test:** Verify tag-based targeting

**Steps:**
1. Create contacts:
 - Contact 1: Tag "VIP"
 - Contact 2: Tag "Customer"
 - Contact 3: Tag "VIP"
2. Create campaign
3. Set target type: "TAGS"
4. Select tags: ["VIP"]
5. Save and send campaign
6. Check notification logs
7. Verify only Contact 1 and Contact 3 receive message
8. Verify Contact 2 does not receive message

**Expected Result:** Campaign targets only contacts with selected tags

---

### TC-CAMP-006: Variable Substitution

**Test:** Verify variable replacement in messages

**Steps:**
1. Create contact: Name "John Doe", Company "Acme Inc"
2. Create campaign
3. Compose message: "Hello {{name}}, welcome to {{company}}!"
4. Target: Individual contact (John Doe)
5. Preview campaign
6. Verify variables replaced: "Hello John Doe, welcome to Acme Inc!"
7. Send campaign
8. Verify message received with variables replaced

**Expected Result:** Variables correctly replaced in sent messages

---

### TC-CAMP-007: Campaign Cancellation

**Test:** Verify campaign cancellation

**Steps:**
1. Create and schedule campaign
2. Verify status: "SCHEDULED"
3. Click "Cancel"
4. Confirm cancellation
5. Verify status: "CANCELLED"
6. Verify campaign does not send
7. Check notification logs
8. Verify no messages sent

**Expected Result:** Scheduled campaign cancelled successfully

---

### TC-CAMP-008: Delivery Tracking

**Test:** Verify delivery status tracking

**Steps:**
1. Create and send campaign
2. Monitor notification logs
3. Verify statuses tracked:
 - PENDING
 - SENT
 - DELIVERED
 - READ (if supported)
4. Check delivery statistics
5. Verify counts accurate
6. Review failed messages
7. Check failure reasons

**Expected Result:** Delivery status tracked accurately

---

### TC-CAMP-009: Campaign Analytics

**Test:** Verify campaign analytics

**Steps:**
1. Send campaign to 100 contacts
2. Wait for delivery completion
3. Open campaign analytics
4. Verify metrics:
 - Sent: 100
 - Delivered: 95
 - Failed: 5
 - Read: 80
5. Calculate rates:
 - Delivery rate: 95%
 - Read rate: 84%
6. Verify analytics accurate

**Expected Result:** Campaign analytics display accurate metrics

---

### TC-CAMP-010: Campaign Preview

**Test:** Verify campaign preview functionality

**Steps:**
1. Create campaign with variables
2. Click "Preview"
3. Verify preview displayed
4. Verify variables replaced in preview
5. Test different contact data
6. Preview media attachments
7. Check character count
8. Verify preview accuracy

**Expected Result:** Campaign preview shows accurate message

---

## API Integration

### Create Campaign

**Endpoint:** `POST /rest/v1/campaigns`

**Request:**
```json
{
 "organization_id": "org-uuid",
 "name": "New Product Launch",
 "type": "WHATSAPP_LITE",
 "content": "Check out our new product!",
 "target_type": "TAGS",
 "target_tags": ["VIP", "Customer"],
 "status": "DRAFT",
 "scheduled_at": "2025-02-01T10:00:00Z",
 "timezone": "America/New_York"
}
```

### Send Campaign

**Endpoint:** `POST /functions/v1/send-campaign`

**Request:**
```json
{
 "campaignId": "campaign-uuid"
}
```

### Get Campaign Analytics

**Endpoint:** `GET /rest/v1/notification_logs?campaign_id=eq.{campaign_id}`

---

## Best Practices

1. **Targeting**
 - Use tags for segmentation
 - Test with small group first
 - Exclude opted-out contacts
 - Respect contact preferences

2. **Timing**
 - Send during business hours
 - Consider timezone differences
 - Avoid spam hours
 - Test optimal send times

3. **Content**
 - Keep messages concise
 - Use clear call-to-action
 - Personalize with variables
 - Test before sending

4. **Compliance**
 - Obtain consent
 - Include opt-out option
 - Follow channel guidelines
 - Respect rate limits

5. **Tracking**
 - Monitor delivery rates
 - Track engagement
 - Analyze performance
 - Optimize based on data

---

## Troubleshooting

### Campaign Not Sending

**Issue:** Campaign stuck in SENDING status

**Solutions:**
- Check channel connections
- Verify target contacts exist
- Check rate limits
- Review error logs
- Retry failed messages

### Low Delivery Rate

**Issue:** Many messages failing to deliver

**Solutions:**
- Verify phone number formats
- Check contact opt-in status
- Review channel restrictions
- Check message content
- Verify channel credentials

### Scheduling Issues

**Issue:** Scheduled campaign not sending

**Solutions:**
- Verify scheduled time
- Check timezone settings
- Verify campaign not cancelled
- Check system time
- Review scheduler logs

---

## See also

- [Sequences](https://docs.connectgain.cloud/02-user-guide/campaigns/sequences.md) — automated multi-step drip campaigns
- [Contacts](https://docs.connectgain.cloud/02-user-guide/campaigns/contacts.md) — tagging and segmenting recipients
- [Templates](https://docs.connectgain.cloud/02-user-guide/campaigns/templates.md) — reusable message content
- [Channels](https://docs.connectgain.cloud/02-user-guide/05-integrations/channels.md) — connecting sending channels
- [API Documentation](https://docs.connectgain.cloud/02-user-guide/07-api/complete-api.md) — REST API reference
- [Campaigns on connectgain.cloud](https://connectgain.cloud/en/campaigns) — feature overview on the ConnectGain website

---

**Last Updated:** July 2026

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Company Management for B2B CRM – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/companies/

# Company Management Feature

## Overview

Company Management (`/companies`) is a B2B-focused CRM feature that allows businesses to track and manage company relationships, import company data, merge duplicates, and link companies to contacts and deals. It provides comprehensive company profiles with industry classification, revenue tracking, and address management.

**On this page:** [Features](#features) · [Use Cases](#use-cases) · [Test Cases](#test-cases) · [API Integration](#api-integration) · [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting)

---

## Features

### 1. Company Management

**Create Companies:**
- Add new companies with:
 - Company name
 - Industry
 - Website
 - Address (street, city, state, postal code, country)
 - Phone numbers
 - Email addresses
 - Company size
 - Annual revenue
 - Tags
 - Notes
 - Create deal option during company creation

**Edit Companies:**
- Update company information
- Modify all company fields
- Update relationships

**Delete Companies:**
- Remove companies (contacts preserved)
- Cascade deletion handling

**Company Details View:**
- Comprehensive company profile
- All company information
- Associated contacts
- Related deals
- Activity timeline
- Notes

### 2. Search & Filtering

**Search Companies:**
- Search by:
 - Company name
 - Industry
 - Website
 - Country
- Real-time search results

**Country Filtering:**
- Filter by country
- All countries dropdown
- "No Country" option

**Sorting Options:**
- Alphabetical (A-Z, Z-A)
- Newest added (newest first, oldest first)

### 3. View Modes

**Grid View:**
- Card-based layout
- Company cards with key info
- Quick action buttons
- Visual tags
- Country badges

**Table View:**
- Spreadsheet-style layout
- Sortable columns
- Bulk selection
- Inline actions
- Export capabilities

### 4. Company Import

**CSV Import:**
- Bulk import companies
- Column mapping
- Data validation
- Duplicate detection
- Import progress tracking

### 5. Company Organization

**Tags System:**
- Flexible tagging
- Create custom tags
- Multiple tags per company
- Tag-based filtering

**Contact Association:**
- Link contacts to companies
- Multiple contacts per company
- Contact management from company view

**Deal Association:**
- Track deals by company
- Company-level deal tracking
- Revenue aggregation

### 6. Duplicate Management

**Duplicate Detection:**
- Find and merge duplicates
- Automatic duplicate detection
- Manual merge options
- Merge conflict resolution

### 7. Pagination

**50 Companies Per Page:**
- Efficient loading
- Page navigation
- Total count display

### 8. Company Details

**Company Information:**
- Company name
- Country
- Address
- Website
- Industry
- Company size
- Description
- Linked contacts
- Linked deals

---

## Use Cases

### Use Case 1: Import Companies from HubSpot

**Scenario:**
Company wants to migrate 1,000 companies from HubSpot to ConnectGain.

**Steps:**
1. Export your companies from HubSpot as a CSV (HubSpot company export)
2. Go to Companies → Import from HubSpot
3. Upload the HubSpot export CSV file
4. HubSpot fields are automatically mapped to ConnectGain company fields
5. Review import preview
6. Start import
7. Review import results
8. Verify imported companies

**Expected Outcome:**
All companies imported successfully via CSV, with HubSpot columns auto-mapped. (This is a CSV import, not a live HubSpot API/OAuth connection.)

### Use Case 2: Find Company by Country

**Scenario:**
Sales team wants to find all companies in a specific country.

**Steps:**
1. Go to Companies
2. Select country from filter dropdown
3. View filtered companies
4. Export filtered list if needed

**Expected Outcome:**
All companies in selected country displayed.

### Use Case 3: Merge Duplicate Companies

**Scenario:**
System has duplicate company entries that need merging.

**Steps:**
1. Go to Companies → Find Duplicates
2. Review duplicate suggestions
3. Select companies to merge
4. Choose primary company
5. Review merged data
6. Confirm merge
7. Verify merged company

**Expected Outcome:**
Duplicates merged into single company with all data preserved.

### Use Case 4: Link Company to Deal

**Scenario:**
Create a deal and link it to a company during company creation.

**Steps:**
1. Go to Companies → Add Company
2. Fill company information
3. Optionally create deal:
 - Deal title
 - Contact selection
 - Pipeline selection
 - Stage selection
 - Deal value
4. Save company and deal
5. Verify both created and linked

**Expected Outcome:**
Company and deal created successfully with proper linkage.

---

## Test Cases

### Test Case 1: Create Company

**Test:** Verify company creation

**Steps:**
1. Go to Companies
2. Click "Add Company"
3. Fill in required fields:
 - Name: "Acme Inc"
 - Country: "United States"
4. Add optional fields:
 - Website: "https://acme.com"
 - Industry: "Technology"
5. Click "Save"
6. Verify company appears in list
7. Open company details
8. Verify all data saved correctly

**Expected Result:**
Company created successfully with all data preserved

### Test Case 2: Search Company by Name

**Test:** Verify name search functionality

**Steps:**
1. Create test company: "Acme Inc"
2. Go to Companies
3. Enter "Acme" in search
4. Verify company appears in results
5. Enter "Inc" in search
6. Verify company appears
7. Enter "Acme Inc" in search
8. Verify company appears

**Expected Result:**
Company found by partial and full name

### Test Case 3: Filter by Country

**Test:** Verify country filtering

**Steps:**
1. Create companies in different countries
2. Go to Companies
3. Select country from filter
4. Verify only companies in that country shown
5. Select "All countries"
6. Verify all companies shown

**Expected Result:**
Country filtering works correctly

### Test Case 4: Switch View Modes

**Test:** Verify view mode switching

**Steps:**
1. Go to Companies
2. Verify default grid view
3. Switch to table view
4. Verify table displayed
5. Switch back to grid view
6. Verify cards displayed

**Expected Result:**
View modes switch correctly

### Test Case 5: Sort Companies

**Test:** Verify sorting functionality

**Steps:**
1. Create multiple companies
2. Sort by alphabetical (A-Z)
3. Verify companies sorted correctly
4. Sort by newest
5. Verify newest companies first
6. Sort by oldest
7. Verify oldest companies first

**Expected Result:**
Sorting works correctly for all options

### Test Case 6: Pagination

**Test:** Verify pagination functionality

**Steps:**
1. Create 100+ companies
2. Go to Companies
3. Verify pagination controls appear
4. Navigate to page 2
5. Verify different companies shown
6. Navigate back to page 1
7. Verify original companies shown

**Expected Result:**
Pagination works correctly

### Test Case 7: Delete Company

**Test:** Verify company deletion

**Steps:**
1. Create company
2. Link contact to company
3. Delete company
4. Verify company deleted
5. Verify contact remains (not deleted)

**Expected Result:**
Company deleted, contacts preserved

### Test Case 8: Merge Duplicates

**Test:** Verify duplicate merging

**Steps:**
1. Create duplicate companies
2. Go to Companies → Find Duplicates
3. Select duplicates to merge
4. Choose primary company
5. Merge companies
6. Verify merged company has all data
7. Verify duplicate deleted

**Expected Result:**
Duplicates merged correctly

---

## API Integration

### Create Company

**Endpoint:** `POST /rest/v1/companies`

**Request:**
```json
{
 "organization_id": "org-uuid",
 "name": "Acme Inc",
 "country": "United States",
 "website": "https://acme.com",
 "industry": "Technology"
}
```

### Search Companies

**Endpoint:** `POST /functions/v1/search-companies`

**Request:**
```json
{
 "searchTerm": "Acme",
 "country": "United States"
}
```

### Merge Companies

**Endpoint:** `POST /functions/v1/find-duplicate-companies`

**Request:**
```json
{
 "companyIds": ["uuid1", "uuid2"],
 "primaryCompanyId": "uuid1"
}
```

---

## Best Practices

1. **Data Quality**
 - Use consistent company name format
 - Standardize country names
 - Keep company data updated

2. **Organization**
 - Link contacts to companies
 - Use company hierarchy when applicable
 - Tag companies for categorization

3. **Import**
 - Clean data before import
 - Map fields carefully
 - Review preview before importing
 - Handle duplicates appropriately

4. **Search**
 - Use specific search terms
 - Combine with country filter for precision
 - Use table view for detailed comparison

5. **Maintenance**
 - Regular duplicate cleanup
 - Update company information
 - Review and merge duplicates regularly

---

## Troubleshooting

### Import Errors

**Issue:** Companies not importing

**Solutions:**
- Check CSV format
- Verify field mapping
- Check data validation errors
- Review import logs

### Search Not Finding Companies

**Issue:** Known companies not appearing in search

**Solutions:**
- Check search term spelling
- Verify country filter
- Check organization filter
- Try different search terms

### Duplicate Companies

**Issue:** Multiple entries for same company

**Solutions:**
- Use duplicate detection tool
- Merge duplicates
- Standardize import process
- Use unique identifiers

---

## See also

- [Contacts](https://docs.connectgain.cloud/02-user-guide/companies/contacts.md) — the people linked to each company
- [Deals](https://docs.connectgain.cloud/02-user-guide/companies/deals.md) — tracking deals at the company level
- [Tasks](https://docs.connectgain.cloud/02-user-guide/companies/tasks.md) — follow-up tasks for accounts
- [API Documentation](https://docs.connectgain.cloud/02-user-guide/07-api/complete-api.md) — REST API reference
- [Companies on connectgain.cloud](https://connectgain.cloud/en/companies) — feature overview on the ConnectGain website

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Contact Management & CRM Database – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/contacts/

# Contact Management Feature

## Overview

Contact Management (`/contacts`) is the core CRM feature of ConnectGain, providing comprehensive contact database management with advanced search, filtering, tagging, custom fields, and integration with deals, conversations, and tasks. It enables businesses to organize, segment, and manage customer relationships effectively.

**On this page:** [Features](#features) · [Use Cases](#use-cases) · [Test Cases](#test-cases) · [API Integration](#api-integration) · [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting)

---

## Features

### 1. Contact Management

**Create Contacts:**
- Add new contacts manually with:
 - First name, last name
 - Multiple phone numbers
 - Multiple email addresses
 - Company association
 - Tags
 - Custom fields
 - Opt-in status
 - Notes
 - Create deal option during contact creation

**Edit Contacts:**
- Update contact information
- Modify all contact fields
- Update relationships

**Delete Contacts:**
- Remove contacts (with cascade protection)
- Bulk delete operations

**Bulk Operations:**
- Bulk import from CSV
- Bulk export to CSV
- Bulk delete
- Bulk merge
- Bulk marketing opt-in / opt-out
- Bulk add / remove tags

**Contact Details View:**
- Comprehensive contact profile
- All contact information
- Communication history
- Related deals
- Related tasks
- Notes timeline
- Activity log

### 2. Search & Filtering

**Advanced Search:**
- Search by:
 - Name (first, last, full)
 - Phone number (partial matching)
 - Email address
 - Company name
 - Tags
 - Custom fields
- Real-time search results

**Tag Filtering:**
- Filter by contact tags
- All tags dropdown
- Multiple tag selection

> Open-deal counts appear as badges on contacts for reference; they are not a filter option.

**Sorting Options:**
- Alphabetical (A-Z, Z-A)
- Newest added (newest first, oldest first)

### 3. View Modes

**Grid View (default):**
- Card-based layout
- Contact cards with key info
- Quick action buttons
- Visual tags
- Company badges

**Table View:**
- Spreadsheet-style layout
- Bulk selection
- Inline actions
- Export capabilities

(Only Grid and Table views exist. On mobile, Grid is used.)

### 4. Contact Organization

**Tags System:**
- Flexible tagging
- Create custom tags
- Multiple tags per contact
- Tag-based filtering
- Auto-tagging by country
- Tag management

**Company Association:**
- Link contacts to companies
- Company selection
- Company creation from contact
- Company details view

**Custom Fields:**
- Extend contact data
- Text fields
- Number fields
- Date fields
- Dropdown fields

### 5. Custom Fields

**Field Types:**
- Text
- Number
- Date
- Boolean
- Dropdown
- Multi-select

**Use Cases:**
- Store industry-specific data
- Track custom attributes
- Integration with external systems

### 6. Contact Import

**CSV Import:**
- Bulk import contacts
- Column mapping
- Data validation
- Duplicate detection
- Import progress tracking
- Error reporting

**HubSpot Import:**
- CSV import using a HubSpot-export column mapping (no direct HubSpot API/OAuth connection; routed through the standard `import-contacts` function)

**Duplicate Detection:**
- Find and merge duplicates
- Automatic duplicate detection
- Manual merge options
- Merge conflict resolution

### 7. Contact Actions

**Quick Actions:**
- View contact details
- Edit contact
- Delete contact
- Send message
- Make phone call
- Open WhatsApp
- Copy phone number
- Copy email address

**Bulk Actions:**
- Export selected contacts
- Delete selected contacts
- Merge selected contacts
- Add / remove tags on selected contacts
- Set marketing opt-in / opt-out

### 8. Contact Analytics

**Deal Count:**
- Number of open deals per contact

**Notes Count:**
- Number of notes per contact

**Activity Timeline:**
- Recent activity tracking

**Engagement Metrics:**
- Message frequency
- Last contact date

### 9. Pagination

**50 Contacts Per Page:**
- Efficient loading
- Page navigation
- Total count display

### 10. Auto-Tagging

**Country-Based Tagging:**
- Automatically tag contacts by country
- Phone number analysis
- Country code detection
- Batch processing
- Progress tracking
- Completion notifications

### 11. Call Tracking

**Call Features:**
- Initiate calls from contact card
- Initiate calls from contact details
- Call event tracking
- Call history per contact
- Call status tracking (INITIATED, CONNECTED, COMPLETED, MISSED, FAILED)
- Call duration tracking
- Call notes
- Link calls to conversations

**Call Actions:**
- Click phone icon to initiate call
- Opens device phone dialer
- Automatically records call event
- Tracks call status and duration
- Add call notes after completion

### 12. Contact Relationships

**Relationships:**
- Company association
- Deal association
- Conversation association
- Task association
- Note association

### 13. Contact Assignment

**Assignment Features:**
- Assign a contact to a team member via the contact form ("Assign To")
- Reassign by editing the contact

---

## Use Cases

### Use Case 1: Import Existing Customer Database

**Scenario:**
Company wants to migrate 5,000 contacts from Excel to ConnectGain.

**Steps:**
1. Export contacts from Excel to CSV
2. Go to Contacts → Import
3. Upload CSV file
4. Map CSV columns to ConnectGain fields
5. Review import preview
6. Configure duplicate handling
7. Start import
8. Review import results
9. Fix any errors
10. Verify imported contacts

**Expected Outcome:**
All contacts imported successfully with proper field mapping.

### Use Case 2: Find Contact by Phone Number

**Scenario:**
Customer calls, agent needs to find contact quickly.

**Steps:**
1. Go to Contacts
2. Enter phone number in search
3. View search results
4. Click on matching contact
5. View contact details and history

**Expected Outcome:**
Contact found instantly with full history visible.

### Use Case 3: Tag Contacts for Campaign

**Scenario:**
Marketing wants to send campaign to "VIP Customers" only.

**Steps:**
1. Go to Contacts
2. Filter contacts by criteria (e.g., deals > $10,000)
3. Select all filtered contacts
4. Add tag "VIP Customer"
5. Go to Broadcast (`/broadcast`)
6. Create a campaign targeting the "VIP Customer" tag
7. Send campaign

**Expected Outcome:**
Campaign sent only to VIP customers.

### Use Case 4: Merge Duplicate Contacts

**Scenario:**
System has duplicate contacts that need merging.

**Steps:**
1. Go to Contacts → Find Duplicates
2. Review duplicate suggestions
3. Select contacts to merge
4. Choose primary contact
5. Review merged data
6. Confirm merge
7. Verify merged contact

**Expected Outcome:**
Duplicates merged into single contact with all data preserved.

### Use Case 5: Assign Contacts to Sales Team

**Scenario:**
Sales manager wants to distribute contacts evenly among team.

**Steps:**
1. Go to Contacts
2. Filter contacts (e.g., no assignee, tag "Lead")
3. Select contacts to assign
4. Click "Assign"
5. Select team member
6. Confirm assignment
7. Verify assignments

**Expected Outcome:**
Contacts distributed evenly among sales team.

---

## Test Cases

### Test Case 1: Create Contact

**Test:** Verify contact creation

**Steps:**
1. Go to Contacts
2. Click "New Contact"
3. Fill in required fields:
 - First Name: "John"
 - Last Name: "Doe"
 - Phone: "+1234567890"
 - Email: "john@example.com"
4. Add optional fields:
 - Company: "Acme Inc"
 - Tags: ["Customer", "VIP"]
 - Custom Fields: { "Industry": "Technology" }
5. Click "Save"
6. Verify contact appears in list
7. Open contact details
8. Verify all data saved correctly

**Expected Result:**
Contact created successfully with all data preserved

### Test Case 2: Search Contact by Name

**Test:** Verify name search functionality

**Steps:**
1. Create test contact: "John Doe"
2. Go to Contacts
3. Enter "John" in search
4. Verify contact appears in results
5. Enter "Doe" in search
6. Verify contact appears
7. Enter "John Doe" in search
8. Verify contact appears
9. Enter "Doe John" in search
10. Verify contact appears (reversed name)

**Expected Result:**
Contact found by first name, last name, full name, and reversed name

### Test Case 3: Search Contact by Phone

**Test:** Verify phone number search

**Steps:**
1. Create contact with phone: "+1234567890"
2. Search for "1234567890"
3. Verify contact found
4. Search for "234567890"
5. Verify contact found (partial match)
6. Search for "+1-234-567-890"
7. Verify contact found (formatted number)

**Expected Result:**
Contact found by full phone, partial phone, and formatted phone

### Test Case 4: Bulk Import Contacts

**Test:** Verify CSV import functionality

**Steps:**
1. Create CSV file with 100 contacts
2. Go to Contacts → Import
3. Upload CSV file
4. Map columns:
 - First Name → first_name
 - Last Name → last_name
 - Email → emails
 - Phone → phones
5. Review preview
6. Start import
7. Wait for import completion
8. Verify import results:
 - Success count: 100
 - Error count: 0
9. Verify contacts in list
10. Check imported data accuracy

**Expected Result:**
All contacts imported successfully with correct data mapping

### Test Case 5: Update Contact

**Test:** Verify contact update functionality

**Steps:**
1. Create contact
2. Open contact details
3. Click "Edit"
4. Update fields:
 - Change first name
 - Add phone number
 - Add tag
 - Update custom field
5. Save changes
6. Verify updates reflected
7. Check updated_at timestamp

**Expected Result:**
Contact updated successfully with all changes preserved

### Test Case 6: Delete Contact

**Test:** Verify contact deletion

**Steps:**
1. Create contact
2. Create related conversation
3. Create related deal
4. Create related task
5. Delete contact
6. Verify contact deleted
7. Verify cascade deletion:
 - Conversation deleted
 - Deal deleted
 - Task deleted

**Expected Result:**
Contact and all related data deleted (cascade)

### Test Case 7: Tag Management

**Test:** Verify tagging functionality

**Steps:**
1. Create contact
2. Add tag "Customer"
3. Add tag "VIP"
4. Verify tags displayed
5. Remove tag "Customer"
6. Verify tag removed
7. Filter contacts by tag "VIP"
8. Verify contact appears in filtered list
9. Bulk tag multiple contacts
10. Verify all contacts tagged

**Expected Result:**
Tag management works correctly for single and bulk operations

### Test Case 8: Custom Fields

**Test:** Verify custom fields functionality

**Steps:**
1. Go to Contacts
2. Edit a contact
3. Add a custom field (e.g. "Industry" = "Technology")
4. Save contact
5. Verify custom field saved
6. Reopen the contact and verify the custom field persists

**Expected Result:**
Custom fields can be added to a contact and saved

### Test Case 9: Contact Assignment

**Test:** Verify contact assignment

**Steps:**
1. Create contact
2. Verify no assignee
3. Assign to user "John Smith"
4. Verify assignee set
5. Filter contacts by assignee
6. Verify contact appears
7. Reassign to "Jane Doe"
8. Verify assignee updated
9. Bulk assign multiple contacts
10. Verify all contacts assigned

**Expected Result:**
Contact assignment works for single and bulk operations

### Test Case 10: Duplicate Detection

**Test:** Verify duplicate detection and merging

**Steps:**
1. Create contact: "John Doe", "+1234567890"
2. Create duplicate contact: "John Doe", "+1234567890"
3. Go to Contacts → Find Duplicates
4. Verify duplicates detected
5. Select both contacts
6. Choose primary contact
7. Merge contacts
8. Verify merged contact has all data
9. Verify duplicate contact deleted

**Expected Result:**
Duplicates detected and merged correctly

### Test Case 11: Contact Views

**Test:** Verify different view modes

**Steps:**
1. Go to Contacts
2. Switch to Grid view
3. Verify cards displayed
4. Switch to Table view
5. Verify table displayed
6. Test sorting in table view
7. Test filtering in both views
8. Verify data consistency

**Expected Result:**
All view modes work correctly with consistent data

### Test Case 12: Contact Export

**Test:** Verify contact export

**Steps:**
1. Create 10 test contacts
2. Go to Contacts
3. Click "Export"
4. Select export format: CSV
5. Select fields to export
6. Download file
7. Open CSV file
8. Verify all contacts exported
9. Verify data accuracy

**Expected Result:**
Contacts exported correctly with accurate data

---

## API Integration

### Create Contact

**Endpoint:** `POST /rest/v1/contacts`

**Request:**
```json
{
 "organization_id": "org-uuid",
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+1234567890"],
 "emails": ["john@example.com"],
 "tags": ["customer", "vip"],
 "custom_fields": {
 "industry": "Technology"
 }
}
```

### Search Contacts

**Endpoint:** `POST /functions/v1/search-contacts`

**Request:**
```json
{
 "searchTerm": "John",
 "tags": ["customer"],
 "dealStatus": "open"
}
```

### Bulk Import

**Endpoint:** `POST /functions/v1/import-contacts`

**Request:**
```json
{
 "csvData": "First Name,Last Name,Email\nJohn,Doe,john@example.com",
 "organizationId": "org-uuid"
}
```

---

## Best Practices

1. **Data Quality**
 - Use consistent phone number format
 - Validate email addresses
 - Keep names standardized
 - Use tags consistently

2. **Organization**
 - Use tags for categorization
 - Assign contacts to team members
 - Link contacts to companies
 - Keep custom fields organized

3. **Import**
 - Clean data before import
 - Map fields carefully
 - Review preview before importing
 - Handle duplicates appropriately

4. **Search**
 - Use specific search terms
 - Combine filters for precision
 - Save frequently used searches
 - Use tags for quick filtering

5. **Maintenance**
 - Regular duplicate cleanup
 - Update contact information
 - Archive inactive contacts
 - Review and update tags

---

## Troubleshooting

### Import Errors

**Issue:** Contacts not importing

**Solutions:**
- Check CSV format
- Verify field mapping
- Check data validation errors
- Review import logs

### Search Not Finding Contacts

**Issue:** Known contacts not appearing in search

**Solutions:**
- Check search term spelling
- Verify phone number format
- Check organization filter
- Try different search terms

### Duplicate Contacts

**Issue:** Multiple entries for same contact

**Solutions:**
- Use duplicate detection tool
- Merge duplicates
- Standardize import process
- Use unique identifiers

---

## See also

- [Companies](https://docs.connectgain.cloud/02-user-guide/contacts/companies.md) — organizing contacts by company
- [Deals](https://docs.connectgain.cloud/02-user-guide/contacts/deals.md) — pipeline deals linked to contacts
- [Tasks](https://docs.connectgain.cloud/02-user-guide/contacts/tasks.md) — follow-up tasks linked to contacts
- [Inbox](https://docs.connectgain.cloud/02-user-guide/contacts/inbox.md) — conversations tied to each contact
- [API Documentation](https://docs.connectgain.cloud/02-user-guide/07-api/complete-api.md) — REST API reference
- [Contacts & CRM on connectgain.cloud](https://connectgain.cloud/en/contacts) — feature overview on the ConnectGain website

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Dashboard Widgets & Real-Time Metrics – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/dashboard/

# Dashboard & Analytics Feature

## Overview

The Dashboard (`/dashboard`) is the central command center of ConnectGain, providing real-time insights, metrics, and customizable widgets to monitor your business performance at a glance. It serves as the primary interface for tracking communication metrics, sales performance, task completion, and contact growth.

**On this page:** [Features](#features) · [Use Cases](#use-cases) · [Test Cases](#test-cases) · [API Integration](#api-integration) · [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting)

---

## Features

### 1. Communication Metrics Widgets

**Incoming Messages:**
- Real-time count of messages received across all channels
- Channel breakdown ([WhatsApp Lite](https://docs.connectgain.cloud/02-user-guide/05-integrations/whatsapp-lite-api.md), WhatsApp Cloud, Facebook Messenger, Instagram)
- Click-through to channel settings
- Date range filtering (Today, Yesterday, This Week, This Month, Custom Range)
- Comparison with previous period
- Percentage change indicators

**Ongoing Conversations:**
- Active conversation count
- Real-time updates
- Period-over-period comparison
- Visual trend indicators

**Unread Conversations:**
- Conversations with unread messages
- SLA tracking
- Priority indicators
- Quick action buttons

**Online Agents:**
- Count and list of agents currently online
- At-a-glance team availability

**Median Reply Time:**
- Average response time across team
- Performance benchmarking
- Historical trends

**Longest Awaiting Reply:**
- Oldest unresponded conversation
- Urgency indicators
- Direct link to conversation

### 2. Sales & Deals Widgets

**Won Leads:**
- Successfully closed deals
- Value tracking
- Period comparison
- Conversion metrics

**Active Leads:**
- Deals in pipeline
- Stage breakdown
- Value aggregation

**Lead Sources:**
- Origin tracking for leads
- Channel attribution
- Source performance

**Active Deals:**
- Current pipeline value
- Deal count
- Total value

### 3. Tasks & Contacts Widgets

**Tasks Overview:**
- Task completion metrics
- Overdue tasks count
- Completion rate
- Priority breakdown

**Total Companies:**
- Company database size
- Growth tracking

**Total Contacts:**
- Contact database size
- Growth metrics
- Period comparison

**Upcoming Meetings:**
- Next scheduled meetings / bookings
- Quick view of what's coming up

### 4. Custom Widgets

**Create Custom Metrics:**
- Build personalized widgets
- Query any database table
- Aggregation options (Count, Sum, Average, Min, Max)
- Format options (Number, Currency, Percentage, Time Duration)
- Custom positioning
- Show/hide controls

### 5. Performance Charts

**4-Week Performance Overview:**
- Visual trend analysis
- Conversations over time
- Deals closed tracking
- New contacts growth
- Interactive charts

### 6. Recent Activity Feed

**Live Activity Stream:**
- Latest platform events
- New messages
- Deal updates
- New contacts
- Clickable items for quick navigation
- Time-ago indicators

### 7. Dashboard Customization

**Drag-and-Drop Widgets:**
- Reorder predefined widgets
- Hide/Show widgets
- Customize visible metrics

**Date Range Selection:**
- Today, Yesterday, This Week, This Month
- Custom date range picker
- Saved preferences

**Widget Management:**
- Add, edit, delete custom widgets
- Widget positioning
- Widget visibility controls

---

## Use Cases

### Use Case 1: Daily Performance Monitoring

**Scenario:**
A sales manager wants to monitor daily team performance.

**Steps:**
1. Open Dashboard
2. Set date range to "Today"
3. View widget metrics:
 - Incoming Messages (target: < 10)
 - Unread Conversations (target: 0)
 - Active Leads (target: > 20)
 - Tasks Completed (target: > 5)
4. Review recent activity feed
5. Check performance charts for trends

**Expected Outcome:**
Manager sees real-time performance metrics and can identify areas needing attention.

### Use Case 2: Weekly Team Review

**Scenario:**
Team lead conducts weekly performance review.

**Steps:**
1. Open Dashboard
2. Set date range to "Last 7 days"
3. Review all widget metrics
4. Analyze performance charts
5. Export metrics report
6. Share with team

**Expected Outcome:**
Team lead has comprehensive weekly performance data for team meeting.

### Use Case 3: Custom Metric Tracking

**Scenario:**
Business wants to track custom metric (e.g., high-value deals).

**Steps:**
1. Open Dashboard
2. Click "Add Widget"
3. Select "Custom Widget"
4. Configure query:
 - Table: `deals`
 - Filter: `value > 10000`
 - Aggregation: `COUNT`
5. Set title: "High-Value Deals"
6. Save widget
7. Position widget on dashboard

**Expected Outcome:**
Custom metric displayed on dashboard and tracked over time.

### Use Case 4: Executive Dashboard

**Scenario:**
Executive needs high-level overview of business metrics.

**Steps:**
1. Configure dashboard with key widgets:
 - Total Contacts
 - Active Deals
 - Won Leads
 - Total Revenue
2. Hide detailed widgets
3. Set default view
4. Share dashboard link

**Expected Outcome:**
Executive has clean, focused dashboard with key metrics.

---

## Test Cases

### Test Case 1: Widget Display

**Test:** Verify widgets display correct data

**Steps:**
1. Open Dashboard
2. Verify each widget displays data
3. Check data accuracy against source tables
4. Verify date range filtering works

**Expected Result:**
All widgets display accurate, up-to-date data

**Test Data:**
- Create test contacts, deals, conversations
- Verify widget counts match actual data

### Test Case 2: Widget Customization

**Test:** Verify widget customization functionality

**Steps:**
1. Click "Add Widget"
2. Select widget type
3. Configure widget settings
4. Save widget
5. Drag widget to new position
6. Hide widget
7. Show hidden widget
8. Delete widget

**Expected Result:**
Widget customization works correctly

### Test Case 3: Date Range Filtering

**Test:** Verify date range filtering

**Steps:**
1. Set date range to "Today"
2. Verify widget data updates
3. Set date range to "Last 7 days"
4. Verify widget data updates
5. Set custom date range
6. Verify widget data updates

**Expected Result:**
All widgets correctly filter by selected date range

### Test Case 4: Performance Charts

**Test:** Verify performance charts display correctly

**Steps:**
1. Open Dashboard
2. Verify charts render
3. Check chart data accuracy
4. Change date range
5. Verify charts update
6. Test different chart types

**Expected Result:**
Charts display accurate data and update correctly

### Test Case 5: Recent Activity Feed

**Test:** Verify recent activity feed

**Steps:**
1. Perform various actions (send message, create deal, etc.)
2. Open Dashboard
3. Verify activities appear in feed
4. Check activity timestamps
5. Verify activity details

**Expected Result:**
Activity feed shows recent activities in real-time

### Test Case 6: Real-time Updates

**Test:** Verify dashboard updates in real-time

**Steps:**
1. Open Dashboard
2. Note current widget values
3. Perform action (create contact, send message)
4. Verify widgets update automatically
5. Check activity feed updates

**Expected Result:**
Dashboard updates in real-time without refresh

### Test Case 7: Custom Widget Creation

**Test:** Verify custom widget creation

**Steps:**
1. Click "Add Widget" → "Custom"
2. Pick a source table
3. Choose an aggregation (Count, Sum, Average, Min, Max)
4. Set title and format
5. Save widget
6. Verify widget displays correct data
7. Edit widget
8. Delete widget

**Expected Result:**
Custom widgets can be created, edited, and deleted

### Test Case 8: Dashboard Persistence

**Test:** Verify dashboard configuration persists

**Steps:**
1. Configure dashboard layout
2. Add/remove widgets
3. Set date range
4. Refresh page
5. Verify configuration persists
6. Log out and log back in
7. Verify configuration persists

**Expected Result:**
Dashboard configuration persists across sessions

### Test Case 9: Multi-User Dashboard

**Test:** Verify dashboard works for multiple users

**Steps:**
1. User A configures dashboard
2. User B logs in
3. Verify User B sees default dashboard
4. User B configures dashboard
5. Verify User A's dashboard unchanged
6. Verify User B's dashboard saved

**Expected Result:**
Each user has independent dashboard configuration

### Test Case 10: Performance with Large Datasets

**Test:** Verify dashboard performance with large data

**Steps:**
1. Import 10,000+ contacts
2. Create 1,000+ deals
3. Create 5,000+ conversations
4. Open Dashboard
5. Measure load time
6. Verify widgets load correctly
7. Test date range filtering performance

**Expected Result:**
Dashboard loads within acceptable time (< 3 seconds)

---

## API Integration

### Get Dashboard Metrics

**Endpoint:** `GET /rest/v1/dashboard_widgets`

**Query Parameters:**
- `organization_id` - Filter by organization
- `is_visible` - Filter visible widgets only

**Response:**
```json
{
 "widgets": [
 {
 "id": "uuid",
 "widget_type": "incoming_messages",
 "widget_config": {
 "title": "Incoming Messages",
 "query": "SELECT COUNT(*) FROM messages WHERE direction = 'INBOUND'",
 "date_range": "today"
 },
 "value": 42,
 "position": 0,
 "is_visible": true
 }
 ]
}
```

### Create Custom Widget

**Endpoint:** `POST /rest/v1/dashboard_widgets`

**Request Body:**
```json
{
 "organization_id": "org-uuid",
 "widget_type": "custom",
 "widget_config": {
 "title": "High-Value Deals",
 "table": "deals",
 "aggregation": "count"
 },
 "position": 5,
 "is_visible": true
}
```

---

## Best Practices

1. **Widget Organization**
 - Group related widgets together
 - Place most important widgets at top
 - Limit to 12-15 widgets for performance

2. **Date Range Selection**
 - Use "Today" for daily monitoring
 - Use "Last 7 days" for weekly reviews
 - Use "Last 30 days" for monthly analysis

3. **Custom Widgets**
 - Keep queries simple and optimized
 - Use appropriate aggregations
 - Test queries before creating widgets

4. **Performance**
 - Hide unused widgets
 - Use date range filtering to limit data
 - Refresh dashboard periodically

5. **Sharing**
 - Export dashboard reports for stakeholders
 - Use screenshots for presentations
 - Share dashboard links for real-time access

---

## Troubleshooting

### Widgets Not Loading

**Issue:** Widgets show loading state indefinitely

**Solutions:**
- Check database connection
- Verify the selected table and aggregation for custom widgets
- Check date range validity
- Refresh page

### Incorrect Data

**Issue:** Widget shows incorrect data

**Solutions:**
- Verify date range selection
- Check organization filter
- Verify the table and aggregation chosen for custom widgets
- Check data in source tables

### Performance Issues

**Issue:** Dashboard loads slowly

**Solutions:**
- Reduce number of widgets
- Use date range filtering
- Optimize custom widget queries
- Check database indexes

---

## See also

- [Analytics](https://docs.connectgain.cloud/02-user-guide/dashboard/analytics.md) — deeper reporting beyond dashboard widgets
- [Sales Report](https://docs.connectgain.cloud/02-user-guide/dashboard/sales-report.md) — pipeline and revenue reporting
- [Inbox](https://docs.connectgain.cloud/02-user-guide/dashboard/inbox.md) — the conversations behind your communication metrics
- [Deals](https://docs.connectgain.cloud/02-user-guide/dashboard/deals.md) — the pipeline data behind sales widgets
- [API Documentation](https://docs.connectgain.cloud/02-user-guide/07-api/complete-api.md) — REST API reference
- [Dashboard on connectgain.cloud](https://connectgain.cloud/en/dashboard) — feature overview on the ConnectGain website

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Sales Pipeline & Deal Management – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/deals/

# Deal Pipeline Management Feature

## Overview

Deal Pipeline Management (`/deals`) provides a complete sales CRM solution with visual kanban boards, customizable pipelines, deal stages, value tracking, and integration with contacts, tasks, and conversations. It enables sales teams to track opportunities from initial contact through to closed deals.

**On this page:** [Features](#features) · [Use Cases](#use-cases) · [Test Cases](#test-cases) · [API Integration](#api-integration) · [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting)

---

## Features

### 1. Deal Pipeline Management

**Multiple Pipelines:**
- Create custom sales pipelines
- Pipeline creation, editing, deletion
- Set default pipeline
- Pipeline switching

**Custom Stages:**
- Define pipeline stages
- Stage name, color coding, order
- Default stages: Deal, Qualified, Proposal, Negotiation, Closed Won, Closed Lost

**Visual Kanban Board:**
- Drag-and-drop deal management
- Column-based layout
- Drag deals between stages
- Visual stage indicators
- Deal count per stage
- Stage value totals

### 2. Deal Management

**Create Deals:**
- Add new deals with:
 - Deal title, description
 - Contact association
 - Company association
 - Pipeline selection
 - Initial stage
 - Deal value (currency)
 - Probability percentage
 - Owner assignment
 - Tags
 - Expected close date
 - Custom fields

**Edit Deals:**
- Update deal information
- All deal fields editable
- Stage changes tracked
- Activity timeline

**Delete Deals:**
- Remove deals

**Deal Details View:**
- Comprehensive deal profile
- All deal information
- Contact/company details
- Activity timeline
- Notes
- Attachments
- Related tasks
- Stage history

### 3. Pipeline Management

**Pipeline Features:**
- Multiple pipelines
- Custom stages
- Stage colors
- Stage order
- Default pipeline
- Pipeline templates

**Stage Configuration:**
- Stage name
- Stage color
- Stage probability
- Stage order
- Stage requirements

### 4. Kanban Board View

**Board Features:**
- Drag-and-drop deal movement
- Stage columns
- Deal cards
- Quick actions
- Stage totals
- Value totals

**Card Information:**
- Deal title
- Contact name
- Deal value
- Probability
- Assignee
- Tags
- Due date

### 5. Deal Filtering

**Value Range Filter:**
- Filter by deal value
- Minimum value
- Maximum value
- Validation (max > min)

**Owner Filter:**
- Filter by deal owner
- All assignees
- Specific team member

**Tag Filtering:**
- Filter by deal tags
- Multiple tag selection
- Tag badges

**Pipeline Filtering:**
- Filter by pipeline
- Pipeline selector
- Default pipeline

### 6. Deal Assignment

**Assignment Features:**
- Assign to team member
- Reassign deals
- Bulk assignment
- Assignment history
- Auto-assignment rules

### 7. Deal Tracking

**Deal Value Tracking:**
- Monetary value tracking
- Currency support
- Value aggregation
- Stage value totals

**Probability Tracking:**
- Win probability percentage
- Stage-based defaults
- Manual adjustment

**Expected Close Date:**
- Timeline tracking
- Date picker
- Overdue indicators

**Deal Activity:**
- Complete activity log
- Stage changes
- Value updates
- Owner changes
- Notes added
- Tasks created

### 8. Deal Ownership Tracking

**Ownership History:**
- Complete audit trail of all ownership changes
- Duration with each owner tracked automatically
- Change timestamps recorded
- Change reasons logged (Initial assignment, Reassigned, Unassigned, Auto-reassigned)
- Changed by user tracking
- Real-time history updates

**Ownership History View:**
- Timeline of all ownership changes
- Duration calculations (days with each owner)
- Owner information display
- Change reason display
- Visual timeline interface
- Accessible from deal details

**Automatic Reassignment:**
- Round-robin assignment for inactive deals
- Configurable inactivity threshold (default: 7 days)
- Only reassigns to active users (is_online = true)
- Automatic logging of reassignments
- Prevents deal stagnation
- Fair workload distribution

**Performance Metrics:**
- Average time deals spend with each owner
- Deal handling time per team member
- Ownership change frequency tracking
- Bottleneck identification
- Workload distribution analysis

**Manual Reassignment:**
- Manager can manually reassign deals
- System logs all manual changes
- Duration calculated automatically
- Reason recorded for audit trail

**Database Integration:**
- `deal_owner_history` table stores all changes
- Automatic trigger on owner changes
- Duration calculation on reassignment
- Secure RLS policies for access control

### 9. Deal Actions

**Quick Actions:**
- View deal details
- Edit deal
- Delete deal
- Change stage (drag-and-drop)
- Assign owner
- Add tags
- Add notes
- Create task

**Bulk Actions:**
- Bulk stage change
- Bulk owner assignment
- Bulk delete

### 10. Pipeline Analytics

**Stage Distribution:**
- Visual breakdown
- Deal count per stage
- Value per stage
- Conversion funnel

**Pipeline Performance:**
- Performance metrics
- Average deal value
- Average deal duration
- Win rate
- Loss rate

### 11. Deal Cards

**Visual Deal Cards:**
- Information-rich cards
- Deal title
- Contact/company name
- Deal value
- Owner avatar
- Tags
- Stage indicator
- Quick actions

---

## Use Cases

### Use Case 1: Sales Team Managing Pipeline

**Scenario:**
Sales team tracks deals through sales process.

**Steps:**
1. Create deal from qualified lead
2. Set initial stage: "Deal"
3. Set value: $10,000
4. Assign to sales rep
5. Move deal through stages:
 - Deal → Qualified
 - Qualified → Proposal
 - Proposal → Negotiation
 - Negotiation → Closed Won
6. Update value as deal progresses
7. Add notes at each stage
8. Create tasks for follow-ups
9. Close deal as Won
10. Review pipeline metrics

**Expected Outcome:**
Deal tracked through complete sales cycle with full history.

### Use Case 2: Sales Manager Pipeline Review

**Scenario:**
Sales manager reviews team pipeline weekly.

**Steps:**
1. Open Deals page
2. Select pipeline
3. Review deals by stage
4. Check stage totals
5. Review value totals
6. Filter by assignee
7. Review individual rep performance
8. Identify deals needing attention
9. Reassign deals if needed
10. Export pipeline report

**Expected Outcome:**
Manager has complete pipeline visibility and can take action.

### Use Case 3: Deal Forecasting

**Scenario:**
Sales team needs revenue forecast.

**Steps:**
1. Open Deals page
2. Filter deals by stage (exclude Closed Lost)
3. Calculate weighted value:
 - Value × Probability
4. Sum weighted values
5. Add closed won deals value
6. Generate forecast report
7. Compare to target
8. Identify gaps

**Expected Outcome:**
Accurate revenue forecast based on pipeline data.

### Use Case 4: Deal Conversion from Conversation

**Scenario:**
Customer inquiry converts to deal.

**Steps:**
1. Customer sends message via WhatsApp
2. Sales rep responds
3. Qualifies customer need
4. Creates deal from conversation
5. Links deal to contact
6. Sets initial stage: "Qualified"
7. Sets value based on discussion
8. Creates follow-up task
9. Moves deal through pipeline
10. Closes deal as Won

**Expected Outcome:**
Conversation seamlessly converts to tracked deal.

---

## Test Cases

### Test Case 1: Create Deal

**Test:** Verify deal creation

**Steps:**
1. Go to Deals
2. Click "New Deal"
3. Fill in required fields:
 - Title: "New Customer Deal"
 - Contact: Select contact
 - Pipeline: Select pipeline
 - Stage: "Deal"
 - Value: 5000
4. Add optional fields:
 - Probability: 10
 - Expected Close Date: Future date
 - Tags: ["New", "Hot"]
5. Save deal
6. Verify deal appears in kanban board
7. Verify deal in correct stage column
8. Open deal details
9. Verify all data saved

**Expected Result:**
Deal created successfully with all data preserved

### Test Case 2: Move Deal Between Stages

**Test:** Verify stage movement

**Steps:**
1. Create deal in "Deal" stage
2. Drag deal to "Qualified" stage
3. Verify deal moved
4. Verify stage updated
5. Verify probability updated (if stage has default probability)
6. Check deal history
7. Verify stage change recorded
8. Move deal to "Closed Won"
9. Verify deal moved to closed stage
10. Verify deal marked as won

**Expected Result:**
Deal moves between stages correctly with history tracking

### Test Case 3: Update Deal Value

**Test:** Verify value updates

**Steps:**
1. Create deal with value: 5000
2. Open deal details
3. Update value to 7500
4. Save changes
5. Verify value updated
6. Check deal history
7. Verify value change recorded
8. Update value multiple times
9. Verify all changes tracked

**Expected Result:**
Deal value updates correctly with history

### Test Case 4: Assign Deal

**Test:** Verify deal assignment

**Steps:**
1. Create unassigned deal
2. Click "Assign"
3. Select team member
4. Confirm assignment
5. Verify deal assigned
6. Filter deals by assignee
7. Verify deal appears
8. Reassign to different team member
9. Verify reassignment works
10. Bulk assign multiple deals
11. Verify all deals assigned

**Expected Result:**
Deal assignment works for single and bulk operations

### Test Case 5: Filter Deals

**Test:** Verify filtering functionality

**Steps:**
1. Create multiple deals:
 - Different stages
 - Different assignees
 - Different values
 - Different tags
2. Filter by stage: "Deal"
3. Verify only deals in that stage shown
4. Filter by assignee
5. Verify only assigned deals shown
6. Filter by value range: 5000-10000
7. Verify only deals in range shown
8. Filter by tags
9. Verify only tagged deals shown
10. Combine multiple filters
11. Verify combined filter works

**Expected Result:**
All filters work correctly individually and combined

### Test Case 6: Create Pipeline

**Test:** Verify pipeline creation

**Steps:**
1. Go to Deals → Pipelines
2. Click "New Pipeline"
3. Enter name: "Sales Pipeline"
4. Configure stages:
 - Deal (Gray)
 - Qualified (Blue)
 - Proposal (Yellow)
 - Negotiation (Red)
 - Closed Won (Green)
 - Closed Lost (Gray)
5. Set default probabilities
6. Save pipeline
7. Verify pipeline created
8. Set as default pipeline
9. Verify default set
10. Create deal
11. Verify uses default pipeline

**Expected Result:**
Pipeline created and configured correctly

### Test Case 7: Deal from Contact

**Test:** Verify deal creation from contact

**Steps:**
1. Go to Contacts
2. Open contact details
3. Click "Create Deal"
4. Fill in deal details
5. Save deal
6. Verify deal created
7. Verify deal linked to contact
8. Go to Deals
9. Verify deal appears
10. Open deal details
11. Verify contact link

**Expected Result:**
Deal created from contact with proper linking

### Test Case 8: Deal from Conversation

**Test:** Verify deal creation from conversation

**Steps:**
1. Go to Inbox
2. Open conversation
3. Click "Create Deal"
4. Fill in deal details
5. Save deal
6. Verify deal created
7. Verify deal linked to contact
8. Verify deal linked to conversation
9. Go to Deals
10. Verify deal appears
11. Open deal details
12. Verify conversation link

**Expected Result:**
Deal created from conversation with proper linking

### Test Case 9: Deal Tags

**Test:** Verify tagging functionality

**Steps:**
1. Create deal
2. Add tag: "Hot"
3. Add tag: "VIP"
4. Verify tags displayed
5. Remove tag: "Hot"
6. Verify tag removed
7. Filter deals by tag: "VIP"
8. Verify deal appears

**Expected Result:**
Tag management works correctly

### Test Case 10: Deal Probability

**Test:** Verify probability tracking

**Steps:**
1. Create deal
2. Set probability: 10%
3. Verify probability saved
4. Move to "Qualified" stage
5. Verify probability updates (if stage has default)
6. Manually update probability: 50%
7. Verify probability updated
8. Move to "Closed Won"
9. Verify probability: 100%
10. Check probability history

**Expected Result:**
Probability tracks correctly through deal lifecycle

### Test Case 11: Deal Value Forecasting

**Test:** Verify forecasting calculations

**Steps:**
1. Create multiple deals:
 - Deal 1: Value 10000, Probability 50%
 - Deal 2: Value 5000, Probability 80%
 - Deal 3: Value 15000, Probability 30%
2. Calculate weighted value:
 - Deal 1: 10000 × 0.5 = 5000
 - Deal 2: 5000 × 0.8 = 4000
 - Deal 3: 15000 × 0.3 = 4500
3. Total forecast: 13500
4. Verify calculation matches system
5. Add closed won deals
6. Verify total includes closed deals

**Expected Result:**
Forecasting calculations are accurate

### Test Case 12: Bulk Deal Operations

**Test:** Verify bulk operations

**Steps:**
1. Create 10 test deals
2. Select multiple deals
3. Bulk assign to team member (owner)
4. Verify all deals assigned
5. Bulk update stage
6. Verify all deals updated
7. Bulk delete deals
8. Verify all deals deleted

**Expected Result:**
Bulk operations work correctly

---

## API Integration

### Create Deal

**Endpoint:** `POST /rest/v1/deals`

**Request:**
```json
{
 "organization_id": "org-uuid",
 "contact_id": "contact-uuid",
 "pipeline_id": "pipeline-uuid",
 "title": "New Deal",
 "stage": "lead",
 "value": 5000,
 "probability": 10
}
```

### Update Deal Stage

**Endpoint:** `PATCH /rest/v1/deals?id=eq.{deal_id}`

**Request:**
```json
{
 "stage": "qualified",
 "probability": 50,
 "value": 7500
}
```

### List Deals

**Endpoint:** `GET /rest/v1/deals?select=*,contacts(*),profiles!deals_owner_id_fkey(*)`

---

## Best Practices

1. **Pipeline Design**
 - Keep stages clear and distinct
 - Limit to 5-7 stages
 - Use consistent naming
 - Set appropriate probabilities

2. **Deal Management**
 - Update deals regularly
 - Keep values accurate
 - Set realistic probabilities
 - Add notes for context

3. **Forecasting**
 - Review pipeline weekly
 - Update probabilities regularly
 - Consider deal age
 - Factor in external factors

4. **Organization**
 - Use tags consistently
 - Assign deals promptly
 - Close lost deals
 - Archive old deals

5. **Reporting**
 - Track conversion rates
 - Monitor stage durations
 - Analyze win rates
 - Review pipeline health

---

## Troubleshooting

### Deals Not Moving

**Issue:** Cannot drag deals between stages

**Solutions:**
- Check browser compatibility
- Verify pipeline configuration
- Refresh page
- Check permissions

### Incorrect Totals

**Issue:** Stage/value totals incorrect

**Solutions:**
- Refresh page
- Check filters
- Verify deal data
- Clear cache

### Missing Deals

**Issue:** Deals not appearing

**Solutions:**
- Check pipeline filter
- Verify organization filter
- Check date filters
- Review permissions

---

## See also

- [Contacts](https://docs.connectgain.cloud/02-user-guide/deals/contacts.md) — the people behind each deal
- [Companies](https://docs.connectgain.cloud/02-user-guide/deals/companies.md) — company-level deal tracking
- [Inbox](https://docs.connectgain.cloud/02-user-guide/deals/inbox.md) — converting conversations into deals
- [Tasks](https://docs.connectgain.cloud/02-user-guide/deals/tasks.md) — follow-up tasks linked to deals
- [Sales Report](https://docs.connectgain.cloud/02-user-guide/deals/sales-report.md) — pipeline and revenue reporting
- [Deal pipelines on connectgain.cloud](https://connectgain.cloud/en/deals) — feature overview on the ConnectGain website

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Unified Inbox for WhatsApp, Messenger & More – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/inbox/

# Conversation Management (Inbox) Feature

## Overview

The Inbox (`/inbox`) is the unified messaging center where all customer conversations across channels ([WhatsApp Lite](https://docs.connectgain.cloud/02-user-guide/05-integrations/whatsapp-lite-api.md), WhatsApp Cloud, Facebook Messenger, Instagram Direct Messages, Telegram, TikTok, Shopify Inbox, LinkedIn, and Email) are managed in one place. It provides real-time messaging, conversation assignment, quick replies, and integration with CRM features. (SMS is broadcast-only and does not appear in the inbox.)

**On this page:** [Features](#features) · [Use Cases](#use-cases) · [Test Cases](#test-cases) · [API Integration](#api-integration) · [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting)

---

## Features

### 1. Unified Conversation List

**Multi-Channel View:**
- All conversations in one list
- WhatsApp (Lite & Cloud)
- Facebook Messenger
- Instagram Direct Messages
- Telegram
- TikTok
- Shopify Inbox
- LinkedIn
- Email

**Real-Time Updates:**
- Live conversation sync
- Unread indicators
- Last message preview
- Contact information (name, avatar, channel badge)
- Status indicators (Open/Closed)
- Channel badges for visual identification

**Filtering Options:**
- Quick filters by channel type
- Quick filters by status (Open/Closed)
- Quick filters by message type
- Saved filters (persisted per user)

**Additional Features:**
- Search functionality
- Bulk actions (clear all conversations)
- Refresh control
- Split view toggle
- Full-screen mode (Esc to exit)
- Online agents count and list
- "Analyze Interest" conversation analysis
- Online/offline connection status indicator

### 2. Message Thread View

**Complete Message History:**
- Full conversation timeline
- Real-time message delivery
- Message status tracking:
 - Sent ✓
 - Delivered ✓✓
 - Read ✓✓ (blue)
 - Failed ✗
 - Pending ⏳

**Message Types Support:**
- Text messages
- Images (JPG, PNG, GIF, WebP)
- Videos (MP4, MOV, AVI)
- Audio files (MP3, WAV, OGG)
- Documents (PDF, DOCX, XLSX, etc.)
- Location sharing
- Contact cards (vCard)

**Message Information:**
- Precise timestamps
- Sender information (contact details and channel)
- Message actions:
 - Reply
 - Forward
 - Delete
 - Copy message text
 - Download attachments
 - View full details

### 3. Message Composer

**Rich Text Input:**
- Full message composition
- Media attachments (upload images, videos, documents)
- Quick reply templates
- Emoji support (full emoji picker)
- Typing indicators
- Message scheduling

**Channel-Specific Features:**
- WhatsApp: Templates, media, location
- Messenger: Quick replies, buttons
- Instagram: Stories, media
- Telegram: Stickers, polls

### 4. Contact Panel

**Contact Details:**
- Full contact information (name, email, phone)
- Company association
- Tags
- Custom fields

**Contact History:**
- All past interactions
- Related deals
- Related tasks
- Related notes

**Quick Actions:**
- Send message
- Create deal
- Create task
- Add note
- Edit contact
- View full profile

### 5. Conversation Management

**Conversation Actions:**
- Assign conversations to team members
- Status management (Open/Close conversations)
- Add tags to organize conversations
- Add notes (internal notes)
- Create deal (convert conversation to deal)
- Create task (create follow-up task)
- Delete conversation
- Conversation search

**Mobile Optimization:**
- Responsive layout (optimized for mobile devices)
- Touch-friendly interactions
- Sheet panels (slide-out panels for mobile)
- Swipe actions (gesture-based controls)

### 6. Quick Replies

**Features:**
- Pre-defined message templates
- Variable substitution
- Category organization
- Quick access (type `/`)
- Recent replies
- Favorite replies

### 7. Real-time Updates

**Real-time Features:**
- New message notifications
- Typing indicators
- Message status updates
- Conversation status changes
- Assignment notifications
- Online/offline status

### 8. Mobile Responsive

**Mobile Features:**
- Touch-optimized interface
- Swipe actions
- Mobile notifications
- Offline support
- Quick actions menu

---

## Use Cases

### Use Case 1: Customer Support Agent Responding to Inquiries

**Scenario:**
Support agent receives customer inquiry via WhatsApp.

**Steps:**
1. Agent opens Inbox
2. Sees new unread conversation
3. Clicks on conversation
4. Reads customer message
5. Reviews contact panel for customer history
6. Types response
7. Uses quick reply template if applicable
8. Sends message
9. Marks conversation as assigned to self
10. Updates conversation status if resolved

**Expected Outcome:**
Customer receives timely response, conversation tracked in system.

### Use Case 2: Sales Team Managing Lead Conversations

**Scenario:**
Sales team receives lead inquiry, needs to qualify and convert.

**Steps:**
1. Lead message received in Inbox
2. Sales agent assigns conversation to self
3. Reviews contact information
4. Qualifies lead through conversation
5. Adds tags: "Qualified Lead", "Interested"
6. Creates deal from conversation
7. Links deal to contact
8. Updates deal stage based on conversation
9. Schedules follow-up task
10. Closes conversation when deal won

**Expected Outcome:**
Lead qualified, deal created, follow-up scheduled.

### Use Case 3: Multi-Channel Customer Engagement

**Scenario:**
Customer contacts via multiple channels, needs unified view.

**Steps:**
1. Customer sends WhatsApp message
2. Customer sends Instagram DM
3. Customer sends email
4. Agent sees all conversations in Inbox
5. Agent identifies same customer across channels
6. Agent merges conversations (if needed)
7. Agent responds via preferred channel
8. Agent maintains context across channels

**Expected Outcome:**
Unified customer view, consistent experience across channels.

### Use Case 4: Team Collaboration on Complex Issue

**Scenario:**
Complex customer issue requires team collaboration.

**Steps:**
1. Agent receives complex inquiry
2. Agent assigns conversation to specialist
3. Specialist reviews conversation history
4. Specialist adds internal notes
5. Specialist escalates to manager (via assignment)
6. Manager reviews and responds
7. Manager adds notes with resolution
8. Agent follows up with customer
9. Conversation closed with resolution documented

**Expected Outcome:**
Issue resolved through team collaboration, full history maintained.

### Use Case 5: Automated Response with Bot Flow

**Scenario:**
Customer inquiry triggers automated [bot flow](https://docs.connectgain.cloud/02-user-guide/inbox/bot-flows.md).

**Steps:**
1. Customer sends message
2. Bot flow automatically triggered
3. Bot sends initial greeting
4. Bot collects customer information
5. Bot provides automated responses
6. Bot escalates to human agent if needed
7. Agent sees conversation with bot history
8. Agent takes over conversation
9. Agent completes customer request

**Expected Outcome:**
Initial interaction automated, seamless handoff to human agent.

---

## Test Cases

### Test Case 1: Receive Message

**Test:** Verify message reception

**Steps:**
1. Send test message via WhatsApp to connected number
2. Open Inbox
3. Verify message appears in conversation list
4. Verify unread indicator
5. Click conversation
6. Verify message displayed in thread
7. Verify contact information displayed
8. Verify timestamp correct
9. Verify channel badge displayed

**Expected Result:**
Message received and displayed correctly

### Test Case 2: Send Message

**Test:** Verify message sending

**Steps:**
1. Open conversation
2. Type message: "Hello, this is a test"
3. Click "Send"
4. Verify message appears in thread
5. Verify message status: "Sending"
6. Wait for delivery
7. Verify message status: "Sent"
8. Wait for read receipt (if enabled)
9. Verify message status: "Read"

**Expected Result:**
Message sent successfully with status updates

### Test Case 3: Assign Conversation

**Test:** Verify conversation assignment

**Steps:**
1. Open unassigned conversation
2. Click "Assign"
3. Select team member
4. Confirm assignment
5. Verify conversation assigned
6. Verify assignee sees conversation in "Assigned to me" filter
7. Verify assignment notification (if enabled)
8. Reassign to different team member
9. Verify reassignment works

**Expected Result:**
Conversation assigned and reassigned correctly

### Test Case 4: Change Conversation Status

**Test:** Verify status changes

**Steps:**
1. Open conversation (status: Open)
2. Click "Close Conversation"
3. Verify status changed to "Closed"
4. Verify conversation moved to closed filter
5. Send new message to closed conversation
6. Verify conversation reopened automatically
7. Verify status changed to "Open"

**Expected Result:**
Status changes work correctly, auto-reopen on new message

### Test Case 5: Quick Replies

**Test:** Verify quick reply functionality

**Steps:**
1. Go to Settings → Quick Replies
2. Create quick reply: "Thank you for contacting us!"
3. Open conversation
4. Type "/"
5. Verify quick replies menu appears
6. Select quick reply
7. Verify message inserted
8. Customize if needed
9. Send message
10. Verify message sent correctly

**Expected Result:**
Quick replies work correctly

### Test Case 6: Create Deal from Conversation

**Test:** Verify deal creation from conversation

**Steps:**
1. Open conversation
2. Click "Create Deal"
3. Fill in deal details:
 - Title: "Deal from Conversation"
 - Value: 5000
 - Stage: "Lead"
4. Save deal
5. Verify deal created
6. Verify deal linked to contact
7. Verify deal linked to conversation
8. Go to Deals page
9. Verify deal appears

**Expected Result:**
Deal created and linked correctly

### Test Case 7: Add Note to Conversation

**Test:** Verify note addition

**Steps:**
1. Open conversation
2. Click "Add Note"
3. Enter note: "Customer requested callback"
4. Save note
5. Verify note appears in contact panel
6. Verify note timestamp
7. Verify note author
8. Edit note
9. Delete note

**Expected Result:**
Notes can be added, edited, and deleted

### Test Case 8: Real-time Updates

**Test:** Verify real-time functionality

**Steps:**
1. Open Inbox in Browser A
2. Open Inbox in Browser B (different user)
3. Send message from Browser A
4. Verify message appears in Browser B without refresh
5. Assign conversation in Browser A
6. Verify assignment updates in Browser B
7. Close conversation in Browser A
8. Verify status updates in Browser B

**Expected Result:**
Real-time updates work across multiple clients

### Test Case 9: Multi-Channel Conversation

**Test:** Verify multi-channel support

**Steps:**
1. Create conversation via WhatsApp
2. Send message via WhatsApp
3. Create conversation via Messenger (same contact)
4. Verify both conversations appear
5. Merge conversations (if feature available)
6. Send message via Messenger
7. Verify message appears in merged conversation
8. Verify channel badges displayed

**Expected Result:**
Multi-channel conversations handled correctly

### Test Case 10: Message Search

**Test:** Verify message search functionality

**Steps:**
1. Create conversation with multiple messages
2. Use search in conversation
3. Search for specific text
4. Verify matching messages highlighted
5. Navigate between matches
6. Search across all conversations
7. Verify search results displayed

**Expected Result:**
Message search works correctly

### Test Case 11: Attachment Handling

**Test:** Verify attachment support

**Steps:**
1. Open conversation
2. Click "Attach File"
3. Select image file
4. Upload attachment
5. Verify attachment uploaded
6. Send message with attachment
7. Verify attachment displayed in thread
8. Download attachment
9. Verify download works
10. Test with different file types (PDF, video, audio)

**Expected Result:**
Attachments handled correctly for all supported types

### Test Case 12: Conversation Filtering

**Test:** Verify filtering functionality

**Steps:**
1. Create multiple conversations:
 - Open, assigned
 - Open, unassigned
 - Closed
 - Different channels
2. Filter by status: "Open"
3. Verify only open conversations shown
4. Filter by assignee
5. Verify only assigned conversations shown
6. Filter by channel
7. Verify only selected channel shown
8. Combine filters
9. Verify combined filter works

**Expected Result:**
All filters work correctly individually and combined

---

## API Integration

### List Conversations

**Endpoint:** `GET /rest/v1/conversations`

**Query Parameters:**
- `organization_id` - Filter by organization
- `status` - Filter by status (OPEN/CLOSED)
- `assignee_id` - Filter by assignee
- `channel_account_id` - Filter by channel

**Response:**
```json
{
 "conversations": [
 {
 "id": "conv-uuid",
 "contact_id": "contact-uuid",
 "channel_account_id": "channel-uuid",
 "status": "OPEN",
 "last_message_at": "2025-01-15T10:30:00Z",
 "contact": {
 "first_name": "John",
 "last_name": "Doe"
 }
 }
 ]
}
```

### Send Message

**Endpoint:** `POST /functions/v1/whatsapp-lite-send`

**Request:**
```json
{
 "to": "201001383533",
 "message": "Hello!",
 "organizationId": "org-uuid",
 "conversationId": "conv-uuid"
}
```

### Assign Conversation

**Endpoint:** `PATCH /rest/v1/conversations?id=eq.{conversation_id}`

**Request:**
```json
{
 "assignee_id": "user-uuid"
}
```

---

## Best Practices

1. **Response Time**
 - Respond within SLA (e.g., 24 hours)
 - Use quick replies for common responses
 - Set up automation for after-hours

2. **Organization**
 - Assign conversations promptly
 - Use tags for categorization
 - Close resolved conversations
 - Add notes for context

3. **Communication**
 - Use appropriate channel for customer
 - Maintain professional tone
 - Be concise and clear
 - Follow up when promised

4. **Efficiency**
 - Use quick replies for common questions
 - Create templates for frequent scenarios
 - Use automation for routine tasks
 - Batch similar responses

5. **Quality**
 - Review before sending
 - Check spelling and grammar
 - Verify customer information
 - Document important details

---

## Troubleshooting

### Messages Not Appearing

**Issue:** Messages not showing in inbox

**Solutions:**
- Check channel connection status
- Verify webhook configuration
- Check message filters
- Refresh inbox
- Check real-time connection

### Messages Not Sending

**Issue:** Messages fail to send

**Solutions:**
- Check channel connection
- Verify message format
- Check rate limits
- Review error messages
- Test channel separately

### Real-time Updates Not Working

**Issue:** Updates not appearing in real-time

**Solutions:**
- Check browser connection
- Verify WebSocket connection
- Refresh page
- Check Supabase real-time status
- Review browser console

---

## See also

- [Messages](https://docs.connectgain.cloud/02-user-guide/inbox/messages.md) — message types, sending and status tracking
- [Templates](https://docs.connectgain.cloud/02-user-guide/inbox/templates.md) — quick replies used in the composer
- [Contacts](https://docs.connectgain.cloud/02-user-guide/inbox/contacts.md) — the contact panel and CRM data
- [Channels](https://docs.connectgain.cloud/02-user-guide/05-integrations/channels.md) — connecting messaging channels
- [API Documentation](https://docs.connectgain.cloud/02-user-guide/07-api/complete-api.md) — REST API reference
- [Unified Inbox on connectgain.cloud](https://connectgain.cloud/en/inbox) — feature overview on the ConnectGain website

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Sending & Receiving Messages Across Channels – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/messages/

# Message Management Feature

## Overview

Message Management is the core messaging functionality that enables sending and receiving messages across multiple channels ([WhatsApp Lite](https://docs.connectgain.cloud/02-user-guide/05-integrations/whatsapp-lite-api.md), WhatsApp Cloud, Facebook Messenger, Instagram Direct Messages, Telegram, TikTok, Shopify Inbox, LinkedIn, and Email — plus broadcast-only SMS and Web Push) with support for rich media, message status tracking, and real-time delivery. Messages are managed within conversations in the unified inbox.

**On this page:** [Features](#features) · [Use Cases](#use-cases) · [Test Cases](#test-cases) · [API Integration](#api-integration) · [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting)

---

## Features

### 1. Multi-Channel Messaging

**Supported Channels:**
- **WhatsApp Lite (AppGain)** - QR code authentication, media support, delivery receipts, template messaging, link shortening
- **[WhatsApp Cloud](https://docs.connectgain.cloud/02-user-guide/05-integrations/whatsapp-cloud-system-user.md) (Meta)** - Business API integration, OAuth authentication, approved templates, rich media, interactive buttons
- **Facebook Messenger** - OAuth integration, page connection, quick replies, buttons and carousels, typing indicators
- **Instagram Direct Messages** - Business account connection, OAuth authentication, stories, media support, message requests
- **Telegram** - Bot API integration, bot token authentication, stickers, polls, group messaging, channel broadcasting
- **TikTok** - Business API integration, token authentication, video messaging, media support
- **Shopify Inbox** - Custom-app connection, store chat conversations synced via webhook
- **LinkedIn** - OAuth integration, messaging webhooks, publishing support
- **Email** - SMTP integration, HTML email support, attachment support, email threading
- **SMS** *(outbound broadcast/sequences only — not in the inbox)* - via Appgain Notify (VictoryLink provider), character limit management (160/1600), delivery tracking, link shortening
- **Web Push Notifications** - Background notifications (Android/iOS PWA), automatic subscription, VAPID authentication

**Channel Features:**
- Channel-specific capabilities
- Channel-specific formatting
- Channel status tracking (Active/Inactive)
- Channel-specific media support
- Channel health monitoring
- Delivery and read receipts (where supported)

### 2. Message Types

**Text Messages:**
- Plain text
- Rich text formatting
- Emoji support
- Character limits per channel

**Media Messages:**
- **Images** - JPG, PNG, GIF, WebP
- **Videos** - MP4, MOV, AVI
- **Audio** - MP3, WAV, OGG
- **Documents** - PDF, DOCX, XLSX, etc.
- **Location** - GPS coordinates
- **Contacts** - vCard format

**Interactive Messages:**
- Buttons
- Quick replies
- Lists
- Templates

### 3. Message Status Tracking

**Status Types:**
- **Sent ✓** - Message sent successfully
- **Delivered ✓✓** - Message delivered to recipient
- **Read ✓✓ (blue)** - Message read by recipient (WhatsApp)
- **Failed ✗** - Message failed to send
- **Pending ⏳** - Message queued for sending

**Status Features:**
- Real-time status updates
- Status indicators in UI (visual icons)
- Status history tracking
- Delivery receipts (channel-dependent)
- Read receipts (WhatsApp, Messenger)
- Failed message retry logic
- Error message details

### 4. Message Sending

**Sending Features:**
- Send to single contact
- Send to multiple contacts
- Schedule messages
- Template-based sending
- Variable substitution
- Media attachments

**Sending Options:**
- Send immediately
- Schedule for later
- Recurring messages
- Bulk sending

### 5. Message Receiving

**Receiving Features:**
- Real-time message delivery
- Webhook integration
- Message parsing
- Contact auto-creation
- Conversation auto-creation
- Media download

### 6. Message Threading

**Threading Features:**
- Conversation-based threading
- Message history
- Thread continuity
- Multi-participant threads
- Thread assignment

### 7. Message History

**History Features:**
- Complete message history
- Search messages
- Filter by date
- Filter by channel
- Filter by contact
- Export messages

### 8. Message Actions

**Available Actions:**
- Reply to message
- Forward message
- Delete message
- Mark as read/unread
- Copy message text
- Download attachments
- Create task from message
- Create deal from message

---

## Use Cases

### Use Case 1: Send Text Message

**Scenario:**
Agent wants to send a text message to a customer.

**Steps:**
1. Open conversation in Inbox
2. Type message in composer
3. Click send
4. Verify message sent
5. Check message status
6. Wait for delivery confirmation
7. Wait for read receipt (if available)

**Expected Outcome:**
Message sent successfully with status tracking.

### Use Case 2: Send Media Message

**Scenario:**
Agent wants to send product image to customer.

**Steps:**
1. Open conversation
2. Click attach media button
3. Select image file
4. Add caption (optional)
5. Send message
6. Verify image sent
7. Check delivery status

**Expected Outcome:**
Image message sent and delivered successfully.

### Use Case 3: Send Template Message

**Scenario:**
Business wants to send approved template message.

**Steps:**
1. Open conversation
2. Click template button
3. Select template from library
4. Fill template variables
5. Preview message
6. Send message
7. Verify template used correctly

**Expected Outcome:**
Template message sent with variables substituted.

### Use Case 4: Schedule Message

**Scenario:**
Agent wants to send message at specific time.

**Steps:**
1. Compose message
2. Click schedule button
3. Select date and time
4. Confirm schedule
5. Verify message scheduled
6. Wait for scheduled time
7. Verify message sent automatically

**Expected Outcome:**
Message scheduled and sent at specified time.

### Use Case 5: Receive and Respond

**Scenario:**
Customer sends message, agent needs to respond.

**Steps:**
1. Receive notification of new message
2. Open conversation
3. View incoming message
4. Read message content
5. Compose response
6. Send reply
7. Verify conversation updated

**Expected Outcome:**
Message received and responded to successfully.

---

## Test Cases

### Test Case 1: Send Text Message

**Test:** Verify text message sending

**Steps:**
1. Open conversation
2. Type message: "Hello, how can I help?"
3. Send message
4. Verify message appears in thread
5. Check status: SENT
6. Wait for delivery
7. Verify status: DELIVERED
8. Wait for read receipt
9. Verify status: READ (if supported)

**Expected Result:**
Message sent and status tracked correctly

### Test Case 2: Send Image Message

**Test:** Verify image message sending

**Steps:**
1. Open conversation
2. Click attach image
3. Select image file
4. Add caption: "Product image"
5. Send message
6. Verify image uploaded
7. Verify message sent
8. Check image displays correctly
9. Verify delivery status

**Expected Result:**
Image message sent and displayed correctly

### Test Case 3: Receive Message

**Test:** Verify message receiving

**Steps:**
1. Send test message from external channel
2. Verify webhook received
3. Verify message created in system
4. Verify conversation created/updated
5. Verify contact created/updated
6. Check message appears in inbox
7. Verify real-time update

**Expected Result:**
Message received and processed correctly

### Test Case 4: Message Status Tracking

**Test:** Verify status tracking

**Steps:**
1. Send message
2. Verify initial status: SENT
3. Wait for delivery confirmation
4. Verify status: DELIVERED
5. Wait for read receipt
6. Verify status: READ
7. Check status history

**Expected Result:**
Message status tracked through all stages

### Test Case 5: Multi-Channel Messaging

**Test:** Verify multi-channel support

**Steps:**
1. Send WhatsApp message
2. Verify WhatsApp formatting
3. Send Messenger message
4. Verify Messenger formatting
5. Send Instagram message
6. Verify Instagram formatting
7. Check channel-specific features

**Expected Result:**
All channels supported with correct formatting

### Test Case 6: Message Threading

**Test:** Verify message threading

**Steps:**
1. Send initial message
2. Receive reply
3. Send follow-up message
4. Verify all messages in same thread
5. Check conversation continuity
6. Verify thread assignment

**Expected Result:**
Messages threaded correctly in conversation

### Test Case 7: Message Search

**Test:** Verify message search

**Steps:**
1. Send multiple messages
2. Search for specific text
3. Verify matching messages found
4. Filter by date range
5. Filter by channel
6. Filter by contact
7. Verify filters work correctly

**Expected Result:**
Message search and filtering work correctly

### Test Case 8: Message Actions

**Test:** Verify message actions

**Steps:**
1. Send message
2. Reply to message
3. Forward message
4. Copy message text
5. Delete message
6. Mark as read/unread
7. Verify all actions work

**Expected Result:**
All message actions work correctly

---

## API Integration

### Send Message

**Endpoint:** `POST /functions/v1/{channel}-send`

**Request (WhatsApp Lite):**
```json
{
 "phone_number": "+1234567890",
 "message": "Hello, this is a test message",
 "organization_id": "org-uuid",
 "contact_id": "contact-uuid"
}
```

**Request (with media):**
```json
{
 "phone_number": "+1234567890",
 "message": "Check out this image",
 "media_url": "https://example.com/image.jpg",
 "media_type": "image",
 "organization_id": "org-uuid"
}
```

### Get Messages

**Endpoint:** `GET /rest/v1/messages`

**Query Parameters:**
- `conversation_id` - Filter by conversation
- `contact_id` - Filter by contact
- `channel` - Filter by channel
- `direction` - Filter by direction (INBOUND/OUTBOUND)
- `status` - Filter by status

### Webhook Receiver

**Endpoint:** `POST /functions/v1/{channel}-webhook`

**Webhook Payload:**
```json
{
 "message_id": "msg-123",
 "from": "+1234567890",
 "to": "+0987654321",
 "message": "Hello",
 "timestamp": "2025-01-15T10:00:00Z",
 "channel": "whatsapp_lite"
}
```

---

## Best Practices

1. **Message Composition**
 - Keep messages concise
 - Use appropriate tone
 - Include clear call-to-action
 - Personalize when possible

2. **Media Usage**
 - Optimize image sizes
 - Use appropriate formats
 - Add captions to media
 - Test media delivery

3. **Status Monitoring**
 - Monitor delivery status
 - Follow up on failed messages
 - Track read receipts
 - Analyze delivery rates

4. **Channel Selection**
 - Use appropriate channel
 - Respect channel limits
 - Follow channel guidelines
 - Test channel features

5. **Message Timing**
 - Send during business hours
 - Respect time zones
 - Use scheduling for off-hours
 - Avoid spam patterns

---

## Troubleshooting

### Message Not Sending

**Issue:** Message fails to send

**Solutions:**
- Check channel configuration
- Verify contact phone number
- Check message format
- Review error logs
- Verify channel status

### Message Not Delivered

**Issue:** Message sent but not delivered

**Solutions:**
- Check recipient phone number
- Verify channel connectivity
- Check delivery status
- Review channel logs
- Contact channel support

### Media Not Sending

**Issue:** Media attachments not sending

**Solutions:**
- Check file size limits
- Verify file format supported
- Check media URL accessibility
- Verify channel media support
- Test with different file

---

## See also

- [Inbox](https://docs.connectgain.cloud/02-user-guide/messages/inbox.md) — the unified conversation view where messages live
- [Templates](https://docs.connectgain.cloud/02-user-guide/messages/templates.md) — saved replies and WhatsApp templates
- [Campaigns](https://docs.connectgain.cloud/02-user-guide/messages/campaigns.md) — bulk broadcast messaging (including SMS)
- [Channels](https://docs.connectgain.cloud/02-user-guide/05-integrations/channels.md) — connecting messaging channels
- [API Documentation](https://docs.connectgain.cloud/02-user-guide/07-api/complete-api.md) — REST API reference
- [Messaging features on connectgain.cloud](https://connectgain.cloud/en/messages) — feature overview on the ConnectGain website

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Multilingual Bot Flows – ConnectGain Bot Builder Guide

Source: https://docs.connectgain.cloud/02-user-guide/multilingual-flows/

# Building Multilingual Bot Flows

How to make one bot flow answer each customer in **their own language** — without duplicating the whole flow per language.

> **Backward compatibility:** Everything here is **opt-in and additive**. Flows built before multilingual support keep working exactly as-is. The localized fields are optional; when a node has none, the engine uses its single base text just like before.

---

## 1. How language selection works

Every running flow has a per-conversation bag of **session variables**. The engine picks the language from a variable named **`lang`** (or **`language`**) at *send time*:

- `{{lang}}` = `ar` → Arabic content is sent
- `{{lang}}` = `fr` → French content is sent
- variable missing / no matching translation → **falls back to the Default (base) content**, then to `en`

Language resolution happens automatically on the server. You never configure it directly — you just make sure a `lang` variable exists in the session.

Language codes are lowercase ISO-639 (`en`, `ar`, `fr`, `es`, `de`, `pt`, …). `en_other` is normalized to `en`.

---

## 2. Step-by-step

### Step 1 — Ask the user their language (once)

Add a **Quick Reply** node near the start of the flow as a language picker:

| Field | Value |
|---|---|
| Message Body | `Choose your language / اختر لغتك / Choisissez votre langue` |
| Collect answer into a variable | **On** |
| Variable name | `lang` |
| Save | **Button payload (fallback to title)** |

Buttons (set the **payload** to the language *code*, the title to the display name):

| Title | Payload |
|---|---|
| English | `en` |
| العربية | `ar` |
| Français | `fr` |

Because *Save = payload*, tapping "العربية" stores `lang = "ar"` in the session. Every node after this can now localize itself.

> Prefer to **auto-detect** instead of asking? Set `lang` with a **Set Variable** node from any source you trust — e.g. `{{contact.language}}`, a CRM field, or the result of a **Classify Intent** / **AI Response** node that detects language. The only requirement is that a `lang` (or `language`) variable is present before localized nodes run.

### Step 2 — Author localized Quick Replies

Open any **Quick Reply** node. At the top you'll see **Content language**:

1. Leave it on **Default (fallback)** and write your base message body + buttons (this is what older flows already had — and what any unconfigured language falls back to).
2. Type a code (e.g. `ar`) into **Add language → Add**.
3. The selector switches to **AR**. Now the **Message Body** field and each **button title** edit the *Arabic* text. Leave any field blank to fall back to Default for that one string.
4. Repeat for `fr`, `es`, …
5. Save.

Button **payloads stay shared** across languages (they're codes, not display text), so your branching/Switch logic doesn't change between languages. Only the visible labels are translated.

At send time the node automatically renders the body + button labels in `{{lang}}`, falling back to Default per-string when a translation is missing.

### Step 3 — Inject dynamic values

Localized text supports `{{variable}}` interpolation, in **both the body and the button labels**:

```text
Default: Hi {{contact.first_name}}, your order {{order_id}} is ready.
AR: مرحبًا {{contact.first_name}}، طلبك {{order_id}} جاهز.
```

`{{contact.first_name}}` and `{{order_id}}` resolve from session/contact variables regardless of language. (If a variable is missing, the `{{token}}` is left untouched — never blanked.)

---

## 3. Localizing plain Send Message nodes

The **Send Message** node has its own localization for **WhatsApp templates / freeform smart-send**:

- `localizedBodies` — per-language freeform bodies (used when inside the 24-hour window)
- `templateNameBase` — a Meta template base name; the engine appends the language suffix (`__ar`, `__fr`) and falls back to `__en`

So for template-driven sends, create your Meta templates as `myflow_welcome__en`, `myflow_welcome__ar`, … and set the base name; the right one is chosen by `{{lang}}`.

---

## 4. When you still need to branch on language

Native localization covers message bodies and button labels. If a **different path** must run per language (different nodes, not just different text — e.g. Arabic routes to an Arabic-speaking agent), branch explicitly:

1. After the language picker, add a **Switch** node with `inputVariable = {{lang}}`.
2. Add cases `en`, `ar`, `fr`, … each leading to its own sub-path.
3. Use **Jump To** at the end of each path to converge back to a shared continuation, avoiding duplicate tails.

Use localization for *content*, branching for *flow shape*. Most flows only need localization.

---

## 5. Reference — what is / isn't localizable today

| Element | Localizable | How |
|---|---|---|
| Quick Reply message body | ✅ | Per-language editor (`localizedMessage`) |
| Quick Reply button labels | ✅ | Per-language editor (`localizedTitles` per button) |
| Quick Reply button payloads | — (shared) | Codes, not display text — intentionally shared |
| Send Message (template/freeform) | ✅ | `localizedBodies` + `templateNameBase` (`__lang` suffix) |
| Any `{{variable}}` in text | ✅ | Interpolated in every language |
| Quick Reply header/footer text | ❌ (base only) | Use the message body for localized content |
| Collect Input prompt, AI prompts, etc. | ➖ | Use `{{variable}}` + branch on `{{lang}}` if needed |

---

## 6. Developer notes (data shape & resolution)

Stored on the Quick Reply node's `data` (all optional — absent on legacy nodes):

```jsonc
{
 "message": "Choose an option", // base / fallback body
 "localizedMessage": { "ar": "اختر خيارًا", "fr": "Choisissez" },
 "languages": ["ar", "fr"], // configured locales (editor only)
 "buttons": [
 {
 "id": "btn-1",
 "title": "Yes", // base / fallback label
 "payload": "yes", // shared across languages
 "localizedTitles": { "ar": "نعم", "fr": "Oui" }
 }
 ]
}
```

Resolution order at send time (for example, for a quick-reply message):

1. `qrLang = resolveFlowLanguage("", flowVars)` → reads `flowVars.lang ?? flowVars.language`, else `en`.
2. Body = `resolveLocalizedBody(localized_message, qrLang) ?? message`, then `interpolateFlowString(...)`.
3. Each button title = `resolveLocalizedBody(button.localizedTitles, qrLang) ?? button.title`, then interpolated.

`resolveLocalizedBody` returns `null` when there's no map → **legacy/non-localized nodes take the exact same path as before** (base text, no behavior change). The deploy step (`n8n-deploy-flow`, `quickReply` case) only includes `localized_message` in the callback payload when it is present, so non-localized nodes produce a byte-identical payload to pre-feature builds.

---

## See also

- [Bot Flows](https://docs.connectgain.cloud/02-user-guide/multilingual-flows/bot-flows.md) — visual bot builder: every node, trigger, and scenario
- [Templates](https://docs.connectgain.cloud/02-user-guide/multilingual-flows/templates.md) — WhatsApp template management

---

**Last Updated:** June 2026

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Project, Milestone & Deliverable Tracking – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/projects/

# Project Management Feature

## Overview

Project Management (`/projects`) enables businesses to track projects, milestones, and deliverables with timeline views, progress tracking, and public sharing capabilities. Projects can be linked to contacts, deals, and team members, providing comprehensive project oversight and client visibility.

**On this page:** [Features](#features) · [Use Cases](#use-cases) · [Test Cases](#test-cases) · [API Integration](#api-integration) · [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting)

---

## Features

### 1. Project Management

**Create Projects:**
- Add new projects with:
 - Project name, description
 - Start date, end date
 - Status (Planning, In Progress, On Hold, Completed, Cancelled)
 - Project owner
 - Team members
 - Milestones
 - Deliverables

**Edit Projects:**
- Update project information

**Delete Projects:**
- Remove projects

**Project Details View:**
- Comprehensive project profile
- All project information
- Timeline view
- Milestones
- Deliverables
- Team members
- Activity log
- Notes

### 2. View Modes

**Grid View:**
- Card-based layout
- Project cards with key info
- Status indicators
- Progress bars
- Quick action buttons

**Timeline View:**
- Visual timeline layout
- Gantt-style timeline
- Project duration visualization
- Milestone markers
- Dependency lines
- Interactive timeline

### 3. Project Status Tracking

**Status Types:**
- Planning (blue)
- In Progress (green)
- On Hold (yellow)
- Completed (green)
- Cancelled (gray)

**Status Indicators:**
- Visual status badges

**Status Transitions:**
- Change project status

**Status History:**
- Track status changes

### 4. Project Statistics

**Active Projects:**
- Count of in-progress projects

**Delayed Projects:**
- Count of delayed projects

**Completed Projects:**
- Count of completed projects

**Visual Cards:**
- Quick stats display

### 5. Project Views

**Grid View:**
- Project cards display
- Status indicators
- Progress bars
- Quick actions
- Pagination support

**Timeline View:**
- Gantt-style timeline
- Visual project timeline
- Milestone markers
- Deliverable markers
- Date range display

### 6. Project Organization

**Milestones:**
- Track project milestones
- Milestone name
- Target date
- Status
- Dependencies

**Deliverables:**
- Track project deliverables
- Deliverable name
- Due date
- Status
- Assignee

**Team Assignment:**
- Assign team members
- Multiple team members
- Role assignment
- Responsibility tracking

### 7. Project Actions

**Quick Actions:**
- View project details
- Edit project
- Delete project
- Change status
- Add milestone
- Add deliverable
- Assign team member

> The Projects list offers a project-type filter and pagination. There is no bulk-select toolbar (no bulk status change or bulk team assignment).

### 8. Pagination

**50 Projects Per Page:**
- Efficient loading
- Page navigation

### 9. Public Project Timeline

**Shareable Links:**
- Public project timelines
- Generate shareable URL
- Public view (no login required)
- Read-only access
- Client-friendly view

### 10. Project Progress

**Progress Tracking:**
- Overall progress percentage
- Milestone-based progress
- Deliverable-based progress
- Visual progress bars
- Progress updates

### 11. Public Project Sharing

**Public Sharing:**
- Generate public token
- Share public URL
- Public timeline view
- Milestone visibility
- Deliverable visibility
- No authentication required

### 12. Project Relationships

**Relationships:**
- Link to customer contact
- Link to deal
- Assign project owner
- Team member assignments

### 13. Project Types

**Project Type Support:**
- **DELIVERY** - Delivery project type (default)
 - Has start and end dates
 - Tracks milestones and deliverables
 - Progress tracking
 - Budget management

- **SUPPORT** - Support project type
 - No end date requirement
 - Issues & Fixes tracking (see [Support Tickets](https://docs.connectgain.cloud/02-user-guide/projects/support-tickets.md))
 - SLA tracking and configuration
 - Support-specific workflows

**Type-Specific Features:**
- Type-based organization
- Type-specific fields
- Different views per type
- Type-specific permissions

---

## Use Cases

### Use Case 1: Create Project with Milestones

**Scenario:**
Business wants to track a client project with milestones.

**Steps:**
1. Go to Projects
2. Click "New Project"
3. Enter project name: "Website Redesign"
4. Set start and end dates
5. Set budget: $50,000
6. Assign project owner
7. Link customer contact
8. Save project
9. Add milestones:
 - Design Phase (Due: Week 2)
 - Development Phase (Due: Week 6)
 - Testing Phase (Due: Week 8)
 - Launch (Due: Week 10)
10. Verify milestones created

**Expected Outcome:**
Project created with milestones for tracking.

### Use Case 2: View Project Timeline

**Scenario:**
Project manager wants to see project timeline.

**Steps:**
1. Go to Projects
2. Switch to Timeline view
3. View all projects on timeline
4. See milestone markers
5. See deliverable markers
6. Check project dates
7. Identify overlaps

**Expected Outcome:**
Visual timeline showing all projects and milestones.

### Use Case 3: Share Public Project Timeline

**Scenario:**
Business wants to share project progress with client.

**Steps:**
1. Open project details
2. Click "Share"
3. Generate public token
4. Copy public URL
5. Share URL with client
6. Client views public timeline
7. Client sees milestones and progress

**Expected Outcome:**
Client can view project timeline without login.

### Use Case 4: Track Project Progress

**Scenario:**
Project manager wants to update project progress.

**Steps:**
1. Open project details
2. View current progress
3. Complete milestones
4. Complete deliverables
5. Update progress percentage
6. Verify progress bar updates
7. Check timeline reflects progress

**Expected Outcome:**
Project progress tracked and displayed.

---

## Test Cases

### Test Case 1: Create Project

**Test:** Verify project creation

**Steps:**
1. Go to Projects
2. Click "New Project"
3. Fill in required fields:
 - Name: "Test Project"
 - Start Date: Today
 - End Date: Next month
4. Add optional fields:
 - Budget: $10,000
 - Description: "Test description"
5. Save project
6. Verify project appears in list
7. Open project details
8. Verify all data saved

**Expected Result:**
Project created successfully

### Test Case 2: Add Milestone

**Test:** Verify milestone creation

**Steps:**
1. Open project details
2. Go to Milestones tab
3. Click "Add Milestone"
4. Enter milestone name
5. Set due date
6. Save milestone
7. Verify milestone appears
8. Verify milestone on timeline

**Expected Result:**
Milestone created and displayed

### Test Case 3: Add Deliverable

**Test:** Verify deliverable creation

**Steps:**
1. Open project details
2. Go to Deliverables tab
3. Click "Add Deliverable"
4. Enter deliverable name
5. Link to milestone
6. Set due date
7. Save deliverable
8. Verify deliverable appears

**Expected Result:**
Deliverable created successfully

### Test Case 4: Update Progress

**Test:** Verify progress tracking

**Steps:**
1. Create project with milestones
2. Complete first milestone
3. Verify progress updates
4. Complete second milestone
5. Verify progress increases
6. Check progress bar
7. Verify percentage correct

**Expected Result:**
Progress tracked correctly

### Test Case 5: Public Sharing

**Test:** Verify public sharing

**Steps:**
1. Open project
2. Click "Share"
3. Generate public token
4. Copy public URL
5. Open URL in incognito window
6. Verify timeline visible
7. Verify no login required
8. Verify milestones visible

**Expected Result:**
Public sharing works correctly

### Test Case 6: Timeline View

**Test:** Verify timeline view

**Steps:**
1. Create multiple projects
2. Switch to timeline view
3. Verify projects displayed
4. Verify milestones shown
5. Verify dates correct
6. Check timeline scaling
7. Verify navigation works

**Expected Result:**
Timeline view displays correctly

---

## API Integration

### Create Project

**Endpoint:** `POST /rest/v1/projects`

**Request:**
```json
{
 "organization_id": "org-uuid",
 "name": "Website Redesign",
 "description": "Complete website redesign project",
 "status": "PLANNING",
 "progress": 0,
 "start_date": "2025-01-15",
 "end_date": "2025-04-15",
 "budget": 50000,
 "currency": "USD",
 "owner_id": "user-uuid",
 "customer_contact_id": "contact-uuid",
 "deal_id": "deal-uuid"
}
```

### Create Milestone

**Endpoint:** `POST /rest/v1/project_milestones`

**Request:**
```json
{
 "project_id": "project-uuid",
 "name": "Design Phase",
 "description": "Complete design mockups",
 "due_date": "2025-02-01",
 "status": "PENDING",
 "order_index": 1
}
```

### Create Deliverable

**Endpoint:** `POST /rest/v1/project_deliverables`

**Request:**
```json
{
 "project_id": "project-uuid",
 "milestone_id": "milestone-uuid",
 "name": "Homepage Design",
 "description": "Complete homepage mockup",
 "due_date": "2025-01-25",
 "status": "PENDING"
}
```

---

## Best Practices

1. **Project Planning**
 - Set realistic dates
 - Define clear milestones
 - Break down into deliverables
 - Assign appropriate owners

2. **Progress Tracking**
 - Update progress regularly
 - Complete milestones promptly
 - Track deliverable completion
 - Monitor project health

3. **Communication**
 - Use public sharing for clients
 - Keep stakeholders informed
 - Update project status
 - Document changes

4. **Organization**
 - Use project types
 - Link to contacts/deals
 - Assign team members
 - Set appropriate budgets

---

## Troubleshooting

### Project Not Appearing

**Issue:** Created project not visible

**Solutions:**
- Check view filters
- Verify organization context
- Check permissions
- Refresh page

### Timeline Not Displaying

**Issue:** Timeline view not showing projects

**Solutions:**
- Verify projects have dates
- Check date range
- Refresh timeline
- Verify permissions

### Public Link Not Working

**Issue:** Public timeline not accessible

**Solutions:**
- Verify public sharing enabled
- Check public token generated
- Verify URL correct
- Check project visibility

---

## See also

- [Support Tickets](https://docs.connectgain.cloud/02-user-guide/projects/support-tickets.md) — Issues & Fixes inside Support projects
- [Tasks](https://docs.connectgain.cloud/02-user-guide/projects/tasks.md) — day-to-day task tracking
- [Deals](https://docs.connectgain.cloud/02-user-guide/projects/deals.md) — deals linked to projects
- [Contacts](https://docs.connectgain.cloud/02-user-guide/projects/contacts.md) — customer contacts linked to projects
- [API Documentation](https://docs.connectgain.cloud/02-user-guide/07-api/complete-api.md) — REST API reference
- [Tasks & Projects on connectgain.cloud](https://connectgain.cloud/en/tasks-projects) — feature overview on the ConnectGain website

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Sales Reports & Pipeline Analysis – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/sales-report/

# Sales Report Feature

## Overview

The Sales Report feature (`/sales-report`) provides comprehensive sales pipeline analysis and reporting with detailed deal breakdowns, stage-by-stage analysis, and export capabilities. This feature helps sales managers make data-driven decisions and identify bottlenecks in the sales process.

**Access Level:** CRM access required

**Status:** Production Ready

**Last Updated:** January 2025

---

## Features

### 1. Pipeline Selection

**Multiple Pipeline Support:**
- Select any pipeline for analysis
- Default pipeline auto-selection
- Pipeline switching without page reload
- Real-time data refresh

**Pipeline Information:**
- Pipeline name display
- Pipeline stage configuration
- Deal count per pipeline
- Total value per pipeline

### 2. Summary Metrics

**Key Performance Indicators:**
- **Total Stages:** Number of stages in selected pipeline
- **Total Deals:** Count of all deals across all stages
- **Total Value:** Sum of all deal values (formatted currency)
- **Average Deal Value:** Mean deal value calculation

**Visual Display:**
- Large, prominent metric cards
- Icon indicators
- Formatted currency values
- Real-time calculations

### 3. Stage-by-Stage Analysis

**Collapsible Stage Cards:**
- Expandable/collapsible stage sections
- Color-coded stage headers
- Stage name and color indicators
- Visual stage identification

**Stage Metrics:**
- Deal count per stage
- Total value per stage
- Average deal value per stage
- Average probability per stage

**Expand/Collapse Controls:**
- Individual stage toggle
- Expand All / Collapse All buttons
- Visual chevron indicators
- Smooth animations

### 4. Deal Details Table

**Comprehensive Deal Information:**
- Deal title
- Contact name and information
- Company name
- Description (truncated with tooltip)
- Deal value (formatted currency)
- Expected close date (formatted)
- Probability percentage (badge display)

**Quick Actions:**
- View deal details (navigate to deals page)
- View conversation (navigate to inbox)
- External link icons
- Hover tooltips

**Table Features:**
- Responsive design
- Mobile-optimized layout
- Scrollable content area

### 5. Export Capabilities

**CSV Export:**
- Full report export functionality
- All stages and deals included
- Stage summary rows
- Grand total row
- Formatted currency values
- Date-stamped filename
- Ready for Excel import

**Export Format:**
- Headers row
- Stage-by-stage data
- Summary rows per stage
- Grand total row
- CSV-compatible format

### 6. Data Refresh

**Manual Refresh:**
- Refresh button with loading state
- Real-time data fetching
- Error handling and notifications
- Optimistic updates

**Auto-Refresh:**
- Automatic refresh on pipeline change
- Real-time deal updates
- Stage change detection

---

## Usage

### Generating a Report

1. Navigate to **Sales Report** in the sidebar
2. Select pipeline from dropdown (if multiple pipelines)
3. Report automatically generates
4. View summary metrics at top
5. Expand/collapse stages as needed
6. Review deal details in each stage

### Analyzing Pipeline Performance

1. **Review Summary Metrics:**
 - Check total deals and value
 - Review average deal value
 - Identify pipeline size

2. **Analyze Stage Distribution:**
 - Expand each stage
 - Review deal count per stage
 - Check value distribution
 - Identify bottlenecks

3. **Examine Individual Deals:**
 - Click to view deal details
 - Check contact information
 - Review probability and close date
 - Navigate to conversation if needed

### Exporting Reports

1. Click **Export CSV** button
2. File downloads automatically
3. Open in Excel or spreadsheet application
4. Analyze data further
5. Share with team or stakeholders

### Filtering and Navigation

1. **Pipeline Selection:** Change pipeline to analyze different sales processes
2. **Assignee Filter:** Filter the report by deal assignee (All, a specific team member, or Unassigned)
3. **Stage Expansion:** Expand/collapse stages to focus on specific areas
4. **Deal Navigation:** Click deal links to view full details
5. **Conversation Access:** Click conversation icon to view related messages

---

## Visual Design

### Color-Coded Stages

- Stage-specific colors for visual identification
- Left border accent colors
- Background tinting for stage cards
- Consistent color scheme

### Status Badges

- Probability badges with percentage display
- Deal count badges
- Value highlights
- Visual indicators

### Responsive Layout

- Mobile-optimized design
- Scrollable content areas
- Touch-friendly controls
- Adaptive table layout

---

## Use Cases

### Sales Manager Review

**Scenario:** Weekly pipeline review meeting

1. Generate report for current pipeline
2. Review summary metrics
3. Identify stages with most deals
4. Check average deal values
5. Export report for meeting
6. Share insights with team

### Deal Analysis

**Scenario:** Analyzing stuck deals

1. Generate report
2. Expand each stage
3. Review deal details
4. Identify deals with low probability
5. Check expected close dates
6. Create follow-up tasks

### Performance Tracking

**Scenario:** Monthly performance review

1. Generate report
2. Export to CSV
3. Import into analytics tool
4. Create charts and graphs
5. Track trends over time
6. Identify improvement areas

---

## Benefits

1. **Comprehensive Visibility:** See entire pipeline at a glance
2. **Data-Driven Decisions:** Make informed choices based on data
3. **Easy Export:** Share reports with stakeholders
4. **Quick Identification:** Find bottlenecks and issues quickly
5. **Performance Tracking:** Monitor pipeline health
6. **Team Alignment:** Share insights across team

---

## Best Practices

1. **Regular Reviews:** Generate reports weekly/monthly
2. **Stage Analysis:** Focus on stages with most deals
3. **Deal Follow-Up:** Use reports to identify deals needing attention
4. **Export Regularly:** Keep historical reports for trend analysis
5. **Share Insights:** Distribute reports to relevant stakeholders

---

## Troubleshooting

**"No data showing"**
- Verify pipeline has deals
- Check pipeline selection
- Ensure CRM access permissions
- Refresh the page

**"Export not working"**
- Check browser download settings
- Verify file permissions
- Try different browser
- Check for popup blockers

**"Stages not expanding"**
- Check JavaScript is enabled
- Refresh the page
- Clear browser cache
- Try different browser

---

## Related Documentation

- [Deals](https://docs.connectgain.cloud/02-user-guide/sales-report/deals.md)
- [Analytics](https://docs.connectgain.cloud/02-user-guide/sales-report/analytics.md)
- [Dashboard](https://docs.connectgain.cloud/02-user-guide/sales-report/dashboard.md)
- [Sales Reports on connectgain.cloud](https://connectgain.cloud/en/sales-report) — feature overview on the ConnectGain website

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Scheduling & Appointment Booking – ConnectGain Guide

Source: https://docs.connectgain.cloud/02-user-guide/scheduling/

# Scheduling System (Beta) - Feature Documentation

## Overview
ConnectGain Scheduling is a comprehensive appointment booking system integrated directly into the ConnectGain platform. It provides Calendly-like functionality with advanced features such as Google Calendar integration, custom branding per event type, and seamless CRM integration.

**Status:** Beta

**Version:** 1.0.0

**Last Updated:** November 2025

## Table of Contents
1. [Getting Started](#getting-started)
2. [Event Types](#event-types)
3. [Availability Management](#availability-management)
4. [Google Calendar Integration](#google-calendar-integration)
5. [Booking Process](#booking-process)
6. [Customization & Branding](#customization--branding)
7. [API Reference](#api-reference)
8. [Troubleshooting](#troubleshooting)

---

## Getting Started

### Accessing Scheduling
1. Navigate to **Scheduling** in the main sidebar (marked with Beta badge)
2. The scheduling dashboard shows all your event types
3. Click "New Event Type" to create your first booking type

### Initial Setup
1. **Create Your First Event Type**
 - Click "New Event Type"
 - Enter a title (e.g., "30-minute Consultation")
 - Set the duration
 - Choose a location type (Google Meet recommended)
 - Save to generate your booking link

2. **Configure Your Availability**
 - Edit the event type
 - Go to the "Availability" tab
 - Set your working hours for each day
 - Block specific dates as needed

3. **Connect Google Calendar** (Optional but Recommended)
 - Go to Scheduling > Integrations
 - Click "Connect Google Calendar"
 - Authorize ConnectGain to access your calendar
 - Your calendar events will now block booking slots

4. **Share Your Booking Link**
 - Copy the generated link for your event type
 - Format: `https://dashboard.connectgain.cloud/schedule/[your-username]/[event-slug]`
 - Share with clients, add to email signatures, or embed on websites

---

## Event Types

### Creating Event Types
Event types define the different kinds of meetings people can book with you.

**Required Fields:**
- **Title**: Display name for the event type
- **Slug**: URL-friendly identifier
- **Duration**: Length of the meeting (5 min - 8 hours)
- **Location Type**: Where the meeting will take place

**Optional Settings:**
- **Description**: Explain what the meeting is for
- **Theme Color**: Brand color for booking pages
- **Banner Image URL**: Header image for branding
- **Buffer Time**: Minutes between back-to-back bookings
- **Daily Limit**: Maximum bookings per day
- **Advance Notice**: Minimum hours before booking
- **Availability Window**: How far ahead bookings can be made
- **Confirmation Message**: Custom message after booking

### Location Options
- **Google Meet**: Automatically creates Meet link (requires Google Calendar)
- **Zoom**: Native Zoom integration via OAuth — connect your Zoom account and meeting links are created automatically
- **Phone Call**: Collect phone number from guest
- **In-Person**: Specify meeting location
- **Custom**: Any custom location details

### Managing Event Types
- **Edit**: Click the three-dot menu > Edit
- **Clone**: Duplicate an event type with new settings
- **Activate/Deactivate**: Toggle availability without deleting
- **Delete**: Permanently remove (also deletes associated bookings)
- **Copy Link**: Get the public booking URL

---

## Availability Management

### Setting Weekly Availability
Define your standard working hours for each event type:

1. Edit the event type
2. Go to "Availability" tab
3. For each day:
 - Toggle on/off
 - Set start time
 - Set end time
4. Save changes

### Blocking Dates
Mark specific dates as unavailable:
- Holiday blocks
- Vacation time
- Personal days
- One-time conflicts

### Time Zone Handling
- Host availability is set in their local time zone
- Guests see times in their detected time zone
- All bookings stored in UTC for consistency

### Availability Calculation
The system checks multiple sources to determine available slots:
1. **Availability Rules**: Your defined working hours
2. **Existing Bookings**: Already scheduled appointments
3. **Google Calendar Events**: If connected, blocks busy times
4. **Blocked Dates**: Manually blocked days
5. **Buffer Times**: Spacing between appointments
6. **Advance Notice**: Minimum booking lead time

---

## Google Calendar Integration

### Setup Process
1. Navigate to **Scheduling > Integrations**
2. Click "Connect Google Calendar"
3. Sign in with your Google account
4. Grant necessary permissions:
 - View calendar events (for availability)
 - Create calendar events (for bookings)
5. Select primary calendar or choose specific calendar
6. Connection confirmed!

### What Gets Synced
**From Google to ConnectGain:**
- Busy times block booking slots
- All-day events block entire days
- Recurring events properly handled

**From ConnectGain to Google:**
- New bookings create calendar events
- Event includes guest as attendee
- Google Meet link automatically added
- Cancellations update calendar
- Rescheduling moves the event

### Managing Connection
- **Test Connection**: Verify sync is working
- **Change Calendar**: Select different calendar
- **Pause Sync**: Temporarily disable without disconnecting
- **Disconnect**: Remove integration completely

---

## Booking Process

### Guest Experience
1. **Landing Page**
 - Guest visits your booking link
 - Sees event type details
 - Views your availability calendar

2. **Date Selection**
 - Choose available date
 - See available time slots
 - Times shown in guest's timezone

3. **Information Collection**
 - Enter name (required)
 - Enter email (required)
 - Phone number (optional)
 - Notes/questions (optional)
 - Custom questions if configured

4. **Confirmation**
 - Booking confirmed immediately
 - Confirmation page with details
 - Email sent with calendar invite
 - Google Meet link if applicable

### Host Experience
1. **Notification**
 - Real-time notification of new booking
 - Email notification (if enabled)
 - Dashboard update

2. **Calendar Update**
 - Event added to Google Calendar
 - Guest added as attendee
 - Meet link in event description

3. **Management**
 - View in Bookings dashboard
 - Reschedule if needed
 - Cancel with reason
 - Add to CRM as contact

### Rescheduling
Guests can reschedule using their confirmation link:
1. Access booking via confirmation email
2. Click "Reschedule"
3. Select new date/time
4. Confirm changes
5. Calendar automatically updated

### Cancellations
Both host and guest can cancel:
- Cancellation reason required
- Email notifications sent
- Calendar event removed/updated
- Slot becomes available again

---

## Customization & Branding

### Per-Event Type Branding
Each event type can have unique branding:

**Theme Color**
- Primary color for buttons
- Accent color for selections
- Applied to booking page UI

**Banner Image**
- Header image on booking page
- Recommended: 1200x400px
- Supports JPG, PNG formats
- Enter URL to hosted image

**Custom Messages**
- Confirmation message after booking
- Reminder email templates (coming soon)
- Cancellation messages

### Public Profile Page
Your scheduling profile (`/schedule/[username]`):
- Lists all active event types
- Shows your name and avatar
- Professional landing page
- Mobile-responsive design

### Booking Page Customization
The booking page inherits:
- Event type theme color
- Banner image if set
- Your organization branding
- Professional, clean layout

---

## API Reference

### Database Tables

#### event_types
- `id`: UUID (Primary Key)
- `profile_id`: UUID (Foreign Key to profiles)
- `title`: Text
- `slug`: Text (URL slug)
- `description`: Text
- `duration_minutes`: Integer
- `theme_color`: Text (hex color)
- `banner_image_url`: Text
- `location_type`: Text
- `is_active`: Boolean
- Additional configuration fields

#### bookings
- `id`: UUID (Primary Key)
- `event_type_id`: UUID (Foreign Key)
- `profile_id`: UUID (Host profile)
- `guest_name`: Text
- `guest_email`: Text
- `start_date_time`: Timestamp
- `end_date_time`: Timestamp
- `status`: Text (confirmed/cancelled/rescheduled)
- `google_calendar_event_id`: Text
- `confirmation_token`: UUID

#### availability_rules
- `id`: UUID (Primary Key)
- `event_type_id`: UUID (Foreign Key)
- `weekday`: Integer (0-6, Sunday-Saturday)
- `start_time_minutes`: Integer (minutes from midnight)
- `end_time_minutes`: Integer

#### google_calendar_connections
- `id`: UUID (Primary Key)
- `profile_id`: UUID (Foreign Key)
- `google_user_id`: Text
- `google_email`: Text
- `access_token`: Text (encrypted)
- `refresh_token`: Text (encrypted)
- `token_expiry`: Timestamp

### Service Classes

#### EventTypeService
```typescript
- createEventType(profileId, eventTypeData)
- updateEventType(eventTypeId, updates)
- deleteEventType(eventTypeId)
- getProfileEventTypes(profileId)
- toggleEventTypeStatus(eventTypeId, isActive)
```

#### BookingService
```typescript
- createBooking(bookingData)
- cancelBooking(bookingId, reason, cancelledBy)
- rescheduleBooking(bookingId, newStartDateTime)
- getProfileBookings(profileId, filters)
- getBookingByToken(token)
```

#### AvailabilityService
```typescript
- calculateAvailability(eventTypeId, startDate, endDate)
- isSlotAvailable(eventTypeId, startDateTime, endDateTime)
- getNextAvailableSlot(eventTypeId, afterDate)
```

#### GoogleCalendarService
```typescript
- initiateOAuthFlow(profileId)
- handleOAuthCallback(profileId, code)
- getConnection(profileId)
- disconnect(profileId)
- listCalendars(profileId)
```

### Edge Functions
- `google-calendar-oauth-url`: Generate OAuth URL
- `google-oauth-callback`: Handle OAuth callback
- `google-calendar-busy-times`: Fetch busy times
- `google-calendar-create-event`: Create calendar event

---

## Troubleshooting

### Common Issues

**"No available slots showing"**
- Check your availability settings
- Verify Google Calendar is connected
- Check for conflicting events
- Ensure advance notice settings aren't too restrictive

**"Google Calendar not syncing"**
- Test connection in integrations
- Re-authorize if needed
- Check calendar permissions
- Verify correct calendar selected

**"Booking link not working"**
- Ensure event type is active
- Check URL slug is correct
- Verify profile settings

**"Can't create event type"**
- Ensure unique slug
- Check required fields
- Verify permissions

### Beta Limitations
As this feature is in beta, some limitations exist:
- Email notifications through edge functions only
- Single calendar support per user
- Time zone detection based on browser
- No recurring appointments yet

### Getting Help
1. Check this documentation
2. Review error messages carefully
3. Contact support with:
 - Event type ID
 - Booking ID (if applicable)
 - Error messages
 - Steps to reproduce

---

## Roadmap

### Coming Soon
- **Microsoft Teams**: Teams meeting support
- **Recurring Appointments**: Weekly/monthly recurring slots
- **Group Events**: Multiple attendee support
- **Payment Collection**: Stripe integration for paid bookings
- **SMS Reminders**: Text message notifications
- **Calendar Feed**: iCal subscription for all bookings
- **Round-Robin**: Team scheduling distribution
- **Custom Fields**: Additional booking form fields
- **Webhooks**: Booking event webhooks

### Future Enhancements
- AI-powered scheduling suggestions
- Meeting preparation automation
- Post-meeting follow-up workflows
- Analytics and insights dashboard
- White-label booking pages
- Embedding widget for websites
- Mobile app support
- Voice-activated booking

---

## Security & Privacy

### Data Protection
- All scheduling data encrypted at rest
- OAuth tokens securely stored
- RLS policies enforce data isolation
- HTTPS-only for all communications

### Guest Privacy
- Minimal data collection
- No guest account required
- Data retention policies
- GDPR compliance ready

### Access Control
- Profile-based access control
- Event type ownership validation
- Booking verification via tokens
- Admin override capabilities

---

## Best Practices

### For Sales Teams
- Create different event types for different stages (Discovery, Demo, Follow-up)
- Use buffer time to prepare between calls
- Set daily limits to avoid burnout
- Include prep questions in booking form

### For Consultants
- Use longer advance notice for preparation
- Create premium event types with different durations
- Add detailed descriptions of what's included
- Use custom branding for professionalism

### For Support Teams
- Create priority slots for urgent issues
- Use shorter durations for quick help
- Block time for internal tasks
- Group similar issues in time blocks

### For HR Teams
- Create separate event types per interview stage
- Use buffer time for note-taking
- Include candidate prep information
- Connect with ATS when available

---

This documentation is for the Beta version of ConnectGain Scheduling. Features and functionality may change as we gather user feedback and enhance the system.

---

## See also

- [Bookings](https://docs.connectgain.cloud/02-user-guide/scheduling/bookings.md) — managing booked meetings
- [Contacts](https://docs.connectgain.cloud/02-user-guide/scheduling/contacts.md) — CRM records created from bookings
- Zoom for meeting links — connect Zoom in Settings → Integrations
- [Call Intelligence](https://docs.connectgain.cloud/02-user-guide/scheduling/call-intelligence.md) — AI analysis of synced meeting recordings
- [Scheduling on connectgain.cloud](https://connectgain.cloud/en/scheduling) — feature overview on the ConnectGain website

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Sequences (Drip Campaigns) – ConnectGain User Guide

Source: https://docs.connectgain.cloud/02-user-guide/sequences/

# Sequences (Drip Campaigns) Feature

## Overview

Sequences (`/sequences`) is a multi-channel drip-campaign builder for automated, time-delayed outreach across **Email**, **WhatsApp Lite** (free-form dynamic messages), **[WhatsApp Cloud](https://docs.connectgain.cloud/02-user-guide/05-integrations/whatsapp-cloud-system-user.md)** (Meta-approved templates), and **SMS**. It handles contact enrollment, per-step delays, sending windows, daily send caps, opt-out/unsubscribe compliance, reply-pause, deal-based exit conditions, and analytics — all organization-scoped (multi-tenant, RLS-enforced).

- **Frontend:** the platform, hooks the app, the app
- **Runtime:** `sequence-executor` edge function (cron-driven)
- **Unsubscribe:** `sequence-unsubscribe` edge function (public, token-based)
- **Tables:** `sequences`, `sequence_steps`, `sequence_enrollments`, `sequence_execution_log`, `sequence_daily_send_counts`, `sequence_unsubscribe_tokens`

**Contents:**

1. [Sequence Builder](#1-sequence-builder)
2. [Contact Enrollment](#2-contact-enrollment)
3. [Execution Engine](#3-execution-engine-sequence-executor)
4. [Channels & Sending](#4-channels--sending)
5. [Compliance & Unsubscribe](#5-compliance--unsubscribe)
6. [Analytics & Reporting](#6-analytics--reporting)
7. [Test Sends](#7-test-sends)
8. [How-To Guide](#how-to-guide) · [Use Cases](#use-cases) · [Test Cases](#test-cases)

---

## 1. Sequence Builder

**Sequence:**
- Name + description
- `channels` (JSONB flags): `email`, `sms`, `whatsapp_lite`, `whatsapp_cloud`
- Status: `draft`, `active`, `paused`, `archived` — only **active** sequences are processed by the executor
- Optional **sending window**: `sending_window_start` / `sending_window_end` (`HH:MM`) resolved in `sending_window_timezone` → org `settings.timezone` → UTC
- Optional **exit conditions**: `exit_on_deal_created`, `exit_on_deal_stages[]`

**Steps** (`sequence_steps`, ordered by `step_order`):
- `channel` — `email` | `sms` | `whatsapp_lite` | `whatsapp_cloud` (legacy `whatsapp` treated as Lite)
- `delay_minutes` — wait **after the previous step** before this step fires
- `message_body` (required), `subject` (email), `channel_account_id` (which connected account sends it)
- WhatsApp Cloud: `template_name`, `template_language`, and optional `template_variables[]` (ordered map for placeholder resolution)

**Variable substitution** (message bodies / subject) uses **single-brace** tokens, replaced at send time from the contact:

| Token | Value |
|-------|-------|
| `{first_name}` | contact first name |
| `{last_name}` | contact last name |
| `{name}` | full name |
| `{email}` | primary email (`emails[0]`) |
| `{phone}` | primary phone (`phones[0]`) |

> WhatsApp Cloud templates use Meta's positional `{{1}}`, `{{2}}` placeholders instead. Each placeholder is filled from the step's `template_variables` map when configured (a token like `{first_name}` is resolved from the contact); otherwise it falls back to the contact's name so the send still succeeds.

---

## 2. Contact Enrollment

**Paths:**
- Single contact — `SequenceEnrollmentMenu` (contact profile / dropdown toggle)
- Bulk — `BulkSequenceEnrollmentMenu` (multi-select on the contacts list)
- From a deal — `DealSequenceEnrollmentMenu` (enrolls the deal's linked contacts)
- By tag — `enrollByTag` (all contacts carrying the selected tag)
- Test send — `TestSequenceDialog` (runs the steps immediately against one contact; see §7)

**What is written to `sequence_enrollments`:** `status='active'`, `current_step_index=0`, `enrolled_by`, and `next_step_at = now + firstStep.delay_minutes`. A `UNIQUE(sequence_id, contact_id)` constraint guarantees one enrollment per contact per sequence.

**Entry validation (bulk / dialog / tag paths):**
- Contacts with `opt_in_status = false` are **excluded**.
- Contacts with **no email and no phone** are **excluded** (nothing could ever be sent).
- Contacts **already enrolled** are left untouched — re-enrolling never restarts, resurrects, or resets a `completed`, `removed`, `unsubscribed`, `bounced`, or in-progress contact. The UI reports how many were newly enrolled vs skipped.

**Enrollment status lifecycle:**

| Status | Meaning | Set by |
|--------|---------|--------|
| `active` | receiving steps | enrollment |
| `completed` | all steps sent | executor (no more steps) |
| `paused` | contact replied → held | reply trigger |
| `removed` | manually removed | UI (`removeEnrollments` / toggle) |
| `failed` | step failed 3× or contact permanently unreachable (no email/phone) | executor |
| `exited` | deal exit condition met | deal-exit trigger + executor |
| `bounced` | hard-bounced email address | executor |
| `unsubscribed` | opted out / used unsubscribe link | unsubscribe fn + executor |

`active` is the only status the executor processes; every other status stops sending.

---

## 3. Execution Engine (`sequence-executor`)

Runs on a cron schedule. Each tick:

1. **Dequeue** — selects up to **50** enrollments with `status='active'` and `next_step_at <= now` (partial index `idx_sequence_enrollments_next_step`).
2. **Claim** — optimistic-lock update (`next_step_at` pushed +10 min, matched on the prior `next_step_at`); a losing racer matches 0 rows and skips. Prevents double-send across overlapping runs.
3. **Guards** (in order), each reschedules or stops without sending:
 - Parent sequence still `active`? else skip.
 - **Exit conditions** — if the contact has a deal (created / in an exit stage), enrollment → `exited`.
 - **Sending window** — if outside the window (in the resolved timezone), `next_step_at` is moved to the next window open.
 - **WhatsApp Lite pacing** — a **random 10–45 minute gap is enforced between consecutive sends per WhatsApp Lite account**, guaranteed across cron ticks via an atomic DB slot claim (`claim_wa_lite_send_slot`). When an account is still cooling down, the enrollment is deferred to the reserved time; only one send per account is released per window, so messages are never blasted.
4. **Send** — dispatch by channel (see §4), then write one `sequence_execution_log` row (`sent` | `failed` | `skipped`) with a per-step `executed_at` timestamp and the rendered content.
5. **Progress** the enrollment based on the result:
 - **sent** → advance to the next step (or `completed` if last).
 - **failed** → retry with exponential backoff (5 → 10 → 20 min); after 3 failures → `failed`.
 - **skipped (retry)** — e.g. a **daily send cap** was hit → reschedule the **same** step to the next day. The message is **not** dropped or skipped past.
 - **skipped (terminal)** — opt-out, unsubscribed, hard-bounced, or no email/phone → stop the enrollment with the matching status (`unsubscribed` / `bounced` / `failed`).
 - **skipped (advance)** — recoverable config gaps (e.g. no channel account / no template on this step) → move to the next step.

**Every outbound send is also mirrored to the inbox** (`conversations` + `messages`, `source: "sequence"`).

---

## 4. Channels & Sending

| Channel | Send path | Notes |
|---------|-----------|-------|
| **Email** | `email-send` (SMTP) or `email-send-ses` (AWS SES) | Auto-selects provider from the step's channel account. Injects a CAN-SPAM unsubscribe footer. Hard-bounce detection pauses the contact's active enrollments. Daily cap per sender (SMTP default **150**, SES from account config). |
| **WhatsApp Lite** | `whatsapp-lite-send` (Appgain) | Free-form text + variables. Daily cap **200/account/day**. Enforced **random 10–45 min gap between sends per account** (§3). |
| **WhatsApp Cloud** | `whatsapp-cloud-send` | Requires a Meta-approved `template_name`; components/parameters built from the template definition + `template_variables`. |
| **SMS** | Appgain notify scheduler | Text + variables; uses org or channel Appgain credentials. |

**Daily send caps** are enforced atomically via `increment_sequence_send_count_v2` (per `account_kind` + account + day). If a send is reserved against the cap but then fails, the reserved slot is **returned** (`decrement_sequence_send_count_v2`) so failures/retries don't leak quota.

**Opt-out is checked on every channel** at send time (`contact.opt_in_status`); email additionally checks the unsubscribe-token table and the bounce-suppression list.

---

## 5. Compliance & Unsubscribe

- **Unsubscribe link** is appended to every sequence email, pointing at `/sequence-unsubscribe?token=…`.
- **Tokens** live in `sequence_unsubscribe_tokens`, one per `(email, organization_id)`. Each token is a **256-bit random opaque value** (`encode(gen_random_bytes(32),'hex')`) — unguessable; looked up server-side by the public `sequence-unsubscribe` edge function.
- **On unsubscribe** the function: marks the token `unsubscribed_at`, sets the contact `opt_in_status = false`, sets that contact's **active** enrollments to `unsubscribed`, and logs a `contact_activity_log` entry.
- **Global opt-out:** because `opt_in_status` is honored by all channels, unsubscribing stops Email, WhatsApp, and SMS for that contact — not just the current sequence.
- **Unsubscribes are not silently reversed.** An internal opt-in flip / import does **not** auto-clear a prior unsubscribe; re-subscription requires an explicit, deliberate action.

---

## 6. Analytics & Reporting

Backed by `sequence_execution_log` (statuses `sent` / `failed` / `skipped`), enrollment states, and the bounce-suppression list. The dashboard (`SequenceAnalyticsDashboard`) reads a 30-day window by default (range index `idx_sequence_execution_log_org_executed_at`), paginated to avoid the PostgREST 1000-row cap.

**Headline metrics:**
- **Messages Sent** = executions with status `sent` only (skipped/failed excluded).
- **Success Rate** = `sent / (sent + failed)` — over delivery **attempts**, not skips.
- **Unsubscribes** — count + rate over enrollments in the range.

**Breakdowns:**
- **Channel performance** — sent / failed / rate per channel (rate over attempts).
- **Enrollment status** — active, completed, paused, removed, **unsubscribed, bounced, exited (goal met), failed** (all terminal states are surfaced so the breakdown reflects reality).
- **Per-step** — executions, successes, failures, skips, and grouped error reasons per step.
- **Deliverability** — per-recipient email failures, with bounces reclassified from the suppression list.
- **Recent activity** — latest executions with rendered subject/content.

**Reply-pause rows** (`Auto-paused: contact replied`) are logged as `skipped` but represent a *good* outcome, so they are **excluded** from all error/deliverability aggregations.

**Known reporting gaps (roadmap):** email opens/clicks are tracked in `email_tracking_events` but not yet joined into sequence reports; reply-rate and a true enrolled→step cohort funnel are not yet surfaced.

---

## 7. Test Sends

`TestSequenceDialog` invokes the executor in `test` mode against a single contact. It:
- **Verifies the caller's organization** — the JWT must belong to the `organization_id`, and all lookups are org-scoped (no cross-tenant sends).
- Runs every step immediately (skips daily-cap accounting), staggering consecutive WhatsApp Lite steps.
- **Sends real messages** to the target contact (it is a live test, not a dry run) — still honoring opt-out, unsubscribe, and bounce checks.

---

## How-To Guide

All tasks start at **Sidebar → Sequences** (`/sequences`). The page has two tabs: **Sequences** (list + builder) and **Analytics**.

### A. Create a sequence

1. Click **Create Sequence** (top-right).
2. Enter a **Sequence Name** (required) and an optional **Description**.
3. (Optional) configure a **Sending Window** and **Exit Conditions** — see B and C.
4. Under **Steps**, click one of the channel buttons to add a step: **Email**, **SMS**, **WA Lite**, or **WA Cloud**. Add as many steps as you need; drag the handle to reorder.
5. For each step set:
 - **Delay** — how long to wait *after the previous step* before this one fires (`Immediately`, `5 minutes`, … `1 hour`, `1 day`, `1 week`).
 - **Send via** — the connected channel account that will send it.
 - **Subject** (email only) and **Message** (see D for personalization). For **WA Cloud**, pick an approved **Template** instead of free text (see E).
6. **Save**. The sequence is created as **Draft**.
7. When ready, **Activate** it (see H) — the executor only processes *active* sequences.

> The first step usually uses **Immediately** so enrolled contacts are picked up on the next executor tick.

### B. Configure a sending window (quiet hours)

1. In the builder, enable **Sending Window**.
2. Set **From** / **To** (e.g. `09:00`–`17:00`) and the **Timezone**.
3. Steps that come due outside the window are **held** and automatically sent when the window next opens. Overnight windows (e.g. `20:00`–`06:00`) are supported.

### C. Configure exit conditions (stop on conversion)

1. In the builder, open **Exit Conditions**.
2. Toggle **Exit when any deal is created for the contact**, and/or select deal **stages** that should end the sequence.
3. When a contact matches, their enrollment moves to **`exited`** and no further steps are sent. This fires both instantly (DB trigger) and as a safety check on every executor run.

### D. Personalize messages with variables

Insert single-brace tokens into a subject or message body; they're replaced per contact at send time:

`{first_name}` · `{last_name}` · `{name}` · `{email}` · `{phone}`

Example: `Hi {first_name}, thanks for your interest!` Missing values render as empty (or a safe fallback), so the send never breaks.

### E. Set up a WhatsApp Cloud template step

1. Add a **WA Cloud** step and pick the connected WhatsApp Cloud account under **Send via**.
2. Choose an approved **Template** (name + language) from the picker — WhatsApp Cloud does **not** allow free text outside the 24-hour service window.
3. If the template has positional placeholders (`{{1}}`, `{{2}}`, …), provide an ordered variable map so each placeholder is filled correctly (a token like `{first_name}` is resolved from the contact). Without a map, placeholders fall back to the contact's name.

### F. Enroll contacts

There are four ways to enroll (all skip opted-out contacts, contacts with no email/phone, and contacts already enrolled):

- **From the sequence** — on the Sequences tab, click the **Enroll** (person+) action, then pick contacts or a **tag**.
- **From the contacts list** — select contacts → **Enroll in Sequence** → choose the sequence.
- **From a deal** — use the deal's **Enroll in Sequence** menu to enroll the deal's linked contacts.
- **By tag** — enroll everyone carrying a tag in one action.

The confirmation reports how many were newly enrolled vs skipped (already enrolled / not eligible). Re-enrolling never restarts someone who already completed, unsubscribed, bounced, or is mid-sequence.

### G. Test before launching

1. On the Sequences tab, open the sequence's **Test** action.
2. Search for and pick one contact.
3. Run it — every step executes immediately against that contact. **This sends real messages** (it is a live test, not a preview) and still respects opt-out/unsubscribe/bounce checks. You can only test sequences in your own organization.

### H. Activate, pause, archive, delete

- **Activate / Pause** — the play/pause action toggles the sequence between `active` and `paused`. Pausing holds all its enrollments (no steps sent) until reactivated.
- **Edit** — change steps/settings anytime; changes apply to future sends.
- **Delete / Archive** — removes it from processing.

### I. Monitor performance

Open the **Analytics** tab (default window: last 30 days; adjustable):

- **Overview** — Messages Sent (actual sends), Success Rate (sent ÷ delivery attempts), Unsubscribes.
- **Enrollment Status** — active / completed / paused / removed / unsubscribed / bounced / exited (goal met) / failed.
- **Channel Performance** — sent / failed / rate per channel.
- **Per-step** — executions, successes, failures, skips, and grouped error reasons.
- **Deliverability** — per-recipient email failures with bounces flagged.
- **Activity** — the most recent executions with the rendered content.

To see who is where in a sequence, open its **enrollments** panel from the list.

### J. Handle unsubscribes & opt-outs

- Every sequence email includes an **unsubscribe** footer. When a recipient clicks it, their contact is marked opted-out, active enrollments become **`unsubscribed`**, and they're excluded from *all* future sends on every channel.
- A contact replying (inbound message) **auto-pauses** their active enrollments so you don't message over a live conversation.
- Honored unsubscribes are **not** silently reversed by imports or edits — re-subscribing requires a deliberate action.

### K. Troubleshooting (why a contact didn't receive a step)

Check the **Per-step** / **Deliverability** analytics — the `error_message` explains each skip/failure:

| Symptom | Cause | Resolution |
|---------|-------|------------|
| Enrollment `unsubscribed` right away | Contact opted out / unsubscribed | Expected — respect the opt-out |
| Enrollment `failed`, "no phone/email" | Contact missing the channel's address | Add the contact's email/phone |
| Step skipped, "Daily … limit reached" | Sender hit its daily cap | It auto-retries the next day; raise the cap or add a sender |
| Step skipped, "No template selected" | WA Cloud step without a template | Edit the step and pick an approved template |
| Nothing sends at all | Sequence is Draft/Paused, or outside the sending window | Activate it / wait for the window |
| Enrollment `bounced` | Email hard-bounced previously | Address is suppressed; fix or remove it |

---

## Use Cases

### Welcome Email Sequence
5-email onboarding series (immediate → +1d → +3d → +5d → +7d), auto-enrolled when a contact is tagged "Subscriber" via an automation.

### WhatsApp Follow-Up
3 WhatsApp Lite nudges (+2h → +2d → +5d) manually enrolled after a quote is sent; replies auto-pause the sequence.

### Re-Engagement Campaign
2-email win-back (`We miss you, {first_name}` → last-chance) bulk-enrolled on contacts tagged "Inactive 90 Days".

### Post-Purchase WhatsApp Cloud
Order confirmation → shipping → delivery → feedback using Meta-approved templates, auto-enrolled when a deal closes.

---

## Test Cases

1. **Create sequence with steps** — create, add 3 steps with delays, save, confirm it appears active.
2. **Enroll contacts** — enroll 5; opted-out / no-channel contacts are skipped; already-enrolled are skipped; the rest become `active`.
3. **Step execution** — 1-step sequence, enroll, wait for cron, confirm message sent, `sequence_execution_log` row is `sent`, enrollment `completed`.
4. **Daily cap deferral** — exceed a sender's daily cap; confirm the step is rescheduled to the next day (not dropped) and the message goes out then.
5. **Unsubscribe** — click the unsubscribe link; confirm token `unsubscribed_at` set, contact `opt_in_status=false`, active enrollments become `unsubscribed`, and re-enrollment is skipped.
6. **Reply-pause** — send an inbound message from an enrolled contact; confirm active enrollments become `paused` and the pause does not appear as a delivery error in analytics.
7. **WhatsApp Cloud template** — select an approved template, map `template_variables`, enroll a valid number, confirm the template is delivered.

---

## Related Documentation

- [Automations](https://docs.connectgain.cloud/02-user-guide/sequences/automations.md), [Contacts](https://docs.connectgain.cloud/02-user-guide/sequences/contacts.md), [AI Re-Engagement](https://docs.connectgain.cloud/02-user-guide/sequences/ai-reengagement.md)
- [WhatsApp Lite API Guide](https://docs.connectgain.cloud/02-user-guide/05-integrations/whatsapp-lite-api.md)
- [Sequences on connectgain.cloud](https://connectgain.cloud/en/sequences) — feature overview on the ConnectGain website

---

**Document Version:** 2.1.0
**Last Updated:** July 2026

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Social Media Planner & Post Scheduler – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/social-media-planner/

# Social Media Planner

## Overview

The **Social Media Planner** (found at **/social-media** in the app) lets your team compose, schedule, publish, and track social-media content across multiple platforms without leaving ConnectGain.

Because the planner reuses the connection (OAuth authorization) from your already-connected Meta and LinkedIn messaging channels, most platforms need no separate sign-in step — connect the channel once for messaging and it becomes available for publishing too.

The planner is organized into four tabs:

- **Composer** — create a post, choose platforms, and publish or schedule it.
- **Calendar** — a month-view overview of scheduled and drafted posts.
- **Library** — a searchable, filterable list of all your posts, with bulk import.
- **Analytics** — a summary of how many posts you've created, by status and platform.

Access to the planner requires the **Social Media** permission (see [Permissions](#permissions)).

**Contents:** [Content Types & Platform Support](#content-types--platform-support) · [Composer](#composer) · [Scheduling & Publishing](#scheduling--publishing) · [Library & Calendar](#library--calendar) · [Analytics](#analytics) · [Permissions](#permissions) · [Limitations](#limitations) · [Use Cases](#use-cases) · [FAQ](#faq)

---

## Content Types & Platform Support

The Composer supports **11 content types**. When you pick a content type, the platform picker automatically filters itself to show only the platforms that support that type.

| Content type | Available on |
|--------------|--------------|
| **Text** | Instagram, Facebook, X (Twitter), LinkedIn, TikTok |
| **Image** (1 image) | Instagram, Facebook, X, LinkedIn, TikTok |
| **Carousel** (2–10 images) | Instagram, Facebook, LinkedIn |
| **Video** (1 video) | Instagram, Facebook, X, LinkedIn, TikTok |
| **Reel** (1 video) | Instagram, TikTok |
| **Story** (1 image or video) | Instagram, Facebook |
| **GIF** (1 GIF) | X, Facebook, LinkedIn |
| **Document** (1 PDF) | LinkedIn |
| **Link** | Instagram, Facebook, X, LinkedIn, TikTok |
| **Poll** | X, LinkedIn |
| **Thread** | X |

### Which platforms actually publish

You can **select** five platforms in the Composer — Instagram, Facebook, X (Twitter), LinkedIn, and TikTok — but **automatic publishing is available for three of them**:

| Platform | Publishing status |
|----------|-------------------|
| **Facebook Pages** | Published automatically (text, hashtags, link, media) |
| **Instagram Business** | Published automatically (single image/video, carousels, reels) |
| **LinkedIn** | Published automatically (text and article/link posts) |
| **X (Twitter)** | Draft only — not published to the platform yet |
| **TikTok** | Draft only — not published to the platform yet |

Instagram requires at least one piece of media on a post — Instagram does not accept text-only posts.

> **Note:** The **poll** and **thread** content types can be composed, saved, and previewed in the app, but they are **not yet sent to the social platforms**. For now they behave as draft/composer features.

---

## Composer

The Composer is where you build a post. It includes:

- **Content-type selector** — pick one of the 11 types; the available platforms update automatically to match.
- **Title** (optional) and **content** — the main text/caption of your post.
- **Hashtags** — entered as a comma-separated list; they're appended to the post.
- **Media upload** — drag-and-drop or select files, with progress shown during upload. Each content type has its own media rules (for example, one image for an image post, 2–10 images for a carousel, one video for a video or reel, a single PDF for a document).
- **Link** input with a **live link preview** so you can see how the shared link will appear.
- **Poll composer** — question, options, and duration (composer/draft feature).
- **Thread composer** — build a multi-part thread (composer/draft feature).
- **Platform picker** — shows each supported platform and whether it's **connected** (ready to publish) or **not connected**.
- **Live preview** — see how the post will look on the selected platform.
- **Schedule** (optional) — choose a date and time to publish later.

### Composer actions

- **Save Draft** — saves the post without publishing. Useful for handing work to someone who can publish.
- **Schedule** — saves the post to go out automatically at the date/time you set.
- **Publish Now** — publishes the post immediately to the selected connected platforms.

The **Schedule** and **Publish Now** actions only appear for users who have permission to publish. When you set a schedule, the time you pick is stored correctly so the post goes out at the exact moment you intended, regardless of time zone.

---

## Scheduling & Publishing

Posts move through a clear set of statuses:

**Draft → Scheduled → Publishing → Published**

If something goes wrong, a post ends up as **Partially Failed** (some platforms succeeded, others didn't) or **Failed** (none succeeded). ConnectGain tracks the result for each platform separately, so you can see exactly which platform published and which didn't.

- **Publish Now** sends the post to its platforms right away and shows you the outcome.
- **Scheduled** posts are published automatically by a background scheduler that checks for due posts about once a minute. When a post's scheduled time arrives, it's picked up, published, and its status updated.

If a post fails or only partially succeeds, the failure reason is shown on the post. Common reasons are a disconnected or expired channel connection, or a channel that's missing the permission needed to publish. To recover, reconnect the affected channel (in your channel settings) and then use the **Publish now** or **Retry** action on the post.

---

## Library & Calendar

### Content Library

The **Library** tab lists all your posts as cards, each showing the content type, current status, target platforms, and scheduled/created dates. You can:

- **Search** by content or title.
- **Filter** by status and by content type.
- **Delete** a post.
- **Publish now** a draft or scheduled post, or **Retry** a failed one (for users with publish permission).

### Bulk CSV import

From the Library you can **import posts in bulk from a CSV file**:

1. Use the **Download Template** option to get a correctly formatted starter file.
2. Fill in your posts — content, content type, target platforms, an optional schedule date/time, hashtags, title, link, and poll details.
3. Upload the file. Rows that include a schedule time are imported as **Scheduled**; the rest are imported as **Draft**.
4. Review the import summary, which reports how many posts imported successfully and flags any rows with errors (such as an invalid content type or empty content).

### Calendar

The **Calendar** tab shows your posts on a **month grid**. Navigate with previous / **Today** / next controls. Each day shows the posts due that day, with a "+N more" indicator when there are more than fit. Scheduled posts appear on their scheduled day; drafts appear by the day they were created.

The calendar is a **read-only overview** today — you create and edit posts in the Composer and Library, not by clicking days on the calendar.

---

## Analytics

The **Analytics** tab gives you a quick, internal summary of your posting activity:

- **Summary cards** — total posts, published, drafts, and failed.
- **Breakdowns** — number of posts by content type and by platform.

> These figures count *your posts inside ConnectGain*. Platform engagement metrics — reach, impressions, likes, comments — are **not** yet pulled from the social platforms.

---

## Permissions

Access to the Social Media Planner is controlled by permissions set for each user:

- Users need the **Social Media** permission to open the planner at all.
- A separate **publish** permission controls whether a user sees the **Publish Now**, **Schedule**, and **Retry** actions. Users without it can still write and **Save Draft** posts for someone else to publish.
- Depending on their permissions, a user may see only their own posts or the whole organization's posts.

Your organization must also have the Social Media Planner feature enabled.

---

## Limitations

- **X (Twitter)** and **TikTok** can be selected and drafted, but posts are **not published** to those platforms yet.
- **Polls** and **threads** can be composed and previewed but are **not published** to the platforms yet.
- **Analytics** shows internal post counts, not platform reach, impressions, or engagement.
- The **Calendar** is a read-only month view — there's no drag-to-reschedule, recurring posts, or click-a-day-to-create.
- There is no approval workflow or version history.
- Publishing reuses your **messaging** channel connections, so the connection must include the permissions needed to publish. If a channel is missing a publishing permission, publishing to that platform returns a permission error until you reconnect the channel with the right access.

---

## Use Cases

### Schedule a week of content

1. Open **Social Media → Composer**.
2. Pick a content type (e.g. *Image*), write the caption, add hashtags, and upload media.
3. Select your target platforms (only connected, supported platforms will publish).
4. Set a **Schedule** date/time and click **Schedule**.
5. Repeat for each post and review everything in the **Calendar**.
6. Each post publishes automatically at its scheduled time; watch the status change to **Published** (or **Failed**, with a reason).

### Coordinated launch across platforms

1. In the Composer, create the post and select Facebook, Instagram, and LinkedIn.
2. Either **Publish Now** or **Schedule** all of them for the same launch time.
3. Watch each post's status. A **Partially Failed** post shows which platform didn't publish and why.
4. Fix the failing channel (for example, reconnect it) and use **Retry** from the Library.

### Draft now, publish later

1. A team member without publish permission writes posts and clicks **Save Draft**.
2. A manager with publish permission reviews the drafts in the Library and clicks **Publish now** (or sets a schedule).

### Recover a failed post

1. In the **Library**, filter by **Failed**.
2. Read the error shown on the card (for example, an expired channel connection).
3. Reconnect the affected channel in your channel settings.
4. Click **Retry** on the post to publish it again.

---

## FAQ

**Which platforms will actually post automatically?**
Facebook Pages, Instagram Business, and LinkedIn. X (Twitter) and TikTok can be drafted but aren't published yet.

**Do I need to connect social accounts separately?**
No. The planner reuses your existing Meta and LinkedIn messaging channel connections. Just make sure those connections include the permissions needed to publish.

**Why was my Instagram post rejected?**
Instagram requires at least one image or video — text-only posts aren't accepted.

**How soon does a scheduled post go out?**
Scheduled posts are checked and published about once a minute, so they go out right around their scheduled time.

**Can I see likes and reach?**
Not yet. Analytics currently shows how many posts you've created, by status and platform, not platform engagement.

---

## Related Documentation

- [Channels](https://docs.connectgain.cloud/02-user-guide/05-integrations/channels.md)
- [Analytics](https://docs.connectgain.cloud/02-user-guide/social-media-planner/analytics.md)
- [AI Re-Engagement](https://docs.connectgain.cloud/02-user-guide/social-media-planner/ai-reengagement.md)
- [Social Media Planner on connectgain.cloud](https://connectgain.cloud/en/social-media-planner) — feature overview on the ConnectGain website

---

**Document Version:** 3.0.0
**Last Updated:** July 2026

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Support Issues & Fixes Tracking – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/support-tickets/

# Issues & Fixes (Support Projects)

## Overview

There is no standalone "Support Tickets" screen. Instead, support work is tracked as **Issues & Fixes** inside a **Support-type project**. When a project is created with the **SUPPORT** type, its detail page gains an **Issues & Fixes** tab where your team logs issues, tracks their status and priority, assigns them to team members, and records how each issue was fixed.

Support projects also show an optional **SLA configuration** panel (response and resolution targets, business hours) to help teams keep service levels in view.

> This feature is part of Project Management. To use it, create a project and choose the **SUPPORT** project type.

**On this page:** [Features](#features) · [Use Cases](#use-cases) · [Test Cases](#test-cases) · [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting)

---

## Features

### 1. Logging Issues

From a Support project's **Issues & Fixes** tab, click **Log Issue** to open the issue form. An issue captures:

- **Issue Title** *(required)* — a short summary of the problem.
- **Issue Description** *(required)* — the details of what happened.
- **Category** *(optional)* — one of **Bug**, **Feature Request**, **Performance**, **Security**, or **Other**.
- **Priority** — **LOW**, **MEDIUM** (default), **HIGH**, or **URGENT**.
- **Status** — **OPEN** (default), **IN_PROGRESS**, **RESOLVED**, or **CLOSED**.
- **Assign To** — a team member in your organization (or leave unassigned).
- **Reported At** — date and time the issue was reported (defaults to now).

There is no auto-generated ticket number. Issues are identified by their title and details, not by a code like `CUS-001`.

### 2. Recording the Fix

When an issue is resolved or closed (or whenever you edit an existing issue), extra fields become available to document the resolution:

- **Fix Description** — how the issue was fixed.
- **Fix Steps** — the steps taken to fix it.
- **Resolution Notes** — any additional notes.

Setting the status to **RESOLVED** or **CLOSED** automatically records a resolution timestamp; moving it back to an open state clears it.

### 3. Status Workflow

**Status values:**
- **OPEN** — newly logged, not yet started.
- **IN_PROGRESS** — actively being worked on.
- **RESOLVED** — a fix has been applied.
- **CLOSED** — completed and archived.

Status is chosen directly on the issue form; there is no forced transition order.

### 4. Priority Levels

- **LOW** — can be handled later.
- **MEDIUM** — normal priority (default).
- **HIGH** — needs attention.
- **URGENT** — immediate attention required.

Priority and status are shown as color-coded badges on each issue card for quick scanning.

### 5. Assignment

Issues can be assigned to any team member in the organization via the **Assign To** picker, or left unassigned. Reassignment is done by editing the issue.

### 6. SLA Configuration (Support Projects)

Support projects can display an **SLA configuration** panel showing:

- **Response time** target (time to first response).
- **Resolution time** target (time to resolve).
- **Business hours only** toggle, with business hours start/end when enabled.

These targets give the team visible service-level goals for the support project.

### 7. Managing Issues

Each logged issue card supports:

- **Edit** — update any field, including the fix details.
- **Delete** — remove the issue (with a confirmation prompt).

---

## Use Cases

### Use Case 1: Log an Issue

**Scenario:** A customer reports a problem and an agent records it.

**Steps:**
1. Open the Support project.
2. Go to the **Issues & Fixes** tab.
3. Click **Log Issue**.
4. Enter a title, e.g. "Login not working".
5. Add a description of the problem.
6. (Optional) Choose a category and set priority to HIGH.
7. (Optional) Assign it to a team member.
8. Click **Log Issue** to save.

**Expected Outcome:** The issue appears in the Issues & Fixes list with its priority and status badges.

### Use Case 2: Resolve an Issue and Record the Fix

**Scenario:** An engineer fixes the problem and documents it.

**Steps:**
1. Open the issue and click **Edit**.
2. Change status to **RESOLVED**.
3. Fill in **Fix Description**, **Fix Steps**, and any **Resolution Notes**.
4. Save the issue.

**Expected Outcome:** The issue shows as RESOLVED with the fix details visible on its card, and a resolution timestamp is recorded.

### Use Case 3: Track Open Work

**Scenario:** A lead reviews outstanding issues in the project.

**Steps:**
1. Open the Support project's **Issues & Fixes** tab.
2. Scan the list for OPEN and IN_PROGRESS issues.
3. Use the priority badges to focus on HIGH/URGENT items first.
4. Reassign or update status as needed.

**Expected Outcome:** The team has a clear view of outstanding support work.

---

## Test Cases

### Test Case 1: Log an Issue

1. Open a Support project and go to **Issues & Fixes**.
2. Click **Log Issue**.
3. Enter a title and description, set priority HIGH.
4. Save with **Log Issue**.
5. Verify the issue appears in the list.

**Expected Result:** Issue logged and displayed with correct priority/status.

### Test Case 2: Required Fields

1. Open the **Log Issue** form.
2. Leave the title or description blank.
3. Verify the save button stays disabled until both are filled.

**Expected Result:** Title and description are required.

### Test Case 3: Record a Fix

1. Edit an existing issue.
2. Set status to **RESOLVED**.
3. Fill in Fix Description and Fix Steps.
4. Save and confirm the fix details show on the card.

**Expected Result:** Fix details saved and displayed; resolution timestamp recorded.

### Test Case 4: Delete an Issue

1. Click delete on an issue card.
2. Confirm the prompt.
3. Verify the issue is removed from the list.

**Expected Result:** Issue deleted successfully.

---

## Best Practices

1. **Write clear titles** — a concise title makes issues easy to scan.
2. **Set priority honestly** — reserve URGENT for issues that truly need immediate attention.
3. **Document the fix** — completing Fix Description and Fix Steps builds a useful knowledge base.
4. **Keep status current** — move issues through OPEN → IN_PROGRESS → RESOLVED/CLOSED as work progresses.

---

## Troubleshooting

### Issues & Fixes Tab Not Showing

**Issue:** The tab is missing on a project.

**Solutions:**
- Confirm the project's type is **SUPPORT**. The Issues & Fixes tab only appears on Support-type projects.

### Cannot Assign an Issue

**Issue:** No team members appear in the Assign To list.

**Solutions:**
- Verify the person is a member of your organization.
- Confirm you have access to Project Management for this organization.

### Fix Fields Not Visible

**Issue:** The Fix Description/Steps/Notes fields don't appear when logging a new issue.

**Solutions:**
- These fields appear when the status is RESOLVED or CLOSED, and are always available when editing an existing issue.

---

## See also

- [Projects](https://docs.connectgain.cloud/02-user-guide/support-tickets/projects.md) — creating projects, including Support-type projects
- [Tasks](https://docs.connectgain.cloud/02-user-guide/support-tickets/tasks.md) — general task tracking outside support work
- [Contacts](https://docs.connectgain.cloud/02-user-guide/support-tickets/contacts.md) — the customers behind reported issues
- [Team Management](https://docs.connectgain.cloud/02-user-guide/03-admin-guide/team.md) — adding assignable team members
- [Support Tickets on connectgain.cloud](https://connectgain.cloud/en/support-tickets) — feature overview on the ConnectGain website

---

**Last Updated:** July 2026

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Task Management with List & Calendar Views – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/tasks/

# Task Management Feature

## Overview

Task Management (`/tasks`) enables teams to create, assign, track, and complete tasks with due dates, priorities, and associations to contacts and deals. Tasks support both list and calendar views for flexible task organization, helping teams stay organized and meet deadlines.

**On this page:** [Features](#features) · [Use Cases](#use-cases) · [Test Cases](#test-cases) · [API Integration](#api-integration) · [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting)

---

## Features

### 1. Task Management

**Create Tasks:**
- Add new tasks with:
 - Task title, description
 - Priority (Low, Medium, High)
 - Due date and time
 - Assignee (team member)
 - Related contact (optional)
 - Related deal (optional)
 - Tags

**Edit Tasks:**
- Update task information

**Delete Tasks:**
- Remove tasks

**Complete Tasks:**
- Mark tasks as done
- Toggle completion status
- Completion timestamp

**Task Details View:**
- Comprehensive task profile
- All task information
- Related contact/deal
- Activity timeline
- Notes

### 2. View Modes

**List View:**
- Organized task list
- Grouped by status:
 - Overdue tasks (red indicator)
 - Today's tasks
 - Upcoming tasks
 - Tasks without due date
 - Completed tasks
- Task cards with key info
- Quick action buttons

**Calendar View:**
- Visual calendar layout
- Monthly calendar
- Task placement on dates
- Color-coded priorities
- Click to view details
- Drag-and-drop rescheduling

### 3. Task Filtering

**Status Filter:**
- Filter by completion status
- All tasks
- Pending
- Completed
- Overdue

**Priority Filter:**
- Filter by priority
- All priorities
- High priority
- Medium priority
- Low priority

**Assignee Filter:**
- Filter by assignee
- All assignees
- Assigned to me
- Unassigned
- Specific team member

**Search:**
- Search tasks by title or description

### 4. Task Organization

**Priority Levels:**
- Three priority levels
- High (red indicator)
- Medium (yellow indicator)
- Low (green indicator)

**Due Date Management:**
- Date and time tracking
- Date picker
- Time selection
- Overdue indicators
- Today indicators

**Task Grouping:**
- Automatic organization
- By due date
- By status
- By priority
- By assignee

### 5. Task Actions

**Quick Actions:**
- View task details
- Edit task
- Delete task
- Toggle completion
- Change priority
- Reschedule
- Reassign

### 6. Task Analytics

**Completion Rate:**
- Track task completion
- Overall completion percentage
- Per-assignee completion
- Per-priority completion

**Overdue Tracking:**
- Monitor overdue tasks
- Overdue count
- Overdue duration

**Productivity Metrics:**
- Team productivity insights

### 7. Pagination

**50 Tasks Per Page:**
- Efficient loading
- Page navigation

### 8. Task Relationships

**Relationships:**
- Link to contacts
- Link to deals
- Standalone tasks (no link)

**Relationship Benefits:**
- Context from related records
- Quick navigation
- Relationship history

### 9. Due Date Management

**Due Date Features:**
- Date picker selection
- No due date option
- Overdue detection
- Calendar integration

---

## Use Cases

### Use Case 1: Create Task from Contact

**Scenario:**
Agent needs to follow up with a contact next week.

**Steps:**
1. Open contact details
2. Click "Create Task"
3. Enter task title: "Follow up call"
4. Set due date: Next week
5. Set priority: HIGH
6. Assign to self
7. Save task
8. Verify task appears in Tasks list

**Expected Outcome:**
Task created and linked to contact, visible in Tasks page.

### Use Case 2: View Tasks in Calendar

**Scenario:**
Manager wants to see all team tasks for the month.

**Steps:**
1. Go to Tasks
2. Switch to Calendar view
3. View monthly calendar
4. See tasks on their due dates
5. Click task to view details
6. Drag task to change due date

**Expected Outcome:**
All tasks displayed on calendar with easy date management.

### Use Case 3: Filter Overdue Tasks

**Scenario:**
Team lead needs to find all overdue tasks.

**Steps:**
1. Go to Tasks
2. Set filter: Status = "Overdue"
3. View overdue tasks
4. Assign or complete tasks
5. Update due dates as needed

**Expected Outcome:**
All overdue tasks displayed for action.

### Use Case 4: Assign Task to Team Member

**Scenario:**
Manager wants to assign task to specific team member.

**Steps:**
1. Go to Tasks
2. Create or edit task
3. Select assignee from dropdown
4. Save task
5. Filter by assignee to verify
6. Team member sees task in their list

**Expected Outcome:**
Task assigned and visible to team member.

### Use Case 5: Complete Task

**Scenario:**
Agent finishes a task and marks it complete.

**Steps:**
1. Go to Tasks
2. Find task in list
3. Click complete checkbox
4. Task moves to completed status
5. Verify task marked complete
6. Filter shows in completed view

**Expected Outcome:**
Task marked as completed and filtered accordingly.

---

## Test Cases

### Test Case 1: Create Task

**Test:** Verify task creation

**Steps:**
1. Go to Tasks
2. Click "Add Task"
3. Fill in fields:
 - Title: "Test Task"
 - Description: "Test description"
 - Due Date: Tomorrow
 - Priority: HIGH
 - Assignee: Current user
4. Save task
5. Verify task appears in list
6. Open task details
7. Verify all data saved correctly

**Expected Result:**
Task created successfully with all data preserved

### Test Case 2: Filter by Status

**Test:** Verify status filtering

**Steps:**
1. Create tasks with different statuses
2. Filter by "Pending"
3. Verify only pending tasks shown
4. Filter by "Completed"
5. Verify only completed tasks shown
6. Filter by "Overdue"
7. Verify only overdue tasks shown

**Expected Result:**
Status filtering works correctly

### Test Case 3: Filter by Priority

**Test:** Verify priority filtering

**Steps:**
1. Create tasks with different priorities
2. Filter by "HIGH"
3. Verify only high priority tasks shown
4. Filter by "MEDIUM"
5. Verify only medium priority tasks shown
6. Filter by "LOW"
7. Verify only low priority tasks shown

**Expected Result:**
Priority filtering works correctly

### Test Case 4: Filter by Assignee

**Test:** Verify assignee filtering

**Steps:**
1. Create tasks assigned to different users
2. Filter by specific user
3. Verify only that user's tasks shown
4. Filter by "All"
5. Verify all tasks shown

**Expected Result:**
Assignee filtering works correctly

### Test Case 5: Search Tasks

**Test:** Verify search functionality

**Steps:**
1. Create task: "Follow up with John"
2. Search for "Follow"
3. Verify task appears
4. Search for "John"
5. Verify task appears
6. Search for "nonexistent"
7. Verify no results

**Expected Result:**
Search finds tasks by title and description

### Test Case 6: Complete Task

**Test:** Verify task completion

**Steps:**
1. Create pending task
2. Mark task as complete
3. Verify status changed to completed
4. Filter by completed
5. Verify task appears
6. Uncomplete task
7. Verify status changed back

**Expected Result:**
Task completion toggle works correctly

### Test Case 7: Calendar View

**Test:** Verify calendar view functionality

**Steps:**
1. Create tasks with different due dates
2. Switch to calendar view
3. Verify tasks appear on correct dates
4. Click task on calendar
5. Verify task details shown
6. Drag task to different date
7. Verify due date updated

**Expected Result:**
Calendar view displays and manages tasks correctly

### Test Case 8: Overdue Detection

**Test:** Verify overdue task detection

**Steps:**
1. Create task with past due date
2. Verify task marked as overdue
3. Filter by overdue
4. Verify task appears
5. Update due date to future
6. Verify task no longer overdue

**Expected Result:**
Overdue detection works automatically

### Test Case 9: Task Assignment

**Test:** Verify task assignment

**Steps:**
1. Create task
2. Assign to user A
3. Verify assignee set
4. Filter by user A
5. Verify task appears
6. Reassign to user B
7. Verify assignee updated

**Expected Result:**
Task assignment and reassignment work correctly

### Test Case 10: Link Task to Contact

**Test:** Verify task-contact linking

**Steps:**
1. Create contact
2. Create task linked to contact
3. Verify link established
4. Open contact details
5. Verify task appears in contact's tasks
6. Open task details
7. Verify contact link shown

**Expected Result:**
Task-contact linking works bidirectionally

---

## API Integration

### Create Task

**Endpoint:** `POST /rest/v1/tasks`

**Request:**
```json
{
 "organization_id": "org-uuid",
 "title": "Follow up call",
 "description": "Call customer about quote",
 "due_date": "2025-01-15T10:00:00Z",
 "priority": "HIGH",
 "assignee_id": "user-uuid",
 "contact_id": "contact-uuid",
 "deal_id": null
}
```

### Update Task

**Endpoint:** `PATCH /rest/v1/tasks/{id}`

**Request:**
```json
{
 "completed": true,
 "priority": "MEDIUM"
}
```

### Get Tasks

**Endpoint:** `GET /rest/v1/tasks`

**Query Parameters:**
- `organization_id` - Filter by organization
- `assignee_id` - Filter by assignee
- `contact_id` - Filter by contact
- `deal_id` - Filter by deal
- `completed` - Filter by completion status
- `priority` - Filter by priority

---

## Best Practices

1. **Task Organization**
 - Use clear, descriptive titles
 - Set appropriate priorities
 - Assign tasks promptly
 - Set realistic due dates

2. **Task Management**
 - Review tasks daily
 - Complete tasks promptly
 - Update due dates as needed
 - Link tasks to contacts/deals for context

3. **Team Coordination**
 - Assign tasks clearly
 - Use priorities effectively
 - Communicate task status
 - Review overdue tasks regularly

4. **Calendar Usage**
 - Use calendar view for planning
 - Review monthly task distribution
 - Adjust dates for workload balance
 - Plan ahead for deadlines

5. **Task Completion**
 - Mark tasks complete when done
 - Review completed tasks periodically
 - Archive old completed tasks
 - Learn from task patterns

---

## Troubleshooting

### Tasks Not Appearing

**Issue:** Created tasks not visible

**Solutions:**
- Check filters applied
- Verify organization context
- Refresh page
- Check assignee filter

### Calendar Not Showing Tasks

**Issue:** Tasks not appearing in calendar view

**Solutions:**
- Verify tasks have due dates
- Check date range
- Refresh calendar
- Verify task visibility

### Overdue Not Detecting

**Issue:** Overdue tasks not marked

**Solutions:**
- Verify due dates are set
- Check system time
- Refresh task list
- Verify task status

---

## See also

- [Contacts](https://docs.connectgain.cloud/02-user-guide/tasks/contacts.md) — linking tasks to people
- [Deals](https://docs.connectgain.cloud/02-user-guide/tasks/deals.md) — linking tasks to pipeline deals
- [Projects](https://docs.connectgain.cloud/02-user-guide/tasks/projects.md) — larger project and milestone tracking
- [Automations](https://docs.connectgain.cloud/02-user-guide/tasks/automations.md) — auto-creating tasks from triggers
- [API Documentation](https://docs.connectgain.cloud/02-user-guide/07-api/complete-api.md) — REST API reference
- [Tasks & Projects on connectgain.cloud](https://connectgain.cloud/en/tasks-projects) — feature overview on the ConnectGain website

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Message Templates & Quick Replies – ConnectGain

Source: https://docs.connectgain.cloud/02-user-guide/templates/

# Templates (Quick Replies) Feature

## Overview

Templates are reusable **quick-reply** messages. A template is intentionally simple: it has a **name**, a **text body**, and an **optional image**. Templates let your team save time by reusing pre-written messages instead of retyping common responses.

Templates live under the **Templates** page. They can be reused when composing messages and elsewhere in the product where quick replies are supported.

> Templates are quick replies only. There are no per-channel variants, approval workflows, headers/footers, or interactive buttons.

**On this page:** [Features](#features) · [The Templates List](#the-templates-list) · [Use Cases](#use-cases) · [Test Cases](#test-cases) · [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting)

---

## Features

### 1. Creating a Template

Click **Create Template** to open the editor. A template consists of:

- **Name** — a label to help you find the template later. If you leave it blank, a name is generated automatically (e.g. `General template (dd.mm.yyyy hh:mm)`).
- **Text** — the message body. This is the only required field.
- **Image (optional)** — upload or drag-and-drop an image. Uploaded images are stored securely and shown in a live mobile preview alongside the text.

A phone-style preview on the right shows how the message will look as you type.

### 2. Editing a Template

Use the **Edit** action on any template to update its name, text, or image.

### 3. Copying a Template

Use the **Copy** action to copy a template's text to your clipboard so you can paste it into a conversation or anywhere else.

### 4. Deleting Templates

- **Delete** a single template from its row actions (with a confirmation prompt).
- **Delete Selected** — tick the checkboxes on multiple templates, then remove them all at once.
- **Delete All** — remove every template currently shown.

Bulk selection and the delete actions are available to users who have permission to delete data. Users without that permission can still create, edit, and copy templates.

### 5. Searching Templates

Use the search box to filter the list by typing part of a template's **name** or text. There are no category or status filters — the list is a single flat set of quick replies.

---

## The Templates List

The table shows each template's **name**, a **preview** (image thumbnail and a snippet of the text), and its **created date**, along with per-row actions:

| Action | What it does |
|--------|--------------|
| **Edit** | Open the editor to change name, text, or image |
| **Copy** | Copy the template text to the clipboard |
| **Delete** | Remove the template (requires delete permission) |

When delete permission is present, a checkbox column appears for bulk selection, and **Delete Selected** / **Delete All** buttons are shown at the top of the page.

---

## Use Cases

### Use Case 1: Create a Quick Reply

**Scenario:** A support team wants a canned reply for common questions.

**Steps:**
1. Go to **Templates**.
2. Click **Create Template**.
3. (Optional) Enter a name, e.g. "Response time reply".
4. Enter the text: "Thanks for reaching out! We'll get back to you within 24 hours."
5. (Optional) Upload an image.
6. Click **Save**.

**Expected Outcome:** The template appears in the list, ready to reuse.

### Use Case 2: Reuse a Template While Replying

**Scenario:** An agent wants to paste a saved reply into a conversation.

**Steps:**
1. Go to **Templates**.
2. Find the template (use search if needed).
3. Click **Copy** on its row.
4. Paste the text into the message composer.

**Expected Outcome:** The saved message text is inserted, ready to send.

### Use Case 3: Clean Up Old Templates

**Scenario:** An admin wants to remove templates that are no longer used.

**Steps:**
1. Go to **Templates**.
2. Tick the checkboxes next to the templates to remove (or use **Delete All**).
3. Click **Delete Selected**.
4. Confirm the deletion.

**Expected Outcome:** The selected templates are removed from the list.

---

## Test Cases

### Test Case 1: Create Template

1. Go to **Templates** and click **Create Template**.
2. Enter text: "Hello, thanks for contacting us."
3. Click **Save**.
4. Verify the template appears in the list with its created date.

**Expected Result:** Template created and visible in the list.

### Test Case 2: Text Is Required

1. Open **Create Template**.
2. Leave the text empty and try to save.
3. Verify a validation message asks for text and the save is blocked.

**Expected Result:** A template cannot be saved without text.

### Test Case 3: Optional Image

1. Create a template with text and upload an image.
2. Save and confirm the thumbnail shows in the list preview.

**Expected Result:** Image is stored and displayed with the template.

### Test Case 4: Copy Template

1. Click **Copy** on a template row.
2. Paste into any text field.
3. Verify the pasted text matches the template body.

**Expected Result:** Template text is copied to the clipboard.

### Test Case 5: Search Templates

1. Create a template named "Welcome Message".
2. Type "Welcome" in the search box.
3. Verify the template appears; search for "nonexistent" and verify no results.

**Expected Result:** Search filters the list by name/text.

### Test Case 6: Delete a Template

1. Click **Delete** on a template row.
2. Confirm the deletion.
3. Verify the template is removed from the list.

**Expected Result:** Template deleted successfully.

### Test Case 7: Bulk Delete

1. As a user with delete permission, select several templates via the checkboxes.
2. Click **Delete Selected** and confirm.
3. Verify all selected templates are removed.

**Expected Result:** Selected templates deleted in one action.

---

## Best Practices

1. **Keep them short and reusable** — quick replies work best for common, repeated messages.
2. **Name them clearly** — a descriptive name makes templates easy to find via search.
3. **Add an image only when it helps** — most quick replies are text-only.
4. **Prune regularly** — use bulk delete to remove templates you no longer use.

---

## Troubleshooting

### Template Won't Save

**Issue:** The Save button is disabled or a validation error appears.

**Solutions:**
- Ensure the **Text** field is filled — it is required.
- If uploading an image, wait for the upload to finish before saving.

### Bulk Delete Buttons Not Visible

**Issue:** No checkboxes or **Delete Selected** / **Delete All** buttons appear.

**Solutions:**
- These actions require permission to delete data. Ask an admin to grant it, or delete templates you own individually.

### Template Not Appearing

**Issue:** A created template is not visible in the list.

**Solutions:**
- Clear the search box in case it's filtering the list.
- Refresh the page.

---

## See also

- [Inbox](https://docs.connectgain.cloud/02-user-guide/templates/inbox.md) — where quick replies are used while chatting
- [Messages](https://docs.connectgain.cloud/02-user-guide/templates/messages.md) — message types and sending options
- [Campaigns](https://docs.connectgain.cloud/02-user-guide/templates/campaigns.md) — reusing message content in broadcasts
- [Sequences](https://docs.connectgain.cloud/02-user-guide/templates/sequences.md) — automated drip campaigns
- [Message templates on connectgain.cloud](https://connectgain.cloud/en/templates) — feature overview on the ConnectGain website

---

**Last Updated:** July 2026

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/02-user-guide/index.md)*

---

# Admin Guide – ConnectGain Workspace Administration

Source: https://docs.connectgain.cloud/03-admin-guide/

# Admin Guide

For workspace owners and admins.

- [Settings](https://docs.connectgain.cloud/03-admin-guide/settings.md) — configure your organization, channels, AI, API keys, webhooks, and personal preferences.
- [Team management](https://docs.connectgain.cloud/03-admin-guide/team.md) — invite members, assign roles, manage permissions and availability.
- [Authentication](https://docs.connectgain.cloud/03-admin-guide/authentication.md) — API authentication methods (API keys, Supabase REST, user JWT) and login endpoints.
- [Profile](https://docs.connectgain.cloud/03-admin-guide/profile.md) — manage personal information, subscription, email address, and password.
- [Reset password](https://docs.connectgain.cloud/03-admin-guide/reset-password.md) — the secure email-based password recovery flow.

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/index.md)*

---

# ConnectGain API Authentication – API Keys & JWT Guide

Source: https://docs.connectgain.cloud/03-admin-guide/authentication/

# ConnectGain API Authentication Guide

This guide covers every authentication method supported by the ConnectGain API, and how to obtain and use a user JWT (JSON Web Token). The examples reference the Postman collection at [`../07-api/connectgain.postman_collection.json`](https://docs.connectgain.cloud/03-admin-guide/07-api/connectgain.postman_collection.json) — see the [Postman guide](https://docs.connectgain.cloud/03-admin-guide/07-api/postman.md) for import instructions.

**On this page:**

- [Authentication Methods](#authentication-methods)
- [Getting a JWT Token — Step by Step](#getting-a-jwt-token--step-by-step)
- [Authentication Endpoints](#authentication-endpoints)
- [Collection Variables](#collection-variables)
- [Complete Testing Workflow](#complete-testing-workflow)
- [Which Method to Use](#which-method-to-use)

---

## Authentication Methods

ConnectGain supports **3 authentication methods** for different use cases:

### 1. External API Authentication (X-API-Key)

**Best for:** External systems, third-party integrations, automation

```http
X-API-Key: cg_abc123def456...
```

### 2. Supabase REST API Authentication (Anon Key)

**Best for:** Direct database operations, CRUD operations

```http
apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

### 3. User JWT Authentication (Login Required)

**Best for:** User-specific operations, subscriptions, organizations

```http
Authorization: Bearer USER_JWT_TOKEN
```

---

## Getting a JWT Token — Step by Step

### Method 1: Using the Postman Login Endpoint (Recommended)

#### Step 1: Use the Login Endpoint

```http
POST {{url}}/auth/v1/token?grant_type=password
apikey: {{anon_key}}
Content-Type: application/json

{
 "email": "your_email@example.com",
 "password": "your_password"
}
```

#### Step 2: Automatic Token Extraction

The login endpoint includes a **test script** that automatically:

- Extracts `access_token` from the response
- Saves it as the `user_jwt_token` variable
- Logs a success message

#### Step 3: Use the Token in Other Endpoints

Now you can use `{{user_jwt_token}}` in endpoints that require user authentication.

### Method 2: Using Browser Dev Tools

#### Step 1: Log in to the ConnectGain Web App

1. Go to [dashboard.connectgain.cloud](https://dashboard.connectgain.cloud)
2. Log in with your credentials
3. Wait for successful login

#### Step 2: Extract the Token from the Browser

1. Open **Developer Tools** (F12)
2. Go to the **Application** tab
3. Navigate to **Local Storage** → your domain
4. Find the Supabase session data
5. Copy the JWT token value

#### Step 3: Set It in Postman

1. Go to the collection **Variables** tab
2. Set the `user_jwt_token` value
3. Save the collection

---

## Authentication Endpoints

### 1. Login (Sign In)

```http
POST {{url}}/auth/v1/token?grant_type=password
apikey: {{anon_key}}
Content-Type: application/json

{
 "email": "user@example.com",
 "password": "your_password"
}
```

**Response:**

```json
{
 "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
 "token_type": "bearer",
 "expires_in": 3600,
 "expires_at": 1737123456,
 "refresh_token": "abc123def456...",
 "user": {
 "id": "user-uuid",
 "email": "user@example.com",
 "email_confirmed_at": "2025-01-17T10:30:00Z"
 }
}
```

**Features:**

- **Auto-extracts the JWT token** and saves it to the `user_jwt_token` variable
- **Returns user info** including verification status
- **Provides a refresh token** for token renewal

### 2. Sign Up (Register)

```http
POST {{url}}/auth/v1/signup
apikey: {{anon_key}}
Content-Type: application/json

{
 "email": "newuser@example.com",
 "password": "secure_password",
 "data": {
 "first_name": "John",
 "last_name": "Doe"
 }
}
```

### 3. Refresh Token

```http
POST {{url}}/auth/v1/token?grant_type=refresh_token
apikey: {{anon_key}}
Content-Type: application/json

{
 "refresh_token": "{{refresh_token}}"
}
```

### 4. Get User Info

```http
GET {{url}}/auth/v1/user
apikey: {{anon_key}}
Authorization: Bearer {{user_jwt_token}}
```

### 5. Logout (Sign Out)

```http
POST {{url}}/auth/v1/logout
apikey: {{anon_key}}
Authorization: Bearer {{user_jwt_token}}
Content-Type: application/json

{}
```

---

## Collection Variables

Add these variables to your collection:

```javascript
// Authentication variables
user_jwt_token = (auto-populated by login endpoint)
refresh_token = (auto-populated by login endpoint)

// Base variables
url = https://txpaxbxhnvnhsjwwaeoy.supabase.co
anon_key = eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
api_key = cg_your_api_key_here
organization_id = 40e9bb4c-3b1c-4e5b-8c7d-2f5a9b8e1c3d
```

---

## Complete Testing Workflow

### Phase 1: Authentication Setup

1. **Login** — get a JWT token
2. **Get User Info** — verify the token works
3. **List Organizations** — test a user-specific endpoint

### Phase 2: API Testing

1. **Search Contacts** — test X-API-Key auth
2. **List Contacts** — test REST API auth
3. **Create Contact** — test with a JWT token
4. **Check Subscription** — test the subscription endpoint

### Phase 3: Full Workflow

1. **Create resources** (contacts, companies, deals)
2. **Send messages** via multiple channels
3. **Import data** via CSV
4. **Manage subscriptions**

---

## Which Method to Use

| Endpoint | Auth method |
|----------|-------------|
| List Organizations | User JWT token from login |
| Check Subscription | User JWT token from login |
| Create Contact | User JWT token from login |
| Search Contacts / Companies, Insert Message | X-API-Key |
| Direct table CRUD and queries with relations | Supabase REST (anon key + JWT) |

Note: a `401` response for an invalid API key is the expected, correct behavior.

### Quick Start

1. **Import the collection** into Postman
2. **Set the base variables** (`url`, `anon_key`, `api_key`, `organization_id`)
3. **Run the Login endpoint** with your credentials
4. **The JWT token is auto-saved** to the `user_jwt_token` variable
5. **Test any endpoint** — all authentication methods are now available

### For External Systems

Use X-API-Key endpoints:

- Search Contacts
- Search Companies
- Insert Message

### For Internal Operations

Use JWT token endpoints:

- List Organizations
- Check Subscription
- User-specific operations

### For Database Operations

Use REST API endpoints:

- All CRUD operations
- Complex queries with relations

---

## See also

- [Postman collection guide](https://docs.connectgain.cloud/03-admin-guide/07-api/postman.md)
- [API key authentication](https://docs.connectgain.cloud/03-admin-guide/07-api/api-key-authentication.md)
- [Complete API reference](https://docs.connectgain.cloud/03-admin-guide/07-api/complete-api.md)
- [Password reset](https://docs.connectgain.cloud/03-admin-guide/authentication/reset-password.md)
- [Profile management](https://docs.connectgain.cloud/03-admin-guide/authentication/profile.md)

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/03-admin-guide/index.md)*

---

# Profile Management – Account, Subscription & Password

Source: https://docs.connectgain.cloud/03-admin-guide/profile/

# Profile Management Feature

## Overview

The Profile page (`/profile`) allows users to manage their personal account information, subscription details, email address, and password. It provides a centralized location for users to update their profile and manage their account settings, including subscription management and usage tracking.

**On this page:**

- [Features](#features)
- [Use Cases](#use-cases)
- [API Integration](#api-integration)
- [Best Practices](#best-practices)
- [Troubleshooting](#troubleshooting)

---

## Features

### 1. Profile Information Tab

**Personal Information:**
- Manage personal details
- First name
- Last name
- Avatar (initials-based)
- Email address (read-only in profile tab)
- Role display

**Profile Update:**
- Update profile information
- Form validation
- Success notifications
- Error handling

### 2. Subscription Tab

**Current Plan:**
- View subscription details
- Plan name
- Plan description
- Plan price
- Subscription status (Active, Trial, Cancelled)
- Trial days remaining (if applicable)
- Next billing date
- Current period end date

**Plan Features:**
- View plan features
- Feature list
- Feature checkmarks
- Plan limits display

**Usage Statistics:**
- Track usage
- Contacts used/total
- Conversations used/total
- Team members used/total
- Usage percentages
- Progress bars

**Manage Subscription:**
- Subscription management
- Open the billing customer portal (Stripe or Paddle, depending on your billing provider)
- Update payment method
- Change plan
- Cancel subscription
- View billing history

### 3. Email Address Tab

**Change Email:**
- Update email address
- New email input
- Email validation
- Email change confirmation
- Warning messages

**Email Verification:**
- Email verification process
- Verification email sending
- Verification status

### 4. Password Tab

**Change Password:**
- Update password
- New password input
- Confirm password input
- Password strength requirements
- Show/hide password toggle
- Password validation
- Success notifications

### 5. Profile Organization

**Tabbed Interface:**
- Organized profile sections
- Profile Information
- Subscription
- Email Address
- Password

**Visual Design:**
- Clean profile interface
- Avatar display
- Card-based layout
- Clear section separation

---

## Use Cases

### Use Case 1: Update Profile Information

**Scenario:**
User wants to update their name.

**Steps:**
1. Go to Profile
2. Click "Profile Information" tab
3. Update first name
4. Update last name
5. Click "Update Profile"
6. Verify changes saved

**Expected Outcome:**
Profile information updated successfully.

### Use Case 2: View Subscription Details

**Scenario:**
User wants to check subscription status.

**Steps:**
1. Go to Profile
2. Click "Subscription" tab
3. View current plan details
4. Check plan features
5. View billing information
6. Check trial status if applicable

**Expected Outcome:**
Subscription details displayed correctly.

### Use Case 3: Change Email Address

**Scenario:**
User wants to update email address.

**Steps:**
1. Go to Profile
2. Click "Email Address" tab
3. Enter new email address
4. Click "Update Email"
5. Check current email for verification link
6. Click verification link in email
7. Verify email updated

**Expected Outcome:**
Email address changed after verification.

### Use Case 4: Change Password

**Scenario:**
User wants to update password for security.

**Steps:**
1. Go to Profile
2. Click "Password" tab
3. Enter current password
4. Enter new password
5. Confirm new password
6. Click "Update Password"
7. Verify password updated

**Expected Outcome:**
Password changed successfully.

### Use Case 5: Manage Subscription

**Scenario:**
User wants to upgrade or cancel subscription.

**Steps:**
1. Go to Profile
2. Click "Subscription" tab
3. Click "Manage Subscription"
4. Redirected to the billing customer portal (Stripe or Paddle)
5. Make changes (upgrade/downgrade/cancel)
6. Return to ConnectGain
7. Verify changes reflected

**Expected Outcome:**
Subscription managed through the billing portal.

---

## API Integration

### Update Profile

**Endpoint:** `PATCH /rest/v1/profiles?id=eq.{user_id}`

**Request:**
```json
{
 "first_name": "John",
 "last_name": "Doe"
}
```

### Update Email

**Endpoint:** `POST /auth/v1/user`

**Request:**
```json
{
 "email": "newemail@example.com"
}
```

**Note:** Requires email verification.

### Update Password

**Endpoint:** `POST /auth/v1/user`

**Request:**
```json
{
 "password": "newpassword123"
}
```

---

## Best Practices

1. **Profile Information**
 - Keep profile information up to date
 - Use professional display names
 - Update email if changed

2. **Password Security**
 - Use strong passwords
 - Change passwords regularly
 - Don't reuse passwords
 - Use password managers

3. **Subscription Management**
 - Review subscription regularly
 - Understand plan features
 - Monitor usage limits
 - Update payment methods

4. **Email Management**
 - Use verified email addresses
 - Keep email accessible
 - Update email promptly if changed
 - Check spam folder for verification emails

---

## Troubleshooting

### Profile Update Failing

**Issue:** Cannot update profile information

**Solutions:**
- Verify required fields filled
- Check network connection
- Refresh page and try again
- Check permissions

### Email Verification Not Received

**Issue:** Email verification link not received

**Solutions:**
- Check spam folder
- Verify email address correct
- Request new verification email
- Check email server status

### Password Update Failing

**Issue:** Cannot change password

**Solutions:**
- Verify password meets requirements
- Check passwords match
- Verify current password correct
- Try again after refresh

### Subscription Not Loading

**Issue:** Subscription details not displaying

**Solutions:**
- Check subscription active
- Verify billing provider (Stripe/Paddle) connection
- Refresh page
- Contact support if persists

---

## Related Documentation

- [Settings Feature](https://docs.connectgain.cloud/03-admin-guide/profile/settings.md)
- [Team Management](https://docs.connectgain.cloud/03-admin-guide/profile/team.md)
- [Password Reset](https://docs.connectgain.cloud/03-admin-guide/profile/reset-password.md)
- [API Documentation](https://docs.connectgain.cloud/03-admin-guide/07-api/complete-api.md)

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/03-admin-guide/index.md)*

---

# Password Reset – ConnectGain Account Recovery Guide

Source: https://docs.connectgain.cloud/03-admin-guide/reset-password/

# Password Reset Feature

## Overview

The Password Reset feature allows users to securely reset their forgotten passwords via email verification. It provides a secure flow for password recovery without requiring users to remember their current password.

**On this page:**

- [Features](#features)
- [Use Cases](#use-cases)
- [API Integration](#api-integration)
- [Best Practices](#best-practices)
- [Troubleshooting](#troubleshooting)

---

## Features

### 1. Password Reset Request

**Reset Request Features:**
- Request reset via email
- Email validation
- Reset link generation
- Secure token generation
- Reset link expiration

**Request Process:**
1. User clicks "Forgot Password"
2. Enters email address
3. System validates email
4. Reset link sent to email
5. User receives email with link

### 2. Password Reset Link

**Link Features:**
- Secure token-based link
- Time-limited validity
- Single-use token
- Redirects to reset page
- Token validation

**Link Format:**
- URL: `/reset-password`
- Token in session/auth state
- Secure token handling

### 3. Password Reset Page

**Reset Page Features:**
- Token validation
- New password input
- Password confirmation
- Password strength requirements
- Secure password update

**Reset Process:**
1. User clicks reset link
2. Token validated
3. Reset page displayed
4. User enters new password
5. Password confirmed
6. Password updated
7. User signed out
8. Redirected to login

### 4. Password Requirements

**Requirements:**
- Minimum 8 characters
- Recommended: mix of letters, numbers, symbols
- Password confirmation required
- Password validation

### 5. Security Features

**Security:**
- Secure token generation
- Token expiration
- Single-use tokens
- Session invalidation
- Secure password storage

---

## Use Cases

### Use Case 1: Request Password Reset

**Scenario:**
User forgot password and wants to reset it.

**Steps:**
1. Go to Auth page
2. Click "Forgot Password"
3. Enter email address
4. Click "Send Reset Link"
5. Check email for reset link
6. Click reset link in email
7. Redirected to reset page

**Expected Outcome:**
Reset link sent and accessible.

### Use Case 2: Reset Password

**Scenario:**
User received reset link and wants to set new password.

**Steps:**
1. Click reset link from email
2. Verify reset page loads
3. Enter new password
4. Confirm new password
5. Click "Reset Password"
6. Verify password updated
7. Redirected to login page
8. Login with new password

**Expected Outcome:**
Password reset successfully.

### Use Case 3: Invalid Reset Link

**Scenario:**
User tries to use expired or invalid reset link.

**Steps:**
1. Click expired reset link
2. Verify error message shown
3. Link marked as invalid
4. Redirected to login
5. Request new reset link

**Expected Outcome:**
Invalid link handled gracefully.

---

## API Integration

### Request Password Reset

**Endpoint:** `POST /auth/v1/recover`

**Request:**
```json
{
 "email": "user@example.com",
 "options": {
 "redirect_to": "https://app.example.com/reset-password"
 }
}
```

**Response:**
```json
{
 "message": "Password recovery email sent"
}
```

### Reset Password

**Endpoint:** `POST /auth/v1/user`

**Request:**
```json
{
 "password": "newpassword123"
}
```

**Note:** Requires valid session from reset link.

---

## Best Practices

1. **Password Security**
 - Use strong passwords
 - Don't reuse passwords
 - Change passwords regularly
 - Use password managers

2. **Reset Link Handling**
 - Use reset link promptly
 - Don't share reset links
 - Request new link if expired
 - Check email spam folder

3. **Email Security**
 - Use secure email account
 - Don't share reset emails
 - Verify email sender
 - Report suspicious emails

---

## Troubleshooting

### Reset Email Not Received

**Issue:** Password reset email not arriving

**Solutions:**
- Check spam folder
- Verify email address correct
- Wait a few minutes
- Request new reset link
- Check email server status

### Reset Link Expired

**Issue:** Reset link no longer valid

**Solutions:**
- Request new reset link
- Use link within expiration time
- Check link not already used
- Verify link copied correctly

### Password Reset Failing

**Issue:** Cannot reset password

**Solutions:**
- Verify password meets requirements
- Check passwords match
- Verify reset link valid
- Try again after refresh
- Contact support if persists

### Invalid Token Error

**Issue:** Token validation failing

**Solutions:**
- Request new reset link
- Verify link not expired
- Check link copied correctly
- Clear browser cache
- Try different browser

---

## Related Documentation

- [Profile Management](https://docs.connectgain.cloud/03-admin-guide/reset-password/profile.md)
- [API Authentication](https://docs.connectgain.cloud/03-admin-guide/reset-password/authentication.md)
- [Getting Started](https://docs.connectgain.cloud/03-admin-guide/01-getting-started/README.md)
- [API Documentation](https://docs.connectgain.cloud/03-admin-guide/07-api/complete-api.md)

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/03-admin-guide/index.md)*

---

# Settings – ConnectGain Workspace Configuration Guide

Source: https://docs.connectgain.cloud/03-admin-guide/settings/

# Settings Feature

## Overview

The Settings page (`/settings`) provides comprehensive configuration options for your organization, team members, channels, integrations, and system preferences. It's the central hub for managing all aspects of your ConnectGain workspace.

The settings navigation is organized into **six categories**. Admin-level tabs are only shown to Owners/Admins; personal-preference tabs are visible to everyone.

**On this page:**

- [Features](#features)
- [Use Cases](#use-cases)
- [API Integration](#api-integration)
- [Best Practices](#best-practices)
- [Troubleshooting](#troubleshooting)

---

## Features

Settings are grouped into these six categories:

### 1. My Preferences

Personal settings that apply only to your own account.

- **Notifications** — enable/disable browser push notifications, manage permissions, view notification status, and automatic subscription on login (Web Push API; Android via Chrome/Firefox/Samsung Internet; iOS via Safari PWA on iOS 16.4+).
- **Chat & Contacts** — personal chat and contact display preferences.
- **Inbox Layout** — customize how the inbox is laid out for you.

### 2. Workspace

Organization administration.

- **Organization** — organization name, slug, timezone (used for scheduling), and default currency (used for deals).
- **Team Members** — view members, invite new members, manage roles/permissions/availability, and remove members. See [Team Management](https://docs.connectgain.cloud/03-admin-guide/settings/team.md).
- **Teams** — create and manage sub-teams and their members (Team Admins).
- **Sidebar Menu** — customize which items appear in the sidebar navigation.

### 3. Inbox & Messaging

- **Channels** — connect and manage messaging channels. See [Channels](https://docs.connectgain.cloud/03-admin-guide/05-integrations/channels.md).
- **Email Boxes** *(Beta)* — connect IMAP/SMTP email inboxes.
- **Message Templates** — reusable message templates.
- **Quick Replies** — short canned responses for agents.
- **WhatsApp Templates** — manage approved [WhatsApp Cloud](https://docs.connectgain.cloud/03-admin-guide/05-integrations/whatsapp-cloud-system-user.md) templates.
- **Tags & Labels** — define tags and labels for conversations and contacts.
- **Lifecycle Stages** — configure contact lifecycle stages.
- **SLA & Escalation** — configure response-time SLAs and escalation rules.
- **External Pages** — manage external/embedded pages.

### 4. AI & Automation

- **AI Provider** — choose ConnectGain AI or bring your own Gemini key (BYOK). See [BYOK Gemini](https://docs.connectgain.cloud/03-admin-guide/05-integrations/ai-byok-gemini.md).
- **[AI Re-Engagement](https://docs.connectgain.cloud/03-admin-guide/02-user-guide/ai-reengagement.md)** — configure automated re-engagement nudges.
- **AI Summaries** — configure conversation/AI summarization.
- **Enrichment Tools** — configure contact enrichment.
- **[Call Intelligence](https://docs.connectgain.cloud/03-admin-guide/02-user-guide/call-intelligence.md)** — configure call recording analysis and vendors.

### 5. Storage & Developer

- **Media Storage** — configure media storage.
- **Storage Usage & Cleanup** — monitor storage usage and clean up files (internal Appgain accounts).
- **API Keys** — generate, view, and revoke [API keys](https://docs.connectgain.cloud/03-admin-guide/07-api/api-key-authentication.md); set expiration; track usage.
- **Webhooks** — create webhook endpoints, configure subscribed events, test delivery, and view delivery logs.

### 6. Danger Zone

A dedicated top-level category (not part of the Organization tab).

- **Delete all data** — confirmation required (type "DELETE ALL DATA"). Deletes companies, conversations, contacts, deals, tasks, templates, automations, and [bot flows](https://docs.connectgain.cloud/03-admin-guide/02-user-guide/bot-flows.md).

### Member Roles

Team Members support five roles (see [Team Management](https://docs.connectgain.cloud/03-admin-guide/settings/team.md) for details):

- **Owner** — full access to all features and organization settings.
- **Admin** — manage users, settings, and team members.
- **Agent** — access to conversations, contacts, deals, and tasks.
- **Project Manager** — projects/PM access; excluded from agent auto-assignment and agent-performance reports.
- **Team Admin** — manages a sub-team via the **Teams** tab.

---

## Use Cases

### Use Case 1: Configure Organization Settings

**Scenario:**
Admin wants to update organization timezone and currency.

**Steps:**
1. Go to Settings → Organization
2. Update organization name if needed
3. Select timezone from dropdown
4. Select currency from dropdown
5. Click "Save Changes"
6. Verify settings updated

**Expected Outcome:**
Organization settings updated successfully.

### Use Case 2: Generate API Key

**Scenario:**
Developer needs API key for integration.

**Steps:**
1. Go to Settings → API Keys
2. Click "Generate New API Key"
3. Enter key name/description
4. Set expiration date (optional)
5. Click "Generate"
6. Copy API key immediately
7. Store securely

**Expected Outcome:**
API key generated and ready for use.

### Use Case 3: Configure Webhook

**Scenario:**
Admin wants to receive webhook events for new messages.

**Steps:**
1. Go to Settings → Webhooks
2. Click "Add Webhook"
3. Enter webhook URL
4. Select events to subscribe to:
 - message.created
 - conversation.created
5. Enter secret key
6. Click "Save"
7. Test webhook delivery
8. Verify webhook active

**Expected Outcome:**
Webhook configured and receiving events.

### Use Case 4: Enable Browser Notifications

**Scenario:**
User wants to receive browser notifications for new messages.

**Steps:**
1. Go to Settings → Notifications
2. Click "Enable Notifications"
3. Grant browser permission when prompted
4. Verify notification enabled
5. Test notification delivery

**Expected Outcome:**
Browser notifications enabled and working.

---

## API Integration

### Update Organization Settings

**Endpoint:** `PATCH /rest/v1/organizations?id=eq.{org_id}`

**Request:**
```json
{
 "name": "My Company",
 "slug": "my-company",
 "timezone": "America/New_York",
 "currency": "USD"
}
```

### Generate API Key

**Endpoint:** `POST /functions/v1/generate-api-key`

**Request:**
```json
{
 "name": "Production API Key",
 "expires_at": "2025-12-31T23:59:59Z"
}
```

**Response:**
```json
{
 "api_key": "cg_xxxxxxxxxxxxx",
 "id": "key-uuid",
 "created_at": "2025-01-01T00:00:00Z"
}
```

### Create Webhook

Webhook endpoints are stored in the **`webhook_configurations`** table (there is no `webhooks` table).

**Endpoint:** `POST /rest/v1/webhook_configurations`

**Request:**
```json
{
 "url": "https://example.com/webhook",
 "events": ["message.created", "conversation.created"],
 "secret": "webhook-secret-key"
}
```

---

## Best Practices

1. **Organization Settings**
 - Set accurate timezone for proper scheduling
 - Use appropriate currency for your region
 - Keep organization name professional

2. **API Keys**
 - Generate separate keys for different environments
 - Set expiration dates for security
 - Rotate keys regularly
 - Never commit keys to version control

3. **Webhooks**
 - Use HTTPS endpoints only
 - Implement webhook signature verification
 - Handle retries gracefully
 - Monitor webhook delivery

4. **Notifications**
 - Request permissions at appropriate times
 - Respect user preferences
 - Provide clear notification content

---

## Troubleshooting

### API Key Not Working

**Issue:** API key authentication failing

**Solutions:**
- Verify key copied correctly
- Check key not expired
- Verify key not revoked
- Check API endpoint URL correct

### Webhook Not Receiving Events

**Issue:** Webhook endpoint not receiving events

**Solutions:**
- Verify webhook URL accessible
- Check webhook active status
- Verify event subscriptions correct
- Check webhook logs for errors
- Test webhook endpoint manually

### Notifications Not Working

**Issue:** Browser notifications not appearing

**Solutions:**
- Check browser notification permissions
- Verify notifications enabled in settings
- Check browser notification settings
- Test with different browser

---

## Related Documentation

- [Team Management](https://docs.connectgain.cloud/03-admin-guide/settings/team.md)
- [Channels](https://docs.connectgain.cloud/03-admin-guide/05-integrations/channels.md)
- [Webhooks](https://docs.connectgain.cloud/03-admin-guide/08-webhooks/README.md)
- [Templates](https://docs.connectgain.cloud/03-admin-guide/02-user-guide/templates.md)
- [API Documentation](https://docs.connectgain.cloud/03-admin-guide/07-api/complete-api.md)

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/03-admin-guide/index.md)*

---

# Team Management – Roles, Permissions & Invitations

Source: https://docs.connectgain.cloud/03-admin-guide/team/

# Team Management Feature

## Overview

Team Management enables businesses to manage team members, roles, permissions, invitations, and availability. The feature supports role-based access control (RBAC), team member invitations, permission management, and availability scheduling. Team members can be assigned to conversations, tasks, and deals, with availability-based auto-assignment capabilities.

**On this page:**

- [Features](#features)
- [Use Cases](#use-cases)
- [Test Cases](#test-cases)
- [API Integration](#api-integration)
- [Best Practices](#best-practices)
- [Troubleshooting](#troubleshooting)

---

## Features

### 1. Team Management

**Team Member Operations:**
- View all team members
- Member details (name, email, role, status)
- Active/inactive status
- Invite new team members
- Remove team members
- Manage permissions
- Manage availability

**Invite Members:**
- Add new team members
- Email input
- Role selection (Admin, Agent, Project Manager, Team Admin)
- Invitation sending
- Invitation URL generation
- Auto-copy invitation link

### 2. Member Roles

ConnectGain uses five roles for role-based access control.

**Role Types:**
- **Owner** - Full access to all features and organization settings.
- **Admin** - Manage users, settings, and team members.
- **Agent** - Access to conversations, contacts, deals, and tasks.
- **Project Manager** - Projects and project-management access. Excluded from agent auto-assignment and from agent-performance reports.
- **Team Admin** - Manages a sub-team (its members) via the **Teams** tab.

**Role Permissions:**
- Owners: Full organization access.
- Admins: Manage users, settings, and team members.
- Agents: Access conversations, contacts, deals, and tasks.
- Project Managers: Access projects and PM features; not auto-assigned conversations/tasks and omitted from agent-performance reporting.
- Team Admins: Manage the members of the sub-team they own.

### 3. Permissions

**Permission Categories:**
- **CRM Access** - Access to contacts, companies, deals
- **Broadcast Access** - Access to campaigns
- **PM Access** - Access to projects
- **Custom Permissions** - Feature-specific permissions

**Permission Management:**
- Granular permission control
- Permission assignment per user
- Permission inheritance from roles
- Custom permission sets

### 4. Pending Invitations

**Invitation Management:**
- View pending invitations
- Resend invitation email
- Copy invitation link
- Cancel invitation
- Invitation expiration tracking

**Invitation Features:**
- Email-based invitations
- Invitation tokens
- Invitation expiration (time-limited)
- Resend invitations
- Cancel invitations
- Copy invitation links
- Auto-copy functionality

**Invitation Flow:**
1. Admin/Owner creates invitation
2. Invitation email sent automatically
3. User receives email with invitation link
4. User clicks invitation link
5. User accepts invitation and sets password
6. User joins organization
7. User can access platform based on role

### 5. Availability Management

**Availability Features:**
- Set availability slots
- Timezone support
- Day-of-week selection
- Time range configuration
- Multiple availability slots
- Availability-based auto-assignment

### 6. User Profiles

**Profile Information:**
- First name and last name
- Email address
- Profile picture (avatar)
- Role assignment
- Permission settings
- Activity status

### 7. Team Statistics

**Statistics Display:**
- Total team members
- Active members
- Pending invitations
- Role distribution
- Permission overview

---

## Use Cases

### Use Case 1: Invite Team Member

**Scenario:**
Admin wants to invite new team member.

**Steps:**
1. Go to Settings → Team Members
2. Enter email address
3. Select role (Admin, Agent, Project Manager, or Team Admin)
4. Click "Invite"
5. Invitation email sent
6. User receives email
7. User clicks invitation link
8. User accepts invitation
9. User joins organization
10. Verify member appears in list

**Expected Outcome:**
Team member invited and joined successfully.

### Use Case 2: Set User Permissions

**Scenario:**
Admin wants to customize user permissions.

**Steps:**
1. Go to Settings → Team Members
2. Find user
3. Click "Manage Permissions"
4. Configure permissions:
 - Enable CRM Access
 - Disable Broadcast Access
 - Enable PM Access
5. Save permissions
6. Verify permissions applied
7. User sees updated access

**Expected Outcome:**
User permissions customized successfully.

### Use Case 3: Set User Availability

**Scenario:**
Admin wants to set agent availability for auto-assignment.

**Steps:**
1. Go to Settings → Team Members
2. Find agent
3. Click "Manage Availability"
4. Set availability slots:
 - Monday-Friday: 9:00 AM - 5:00 PM
 - Timezone: America/New_York
5. Save availability
6. Verify availability set
7. Test auto-assignment

**Expected Outcome:**
Agent availability configured for auto-assignment.

### Use Case 4: Remove Team Member

**Scenario:**
Admin wants to remove inactive team member.

**Steps:**
1. Go to Settings → Team Members
2. Find member to remove
3. Verify member not owner
4. Click "Remove"
5. Confirm removal
6. Verify member removed
7. Check member deactivated

**Expected Outcome:**
Team member removed successfully.

---

## Test Cases

### Test Case 1: Invite Team Member

**Test:** Verify invitation process

**Steps:**
1. Go to Settings → Team Members
2. Enter email: "newuser@example.com"
3. Select role: Agent
4. Click "Invite"
5. Verify invitation created
6. Verify invitation email sent
7. Check invitation in pending list
8. Copy invitation link
9. Open link in new browser
10. Verify invitation accepted

**Expected Result:**
Invitation process works correctly

### Test Case 2: Accept Invitation

**Test:** Verify invitation acceptance

**Steps:**
1. Receive invitation email
2. Click invitation link
3. Verify invitation page loads
4. Create account or login
5. Accept invitation
6. Verify organization joined
7. Verify role assigned
8. Verify access granted

**Expected Result:**
Invitation accepted successfully

### Test Case 3: Manage Permissions

**Test:** Verify permission management

**Steps:**
1. Open user permissions dialog
2. Enable CRM Access
3. Disable Broadcast Access
4. Save permissions
5. Verify permissions saved
6. Login as user
7. Verify CRM accessible
8. Verify Broadcast not accessible

**Expected Result:**
Permissions managed correctly

### Test Case 4: Set Availability

**Test:** Verify availability configuration

**Steps:**
1. Open availability dialog
2. Set timezone
3. Add availability slot
4. Select days of week
5. Set time range
6. Save availability
7. Verify availability saved
8. Test auto-assignment

**Expected Result:**
Availability configured correctly

### Test Case 5: Remove Member

**Test:** Verify member removal

**Steps:**
1. Find team member
2. Verify not owner
3. Click remove
4. Confirm removal
5. Verify member removed
6. Verify member deactivated
7. Check member cannot login

**Expected Result:**
Member removed successfully

---

## API Integration

### Create Invitation

**Endpoint:** `POST /functions/v1/send-invitation-email`

**Request:**
```json
{
 "email": "user@example.com",
 "role": "AGENT",
 "organization_id": "org-uuid"
}
```

### Get Team Members

**Endpoint:** `GET /rest/v1/profiles`

**Query Parameters:**
- `organization_id` - Filter by organization
- `is_active` - Filter by status

### Update Permissions

**Endpoint:** `PATCH /rest/v1/profiles/{id}`

**Request:**
```json
{
 "permissions": {
 "can_access_crm": true,
 "can_access_broadcast": false,
 "can_access_pm": true
 }
}
```

---

## Best Practices

1. **Team Organization**
 - Use appropriate roles
 - Assign permissions carefully
 - Review permissions regularly
 - Remove inactive members

2. **Invitations**
 - Send invitations promptly
 - Follow up on pending invitations
 - Resend if needed
 - Cancel unused invitations

3. **Permissions**
 - Follow principle of least privilege
 - Grant only necessary permissions
 - Review permissions periodically
 - Document permission changes

4. **Availability**
 - Set accurate availability
 - Update timezone correctly
 - Configure realistic slots
 - Review availability regularly

---

## Troubleshooting

### Invitation Not Received

**Issue:** User not receiving invitation email

**Solutions:**
- Check email address correct
- Verify email not in spam
- Resend invitation
- Check email server logs

### Permission Not Working

**Issue:** User cannot access feature

**Solutions:**
- Verify permission enabled
- Check role permissions
- Review permission settings
- Refresh user session

### Invitation Expired

**Issue:** Invitation link expired

**Solutions:**
- Resend invitation
- Generate new invitation
- Check expiration date
- Create new invitation

---

## Related Documentation

- [Settings Feature](https://docs.connectgain.cloud/03-admin-guide/team/settings.md)
- [Profile Management](https://docs.connectgain.cloud/03-admin-guide/team/profile.md)
- [Setup & Installation (internal)](https://admindocs.connectgain.cloud/setup/): repo checkout, env vars, Supabase deployment
- [API Documentation](https://docs.connectgain.cloud/03-admin-guide/07-api/complete-api.md)
- [Team Management on connectgain.cloud](https://connectgain.cloud/en/team-management) — feature overview on the ConnectGain website

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/03-admin-guide/index.md)*

---

# ConnectGain Use Cases – Omnichannel Inbox & CRM in Action

Source: https://docs.connectgain.cloud/04-use-cases/

# Use Cases

How real businesses use ConnectGain.

- [Comprehensive overview](https://docs.connectgain.cloud/04-use-cases/overview.md) — 164 detailed use cases across automation, webhooks, AI, deals, campaigns, and 20+ industries.
- [Business use cases](https://docs.connectgain.cloud/04-use-cases/business.md) — end-to-end business scenarios (e-commerce support, sales pipelines, real estate, tourism, healthcare, and more).
- [Bot flow automation recipes](https://docs.connectgain.cloud/04-use-cases/bot-flow-automation-recipes.md) — ready-to-build bot flows: conversation control, time-based routing, Google Sheets, sub-flows, and AI booking.
- [Marketing fact sheet](https://docs.connectgain.cloud/04-use-cases/marketing-fact-sheet.md) — the complete feature-by-feature reference for every screen and capability.
- [Car maintenance + Odoo](https://docs.connectgain.cloud/04-use-cases/car-maintenance-odoo.md) — commercial offer template combining ConnectGain CRM with an Odoo ERP integration.
- [AI Re-Engagement — use cases](https://docs.connectgain.cloud/04-use-cases/ai-reengagement-use-cases.md) — recover silent Messenger and Instagram conversations inside Meta's 24-hour window.
- [AI Re-Engagement — in-app help](https://docs.connectgain.cloud/04-use-cases/ai-reengagement-in-app-help.md) — Help Center articles for enabling re-engagement and BYOK Gemini.
- [Reply Assistant — use cases](https://docs.connectgain.cloud/04-use-cases/reply-assistant-use-cases.md) — AI-suggested sales replies for B2B SaaS, e-commerce, and travel teams.

## See also

- [User guide](https://docs.connectgain.cloud/02-user-guide/README.md) — how-to guides for every feature
- [Channel integrations](https://docs.connectgain.cloud/05-integrations/README.md) — connect WhatsApp, Messenger, Instagram, and more
- [WhatsApp Lite vs Cloud](https://docs.connectgain.cloud/marketing/whatsapp-lite-vs-cloud.md) — choose the right WhatsApp channel
- [Getting started](https://docs.connectgain.cloud/01-getting-started/README.md) — onboarding and first steps
- [Use cases on connectgain.cloud](https://connectgain.cloud/en/use-cases) — feature overview on the ConnectGain website
- [Industries on connectgain.cloud](https://connectgain.cloud/en/industries) — feature overview on the ConnectGain website

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/index.md)*

---

# AI Re-Engagement & BYOK Gemini – In-App Help Articles

Source: https://docs.connectgain.cloud/04-use-cases/ai-reengagement-in-app-help/

# In-App Help — AI Re-Engagement & BYOK

Articles surfaced inside the Help Center widget.

## Article 1 — Enable AI Re-Engagement
1. Go to **Settings → AI & Automation → AI Re-Engagement**.
2. Click **Start 7-day free trial** (or **Subscribe**).
3. Toggle **Enable** on.
4. Set the **threshold** (default 20h; lower = more time before window closes).
5. Pick channels: **Messenger**, **Instagram**, or both.
6. Choose a **tone**: Friendly / Formal / Casual.
7. Optional: turn on **Require agent approval** if you want drafts reviewed before sending.
8. Save.

## Article 2 — Approve or edit AI drafts
When approval mode is on, AI drafts appear in the inbox as a card with **Approve**, **Edit**, **Skip**. Editing replaces the AI text with yours and sends immediately. Skipping logs the reason and prevents another nudge for that 24h window.

## Article 3 — Use your own Gemini key
1. Get a key from [Google AI Studio](https://aistudio.google.com/app/apikey).
2. **Settings → AI → AI Provider → My Google Gemini key (BYOK)**.
3. Paste the key, pick a model, click **Test**.
4. Choose scope: **All AI features** or **Re-engagement only**.
5. Save. Your key is encrypted and never shown again.

## Article 4 — Switch all AI features to my Gemini key
In the AI Provider panel set **Scope = All AI features**. Every Gemini-backed feature in your org — chatbots, classification, internal assistant, translations, auto-tag, call analysis, re-engagement — now uses your key.

## Article 5 — Troubleshooting re-engagement
| No nudge sent? | Likely cause |
|---|---|
| Conversation past 24h | Window closed — wait for customer reply |
| Channel not in settings | Add Messenger / Instagram |
| Customer opted out | Honoured automatically |
| No active subscription | Re-subscribe |
| BYOK key invalid + fallback off | Fix key or enable fallback |
| 3 consecutive unanswered | Conversation auto-paused; re-enable manually |

## Tooltips
- **Threshold slider:** "We'll send the nudge this many hours after the customer's last message, before Meta's 24h window closes."
- **BYOK preview:** "Your key is encrypted. We never display it again after saving."
- **Scope radio:** "All AI features = chatbots, classification, translations, drafts, summaries, and re-engagement all use your key."
- **Fallback toggle:** "If your Google key is temporarily unreachable, ConnectGain AI handles the request so your operations don't stop."

## See also

- [AI Re-Engagement user guide](https://docs.connectgain.cloud/04-use-cases/02-user-guide/ai-reengagement.md)
- [AI Re-Engagement — use cases](https://docs.connectgain.cloud/04-use-cases/ai-reengagement-in-app-help/ai-reengagement-use-cases.md)
- [BYOK — Bring Your Own Gemini Key](https://docs.connectgain.cloud/04-use-cases/05-integrations/ai-byok-gemini.md)
- [AI Re-Engagement sales one-pager](https://docs.connectgain.cloud/04-use-cases/marketing/ai-reengagement-onepager.md)

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/04-use-cases/index.md)*

---

# AI Re-Engagement Use Cases – Recover Messenger & Instagram Leads

Source: https://docs.connectgain.cloud/04-use-cases/ai-reengagement-use-cases/

# AI Re-Engagement — Use Cases

Each case shows the persona, trigger, a sample AI draft, and expected impact.

---

## 1. E-commerce — Abandoned cart on Messenger
- **Persona:** Online shopper who asked about a product, was sent options, then went quiet.
- **Trigger:** 20h after last customer message, deal still in `Interested`.

**Sample draft:**

> Hi Sara — still thinking about the navy linen dress? I can hold your size for the next few hours if you'd like. Want me to send the checkout link?

**Expected uplift:** +15–25% recovered carts on Meta DMs.

---

## 2. Instagram lead follow-up
- **Persona:** IG follower who DM'd "info?" on a sponsored post.
- **Trigger:** 18h after last message, no agent reply yet OR no customer reply after agent answered.

**Sample draft:**

> Hey Jamal 👋 just wanted to make sure you saw the pricing I sent. Happy to set up a quick call or share the demo link — whichever works?

**Expected uplift:** +30% qualified-lead conversion before window closes.

---

## 3. Real-estate inquiry rescue
- **Persona:** Buyer who asked about a listing on Messenger then went silent.
- **Trigger:** 22h, conversation tagged `hot_lead`.

**Sample draft:**

> Hi Ahmed — the 3-bedroom in Sheikh Zayed is still available, and there's a viewing slot tomorrow at 5pm. Want me to book it for you?

**Expected uplift:** +20% viewing bookings.

---

## 4. Support — warm reminder before SLA breach
- **Persona:** Customer who reported an issue, support replied, customer never confirmed resolution.
- **Trigger:** 21h, conversation status `awaiting_customer`.

**Sample draft:**

> Hi Lina, just checking in — did the reset link I sent earlier solve the login issue? If not, I can hop on a quick call.

**Expected uplift:** Fewer reopened tickets, higher CSAT.

---

## 5. Sequence safety-net on Meta
- **Persona:** Contact mid-way through a Messenger drip sequence who stopped responding.
- **Trigger:** Sequence step pauses inside 24h window.

**Sample draft:**

> Hey Omar — wanted to circle back on what we discussed. Any questions I can answer before our next step?

**Expected uplift:** Recovers ~12% of dropped sequences without breaking Meta policy.

## See also

- [AI Re-Engagement user guide](https://docs.connectgain.cloud/04-use-cases/02-user-guide/ai-reengagement.md)
- [AI Re-Engagement — in-app help](https://docs.connectgain.cloud/04-use-cases/ai-reengagement-use-cases/ai-reengagement-in-app-help.md)
- [AI Re-Engagement sales one-pager](https://docs.connectgain.cloud/04-use-cases/marketing/ai-reengagement-onepager.md)
- [BYOK — Bring Your Own Gemini Key](https://docs.connectgain.cloud/04-use-cases/05-integrations/ai-byok-gemini.md)
- [Sequences (drip campaigns)](https://docs.connectgain.cloud/04-use-cases/02-user-guide/sequences.md)

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/04-use-cases/index.md)*

---

# Bot Flow Automation Recipes – WhatsApp Chatbot Workflows

Source: https://docs.connectgain.cloud/04-use-cases/bot-flow-automation-recipes/

# Bot Flow Automation Recipes

> Real-world flows you can build with ConnectGain's bot-flow builder, focused on the capabilities that bring full **respond.io Workflows parity** (and beyond): Jump To, Date & Time, Sub-flow, Google Sheets, Update Lifecycle, Close/Open Conversation, Add Comment, richer Branch logic, and the new triggers (Tag Updated, Field Updated, Lifecycle Updated, New Comment, Call Ended, Broadcast Response, Manual Shortcut).

Each recipe lists the **trigger**, the **nodes** in order, and the **business value**. Build them in **Flows (`/flows`)**, publish, and they deploy to the n8n runtime automatically.

See also: [Bot Flows user guide](https://docs.connectgain.cloud/04-use-cases/02-user-guide/bot-flows.md) · [Automation & webhook use cases](https://docs.connectgain.cloud/04-use-cases/bot-flow-automation-recipes/overview.md).

---

## Table of Contents

- [Conversation control](#conversation-control)
- [Time-based routing](#time-based-routing)
- [Lifecycle & segmentation](#lifecycle--segmentation)
- [Data capture & integrations](#data-capture--integrations)
- [Campaign & post-call follow-up](#campaign--post-call-follow-up)
- [Agent-launched flows](#agent-launched-flows)
- [Modular flows](#modular-flows)
- [Multilingual](#multilingual)
- [AI + data](#ai--data)

---

## Conversation control

### UC-FLOW-001: Auto-Resolve & Close After a Satisfaction Reply

**Business Scenario:**
After a bot answers an FAQ, it asks "Did that solve your issue?" and, on "yes", closes the conversation and tags the contact — keeping the inbox clean without an agent.

**Flow:**
1. **Trigger:** Message Received
2. **Send Message:** "Did that solve your issue? Reply YES or NO."
3. **Collect Input** → store as `resolved`
4. **Condition (Branch):** `resolved` *contains* "yes" (Match ANY with "y")
 - **True →** Add Comment ("Auto-resolved by bot") → **Close Conversation**
 - **False →** Handoff to agent
5. Publish

**Business Value:** Deflects resolved chats automatically, leaves an audit note, and routes only the unresolved ones to humans.

---

### UC-FLOW-002: Reopen on Customer Reply

**Business Scenario:**
When a customer replies to a previously closed conversation, reopen it so it resurfaces in the agent's queue.

**Flow:**
1. **Trigger:** Message Received
2. **Open (Reopen) Conversation**
3. **Assign Conversation** (availability-based)
4. Publish

**Business Value:** No customer message gets stranded in a closed thread.

---

## Time-based routing

### UC-FLOW-003: Business-Hours vs After-Hours Greeting

**Business Scenario:**
During business hours, route new chats to a live agent; outside them, send an expectations-setting message and capture the request.

**Flow:**
1. **Trigger:** Message Received
2. **Date & Time** (timezone `Africa/Cairo`, windows Mon–Fri 09:00–17:00)
 - **In hours →** Assign Conversation → Send "An agent will be right with you."
 - **Out of hours →** Send "We're offline; we'll reply at 9 AM." → Collect Input (their question) → Add Comment with the captured text
3. Publish

**Business Value:** One flow handles both states with the correct timezone — no separate after-hours automation needed.

---

### UC-FLOW-004: Weekend-Only Promotion Branch

**Business Scenario:**
Offer a weekend-only discount code when customers ask about pricing on Saturday/Sunday.

**Flow:**
1. **Trigger:** Message Received
2. **Condition:** message *contains* "price" or "cost" (Match ANY)
3. **Date & Time** (windows Sat 00:00–23:59, Sun 00:00–23:59)
 - **In hours →** Send "Weekend special: use code WK15 for 15% off."
 - **Out of hours →** Send standard pricing link
4. Publish

**Business Value:** Time-gated offers without manual scheduling.

---

## Lifecycle & segmentation

### UC-FLOW-005: Promote to "Customer" on Purchase Confirmation

**Business Scenario:**
When a contact confirms an order in chat, move them from *Lead* to *Customer* and notify the sales flow.

**Prerequisite:** Define stages in **Settings → Lifecycle Stages** (e.g. Lead, Opportunity, Customer).

**Flow:**
1. **Trigger:** Message Received
2. **Condition:** message *contains* "confirm" / "paid" (Match ANY)
3. **Update Lifecycle →** Customer
4. **Add Tag:** "Won" (mode: add)
5. Publish

**Business Value:** Lifecycle stays accurate automatically; the **Lifecycle Updated** trigger can kick off onboarding.

---

### UC-FLOW-006: Onboarding Flow on Lifecycle Change

**Business Scenario:**
The moment a contact becomes a *Customer* (by any path — bot, manual, or import), start an onboarding sequence.

**Flow:**
1. **Trigger:** Contact Lifecycle Updated
2. **Condition:** `lifecycle_stage` *equals* "Customer"
3. **Send Message:** welcome + onboarding checklist
4. **Create Task:** "Onboarding call" assigned to the account owner
5. Publish

**Business Value:** Decouples onboarding from *how* the stage changed — a single trigger covers every path.

---

### UC-FLOW-007: React to a Specific Field Change

**Business Scenario:**
When a contact's `lead_score` field is updated, re-evaluate routing.

**Flow:**
1. **Trigger:** Field Updated (Contact Updated, **watch field** = `lead_score`)
2. **Condition:** `lead_score` *greater than or equal* `80`
3. **Add Tag:** "Hot" → **Assign Conversation** to a senior rep
4. Publish

**Business Value:** Fires only when the field you care about changes — not on every contact edit.

---

### UC-FLOW-008: Tag-Driven Welcome

**Business Scenario:**
When the "VIP" tag is added to a contact, send a white-glove greeting.

**Flow:**
1. **Trigger:** Contact Tag Updated
2. **Condition:** tags *contains* "VIP"
3. **Send Message:** VIP greeting → **Add Comment:** "VIP greeting sent"
4. Publish

**Business Value:** Tag changes become first-class automation triggers.

---

## Data capture & integrations

### UC-FLOW-009: Log Every Lead to Google Sheets

**Business Scenario:**
The marketing team wants a live spreadsheet of inbound leads captured by the bot.

**Prerequisite:** Connect Google (Settings) — reconnect once to grant Sheets access.

**Flow:**
1. **Trigger:** Message Received
2. **Collect Input:** name → `name`
3. **Collect Input:** email → `email`
4. **Google Sheets (Append Row):** spreadsheet URL, tab `Leads`, values `{{name}}`, `{{email}}`, `{{contact.phone}}` (there's no `{{now}}` variable — let the sheet auto-timestamp with a `=NOW` column, or capture a value into a variable first)
5. **Create Deal:** "New web lead" in the Sales pipeline
6. Publish

**Business Value:** Captures structured lead data into a shared sheet and the CRM in one pass — no Zapier needed.

---

## Campaign & post-call follow-up

### UC-FLOW-010: Auto-Respond to Broadcast Replies

**Business Scenario:**
After a WhatsApp campaign goes out, automatically engage contacts who reply, and tag them as engaged.

**Flow:**
1. **Trigger:** Broadcast Response *(fires when a contact replies within 72h of receiving a campaign; carries `campaign_id`, `campaign_name`)*
2. **Add Tag:** "Campaign Engaged"
3. **Send Message:** "Thanks for replying to {{campaign_name}}! Want to book a demo?"
4. **Condition:** reply *contains* "yes" → **Sub-flow:** Booking flow
5. Publish

**Business Value:** Turns broadcast replies into conversations instantly, with full attribution to the originating campaign.

---

### UC-FLOW-011: Post-Call Follow-Up

**Business Scenario:**
After every recorded call, send a follow-up message and log a note.

**Flow:**
1. **Trigger:** Call Ended *(fires when the recording arrives; carries call id, contact, duration)*
2. **Send Message:** "Thanks for the call! Here's a summary link…"
3. **Add Comment:** "Follow-up sent after {{duration_seconds}}s call"
4. **Create Task:** "Send proposal" (due in 2 days)
5. Publish

**Business Value:** No post-call follow-up slips through the cracks.

---

## Agent-launched flows

### UC-FLOW-012: One-Click "Send Pricing Pack" Shortcut

**Business Scenario:**
Agents want to fire a multi-step pricing sequence from the inbox without typing it each time.

**Flow:**
1. **Trigger:** Manual Shortcut
2. **Send Message:** pricing PDF + intro
3. **Add Tag:** "Pricing Sent"
4. **Update Lifecycle →** Opportunity
5. Publish

**Usage:** In the inbox conversation header, open the **⚡ Shortcuts** menu and pick "Send Pricing Pack." It runs for the current conversation, passing the contact context.

**Business Value:** Repeatable, on-demand playbooks an agent triggers in one click.

---

## Modular flows

### UC-FLOW-013: Reusable Booking Sub-flow

**Business Scenario:**
Several flows need the same booking steps. Build it once and call it from anywhere.

**Setup:**
- **Booking flow** (child): Trigger = Manual Shortcut (or any trigger) → collect date/time → create scheduled event → confirm.
- **Any parent flow:** add a **Sub-flow** node pointing to "Booking flow", with *pass current variables* enabled.

**Business Value:** DRY flow design — update the booking logic in one place and every caller benefits.

---

### UC-FLOW-014: Loop Back to the Main Menu with Jump To

**Business Scenario:**
After completing any branch, return the user to the main menu instead of duplicating menu nodes.

**Flow:**
1. **Trigger:** Message Received → **Send Message:** main menu (1. Sales, 2. Support, 3. Hours)
2. **Switch** on the choice → each branch does its work
3. At the end of each branch, add a **Jump To** node targeting the main-menu Send Message node
4. Publish

**Business Value:** Clean, maintainable menus with no copy-pasted nodes; the Jump To resolves transparently at deploy time.

---

## Multilingual

> Full step-by-step, data shapes, and fallback rules: **[Building Multilingual Bot Flows](https://docs.connectgain.cloud/04-use-cases/02-user-guide/multilingual-flows.md)**.

### UC-FLOW-015: One Bot, Many Languages (localized Quick Reply)

**Business Scenario:**
A support bot must greet and menu customers in English, Arabic, and French — without maintaining three copies of the flow.

**Flow:**
1. **Trigger:** Message Received
2. **Quick Reply — language picker:** "Choose your language / اختر لغتك / Choisissez" with buttons English/العربية/Français. Enable **Collect into variable** → `lang`, **Save = payload** (payloads `en`/`ar`/`fr`)
3. **Quick Reply — main menu (single node):** in the node's **Content language** selector, fill the Default (English) body + button labels, then add `ar` and `fr` and translate the body and each button label. Payloads stay shared.
4. **Switch** on the chosen menu option → localized answers
5. Publish

**Business Value:** One node per step serves every language; the customer's `{{lang}}` picks the right text at send time, missing translations fall back to Default. No branching, no duplicated flow.

---

### UC-FLOW-016: Auto-Detect Language from the CRM

**Business Scenario:**
Returning customers already have a preferred language on their contact record — don't ask again.

**Flow:**
1. **Trigger:** Message Received
2. **Set Variable:** `lang` = `{{contact.language}}` (or a custom field)
3. **If Condition:** `lang` is empty → fall back to the language-picker Quick Reply (UC-FLOW-015); else continue
4. Localized Quick Replies / Send Messages render in `{{lang}}` automatically

**Business Value:** Seamless, personalized experience for known contacts; only new contacts are asked to pick a language.

---

### UC-FLOW-017: Localized Template Broadcast Follow-up

**Business Scenario:**
After a multilingual WhatsApp campaign, replies should be answered with the right-language template.

**Flow:**
1. **Trigger:** Broadcast Response
2. **Set Variable:** `lang` from the contact's language
3. **Send Message** (template): set `templateNameBase` (e.g. `promo_reply`) — the engine appends `__{{lang}}` (`promo_reply__ar`, `promo_reply__fr`), falling back to `__en`
4. **Quick Reply** (localized) to continue the conversation

**Business Value:** Compliant, on-brand, right-language replies at campaign scale using your existing Meta templates.

---

## AI + data

### UC-FLOW-018: Let AI Offer Scheduler Slots to the Customer

**Business Scenario:**
A booking bot should fetch real availability and have the AI phrase the options naturally ("I have Thu 3 PM or Fri 10 AM — which works?").

**Flow:**
1. **Trigger:** Message Received
2. **Scheduler** (operation `get_slots`, `event_type_id` set) → **output variable** `available_slots`
3. **Transform** (JMESPath) — **input** `available_slots`, **expression** `[*].start`, **output** `slots_text`
4. **AI Response** — prompt: *"The available appointment times are: `{{slots_text}}`. Offer these to the customer and help them pick one."*
5. Publish

**Two gotchas this recipe avoids:**
- **Adjacency:** mid-flow variables reach the next node via the *previous node's output*, not the trigger-time snapshot — so the value-consuming node (Transform, then AI Response) must sit **directly downstream** of the node that produced it.
- **Shape:** the Scheduler returns an array of `{ start, end }` **objects**; dropping `{{available_slots}}` straight into a prompt renders as `[object Object]`. The Transform step projects it to plain strings (`[*].start`) so the model reads a clean list.

> **Note:** the **AI Response** node interpolates `{{variables}}` in its prompt; the **AI Agent** node currently does **not** (its system prompt is sent as static text). Use AI Response when you need to inject flow variables like `{{slots_text}}` into the prompt.

**Business Value:** Real, bookable times phrased conversationally by AI — no hard-coded slot lists, no `[object Object]`.

**Troubleshooting — Transform output is `null`:** the Transform reads its input **by name from the session**, and `evalJmesPath(null, …)` returns `null`, so a null output means the input wasn't found. Check, in order:
1. **Scheduler → Output Variable = `available_slots`** (exact, no braces). The Scheduler only persists the slots when this field is set — it's the most common cause.
2. **Transform → Input Variable = `available_slots`** — the bare name, **not** `{{available_slots}}` (braces break the lookup).
3. **Transform → Expression = `[*].start`** (applied to the array). If Input Variable is left blank, the expression runs against the whole vars object and must be `available_slots[*].start` instead.
4. **Non-empty slots** — with no availability in the window (default `days_ahead` ≈ 14) the Scheduler returns `[]`. Widen `days_ahead` / confirm the event type has availability.
5. **Isolate:** drop a temporary Send Message after the Scheduler with body `{{available_slots.0.start}}` — blank ⇒ the Scheduler side (step 1/4); shows a time ⇒ the Transform config (step 2/3).

---

### UC-FLOW-019: Book Appointments from Relative Dates

**Business Scenario:**
Patients rarely give a full date — they say "tomorrow at 3 PM", "next Monday", "this Friday at 10 AM". The bot must turn that into a real appointment.

**Why it used to break:** the AI Agent's prompt had no reference to *today*, so the model invented a date (e.g. `2024-05-15`) from its training data. The AI Agent (and RAG agent) now receive the **current date/time at run time**, so relative dates resolve correctly.

**How a flow developer uses it:**
1. Open the **AI Agent** node → set **Timezone (for dates)** to your clinic's IANA zone (e.g. `Africa/Cairo`). Blank = server/UTC (can be a day off near midnight).
2. No prompt change is required — the agent is auto-told the current date and instructed to output **ISO 8601** (`YYYY-MM-DDTHH:mm`). Optionally add: *"Resolve the patient's date/time, confirm it back in plain language, then book via the Scheduler."*
3. Wire the booking, either:
 - **Agent-as-booker:** enable the Scheduler/booking tool on the agent, or
 - **Agent-as-extractor:** have the agent put the resolved ISO datetime in its **Output Variable**, then a downstream **Scheduler** node books it (read it by bare name, without braces — the same rule as in UC-FLOW-018).
4. **Re-publish the flow** — the current-date instruction is injected at Publish time, so changes only take effect after re-publishing.

**Verify:** in **n8n → Executions**, open the AI Agent input — the system message starts with `Current date and time: …`, and the emitted datetime matches. Test `tomorrow at 3 PM`, `next Monday`, `in 3 days`.

**Business Value:** patients book the way they talk; the agent produces correct, timezone-aware datetimes instead of hallucinated years.

---

## See also

- [Bot Flows user guide](https://docs.connectgain.cloud/04-use-cases/02-user-guide/bot-flows.md)
- [Building multilingual bot flows](https://docs.connectgain.cloud/04-use-cases/02-user-guide/multilingual-flows.md)
- [Automations user guide](https://docs.connectgain.cloud/04-use-cases/02-user-guide/automations.md)
- [Comprehensive use cases overview](https://docs.connectgain.cloud/04-use-cases/bot-flow-automation-recipes/overview.md)

---

**Last Updated:** June 2026

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/04-use-cases/index.md)*

---

# Business Use Cases by Industry – ConnectGain

Source: https://docs.connectgain.cloud/04-use-cases/business/

# Business Use Cases

## Overview

This document provides real-world business scenarios demonstrating how ConnectGain solves common business challenges across different industries and use cases.

---

## Table of Contents

1. [E-commerce Customer Support](#e-commerce-customer-support)
2. [Sales Team Lead Management](#sales-team-lead-management)
3. [Real Estate & Proptech](#real-estate--proptech)
4. [Tourism & Hospitality](#tourism--hospitality)
5. [Healthcare Appointment Management](#healthcare-appointment-management)
6. [Education Institution Communication](#education-institution-communication)
7. [Restaurant Order Management](#restaurant-order-management)
8. [Financial Services Client Onboarding](#financial-services-client-onboarding)
9. [SaaS Product Support](#saas-product-support)
10. [Retail Store Customer Engagement](#retail-store-customer-engagement)
11. [Service Business Scheduling](#service-business-scheduling)
12. [Team Attendance Management](#team-attendance-management)
13. [Sales Performance Reporting](#sales-performance-reporting)
14. [Booking Management System](#booking-management-system)
15. [Call Intelligence & Sales Coaching](#call-intelligence--sales-coaching)

---

## E-commerce Customer Support

> See also the [E-commerce solution page](https://connectgain.cloud/en/solutions/e-commerce) on the ConnectGain website.

### Scenario

An e-commerce business receives hundreds of customer inquiries daily via WhatsApp, Messenger, and Instagram about orders, products, returns, and shipping. They need to respond quickly, track issues, and maintain customer satisfaction.

### Solution

**Setup:**
1. Connect WhatsApp, Messenger, and Instagram channels
2. Import customer database
3. Create support team with agents
4. Set up automation rules for common inquiries
5. Create quick reply templates

**Workflow:**
1. Customer sends inquiry via WhatsApp
2. Automation rule detects inquiry type (order status, return, etc.)
3. Bot flow provides initial response with options
4. If bot can't resolve, conversation assigned to agent
5. Agent reviews customer history (orders, previous conversations)
6. Agent responds with solution
7. If needed, agent creates task for follow-up
8. Conversation closed when resolved
9. Customer receives satisfaction survey

**Benefits:**
- 24/7 automated responses
- Faster response times
- Complete customer history
- Team collaboration
- Customer satisfaction tracking

**Metrics:**
- Average response time: < 5 minutes
- First contact resolution: 85%
- Customer satisfaction: 4.5/5

---

## Sales Team Lead Management

### Scenario

A B2B sales team manages hundreds of leads from multiple sources (website, referrals, events). They need to qualify leads, track progress through [sales pipeline](https://docs.connectgain.cloud/04-use-cases/02-user-guide/deals.md), and close deals efficiently.

### Solution

**Setup:**
1. Create sales pipeline with stages (Lead, Qualified, Proposal, Negotiation, Closed Won/Lost)
2. Import leads from various sources
3. Set up lead assignment rules
4. Create deal templates
5. Configure automation for lead follow-up

**Workflow:**
1. Lead submits inquiry via website form
2. Lead automatically imported as contact
3. Deal created and assigned to sales rep
4. Sales rep qualifies lead via WhatsApp/Messenger
5. If qualified, deal moved to "Qualified" stage
6. Sales rep sends proposal
7. Deal moved to "Proposal" stage
8. Negotiation happens, deal moved to "Negotiation"
9. Deal closed as Won or Lost
10. If won, customer onboarded; if lost, reason recorded

**Benefits:**
- Centralized lead management
- Pipeline visibility
- Automated follow-ups
- Deal tracking
- Performance analytics

**Metrics:**
- Lead response time: < 1 hour
- Qualification rate: 60%
- Conversion rate: 25%
- Average deal value: $15,000

---

## Real Estate & Proptech

> See also the [Real Estate solution page](https://connectgain.cloud/en/solutions/real-estate) on the ConnectGain website.

ConnectGain is perfectly suited for real estate agencies, property management companies, real estate developers, and proptech platforms. The platform streamlines property inquiries, lead management, client communication, and deal tracking.

### Lead Management & Inquiry Handling

**Property Inquiry Management:**
- **Multi-Channel Property Inquiries** - Receive inquiries from WhatsApp, Messenger, Instagram, and Email (SMS is outbound broadcast/sequence only — it does not deliver inbound messages into the inbox)
 - Unified inbox for all property inquiries
 - Instant notifications for new inquiries
 - Channel identification (Instagram for visual properties, WhatsApp for quick questions)
 - Auto-assignment to property agents based on availability
- **Inquiry Qualification** - Automated [bot flows](https://docs.connectgain.cloud/04-use-cases/02-user-guide/bot-flows.md) to qualify leads
 - Budget range questions
 - Property type preferences (apartment, house, commercial)
 - Location preferences
 - Timeline questions (immediate, 3 months, 6 months)
 - Contact information collection
- **Lead Scoring** - Automatically score leads based on responses
 - High-value leads flagged immediately
 - Follow-up task creation for qualified leads
 - Deal creation from qualified inquiries

**Property Showings & Viewings:**
- **Automated Scheduling** - Bot flows for property viewing appointments
 - Available time slot display
 - Calendar integration
 - Confirmation messages
 - Reminder notifications (24 hours before, 2 hours before)
 - Rescheduling options
 - Cancellation handling
- **Viewing Confirmation** - Automated confirmation workflows
 - SMS/WhatsApp confirmations
 - Property details and address
 - Agent contact information
 - Directions and parking information
 - What to bring checklist

**Follow-Up Automation:**
- **Post-Viewing Follow-Up** - Automated follow-up sequences
 - Thank you message after viewing
 - Feedback request (24 hours after viewing)
 - Additional property suggestions based on preferences
 - Price reduction notifications
 - New listing alerts matching criteria
- **Nurture Campaigns** - Long-term lead nurturing
 - Weekly market updates
 - Neighborhood guides
 - Financing information
 - Property investment tips

### Client Relationship Management

**Buyer Journey Tracking:**
- **Deal Pipeline Management** - Track buyers through sales process
 - Pipeline stages: Inquiry → Qualified → Viewing Scheduled → Offer Submitted → Under Contract → Closed
 - Deal value tracking (purchase price)
 - Commission tracking
 - Expected close date management
 - Probability tracking based on stage
- **Contact Segmentation** - Organize contacts by buyer type
 - Tags: First-time buyer, Investor, Relocator, Luxury buyer
 - Budget ranges: Under $500K, $500K-$1M, $1M-$2M, $2M+
 - Property types: Residential, Commercial, Land, Investment
 - Location preferences: Downtown, Suburbs, Waterfront, etc.

**Seller Management:**
- **Listing Management** - Track property listings
 - Property details in deal records
 - Listing price tracking
 - Days on market tracking
 - Viewing count tracking
 - Offer tracking
- **Seller Communication** - Automated seller updates
 - Viewing notifications
 - Offer notifications
 - Market activity reports
 - Price adjustment recommendations

**Tenant Management (Property Management):**
- **Tenant Onboarding** - Automated tenant communication
 - Welcome messages with move-in instructions
 - Lease document delivery
 - Payment setup instructions
 - Property access codes
 - Emergency contact information
- **Maintenance Requests** - Handle maintenance inquiries
 - Maintenance request intake via bot flows
 - Priority classification (Emergency, Urgent, Normal)
 - Vendor assignment
 - Status updates to tenants
 - Completion confirmations
- **Rent Collection** - Automated rent reminders
 - Rent due reminders (5 days before, 1 day before)
 - Payment confirmation messages
 - Late payment notifications
 - Payment link delivery

### Marketing & Campaigns

**Property Marketing Campaigns:**
- **New Listing Announcements** - Broadcast new properties
 - WhatsApp Business campaigns for new listings
 - Rich media (property photos, virtual tours)
 - Property details and pricing
 - Open house announcements
 - Target by buyer preferences (tags, budget, location)
- **Price Reduction Alerts** - Notify interested buyers
 - Automated price drop campaigns
 - Target contacts who viewed property
 - Personalized messages with new price
- **Open House Invitations** - Event marketing
 - SMS/WhatsApp invitations
 - Calendar integration
 - RSVP tracking
 - Reminder messages

**Lead Generation Campaigns:**
- **Social Media Lead Capture** - Convert social media inquiries
 - Instagram DM to CRM integration
 - Facebook Messenger property inquiries
 - Automated lead qualification
- **Referral Programs** - Client referral campaigns
 - Referral request messages
 - Referral tracking
 - Reward notifications

### Analytics & Performance

**Real Estate Metrics:**
- **Lead Conversion Tracking** - Track inquiry to closing
 - Inquiry source analysis (Instagram, WhatsApp, Website, Referral)
 - Conversion rates by channel
 - Average time to close
 - Lead quality scoring
- **Agent Performance** - Track agent metrics
 - Response time tracking
 - Inquiry handling volume
 - Conversion rates per agent
 - Commission tracking
- **Property Performance** - Analyze property metrics
 - Views per property
 - Inquiries per property
 - Time on market
 - Price reduction impact

**Reporting:**
- **Monthly Reports** - Automated performance reports
 - New leads by source
 - Conversions by stage
 - Revenue tracking
 - Agent performance summaries
- **Market Insights** - Property market analytics
 - Inquiry trends
 - Popular property types
 - Price range preferences
 - Location preferences

### Specific Real Estate Scenarios

**Scenario 1: New Property Listing**
1. Property listed on website and social media
2. Instagram inquiry received → Auto-qualified via bot flow
3. Qualified lead assigned to agent
4. Deal created in pipeline
5. Viewing scheduled via automated flow
6. Post-viewing follow-up automated
7. Offer submitted → Deal moved to "Under Contract"
8. Closing → Deal marked "Closed Won"

**Scenario 2: Property Management Maintenance**
1. Tenant sends WhatsApp message: "AC not working"
2. Bot flow collects details (unit, issue description, urgency)
3. High-priority task created automatically
4. Vendor assigned based on issue type
5. Tenant receives confirmation and ETA
6. Vendor completes work → Status update sent to tenant
7. Follow-up satisfaction survey sent

**Scenario 3: Buyer Lead Nurturing**
1. Website visitor downloads neighborhood guide
2. Contact created with tag "Downloaded Guide"
3. Automated nurture sequence starts:
 - Day 1: Welcome message + market report
 - Day 3: Financing options guide
 - Day 7: Featured properties matching preferences
 - Day 14: Open house invitations
 - Weekly: Market updates and new listings
4. When ready, contact responds → Qualified and assigned to agent

---

## Tourism & Hospitality

> See also the [Tourism solution page](https://connectgain.cloud/en/solutions/tourism) on the ConnectGain website.

ConnectGain empowers tourism businesses, travel agencies, hotels, tour operators, and hospitality companies to deliver exceptional customer experiences through seamless multi-channel communication and automated workflows.

### Booking Management & Inquiries

**Travel Inquiry Handling:**
- **Multi-Channel Booking Inquiries** - Receive inquiries from all channels
 - WhatsApp for international travelers (most popular)
 - Instagram for visual travel inspiration
 - Facebook Messenger for package inquiries
 - Email for detailed itineraries
 - SMS for booking confirmations
- **Automated Booking Bot** - Intelligent booking assistant
 - Destination questions
 - Travel dates collection
 - Number of travelers
 - Budget range
 - Travel preferences (beach, mountain, city, adventure)
 - Accommodation preferences (hotel, resort, villa, hostel)
 - Meal preferences (all-inclusive, breakfast only, self-catering)
- **Availability Checking** - Real-time availability integration
 - Check hotel availability
 - Flight availability
 - Tour availability
 - Instant availability responses

**Booking Confirmation & Management:**
- **Automated Confirmations** - Instant booking confirmations
 - WhatsApp/SMS confirmation messages
 - Booking reference numbers
 - Itinerary details
 - Payment instructions
 - Cancellation policy
 - Contact information
- **Pre-Travel Communication** - Automated pre-travel sequences
 - 7 days before: Final details and reminders
 - 3 days before: Weather forecast and packing tips
 - 1 day before: Check-in instructions and contact details
 - Day of travel: Real-time updates and support

**Modification & Cancellation:**
- **Booking Changes** - Handle modifications via chat
 - Date changes
 - Guest count changes
 - Room/tour upgrades
 - Special requests
- **Cancellation Handling** - Automated cancellation process
 - Cancellation request intake
 - Refund calculation
 - Cancellation confirmation
 - Future booking incentives

### Customer Service & Support

**24/7 Customer Support:**
- **Multi-Language Support** - Serve international travelers
 - Bot flows in multiple languages
 - Agent handoff for complex queries
 - Translation capabilities
- **Common Queries Automation** - Handle frequent questions
 - "What's included in the package?"
 - "What are the check-in/check-out times?"
 - "Do you provide airport transfers?"
 - "What documents do I need?"
 - "What's the cancellation policy?"
- **Emergency Support** - Handle urgent situations
 - Priority routing for emergencies
 - 24/7 agent availability
 - Quick response guarantees

**During-Stay Support:**
- **Concierge Services** - Hotel concierge via messaging
 - Restaurant recommendations
 - Activity bookings
 - Transportation arrangements
 - Room service orders
 - Maintenance requests
- **Real-Time Assistance** - Immediate support during travel
 - Lost luggage assistance
 - Medical emergencies
 - Travel disruptions
 - Local recommendations

### Marketing & Promotions

**Promotional Campaigns:**
- **Seasonal Campaigns** - Targeted seasonal promotions
 - Summer vacation packages
 - Winter getaway deals
 - Holiday specials
 - Last-minute deals
- **Personalized Offers** - Targeted marketing
 - Past traveler specials
 - Birthday offers
 - Anniversary packages
 - Loyalty program benefits
- **Destination Marketing** - Promote specific destinations
 - New destination launches
 - Special event promotions (festivals, sports events)
 - Weather-based promotions

**Upselling & Cross-Selling:**
- **Service Upselling** - Increase booking value
 - Room upgrades
 - Additional services (spa, tours, transfers)
 - Travel insurance
 - Meal plan upgrades
- **Cross-Selling** - Related service promotion
 - Car rentals
 - Travel insurance
 - Excursions and tours
 - Restaurant reservations

### Post-Travel Engagement

**Feedback Collection:**
- **Automated Feedback Requests** - Collect reviews and feedback
 - Post-checkout feedback request (24 hours after)
 - Review platform integration
 - Photo sharing requests
 - Improvement suggestions
- **Review Management** - Handle reviews
 - Positive review thank you messages
 - Negative review follow-up and resolution
 - Review response automation

**Loyalty & Retention:**
- **Loyalty Program** - Reward repeat customers
 - Points tracking
 - Tier status notifications
 - Exclusive offers for members
 - Birthday rewards
- **Re-Engagement Campaigns** - Win back customers
 - "We miss you" campaigns
 - Special return offers
 - New destination suggestions
 - Anniversary reminders

### Group Travel Management

**Group Bookings:**
- **Group Inquiry Handling** - Manage group travel
 - Group size collection
 - Special requirements
 - Custom itinerary requests
 - Group discount information
- **Group Communication** - Coordinate with groups
 - Group WhatsApp broadcasts
 - Itinerary updates
 - Meeting point notifications
 - Group activity reminders

**Corporate Travel:**
- **Corporate Account Management** - B2B travel services
 - Corporate account setup
 - Preferred rates
 - Booking approvals workflow
 - Expense reporting integration

### Analytics & Performance

**Tourism Metrics:**
- **Booking Analytics** - Track booking performance
 - Bookings by channel (WhatsApp, Instagram, Website)
 - Conversion rates by source
 - Average booking value
 - Booking lead time
- **Customer Satisfaction** - Measure satisfaction
 - Response time tracking
 - Customer satisfaction scores
 - Review ratings
 - Repeat booking rate
- **Destination Performance** - Analyze popular destinations
 - Most booked destinations
 - Seasonal trends
 - Package popularity
 - Revenue by destination

**Operational Metrics:**
- **Agent Performance** - Track support team
 - Response times
 - Resolution rates
 - Customer satisfaction per agent
 - Booking conversion per agent
- **Channel Performance** - Optimize channel usage
 - Most effective channels
 - Cost per booking by channel
 - Customer preference by channel

### Specific Tourism Scenarios

**Scenario 1: Hotel Booking Journey**
1. Instagram ad clicked → DM inquiry received
2. Bot flow collects: dates, guests, preferences
3. Availability checked → Options presented
4. Booking confirmed via WhatsApp
5. Payment link sent → Payment received
6. Confirmation with booking details
7. Pre-arrival sequence (7 days, 3 days, 1 day before)
8. Check-in day: Welcome message + room details
9. During stay: Concierge support available
10. Check-out: Feedback request
11. Post-stay: Thank you + loyalty program enrollment

**Scenario 2: Tour Package Inquiry**
1. Website visitor requests "Adventure Tour Package"
2. Bot flow qualifies: destination, dates, group size, experience level
3. Qualified lead assigned to tour specialist
4. Custom itinerary created and shared via WhatsApp
5. Questions answered → Booking confirmed
6. Pre-tour information sent (what to bring, meeting point)
7. Day before: Final reminders and weather update
8. Tour day: Real-time updates and support
9. Post-tour: Thank you + review request + photo sharing
10. Follow-up: Related tour suggestions

**Scenario 3: Travel Agency Customer Service**
1. Customer sends WhatsApp: "My flight was cancelled"
2. Urgent priority assigned automatically
3. Agent responds within SLA (under 5 minutes)
4. Alternative flight options researched
5. New flight booked → Confirmation sent
6. Hotel notified of late arrival
7. Transfer rescheduled
8. Customer updated with all changes
9. Compensation process initiated
10. Follow-up: Satisfaction check + future booking discount

**Scenario 4: Seasonal Campaign**
1. "Summer Sale" campaign created
2. Target: Contacts tagged "Past Traveler" + "Beach Lover"
3. WhatsApp Business campaign sent with:
 - Beautiful destination images
 - Special package pricing
 - Limited-time offer
 - Booking link
4. Interested contacts click → Bot flow captures interest
5. Qualified leads assigned to agents
6. Follow-up calls scheduled
7. Bookings tracked in deals pipeline
8. Campaign performance analyzed:
 - Open rate, click rate, conversion rate
 - Revenue generated
 - ROI calculation

---

## Healthcare Appointment Management

> See also the [Healthcare solution page](https://connectgain.cloud/en/solutions/healthcare) on the ConnectGain website.

### Scenario

A medical clinic needs to manage patient appointments, send reminders, handle cancellations, and provide post-appointment follow-ups.

### Solution

**Setup:**
1. Connect WhatsApp and SMS channels
2. Import patient database
3. Create appointment scheduling bot flow
4. Set up reminder automation
5. Create follow-up templates

**Workflow:**
1. Patient sends appointment request via WhatsApp
2. Bot flow collects:
 - Preferred date/time
 - Reason for visit
 - Insurance information
3. Bot checks availability
4. Bot confirms appointment or suggests alternatives
5. Appointment confirmed, task created for staff
6. 24 hours before appointment, reminder sent
7. 2 hours before, second reminder sent
8. Patient confirms or cancels
9. If cancelled, slot opened for other patients
10. After appointment, follow-up message sent
11. Patient provides feedback

**Benefits:**
- Automated scheduling
- Reduced no-shows
- Patient engagement
- Staff efficiency
- Patient satisfaction

**Metrics:**
- Appointment booking: 70% automated
- No-show rate: Reduced by 40%
- Patient satisfaction: 4.6/5

---

## Education Institution Communication

> See also the [Education solution page](https://connectgain.cloud/en/solutions/education) on the ConnectGain website.

### Scenario

A school needs to communicate with parents about events, announcements, student progress, and emergencies via WhatsApp and SMS.

### Solution

**Setup:**
1. Connect WhatsApp and SMS channels
2. Import parent/student database
3. Create announcement templates
4. Set up class-based groups
5. Configure emergency notification rules

**Workflow:**
1. School creates announcement campaign
2. Targets parents by class/grade
3. Sends announcement via WhatsApp
4. Parents receive message
5. Parents can reply with questions
6. School responds to inquiries
7. For emergencies, SMS sent to all parents
8. Parent responses tracked
9. Follow-up messages sent as needed

**Benefits:**
- Mass communication
- Two-way engagement
- Emergency notifications
- Parent engagement
- Message tracking

**Metrics:**
- Message delivery: 98%
- Response rate: 60%
- Parent engagement: 85%

---

## Restaurant Order Management

> See also the [Restaurants solution page](https://connectgain.cloud/en/solutions/restaurants) on the ConnectGain website.

### Scenario

A restaurant receives orders via WhatsApp and Messenger, needs to confirm orders, send updates, and handle customer inquiries.

### Solution

**Setup:**
1. Connect WhatsApp and Messenger
2. Create menu templates
3. Set up order confirmation bot flow
4. Create order status update templates
5. Configure kitchen notification rules

**Workflow:**
1. Customer sends order via WhatsApp
2. Bot flow collects:
 - Menu items
 - Quantities
 - Delivery address
 - Payment method
3. Bot confirms order and provides order number
4. Order sent to kitchen (via integration or task)
5. Customer receives "Preparing" update
6. Customer receives "Out for delivery" update
7. Customer receives "Delivered" update
8. Customer provides feedback
9. Follow-up message sent next day

**Benefits:**
- Automated order taking
- Order tracking
- Customer updates
- Reduced phone calls
- Customer satisfaction

**Metrics:**
- Order processing time: Reduced by 50%
- Customer inquiries: Reduced by 60%
- Customer satisfaction: 4.8/5

---

## Financial Services Client Onboarding

> See also the [Fintech solution page](https://connectgain.cloud/en/solutions/fintech) on the ConnectGain website.

### Scenario

A financial services company needs to onboard new clients, collect documents, verify information, and provide account updates.

### Solution

**Setup:**
1. Connect WhatsApp and Email channels
2. Create onboarding bot flow
3. Set up document collection automation
4. Create verification workflows
5. Configure account update templates

**Workflow:**
1. Client applies for service via website
2. Client receives WhatsApp message with application link
3. Bot flow guides client through:
 - Information collection
 - Document upload
 - Verification questions
4. Documents collected and stored
5. Application assigned to agent for review
6. Agent verifies information
7. If approved, account created
8. Client receives account details via WhatsApp
9. Client receives welcome message with next steps
10. Ongoing account updates sent automatically

**Benefits:**
- Streamlined onboarding
- Document collection
- Automated verification
- Client communication
- Compliance tracking

**Metrics:**
- Onboarding time: Reduced by 60%
- Document collection: 90% automated
- Client satisfaction: 4.5/5

---

## SaaS Product Support

### Scenario

A SaaS company provides customer support via multiple channels, needs to track issues, provide solutions, and maintain customer relationships.

### Solution

**Setup:**
1. Connect all messaging channels
2. Import customer database
3. Create support ticket system (via deals/tasks)
4. Set up knowledge base integration
5. Configure escalation rules

**Workflow:**
1. Customer reports issue via Messenger
2. Bot flow collects:
 - Issue description
 - Product version
 - Error messages
3. Bot searches knowledge base
4. If solution found, bot provides answer
5. If not, ticket created and assigned to support agent
6. Agent reviews ticket and customer history
7. Agent provides solution
8. If needed, agent escalates to engineering
9. Issue resolved, customer notified
10. Follow-up survey sent

**Benefits:**
- Multi-channel support
- Automated solutions
- Ticket tracking
- Customer history
- Team collaboration

**Metrics:**
- First response time: < 2 hours
- Resolution time: < 24 hours
- Customer satisfaction: 4.6/5

---

## Retail Store Customer Engagement

> See also the [Retail solution page](https://connectgain.cloud/en/solutions/retail) on the ConnectGain website.

### Scenario

A retail store wants to engage customers with promotions, product updates, and personalized offers via WhatsApp and Instagram.

### Solution

**Setup:**
1. Connect WhatsApp and Instagram
2. Import customer database with purchase history
3. Create product catalog templates
4. Set up segmentation (VIP, Regular, New)
5. Configure campaign scheduling

**Workflow:**
1. Store creates promotional campaign
2. Targets customers by segment:
 - VIP customers: Exclusive offers
 - Regular customers: General promotions
 - New customers: Welcome offers
3. Campaign sent via WhatsApp/Instagram
4. Customers receive personalized messages
5. Customers click links or reply
6. Store tracks engagement
7. High-engagers receive additional offers
8. Purchase completed
9. Follow-up message sent
10. Customer feedback collected

**Benefits:**
- Personalized messaging
- Campaign tracking
- Customer segmentation
- Engagement analytics
- Sales increase

**Metrics:**
- Campaign open rate: 70%
- Click-through rate: 25%
- Conversion rate: 10%
- Sales increase: 30%

---

## Service Business Scheduling

### Scenario

A service business (plumbing, HVAC, etc.) needs to schedule appointments, send reminders, handle cancellations, and follow up after service.

### Solution

**Setup:**
1. Connect WhatsApp and SMS
2. Create scheduling bot flow
3. Set up calendar integration
4. Configure reminder automation
5. Create service follow-up templates

**Workflow:**
1. Customer requests service via WhatsApp
2. Bot flow collects:
 - Service type
 - Preferred date/time
 - Address
 - Problem description
3. Bot checks technician availability
4. Bot confirms appointment
5. Reminder sent 24 hours before
6. Reminder sent 2 hours before
7. Customer confirms or reschedules
8. Technician completes service
9. Follow-up message sent
10. Customer provides feedback and rating
11. If positive, referral request sent

**Benefits:**
- Automated scheduling
- Reduced no-shows
- Customer reminders
- Follow-up automation
- Referral generation

**Metrics:**
- Scheduling automation: 80%
- No-show rate: Reduced by 50%
- Customer satisfaction: 4.7/5
- Referral rate: 25%

---

## AI Re-Engagement for Messenger & Instagram

### Scenario

A business receives product inquiries and sales leads via Facebook Messenger and Instagram DMs. Many conversations go silent before the team can follow up, and Meta's 24-hour customer-service window closes, making further outreach impossible without the customer replying first.

### Solution

**Setup:**
1. Enable [AI Re-Engagement](https://docs.connectgain.cloud/04-use-cases/02-user-guide/ai-reengagement.md) add-on (7-day free trial available)
2. Configure threshold (default 20h after last customer message)
3. Select channels: Messenger, Instagram, or both
4. Choose tone: Friendly, Formal, or Casual
5. Optional: enable agent approval workflow

**Workflow:**
1. Customer sends inquiry via Messenger (e.g., "Do you have this in blue?")
2. Agent replies with options; customer goes silent
3. 20 hours later, AI analyses conversation context
4. AI generates personalised nudge message
5. If approval mode on: draft appears in inbox for agent review
6. Nudge sent automatically (or after approval) before 24h window closes
7. Customer replies → window resets, conversation continues
8. If 3 consecutive nudges unanswered: auto-paused for that conversation

**Benefits:**
- Recovers 15–25% of abandoned carts and silent inquiries
- Fully compliant with Meta's 24-hour messaging policy
- No manual follow-up required
- Agent approval option for brand control
- BYOK (Bring Your Own Gemini Key) available for cost control

**Metrics:**
- Cart recovery rate: +15–25%
- Lead response rate: +30%
- Viewing bookings: +20%
- Support ticket reopens: -15%

---

## Team Attendance Management

### Scenario

A customer support team needs to track agent attendance, monitor online status, and ensure proper coverage during business hours. Managers need visibility into who's working, when they clocked in/out, and total hours worked.

### Solution

**Setup:**
1. Enable attendance tracking feature
2. Configure automatic clock in/out on login/logout
3. Set up admin access for attendance reports
4. Configure real-time status updates

**Workflow:**
1. Agent logs into ConnectGain
2. System automatically clocks in agent
3. Agent's online status updated in real-time
4. Manager views attendance dashboard:
 - Sees all online agents
 - Views attendance history
 - Checks hours worked
 - Monitors active sessions
5. Agent logs out
6. System automatically clocks out agent
7. Duration calculated and logged
8. Manager can review attendance reports:
 - Filter by date range
 - Search by agent name
 - Filter by status (active/completed)
 - Export attendance data

**Benefits:**
- Automatic tracking (no manual entry)
- Real-time visibility
- Accurate time tracking
- Historical reporting
- Manager oversight

**Metrics:**
- Attendance compliance: 95%
- Average hours per agent: 8 hours/day
- Online status accuracy: Real-time
- Manager visibility: 100% coverage

---

## Sales Performance Reporting

### Scenario

A sales manager needs comprehensive reports on pipeline performance, deal progression, and team metrics to make data-driven decisions and identify bottlenecks.

### Solution

**Setup:**
1. Configure sales pipelines with stages
2. Set up deal tracking with values and probabilities
3. Assign deals to team members
4. Enable sales report feature

**Workflow:**
1. Sales manager navigates to Sales Report
2. Selects pipeline to analyze
3. System generates comprehensive report:
 - Summary metrics (total stages, deals, value)
 - Stage-by-stage breakdown
 - Deal details per stage
 - Average deal values
 - Probability tracking
4. Manager expands/collapses stages as needed
5. Manager views individual deal details:
 - Deal title and description
 - Contact and company information
 - Deal value and probability
 - Expected close date
6. Manager clicks to view deal or conversation
7. Manager exports report to CSV:
 - All stages included
 - Stage summaries
 - Grand totals
 - Ready for Excel analysis
8. Manager uses insights to:
 - Identify stuck deals
 - Redistribute workload
 - Forecast revenue
 - Plan team activities

**Benefits:**
- Comprehensive pipeline visibility
- Data-driven decision making
- Easy export for analysis
- Quick identification of issues
- Performance tracking

**Metrics:**
- Report generation time: < 2 seconds
- Pipeline visibility: 100%
- Export success rate: 100%
- Manager satisfaction: 4.8/5

---

## Booking Management System

### Scenario

A consulting firm needs to manage client appointments, sync with Google Calendar, and track meeting details. They need a centralized system to view all bookings, manage schedules, and ensure no conflicts.

### Solution

**Setup:**
1. Connect Google Calendar integration
2. Import existing contacts
3. Set up booking templates
4. Configure team member assignments

**Workflow:**
1. Consultant creates booking:
 - Enters title and description
 - Selects contact from CRM
 - Assigns to team member
 - Sets date and time
 - Adds location or meeting link
 - Sets status (scheduled/confirmed)
2. System creates Google Calendar event:
 - Event added to consultant's calendar
 - Contact added as attendee
 - Meeting link included
 - Reminders configured
3. Consultant views booking list:
 - Sees all upcoming bookings
 - Filters by status
 - Searches by contact or title
 - Views booking details
4. Booking confirmed:
 - Status updated to "confirmed"
 - Calendar event updated
 - Contact notified
5. Booking completed:
 - Status updated to "completed"
 - Notes added
 - Follow-up task created
6. Booking cancelled:
 - Status updated to "cancelled"
 - Calendar event removed
 - Contact notified
 - Slot freed up

**Benefits:**
- Centralized booking management
- Google Calendar sync
- Contact integration
- Conflict prevention
- Status tracking

**Metrics:**
- Booking creation time: < 1 minute
- Calendar sync success: 99%
- Conflict prevention: 100%
- User satisfaction: 4.7/5

---

## Deal Ownership Tracking & Management

### Scenario

A sales team needs to track how long deals stay with each team member, identify bottlenecks, and automatically reassign inactive deals to ensure fair distribution and prevent deals from getting stuck.

### Solution

**Setup:**
1. Enable deal ownership tracking
2. Configure automatic reassignment rules
3. Set inactivity threshold (e.g., 7 days)
4. Enable round-robin assignment

**Workflow:**
1. Deal created and assigned to sales rep
2. System logs initial assignment:
 - Records owner
 - Timestamps assignment
 - Logs reason: "Initial assignment"
3. Deal progresses through pipeline
4. If deal becomes inactive (no updates for 7 days):
 - System identifies inactive deals
 - Automatically reassigns using round-robin
 - Logs reassignment with reason: "Auto-reassigned"
 - Notifies new owner
5. Manager views ownership history:
 - Sees all ownership changes
 - Views duration with each owner
 - Identifies bottlenecks
 - Reviews reassignment reasons
6. Manager analyzes performance:
 - Average time per owner
 - Deal handling efficiency
 - Workload distribution
 - Bottleneck identification
7. Manual reassignment:
 - Manager manually reassigns deal
 - System logs change
 - Duration calculated
 - Reason recorded

**Benefits:**
- Complete audit trail
- Fair workload distribution
- Prevents deal stagnation
- Performance insights
- Accountability tracking

**Metrics:**
- Ownership tracking accuracy: 100%
- Auto-reassignment success: 95%
- Average deal duration per owner: Tracked
- Bottleneck identification: Real-time

---

## Call Intelligence & Sales Coaching

### Scenario

A sales and support team runs dozens of calls a day. Managers want to coach reps objectively, understand what really happens on calls (who talks, what topics come up, how customers feel), see which deals are at risk, and track how often competitors or pricing objections are raised — without manually listening to every recording.

### Solution

**Setup:**
1. Send call recordings to ConnectGain (in-app upload, mobile recorder, or the call-recording webhook from a PBX/dialer)
2. Choose the AI vendor in Settings → [Call Intelligence](https://docs.connectgain.cloud/04-use-cases/02-user-guide/call-intelligence.md) (Gemini default, or OpenAI/Claude/Gemini/Ollama/GLM, or Bring-Your-Own-Key)
3. Create **Conversation Trackers** for competitors, pricing, and common objections — keyword (exact phrase) or smart (AI concept) detection
4. Build one or more **Coaching Scorecard templates** (e.g., agenda-setting, discovery, objection handling) with per-criterion max scores

**Workflow:**
1. A call is recorded and ingested; the AI pipeline runs automatically:
 - Transcribes the call in Arabic or English
 - **Diarizes** the audio into agent vs. customer turns
 - Computes **interaction stats** — talk ratio (vs. the ~43:57 benchmark), longest monologue, interactivity, agent question rate, and patience
 - Produces an AI summary, action items (auto-created as CRM tasks), sentiment + a **sentiment timeline**, resolution score, keywords, and classification
 - Matches **trackers** against the transcript (keyword + smart) and records the hits
2. A rep or manager opens the call and sees the full picture in one dialog: transcript with speakers, interaction stats, sentiment over time, tracker hits, AI summary, and action items
3. The manager scores the call:
 - Clicks **AI suggest** to pre-fill scores from the transcript, then adjusts
 - Or scores each criterion manually and adds coaching notes
 - The scorecard is saved with reviewer attribution and an AI/manual badge
4. The rep links the call to its **deal**; the deal's activity tab now shows a Call Intelligence rollup — avg sentiment, resolution, talk time, tracker mentions, and recent calls — so anyone working the deal sees its conversation health
5. The manager reviews the **Tracker Trends** report to see how often competitors/pricing/objections came up across all calls, and whether mentions are rising or falling over time
6. Older calls processed before these analytics show a prompt to re-run transcription to backfill the new insights

**Benefits:**
- Objective, repeatable coaching instead of gut feel
- Reps get instant feedback on talk ratio, questions, and listening
- Deal risk and momentum visible directly on the deal record
- Competitive and objection intelligence aggregated across every call
- Multi-vendor / BYOK AI for cost control and data ownership
- Full Arabic + English support

**Metrics:**
- Calls auto-transcribed & analyzed: 100% (non-silent recordings)
- Speaker-attributed talk metrics: Per call
- Manager scoring time: Reduced via AI-suggested scorecards
- Tracker coverage: Every processed call, keyword + AI concept
- Deal-level conversation signals: Real-time rollup

---

## Implementation Guide

### Step 1: Identify Your Use Case

Review the use cases above and identify which matches your business needs. You can also combine elements from multiple use cases.

### Step 2: Set Up Channels

Connect the messaging channels your customers use most:
- WhatsApp for international reach
- Messenger for Facebook users
- Instagram for younger demographics
- SMS for universal reach

### Step 3: Import Your Data

Import your existing customer database:
- Contacts
- Companies
- Previous conversations
- Purchase history

### Step 4: Configure Automation

Set up automation based on your use case:
- Bot flows for common inquiries
- Automation rules for workflows
- Quick replies for frequent responses

### Step 5: Train Your Team

Train your team on:
- Using the inbox
- Managing conversations
- Creating deals/tasks
- Using templates

### Step 6: Launch and Monitor

Launch your implementation and monitor:
- Response times
- Customer satisfaction
- Automation effectiveness
- Team performance

### Step 7: Optimize

Continuously optimize based on:
- Customer feedback
- Performance metrics
- Team feedback
- Business goals

---

## Success Metrics

### Key Performance Indicators (KPIs)

**Response Metrics:**
- Average response time
- First response time
- Response rate

**Engagement Metrics:**
- Message open rate
- Click-through rate
- Conversation completion rate

**Business Metrics:**
- Conversion rate
- Customer satisfaction
- Revenue impact
- Cost savings

**Operational Metrics:**
- Automation rate
- Team efficiency
- Resolution time
- Ticket volume

---

## Best Practices

1. **Start Simple**
 - Begin with one channel
 - Focus on high-volume use cases
 - Expand gradually

2. **Automate Gradually**
 - Start with simple automation
 - Test and refine
 - Add complexity over time

3. **Monitor and Adjust**
 - Track key metrics
 - Gather feedback
 - Make data-driven decisions

4. **Train Your Team**
 - Provide comprehensive training
 - Create documentation
 - Encourage best practices

5. **Engage Customers**
 - Personalize messages
 - Respond promptly
 - Follow up consistently

---

## Related Documentation

- [Feature Fact Sheet](https://docs.connectgain.cloud/04-use-cases/business/marketing-fact-sheet.md)
- [API Documentation](https://docs.connectgain.cloud/04-use-cases/07-api/complete-api.md)
- [Automation Guide](https://docs.connectgain.cloud/04-use-cases/02-user-guide/automations.md)
- [AI Re-Engagement Fact Sheet](https://docs.connectgain.cloud/04-use-cases/business/marketing-fact-sheet.md)
- [All industry solutions on connectgain.cloud](https://connectgain.cloud/en/industries) — including [Banking](https://connectgain.cloud/en/solutions/banking), [Insurance](https://connectgain.cloud/en/solutions/insurance), [Automotive](https://connectgain.cloud/en/solutions/automotive), [Logistics](https://connectgain.cloud/en/solutions/logistics), [Telecommunications](https://connectgain.cloud/en/solutions/telecommunications), [Government](https://connectgain.cloud/en/solutions/government), [Legal](https://connectgain.cloud/en/solutions/legal), [Fitness](https://connectgain.cloud/en/solutions/fitness), [Call Center](https://connectgain.cloud/en/solutions/call-center) and [Marketing Agencies](https://connectgain.cloud/en/solutions/marketing-agencies)

---

**Last Updated:** June 2026

---

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/04-use-cases/index.md)*

---

# Car Maintenance CRM with Odoo ERP Integration – ConnectGain

Source: https://docs.connectgain.cloud/04-use-cases/car-maintenance-odoo/

# ConnectGain CRM × Odoo — Car Maintenance Shop

## Commercial Offer: Unified Customer & Workshop Management

---

## The Challenge

Car maintenance shops juggle **customer communication, appointment scheduling, invoicing, spare parts inventory, and service follow-ups** across disconnected tools. This leads to:

- Missed follow-up calls and lost repeat customers
- Manual data entry between the CRM and ERP
- No visibility into customer service history during conversations
- Delayed invoicing and payment tracking
- Inconsistent multi-channel communication (WhatsApp, phone, email)

---

## The Solution: ConnectGain + Odoo Integration

ConnectGain CRM connects directly to your Odoo ERP, creating a **single source of truth** for customer relationships and workshop operations.

```text
Customer contacts you (WhatsApp / Call / Web)
 ↓
ConnectGain captures & routes the conversation
 ↓
Agent views full service history (synced from Odoo)
 ↓
Booking created → Odoo Work Order generated
 ↓
Service completed → Invoice auto-synced
 ↓
Follow-up reminders sent automatically
```

---

## Key Features for Car Maintenance Shops

### 1. Omnichannel Customer Communication

| Channel | Use Case |
|---------|----------|
| **WhatsApp** | Appointment reminders, service updates, photo sharing (damage reports) |
| **Phone / VoIP** | Direct calls with AI-powered call logging and transcription |
| **Email** | Invoices, service reports, promotional offers |
| **Web Chat** | Website visitor booking and inquiries |

All conversations are **unified in one inbox** — no switching between apps.

### 2. Odoo-Synced Contact Profiles

Every customer profile in ConnectGain automatically syncs with Odoo, showing:

- **Vehicle details** (make, model, year, plate number)
- **Service history** (oil changes, brake replacements, inspections)
- **Open invoices & payment status**
- **Spare parts used per vehicle**
- **Warranty information**

Agents see everything in one screen during a live conversation.

### 3. Automated Appointment Booking

- Customer sends "I need an oil change" on WhatsApp
- ConnectGain AI suggests available time slots
- Booking confirmed → **Odoo Work Order auto-created**
- Customer receives confirmation + reminder (24h before)
- Workshop calendar updated in real-time

### 4. Service Workflow Automation

| Trigger | Action |
|---------|--------|
| Booking created | Create Odoo repair order + assign technician |
| Service completed in Odoo | Send WhatsApp notification to customer |
| Invoice created in Odoo | Send payment link via WhatsApp/Email |
| Payment received | Send thank-you message + request Google review |
| 6 months since last service | Auto-send maintenance reminder |
| Customer birthday | Send discount coupon |

### 5. Deal Pipeline for High-Value Services

Track upsell opportunities through ConnectGain's visual pipeline:

- **Lead** → Customer inquires about bodywork repair
- **Quoted** → Estimate sent via WhatsApp with photos
- **Approved** → Customer confirms, Odoo sales order created
- **In Progress** → Workshop updates synced to customer
- **Completed** → Invoice sent, payment collected
- **Follow-Up** → 30-day satisfaction check

### 6. AI-Powered Features

- **Auto-reply**: Answer common questions (pricing, hours, location) 24/7
- **Sentiment analysis**: Flag unhappy customers for manager attention
- **[Call intelligence](https://docs.connectgain.cloud/04-use-cases/02-user-guide/call-intelligence.md)**: Transcribe and summarize phone calls automatically
- **Smart tagging**: Auto-categorize contacts by vehicle type, service frequency

### 7. Broadcast & Campaigns

- Seasonal tire change reminders to all SUV owners
- Oil change promotions to customers overdue for service
- New service announcements (e.g., EV charging station)
- Targeted offers based on vehicle age or mileage

---

## Integration Architecture

```text
┌─────────────────┐ ┌─────────────────┐
│ ConnectGain │◄───────►│ Odoo │
│ CRM │ REST │ ERP │
│ │ API │ │
│ • Contacts │◄──sync──► • Partners │
│ • Conversations│ │ • Repair Orders│
│ • Deals │◄──sync──► • Sale Orders │
│ • Bookings │◄──sync──► • Calendar │
│ • Invoices │◄──sync──► • Invoicing │
│ • Inventory │◄──read──► • Stock │
└─────────────────┘ └─────────────────┘
 │
 ▼
┌─────────────────┐
│ Communication │
│ Channels │
│ • WhatsApp │
│ • Phone/VoIP │
│ • Email │
│ • Web Chat │
└─────────────────┘
```

---

## What the Shop Owner Gets

| Metric | Before | After ConnectGain + Odoo |
|--------|--------|--------------------------|
| Response time | 2-4 hours | < 5 minutes (AI auto-reply) |
| Missed follow-ups | ~40% | < 5% (automated reminders) |
| Manual data entry | 2 hrs/day | Near zero (auto-sync) |
| Customer retention | ~55% | ~80% (proactive engagement) |
| Review collection | Manual | Automated post-service |
| Revenue visibility | Spreadsheets | Real-time dashboard |

---

## Implementation Timeline

| Week | Milestone |
|------|-----------|
| **Week 1** | ConnectGain setup, WhatsApp Business API connection, team onboarding |
| **Week 2** | Odoo API integration, contact sync, service history import |
| **Week 3** | Automation workflows configured, AI agent trained on shop FAQ |
| **Week 4** | Go-live, monitoring, optimization |

---

## Why ConnectGain for Car Maintenance?

1. **Built for multi-channel** — Customers reach you on WhatsApp, you respond from one place
2. **Odoo-native sync** — No middleware, no Zapier, direct REST API integration
3. **Arabic & RTL support** — Full localization for MENA market
4. **AI that works** — Auto-reply, call transcription, smart reminders out of the box
5. **Affordable** — Fraction of the cost of HubSpot or Salesforce

---

## Next Steps

1. **Book a demo**: See the integration live with sample car maintenance data
2. **14-day free trial**: Connect your WhatsApp and test with real customers
3. **Go live in 4 weeks**: Full setup with Odoo sync included

**Contact**: sales@connectgain.cloud | [connectgain.cloud](https://connectgain.cloud)

---

## See also

- [Business use cases](https://docs.connectgain.cloud/04-use-cases/car-maintenance-odoo/business.md)
- [Comprehensive use cases overview](https://docs.connectgain.cloud/04-use-cases/car-maintenance-odoo/overview.md)
- [Deals & pipelines user guide](https://docs.connectgain.cloud/04-use-cases/02-user-guide/deals.md)
- [Scheduling user guide](https://docs.connectgain.cloud/04-use-cases/02-user-guide/scheduling.md)
- [Channel connection guide](https://docs.connectgain.cloud/04-use-cases/05-integrations/channels.md)

---

*ConnectGain — Where every customer conversation drives revenue.*

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/04-use-cases/index.md)*

---

# ConnectGain Feature Fact Sheet – Every Capability

Source: https://docs.connectgain.cloud/04-use-cases/marketing-fact-sheet/

# ConnectGain — Complete Marketing & Feature Fact Sheet

**Version:** 7.3.1
**Last Updated:** June 2026 (reconciled against the codebase 2026-06-28)
**Status:** Production Ready

> **This document is the single source of truth for what ConnectGain does.** Every feature, every module, every screen — all in one place. Per-feature how-to guides live in the [User Guide](https://docs.connectgain.cloud/04-use-cases/02-user-guide/README.md); this doc tells you *what exists*, those tell you *how to use it*.

---

## Features at a Glance

| Area | Feature | Detailed how-to |
|---|---|---|
| Conversations | Unified Inbox, Messages, Templates, Channels | [inbox](https://docs.connectgain.cloud/04-use-cases/02-user-guide/inbox.md) · [messages](https://docs.connectgain.cloud/04-use-cases/02-user-guide/messages.md) · [templates](https://docs.connectgain.cloud/04-use-cases/02-user-guide/templates.md) · [channels](https://docs.connectgain.cloud/04-use-cases/05-integrations/channels.md) |
| CRM | Contacts, Companies, Deals, Tasks | [contacts](https://docs.connectgain.cloud/04-use-cases/02-user-guide/contacts.md) · [companies](https://docs.connectgain.cloud/04-use-cases/02-user-guide/companies.md) · [deals](https://docs.connectgain.cloud/04-use-cases/02-user-guide/deals.md) · [tasks](https://docs.connectgain.cloud/04-use-cases/02-user-guide/tasks.md) |
| Marketing | Campaigns, Sequences, Social Media Planner | [campaigns](https://docs.connectgain.cloud/04-use-cases/02-user-guide/campaigns.md) · [sequences](https://docs.connectgain.cloud/04-use-cases/02-user-guide/sequences.md) · [social-media-planner](https://docs.connectgain.cloud/04-use-cases/02-user-guide/social-media-planner.md) |
| Automation & AI | Bot Flows, Automations, AI Re-Engagement, Reply Assistant | [bot-flows](https://docs.connectgain.cloud/04-use-cases/02-user-guide/bot-flows.md) · [automations](https://docs.connectgain.cloud/04-use-cases/02-user-guide/automations.md) · [ai-reengagement](https://docs.connectgain.cloud/04-use-cases/02-user-guide/ai-reengagement.md) · [reply-assistant use cases](https://docs.connectgain.cloud/04-use-cases/marketing-fact-sheet/reply-assistant-use-cases.md) |
| Telephony | SIP Softphone, Call Intelligence | [call-intelligence](https://docs.connectgain.cloud/04-use-cases/02-user-guide/call-intelligence.md) |
| Scheduling | Calendar, Bookings, Zoom sync | [scheduling](https://docs.connectgain.cloud/04-use-cases/02-user-guide/scheduling.md) · [bookings](https://docs.connectgain.cloud/04-use-cases/02-user-guide/bookings.md) |
| Insights | Dashboard, Analytics, Sales Report | [dashboard](https://docs.connectgain.cloud/04-use-cases/02-user-guide/dashboard.md) · [analytics](https://docs.connectgain.cloud/04-use-cases/02-user-guide/analytics.md) · [sales-report](https://docs.connectgain.cloud/04-use-cases/02-user-guide/sales-report.md) |
| Operations | Projects, Support Tickets, Attendance | [projects](https://docs.connectgain.cloud/04-use-cases/02-user-guide/projects.md) · [support-tickets](https://docs.connectgain.cloud/04-use-cases/02-user-guide/support-tickets.md) · [attendance](https://docs.connectgain.cloud/04-use-cases/02-user-guide/attendance.md) |
| Admin | Settings, Team, Permissions | [settings](https://docs.connectgain.cloud/04-use-cases/03-admin-guide/settings.md) · [team](https://docs.connectgain.cloud/04-use-cases/03-admin-guide/team.md) |
| Developer | API, Webhooks, Architecture | [API](https://docs.connectgain.cloud/04-use-cases/07-api/README.md) · [Webhooks](https://docs.connectgain.cloud/04-use-cases/08-webhooks/README.md) |

---

## Table of Contents

1. [Executive Summary](#executive-summary)
2. [Core Platform Features](#core-platform-features)
3. [Screen-by-Screen Feature Breakdown](#screen-by-screen-feature-breakdown)
4. [Supported Channels](#supported-channels)
5. [CRM Capabilities](#crm-capabilities)
6. [Scheduling System](#scheduling-system)
7. [Automation & Workflows](#automation--workflows)
8. [AI-Powered Features](#ai-powered-features)
9. [Analytics & Reporting](#analytics--reporting)
10. [Team Collaboration](#team-collaboration)
11. [Integration Capabilities](#integration-capabilities)
12. [Security & Compliance](#security--compliance)
13. [Industry Use Cases](#industry-use-cases)

---

## Executive Summary

ConnectGain is a comprehensive customer engagement and CRM platform that unifies multiple messaging channels into a single, powerful interface. Designed for businesses of all sizes, ConnectGain combines customer communication, sales pipeline management, automation, AI-powered insights, and analytics into one seamless platform.

### Key Value Propositions

- **Unified Inbox** - Manage all customer conversations from WhatsApp, Messenger, Instagram, Telegram, Email, SMS, LinkedIn, Shopify Inbox, and Web Push in one place
- **Complete CRM** - Full-featured customer relationship management with contacts, companies, deals, tasks, and projects
- **Scheduling System** - Calendly-like appointment scheduling with Google Calendar integration, Zoom integration, custom branding per event type, and automated booking management
- **Attendance Tracking** - Monitor agent attendance, clock in/out times, online status, and attendance history with real-time tracking
- **Sales Pipeline Reports** - Comprehensive sales reports with stage-by-stage analysis, deal value tracking, and CSV export capabilities
- **Bookings Management** - Centralized booking management system for appointments, meetings, and events with Google Calendar sync
- **Deal Ownership Tracking** - Complete audit trail of deal ownership changes with duration tracking and automatic reassignment
- **Deal SLA Monitoring** - Deal-level SLA timers and escalation, provided by the SLA Monitoring add-on
- **AI-Powered Customer Bot** - Intelligent WhatsApp chatbot that handles customer inquiries using RAG-based knowledge base, with automatic handoff to human agents
- **AI Conversation Analysis** - Automated interest scoring, sentiment analysis, and conversation insights
- **AI Conversation Summaries** - Automated AI summaries of conversations, generated by a background scanner and configurable from the "AI Summaries" settings panel
- **Contact Enrichment Tools** - Enrich contacts with additional data, configured from the "Enrichment Tools" settings panel
- **AI Re-Engagement** - Automatically re-open Messenger and Instagram conversations before Meta's 24-hour window closes using AI-generated personalised nudges (paid add-on, BYOK available)
- **Reply Assistant** - On-demand, sales-style reply suggestions for inbox agents, grounded in the org's knowledge base and product catalog and tuned to the org's industry (B2B SaaS, Ecommerce, Tourism). Works with zero setup beyond picking an industry (paid add-on, BYOK available)
- **Call Tracking & Recording** - Native mobile call integration with automatic logging, outcome tracking, manual recording upload, and call history in contact timelines
- **AI Call Intelligence** - Automated transcription with **speaker diarization** (agent/customer, broker/client) for code-switched Arabic/English with exact number/price and ticker fidelity; **conversation interaction stats** (talk ratio, longest monologue, interactivity, agent question rate, patience), sentiment analysis with a **per-call sentiment timeline**, AI summaries, action item extraction, structured topic tracking, keyword detection, and call classification. Powered by multi-vendor AI **for call analysis** — ConnectGain AI (Gemini 2.5 Flash) by default, with optional OpenAI, Anthropic Claude, Google Gemini, Ollama, or GLM/Z.ai, or BYOK. (Multi-vendor selection applies to the call-analysis pipeline only; all other AI features run on Gemini 2.5 Flash via the Lovable Gateway or BYOK Gemini.)
- **Conversation Trackers** - Track competitors, pricing, objections, features, and custom topics across every call — both **keyword** (exact phrase) and **smart AI concept** detection — with per-call hits and a cross-call Tracker Trends report
- **Trade-Call Compliance Surveillance** - AI flags market-abuse and conduct risks on broker–client calls (insider info, manipulation, front-running, guaranteed returns, pressure selling, unauthorized trading, missing disclosure, suitability) with severity, speaker, matched phrase and confidence; tracks instruction-vs-recommendation, disclosure coverage, and a 7-year retention horizon
- **Agent Call-Handling QA Scorecard** - Objective per-call scoring of how well the agent handled the client across five dimensions (professionalism, communication, client-needs handling, market/product knowledge, compliance) with strengths and coaching points
- **Coaching Scorecards** - Manager scorecard templates with manual scoring or **AI-suggested scores** generated from the call transcript
- **Topic & Keyword Trend Tracking** - Structured, normalized topics with category and per-topic sentiment, language detection, top/emerging topics, and "topics driving negative sentiment" reporting
- **Manager Agent-Level KPI Reporting** - Admin-gated, sortable per-agent view of activity, trading, quality and compliance KPIs with per-agent drill-down
- **Call → Deal Revenue Intelligence** - Link calls to deals and roll call signals (avg sentiment, resolution, talk time, trackers, recent calls) up onto the deal record
- **Call Intelligence Analytics** - Comprehensive analytics dashboard with call volume charts, sentiment distribution, agent performance leaderboard, topic & tracker trends, minutes quota tracking, and AI token usage monitoring
- **Email Integration** - Full email sending and receiving capabilities integrated with unified inbox
- **Interest Analysis Dashboard** - Visual breakdown of hot, warm, and cold leads based on AI conversation analysis
- **Agent Performance Metrics** - Comprehensive agent performance tracking with deal metrics, response times, and productivity scores
- **Sequences (Drip Campaigns)** - Multi-channel automated message sequences with Email, [WhatsApp Lite](https://docs.connectgain.cloud/04-use-cases/05-integrations/whatsapp-lite-api.md), and WhatsApp Cloud support, including AI-generated draft content for step messages in the Sequences builder
- **Social Media Planner** - Schedule and publish content across Facebook, Instagram, and LinkedIn with a visual calendar, 11 content formats, and automated failure notifications
- **Lists (Tag Management)** - Visual tag-based contact segmentation and management
- **Task Automation** - Automated task distribution using round-robin, workload-based, and skills-matching assignment strategies
- **Public Sharing** - Shareable links for deals, contacts, companies, tasks, and pipeline reports with password protection and access tracking
- **Visual Automation** - Drag-and-drop bot flow builder with 40+ node types and rule-based automations
- **Real-Time Analytics** - Comprehensive dashboards with customizable widgets and performance metrics
- **Team Collaboration** - Role-based access control with granular permissions, assignments, availability management, and team collaboration
- **Web Push Notifications** - Background push notifications for Android and iOS (PWA) to stay connected even when app is closed
- **Cross-Channel Response** - Receive messages via one channel and respond via another (e.g., receive [WhatsApp Cloud](https://docs.connectgain.cloud/04-use-cases/05-integrations/whatsapp-cloud-system-user.md), respond via WhatsApp Lite)
- **Internal AI Assistant** - In-app AI-powered assistant with voice input for platform management and natural language commands (admin only)
- **BYOK AI** - Bring Your Own Gemini Key for all AI features (chatbots, classification, translations, re-engagement, call analysis) — free to enable, full data control
- **Enterprise Ready** - Scalable, secure, and compliant platform with API access and webhook support

---

## Core Platform Features

### Platform Architecture

- **Cloud-Based SaaS** - Fully hosted, no infrastructure management required
- **Real-Time Updates** - Live synchronization across all devices and team members
- **Mobile Responsive** - Full functionality on desktop, tablet, and mobile devices
- **Multi-Language Support** - Internationalization (i18n) ready
- **API-First Design** - Complete REST API and webhook support
- **PWA Support** - Progressive Web App capabilities

### User Experience

- **Modern UI/UX** - Clean, intuitive interface built with shadcn/ui components
- **Dark Mode** - Full dark mode support
- **Keyboard Shortcuts** - Power user productivity features
- **Contextual Help** - In-app help hotspots and tooltips
- **Onboarding Tour** - Guided setup for new users
- **Customizable Dashboard** - Drag-and-drop widgets, custom metrics

---

## Screen-by-Screen Feature Breakdown

### 1. Dashboard (`/dashboard`)

**Purpose:** Central command center providing real-time insights and quick access to key metrics.

#### Key Features:

**Communication Metrics Widgets:**
- **Incoming Messages** - Real-time count of messages received across all channels
 - Channel breakdown (WhatsApp Lite, WhatsApp Cloud, Facebook Messenger, Instagram)
 - Click-through to channel settings
 - Date range filtering (Today, Yesterday, This Week, This Month, Custom Range)
 - Comparison with previous period
 - Percentage change indicators

- **Ongoing Conversations** - Active conversation count
 - Real-time updates
 - Period-over-period comparison
 - Visual trend indicators

- **Unanswered Conversations** - Conversations awaiting response
 - SLA tracking
 - Priority indicators
 - Quick action buttons

- **Median Reply Time** - Average response time across team
 - Performance benchmarking
 - Historical trends

- **Longest Awaiting Reply** - Oldest unresponded conversation
 - Urgency indicators
 - Direct link to conversation

**Sales & Deals Widgets:**
- **Won Leads** - Successfully closed deals
 - Value tracking
 - Period comparison
 - Conversion metrics

- **Active Leads** - Deals in pipeline
 - Stage breakdown
 - Value aggregation

- **Lead Sources** - Origin tracking for leads
 - Channel attribution
 - Source performance

- **Active Deals** - Current pipeline value
 - Deal count
 - Total value

**Tasks & Contacts Widgets:**
- **Tasks Overview** - Task completion metrics
 - Overdue tasks count
 - Completion rate
 - Priority breakdown

- **Total Companies** - Company database size
 - Growth tracking

- **Total Contacts** - Contact database size
 - Growth metrics
 - Period comparison

**Custom Widgets:**
- **Create Custom Metrics** - Build personalized widgets
 - Query any database table
 - Aggregation options (Count, Sum, Average, Min, Max)
 - Format options (Number, Currency, Percentage, Time Duration)
 - Custom positioning
 - Show/hide controls

**Performance Charts:**
- **4-Week Performance Overview** - Visual trend analysis
 - Conversations over time
 - Deals closed tracking
 - New contacts growth
 - Interactive charts

**Recent Activity Feed:**
- **Live Activity Stream** - Latest platform events
 - New messages
 - Deal updates
 - New contacts
 - Clickable items for quick navigation
 - Time-ago indicators

**Dashboard Customization:**
- **Drag-and-Drop Widgets** - Reorder predefined widgets
- **Hide/Show Widgets** - Customize visible metrics
- **Date Range Selection** - Flexible time period analysis
 - Today, Yesterday, This Week, This Month
 - Custom date range picker
 - Saved preferences
- **Widget Management** - Add, edit, delete custom widgets

---

### 2. Inbox (`/inbox`)

**Purpose:** Unified messaging center for all customer conversations across all channels.

#### Key Features:

**Unified Conversation List:**
- **Multi-Channel View** - All conversations in one list
 - WhatsApp (Lite & Cloud)
 - Facebook Messenger
 - Instagram Direct Messages
 - Telegram
 - TikTok
 - LinkedIn
 - Shopify Inbox
 - Email
 - *(SMS is broadcast/sequence-only and is intentionally excluded from the inbox)*
- **Real-Time Updates** - Live conversation sync
- **Unread Indicators** - Visual badges for unread messages
- **Last Message Preview** - Quick context without opening
- **Contact Information** - Name, avatar, channel badge
- **Status Indicators** - Open/Closed conversation status
- **Channel Badges** - Visual channel identification
- **Sorting Options:**
 - Most recent first (default)
 - Unread first
 - Assigned to me
 - Unassigned
- **Filtering Options:**
 - By channel type
 - By status (Open/Closed)
 - By assignee
 - By tags
 - By date range
- **Search Functionality** - Find conversations quickly
- **Bulk Actions** - Clear all conversations
- **Refresh Control** - Manual refresh button
- **Online/Offline Status** - Connection indicator

**Message Thread View:**
- **Complete Message History** - Full conversation timeline
- **Real-Time Message Delivery** - Instant message updates
- **Message Status Tracking:**
 - Sent ✓
 - Delivered ✓✓
 - Read ✓✓ (blue)
 - Failed ✗
 - Pending ⏳
- **Message Types Support:**
 - Text messages
 - Images (JPG, PNG, GIF, WebP)
 - Videos (MP4, MOV, AVI)
 - Audio files (MP3, WAV, OGG)
 - Documents (PDF, DOCX, XLSX, etc.)
 - Location (inbound rendering)
 - Contact cards / vCard (inbound rendering)
- **Message Timestamps** - Precise time tracking
- **Sender Information** - Contact details and channel
- **Message Actions:**
 - Reply
 - Delete
 - Copy message text
 - Download attachments
 - View full details

**Message Composer:**
- **Rich Text Input** - Full message composition
- **Media Attachments** - Upload images, videos, documents
- **Quick Reply Templates** - Pre-written responses
- **Emoji Support** - Full emoji picker
- **Channel-Specific Features:**
 - WhatsApp: Templates, media, location
 - Messenger: Quick replies, buttons
 - Instagram: Stories, media
 - Telegram: Stickers, polls

**Contact Panel:**
- **Contact Details** - Full contact information
 - Name, email, phone
 - Company association
 - Tags
 - Custom fields
- **Contact History** - All past interactions
- **Related Deals** - Associated sales opportunities
- **Related Tasks** - Assigned tasks
- **Related Notes** - Internal notes
- **Quick Actions:**
 - Send message
 - Create deal
 - Create task
 - Add note
 - Edit contact
 - View full profile

**Conversation Management:**
- **Assign Conversations** - Assign to team members
- **Status Management** - Open/Close conversations
- **Add Tags** - Organize conversations
- **Add Notes** - Internal notes
- **Create Deal** - Convert conversation to deal
- **Create Task** - Create follow-up task
- **Delete Conversation** - Remove conversation
- **Conversation Search** - Find specific conversations

**Mobile Optimization:**
- **Responsive Layout** - Optimized for mobile devices
- **Touch-Friendly** - Mobile-optimized interactions
- **Sheet Panels** - Slide-out panels for mobile
- **Swipe Actions** - Gesture-based controls

---

### 3. Contacts (`/contacts`)

**Purpose:** Comprehensive contact management with advanced filtering, search, and organization capabilities.

#### Key Features:

**Contact Management:**
- **Create Contacts** - Add new contacts manually
 - First name, last name
 - Multiple phone numbers
 - Multiple email addresses
 - Company association
 - Tags
 - Custom fields
 - Opt-in status
 - Notes
 - Create deal option during contact creation
- **Edit Contacts** - Update contact information
- **Delete Contacts** - Remove contacts (with cascade protection)
- **Bulk Operations:**
 - Bulk import from CSV
 - Bulk export to CSV
 - Bulk delete
 - Bulk tag assignment
- **Contact Details View** - Comprehensive contact profile
 - All contact information
 - Communication history
 - Related deals
 - Related tasks
 - Notes timeline
 - Activity log

**Search & Filtering:**
- **Advanced Search** - Search by:
 - Name (first, last, full)
 - Phone number (partial matching)
 - Email address
 - Company name
 - Tags
 - Custom fields
- **Tag Filtering** - Filter by contact tags
 - All tags dropdown
 - Multiple tag selection
- **Deals Filtering** - Filter by open deals count:
 - No open deals
 - 1-3 open deals
 - 4-10 open deals
 - 10+ open deals
- **Sorting Options:**
 - Alphabetical (A-Z, Z-A)
 - Newest added (newest first, oldest first)
- **Real-Time Search** - Instant search results

**View Modes:**
- **Grid View** - Card-based layout
 - Contact cards with key info
 - Quick action buttons
 - Visual tags
 - Company badges
- **Table View** - Spreadsheet-style layout
 - Sortable columns
 - Bulk selection
 - Inline actions
 - Export capabilities

**Contact Import:**
- **CSV Import** - Bulk import contacts
 - Column mapping
 - Data validation
 - Duplicate detection
 - Import progress tracking
 - Error reporting
- **HubSpot Import** - CSV import using a HubSpot-export column mapping (no direct HubSpot API/OAuth connection; routed through the standard `import-contacts` function)
- **Duplicate Detection** - Find and merge duplicates
 - Automatic duplicate detection
 - Manual merge options
 - Merge conflict resolution

**Contact Organization:**
- **Tags System** - Flexible tagging
 - Create custom tags
 - Multiple tags per contact
 - Tag-based filtering
 - Auto-tagging by country
 - Tag management
- **Company Association** - Link contacts to companies
 - Company selection
 - Company creation from contact
 - Company details view
- **Custom Fields** - Extend contact data
 - Text fields
 - Number fields
 - Date fields
 - Dropdown fields

**Contact Actions:**
- **Quick Actions:**
 - View contact details
 - Edit contact
 - Delete contact
 - Send message
 - Make phone call
 - Open WhatsApp
 - Copy phone number
 - Copy email address
- **Bulk Actions:**
 - Export selected contacts
 - Delete selected contacts
 - Tag selected contacts
 - Assign to team member

**Contact Analytics:**
- **Deal Count** - Number of open deals per contact
- **Notes Count** - Number of notes per contact
- **Activity Timeline** - Recent activity tracking
- **Engagement Metrics** - Message frequency, last contact date

**Pagination:**
- **50 Contacts Per Page** - Efficient loading
- **Page Navigation** - Easy browsing
- **Total Count Display** - See total contacts

**Auto-Tagging:**
- **Country-Based Tagging** - Automatically tag contacts by country
 - Phone number analysis
 - Country code detection
 - Batch processing
 - Progress tracking
 - Completion notifications

---

### 4. Companies (`/companies`)

**Purpose:** Manage company relationships and B2B accounts.

#### Key Features:

**Company Management:**
- **Create Companies** - Add new companies
 - Company name
 - Industry
 - Website
 - Address (street, city, state, postal code, country)
 - Phone numbers
 - Email addresses
 - Company size
 - Annual revenue
 - Tags
 - Notes
 - Create deal option during company creation
- **Edit Companies** - Update company information
- **Delete Companies** - Remove companies (contacts preserved)
- **Company Details View** - Comprehensive company profile
 - All company information
 - Associated contacts
 - Related deals
 - Activity timeline
 - Notes

**Search & Filtering:**
- **Search Companies** - Search by:
 - Company name
 - Industry
 - Website
 - Country
- **Country Filtering** - Filter by country
 - All countries dropdown
 - "No Country" option
- **Sorting Options:**
 - Alphabetical (A-Z, Z-A)
 - Newest added (newest first, oldest first)
- **Real-Time Search** - Instant search results

**View Modes:**
- **Grid View** - Card-based layout
 - Company cards with key info
 - Quick action buttons
 - Visual tags
 - Country badges
- **Table View** - Spreadsheet-style layout
 - Sortable columns
 - Bulk selection
 - Inline actions
 - Export capabilities

**Company Import:**
- **CSV Import** - Bulk import companies
 - Column mapping
 - Data validation
 - Duplicate detection
 - Import progress tracking

**Company Organization:**
- **Tags System** - Flexible tagging
 - Create custom tags
 - Multiple tags per company
 - Tag-based filtering
- **Contact Association** - Link contacts to companies
 - Multiple contacts per company
 - Contact management from company view
- **Deal Association** - Track deals by company
 - Company-level deal tracking
 - Revenue aggregation

**Duplicate Management:**
- **Duplicate Detection** - Find and merge duplicates
 - Automatic duplicate detection
 - Manual merge options
 - Merge conflict resolution

**Pagination:**
- **50 Companies Per Page** - Efficient loading
- **Page Navigation** - Easy browsing
- **Total Count Display** - See total companies

---

### 5. Deals (`/deals`)

**Purpose:** Sales pipeline management with visual kanban board and deal tracking.

#### Key Features:

**Deal Pipeline Management:**
- **Multiple Pipelines** - Create custom sales pipelines
 - Pipeline creation
 - Pipeline editing
 - Pipeline deletion
 - Set default pipeline
 - Pipeline switching
- **Custom Stages** - Define pipeline stages
 - Stage name
 - Stage color coding
 - Stage order
 - Default stages: Deal, Qualified, Proposal, Negotiation, Closed Won, Closed Lost
- **Visual Kanban Board** - Drag-and-drop deal management
 - Column-based layout
 - Drag deals between stages
 - Visual stage indicators
 - Deal count per stage
 - Stage value totals

**Deal Management:**
- **Create Deals** - Add new deals
 - Deal title
 - Description
 - Contact association
 - Company association
 - Pipeline selection
 - Initial stage
 - Deal value (currency)
 - Probability percentage
 - Owner assignment
 - Tags
 - Expected close date
 - Custom fields
- **Edit Deals** - Update deal information
 - All deal fields editable
 - Stage changes tracked
 - Activity timeline
- **Delete Deals** - Remove deals
- **Deal Details View** - Comprehensive deal profile
 - All deal information
 - Contact/company details
 - Activity timeline
 - Notes
 - Attachments
 - Related tasks
 - Stage history

**Deal Filtering:**
- **Value Range Filter** - Filter by deal value
 - Minimum value
 - Maximum value
 - Validation (max > min)
- **Owner Filter** - Filter by deal owner
 - All assignees
 - Specific team member
- **Tag Filtering** - Filter by deal tags
 - Multiple tag selection
 - Tag badges
- **Pipeline Filtering** - Filter by pipeline
 - Pipeline selector
 - Default pipeline

**Deal Tracking:**
- **Deal Value Tracking** - Monetary value tracking
 - Currency support
 - Value aggregation
 - Stage value totals
- **Probability Tracking** - Win probability percentage
 - Stage-based defaults
 - Manual adjustment
- **Expected Close Date** - Timeline tracking
 - Date picker
 - Overdue indicators
- **Deal Activity** - Complete activity log
 - Stage changes
 - Value updates
 - Owner changes
 - Notes added
 - Tasks created

**Deal Actions:**
- **Quick Actions:**
 - View deal details
 - Edit deal
 - Delete deal
 - Change stage (drag-and-drop)
 - Assign owner
 - Add tags
 - Add notes
 - Create task
- **Bulk Actions:**
 - Bulk stage change
 - Bulk owner assignment
 - Bulk tag assignment
 - Bulk delete

**Call Intelligence on Deals:**
- **Linked Call Signals** - Call Intelligence rollup on the deal's activity tab
 - Avg sentiment, avg resolution, total talk time, and last-call date across linked calls
 - Aggregated conversation tracker mentions (competitors, pricing, objections)
 - Recent linked calls with direction, agent, duration, and sentiment
 - Calls are linked from the Call Intelligence detail dialog

**Deal Ownership Tracking:**
- **Ownership History** - Complete audit trail
 - All ownership changes logged
 - Duration with each owner tracked
 - Change timestamps
 - Change reasons (Initial assignment, Reassigned, Unassigned, Auto-reassigned)
 - Changed by user tracking
- **Ownership History View:**
 - Timeline of all ownership changes
 - Duration calculations
 - Owner information display
 - Real-time updates
- **Automatic Reassignment:**
 - Round-robin assignment for inactive deals
 - Configurable inactivity threshold (days)
 - Only reassigns to active users
 - Automatic logging of reassignments
- **Performance Metrics:**
 - Average time deals spend with each owner
 - Deal handling time per team member
 - Ownership change frequency
 - Bottleneck identification

**Pipeline Analytics:**
- **Stage Distribution** - Visual breakdown
 - Deal count per stage
 - Value per stage
 - Conversion funnel
- **Pipeline Performance** - Performance metrics
 - Average deal value
 - Average deal duration
 - Win rate
 - Loss rate

**Deal Cards:**
- **Visual Deal Cards** - Information-rich cards
 - Deal title
 - Contact/company name
 - Deal value
 - Owner avatar
 - Tags
 - Stage indicator
 - Quick actions

---

### 6. Tasks (`/tasks`)

**Purpose:** Task management with calendar view and priority tracking.

#### Key Features:

**Task Management:**
- **Create Tasks** - Add new tasks
 - Task title
 - Description
 - Priority (Low, Medium, High)
 - Due date and time
 - Assignee (team member)
 - Related contact (optional)
 - Related deal (optional)
 - Tags
- **Edit Tasks** - Update task information
- **Delete Tasks** - Remove tasks
- **Complete Tasks** - Mark tasks as done
 - Toggle completion status
 - Completion timestamp
- **Task Details View** - Comprehensive task profile
 - All task information
 - Related contact/deal
 - Activity timeline
 - Notes

**View Modes:**
- **List View** - Organized task list
 - Grouped by status:
 - Overdue tasks (red indicator)
 - Today's tasks
 - Upcoming tasks
 - Tasks without due date
 - Completed tasks
 - Task cards with key info
 - Quick action buttons
- **Calendar View** - Visual calendar layout
 - Monthly calendar
 - Task placement on dates
 - Color-coded priorities
 - Click to view details
 - Drag-and-drop rescheduling

**Task Filtering:**
- **Status Filter** - Filter by completion status
 - All tasks
 - Pending
 - Completed
 - Overdue
- **Priority Filter** - Filter by priority
 - All priorities
 - High priority
 - Medium priority
 - Low priority
- **Assignee Filter** - Filter by assignee
 - All assignees
 - Assigned to me
 - Unassigned
 - Specific team member
- **Search** - Search tasks by title or description

**Task Organization:**
- **Priority Levels** - Three priority levels
 - High (red indicator)
 - Medium (yellow indicator)
 - Low (green indicator)
- **Due Date Management** - Date and time tracking
 - Date picker
 - Time selection
 - Overdue indicators
 - Today indicators
- **Task Grouping** - Automatic organization
 - By due date
 - By status
 - By priority
 - By assignee

**Task Actions:**
- **Quick Actions:**
 - View task details
 - Edit task
 - Delete task
 - Toggle completion
 - Change priority
 - Reschedule
 - Reassign
- **Bulk Actions:**
 - Bulk complete
 - Bulk delete
 - Bulk reassign
 - Bulk priority change

**Task Analytics:**
- **Completion Rate** - Track task completion
 - Overall completion percentage
 - Per-assignee completion
 - Per-priority completion
- **Overdue Tracking** - Monitor overdue tasks
 - Overdue count
 - Overdue duration
- **Productivity Metrics** - Team productivity insights

**Pagination:**
- **50 Tasks Per Page** - Efficient loading
- **Page Navigation** - Easy browsing

---

### 7. Projects (`/projects`)

**Purpose:** Project management with timeline view and milestone tracking.

#### Key Features:

**Project Management:**
- **Create Projects** - Add new projects
 - Project name
 - Description
 - Start date
 - End date
 - Status (Planning, In Progress, Completed, Delayed, Cancelled)
 - Project owner
 - Team members
 - Milestones
 - Deliverables
- **Edit Projects** - Update project information
- **Delete Projects** - Remove projects
- **Project Details View** - Comprehensive project profile
 - All project information
 - Timeline view
 - Milestones
 - Deliverables
 - Team members
 - Activity log
 - Notes

**View Modes:**
- **Grid View** - Card-based layout
 - Project cards with key info
 - Status indicators
 - Progress bars
 - Quick action buttons
- **Timeline View** - Visual timeline layout
 - Gantt-style timeline
 - Project duration visualization
 - Milestone markers
 - Dependency lines
 - Interactive timeline

**Project Status Tracking:**
- **Status Types:**
 - Planning (blue)
 - In Progress (green)
 - Completed (gray)
 - Delayed (red)
 - Cancelled (black)
- **Status Indicators** - Visual status badges
- **Status Transitions** - Change project status
- **Status History** - Track status changes

**Project Statistics:**
- **Active Projects** - Count of in-progress projects
- **Delayed Projects** - Count of delayed projects
- **Completed Projects** - Count of completed projects
- **Visual Cards** - Quick stats display

**Project Organization:**
- **Milestones** - Track project milestones
 - Milestone name
 - Target date
 - Status
 - Dependencies
- **Deliverables** - Track project deliverables
 - Deliverable name
 - Due date
 - Status
 - Assignee
- **Team Assignment** - Assign team members
 - Multiple team members
 - Role assignment
 - Responsibility tracking

**Project Actions:**
- **Quick Actions:**
 - View project details
 - Edit project
 - Delete project
 - Change status
 - Add milestone
 - Add deliverable
 - Assign team member
- **Bulk Actions:**
 - Bulk status change
 - Bulk team assignment

**Pagination:**
- **50 Projects Per Page** - Efficient loading
- **Page Navigation** - Easy browsing

**Public Project Timeline:**
- **Shareable Links** - Public project timelines
 - Generate shareable URL
 - Public view (no login required)
 - Read-only access
 - Client-friendly view

---

### 8. Flows (`/flows`)

**Purpose:** Visual bot flow builder for creating conversational chatbots and automation workflows.

> **Full respond.io Workflows parity (+ more).** ConnectGain's flow builder now matches every node, trigger, and use case offered by respond.io — and layers its own deals, tasks, RAG, ElevenLabs voice, multi-LLM, and cross-turn merge capabilities on top. Highlights added: **Jump To**, **Date & Time** (business-hours branching), **Sub-flow** (trigger another workflow), **Google Sheets** (append row), **Update Lifecycle**, **Close/Open Conversation**, **Add Comment**, **Add/Remove Tag**, a richer **Branch** operator set with AND/OR, plus triggers for **Tag Updated**, **Field Updated**, **Lifecycle Updated**, **New Comment**, **Call Ended**, **Broadcast Response**, and **Manual Shortcut** (agent-launched from the inbox).

#### Key Features:

**Flow Builder:**
- **Visual Flow Editor** - Drag-and-drop interface
 - Node-based design
 - Connection lines
 - Zoom and pan
 - Grid alignment
 - Snap-to-grid
- **Flow Management:**
 - Create new flows
 - Edit existing flows
 - Delete flows
 - Duplicate flows
 - Archive flows
 - Version control

**Flow Nodes:**
- **Trigger Node** - Start of flow
 - Message received trigger
 - Keyword trigger
 - Time-based trigger
 - Event trigger
- **Send Message Node** - Send messages
 - Text messages
 - Template messages
 - Variable substitution
 - Media attachments
- **Collect Input Node** - Gather user input
 - Text input
 - Number input
 - Date input
 - Choice selection
 - Validation rules
- **Condition Node** - Conditional logic
 - If/else branches
 - Multiple conditions
 - Comparison operators
 - Variable comparisons
- **Switch Node** - Multi-way branching
 - Multiple paths
 - Case matching
 - Default case
- **Delay Node** - Add delays
 - Time-based delays
 - Duration selection
 - Conditional delays
- **Create Deal Node** - Create deals from flow
 - Deal title
 - Deal value
 - Pipeline selection
 - Stage assignment
- **Update Deal Node** - Update existing deals
 - Stage changes
 - Value updates
 - Field updates
- **Create Task Node** - Create tasks from flow
 - Task title
 - Priority
 - Assignee
 - Due date
- **Auto Assign Task Node** - Auto-assign tasks
 - Round-robin assignment
 - Availability-based assignment
- **Assign Conversation Node** - Assign conversations
 - Team member assignment
 - Round-robin assignment
- **Add Tag Node** - Add tags to contacts
 - Tag selection
 - Multiple tags
- **Update Contact Node** - Update contact information
 - Field updates
 - Custom field updates
- **Get Variable Node** - Retrieve variables
 - Variable storage
 - Variable retrieval
- **Set Variable Node** - Store variables
 - Variable assignment
 - Variable types
- **Transform Node** - Data transformation
 - String manipulation
 - Number formatting
 - Date formatting
- **Database Query Node** - Query database
 - Custom queries
 - Result processing
- **HTTP Request Node** - External API calls
 - GET, POST, PUT, DELETE
 - Headers configuration
 - Body configuration
 - Response handling
- **AI Response Node** - AI-powered responses
 - AI integration
 - Context-aware responses
- **Error Handler Node** - Error handling
 - Error catching
 - Error messages
 - Fallback actions
- **Handoff Node** - Transfer to human agent
 - Agent assignment
 - Context transfer
- **Loop Node** - Iteration
 - For loops
 - While loops
 - Loop conditions
- **End Node** - Flow termination
 - Flow completion
 - Final actions
- **Close / Open Conversation Nodes** - mark a conversation closed or reopen it
- **Add Comment Node** - leave an internal note on the contact timeline ({{variables}} supported)
- **Jump To Node** - redirect execution to any node (loops, skip-ahead, reusable sections)
- **Date & Time Node** - branch on business-hours windows in any timezone (In hours / Out)
- **Sub-flow Node** - trigger another published flow, optionally passing variables
- **Google Sheets Node** - append a row to a Google Sheet (uses the org's connected Google account)
- **Update Lifecycle Node** - move the contact to a lifecycle stage and fire a Lifecycle Updated event
- **Enhanced Branch logic** - equals/not-equals, contains/not-contains, starts/ends with, regex, >, >=, <, <=, is empty/not empty, with **Match ALL (AND)** or **Match ANY (OR)**

**Flow Triggers:**
- Message Received / Sent, Conversation Created / Assigned / Status Changed
- Contact Created / Updated / Assigned, **Tag Updated**, **Field Updated** (per-field watch), **Lifecycle Updated**
- Deal Created / Stage Changed / Updated / Assigned, Task Created / Updated / Completed / Overdue
- **New Comment**, **Call Ended**, **Broadcast Response** (campaign reply), **Manual Shortcut** (agent-launched), Incoming Webhook, Zoom Recording Completed

**Inbox Shortcuts:**
- A ⚡ Shortcuts menu in the conversation header lets agents launch any Manual Shortcut flow for the current conversation on demand

**Multilingual Quick Replies:**
- A single **Quick Reply** node holds per-language **message bodies and button labels**, auto-selected at send time from the customer's `{{lang}}` / `{{language}}` variable — one node answers every language, no per-language branching
- Missing translations fall back to the Default content per-string; `{{variables}}` interpolate inside every language (and now inside button labels too)
- **Send Message** template/freeform localization via `localizedBodies` + `templateNameBase` (`__lang` suffix)
- **Fully backward compatible** — flows built before localization keep sending their single base text unchanged

**Reliability:**
- Deploy now **surfaces n8n activation failures** instead of silently marking a flow published — a workflow that n8n can't activate (e.g. an AI node with no LLM key) returns a clear, actionable error rather than a dead trigger
- AI Agent nodes are **guarded against missing LLM keys** at deploy time (fails fast with the exact node/reason)

**Flow Configuration:**
- **Flow Settings** - Configure flow properties
 - Flow name
 - Description
 - Status (Draft, Published, Archived)
 - Version tracking
- **Node Configuration** - Configure individual nodes
 - Node properties
 - Validation rules
 - Error handling
- **Connection Management** - Manage node connections
 - Add connections
 - Remove connections
 - Conditional connections

**Flow Testing:**
- **Test Mode** - Test flows before publishing
 - Simulate conversations
 - Debug mode
 - Step-through execution
 - Variable inspection
- **Flow Validation** - Validate flow logic
 - Error detection
 - Warning messages
 - Best practice suggestions

**Flow Publishing:**
- **Publish Flows** - Make flows active
 - Publish to production
 - Version management
 - Rollback capability
- **Flow Status:**
 - Draft - In development
 - Published - Active and running
 - Archived - Disabled
- **Unpublish Flows** - Disable flows
 - Temporary disable
 - Permanent archive

**Flow Analytics:**
- **Flow Performance** - Track flow metrics
 - Execution count
 - Success rate
 - Average completion time
 - Drop-off points
- **Node Analytics** - Individual node metrics
 - Node execution count
 - Success/failure rates
 - Average processing time

**Pagination:**
- **50 Flows Per Page** - Efficient loading
- **Page Navigation** - Easy browsing

---

### 9. Automations (`/automations`)

**Purpose:** Rule-based automation system for triggering actions based on events and conditions.

#### Key Features:

**Automation Rules:**
- **Create Automations** - Build automation rules
 - Rule name
 - Description
 - Trigger event
 - Conditions
 - Actions
 - Active/inactive status
- **Edit Automations** - Update automation rules
- **Delete Automations** - Remove automation rules
- **Enable/Disable** - Toggle automation status
 - Active automations run automatically
 - Inactive automations are paused

**Trigger Events:**
- **Message Events:**
 - Message received
 - Message sent
 - Message failed
- **Contact Events:**
 - Contact created
 - Contact updated
 - Contact assigned
- **Deal Events:**
 - Deal created
 - Deal updated
 - Deal stage changed
 - Deal assigned
- **Conversation Events:**
 - Conversation created
 - Conversation assigned
 - Conversation status changed
- **Task Events:**
 - Task created
 - Task completed
 - Task overdue

**Conditions:**
- **Field Conditions** - Check field values
 - Equals
 - Contains
 - Starts with
 - Ends with
 - Not equals
 - Greater than
 - Less than
- **Time Conditions** - Time-based conditions
 - Current time (organization timezone)
 - Between times
 - Before time
 - After time
 - Days of week selection
- **Channel Conditions** - Channel-specific conditions
 - Channel type matching
 - Channel name matching
- **Multiple Conditions** - Combine conditions
 - AND logic
 - OR logic
 - Complex condition groups

**Actions:**
- **Create Task** - Automatically create tasks
 - Task title
 - Description
 - Priority (Low, Medium, High)
 - Assignee (optional, auto-assign available)
 - Due date (optional)
- **Auto Assign Conversation** - Auto-assign conversations
 - Round-robin assignment
 - Availability-based assignment
- **Auto Assign Task** - Auto-assign tasks
 - Round-robin assignment
 - Availability-based assignment
- **Assign Conversation** - Assign to specific user
 - User selection
- **Add Tag** - Add tags to contacts
 - Tag name
 - Multiple tags
- **Reply with Message** - Send automated replies
 - Text message
 - Quick reply template
 - Variable substitution
- **HTTP Request** - Call external APIs
 - GET, POST, PUT, PATCH, DELETE
 - URL configuration
 - Headers configuration
 - Body configuration
 - Response handling

**Automation Management:**
- **Rule List** - View all automation rules
 - Table view (desktop)
 - Card view (mobile)
 - Status indicators
 - Trigger icons
 - Action counts
- **Rule Details** - View rule configuration
 - Full rule definition
 - Execution history
 - Success/failure rates
- **Bulk Operations** - Manage multiple rules
 - Bulk enable/disable
 - Bulk delete

**Automation Execution:**
- **Real-Time Execution** - Immediate rule execution
 - Event-driven triggers
 - Instant action execution
- **Execution Logging** - Track rule executions
 - Execution history
 - Success/failure tracking
 - Error messages
- **Error Handling** - Handle execution errors
 - Error notifications
 - Retry logic
 - Fallback actions

**Automation Analytics:**
- **Per-Rule Statistics** - Track performance per automation
 - Total executions count
 - Successful executions count
 - Failed executions count
 - Success rate percentage
 - Last execution timestamp
- **Visual Indicators:**
 - Success/failure icons
 - Analytics badge on rule card
 - Quick performance overview

**Pagination:**
- **50 Automations Per Page** - Efficient loading
- **Page Navigation** - Easy browsing

---

### 10. Broadcast (`/broadcast`)

**Purpose:** Create and manage bulk messaging campaigns across SMS, WhatsApp Lite, and WhatsApp Business.

#### Key Features:

**Campaign Types:**
- **SMS Campaigns** - Text message campaigns (via Appgain Notify / VictoryLink provider)
 - Character limit: 160 (standard) or 1600 (concatenated)
 - Delivery tracking
 - Link shortening (optional)
- **WhatsApp Lite Campaigns** - WhatsApp Lite messaging
 - Media support (images, videos, documents)
 - Delivery and read receipts
 - Template support
 - Link shortening (optional)
- **WhatsApp Business Campaigns** - Meta WhatsApp Business API
 - Approved templates required
 - Rich media support
 - Interactive buttons
 - Template variables

**Campaign Creation:**
- **Campaign Setup** - Configure campaign
 - Campaign name
 - Description
 - Campaign type selection
 - Channel selection
- **Message Composition** - Create message content
 - Text editor
 - Character counter
 - Variable substitution ({{name}}, {{company}}, etc.)
 - Emoji picker
 - Link shortening toggle
 - Image upload
 - Message preview
- **Template Selection** - Use WhatsApp Business templates
 - Template browser
 - Template variables
 - Variable filling
 - Template preview

**Targeting Options:**
- **Target All Contacts** - Send to all contacts
 - Organization-wide broadcast
 - Optional filters
- **Target by Tags** - Send to tagged contacts
 - Multiple tag selection
 - AND/OR logic
 - Tag search
- **Target Individual Contacts** - Select specific contacts
 - Contact picker
 - Contact search
 - Multiple selection
 - Contact list import

**Campaign Scheduling:**
- **Send Immediately** - Send right away
 - Instant sending
 - Queue management
- **Schedule for Later** - Schedule future sending
 - Date picker
 - Time picker
 - Timezone selection
 - Organization timezone support
- **Recipient Count** - Preview recipient count
 - Real-time calculation
 - Filter-based counting
 - Tag-based counting

**Campaign Management:**
- **Campaign List** - View all campaigns
 - Tabbed view (SMS, WhatsApp Lite, WhatsApp Business, Notification Logs)
 - Campaign status indicators
 - Success ratio display
 - Target information
 - Created date
 - Sent date
 - Scheduled date
- **Campaign Status:**
 - DRAFT - Not sent
 - SCHEDULED - Scheduled for future
 - SENDING - Currently sending
 - COMPLETED - Finished sending
 - CANCELLED - Cancelled before sending
 - PAUSED - Temporarily paused
- **Campaign Actions:**
 - View campaign details
 - Edit campaign (draft only)
 - Delete campaign
 - Send campaign
 - Schedule campaign
 - Cancel scheduled campaign
 - Pause campaign
 - Resume campaign
 - View analytics

**Campaign Analytics:**
- **Delivery Statistics** - Track message delivery
 - Total sent
 - Successfully delivered
 - Failed deliveries
 - Success ratio percentage
- **Read Receipts** - Track message reads (WhatsApp)
 - Read count
 - Read rate
- **Notification Logs** - Detailed delivery logs
 - Per-recipient status
 - Delivery timestamps
 - Error messages
 - Retry attempts
- **Campaign Performance** - Overall campaign metrics
 - Delivery rate
 - Read rate
 - Cost analysis
 - ROI calculation

**Campaign Testing:**
- **Test Campaign** - Send test message
 - Test phone number input
 - Test message preview
 - Test sending
 - Test delivery verification

**WhatsApp Warming:**
- **Warming Campaigns** - Warm up WhatsApp numbers
 - Warming dialog
 - Warming progress tracking
 - Warming recommendations
 - Channel health monitoring

**Table Features:**
- **Sortable Columns** - Sort by any column
 - Created date
 - Sent date
 - Scheduled date
- **Column Visibility** - Show/hide columns
 - Customizable table
 - Saved preferences
- **Filtering** - Filter campaigns
 - By status
 - By type
 - By date range
- **Bulk Selection** - Select multiple campaigns
 - Bulk actions
 - Bulk delete

**Pagination:**
- **50 Campaigns Per Page** - Efficient loading
- **Page Navigation** - Easy browsing

---

### 11. Analytics (`/analytics`)

**Purpose:** Comprehensive analytics and reporting dashboard for performance insights.

#### Key Features:

**Overview Metrics:**
- **Total Messages** - Message volume tracking
 - Period comparison
 - Percentage change
 - Trend indicators
- **Average Response Time** - Team response performance
 - Hours/minutes format
 - Period comparison
 - Improvement tracking
- **SLA Compliance** - Service level agreement tracking
 - Compliance percentage
 - Period comparison
 - Progress indicators
- **Total Contacts** - Contact database growth
 - Period comparison
 - Growth percentage

**Time Range Selection:**
- **Flexible Periods** - Choose analysis period
 - Last 7 days
 - Last 30 days
 - Last 90 days
- **Period Comparison** - Compare with previous period
 - Automatic comparison
 - Percentage change
 - Trend indicators

**Tabbed Analytics:**
- **Inbox Tab** - Inbox performance metrics
 - Response metrics
 - Average response time
 - SLA compliance percentage
 - Progress bars
 - Conversation status
 - Resolved conversations count
 - Unassigned messages count
 - Overdue conversations count
 - Status indicators
- **Deals Tab** - Sales pipeline analytics
 - Deal pipeline
 - Active deals count
 - Pipeline value
 - Conversion rate
 - Lead to customer conversion
 - Conversion percentage
 - Period comparison
- **Contacts Tab** - Contact analytics
 - Contact growth
 - Total contacts
 - Growth percentage
 - Period comparison
 - Engagement rate
 - Contact engagement percentage
 - Period comparison
- **Performance Tab** - Team performance metrics
 - Task completion
 - Completed tasks count
 - Total tasks count
 - Completion rate percentage
 - Progress bars
 - Overall performance
 - Combined efficiency score
 - Performance grade

**Visual Analytics:**
- **Progress Bars** - Visual progress indicators
 - SLA compliance
 - Task completion
 - Conversion rates
- **Metric Cards** - Key metric display
 - Large numbers
 - Trend indicators
 - Comparison values
- **Status Indicators** - Visual status display
 - Color-coded statuses
 - Icon indicators
 - Badge displays

**Real-Time Updates:**
- **Live Data** - Real-time metric updates
 - Automatic refresh
 - Live synchronization
- **Data Accuracy** - Accurate calculations
 - Real-time aggregation
 - Period-based calculations

---

### 12. Settings (`/settings`)

**Purpose:** Comprehensive organization and system configuration.

#### Key Features:

**Organization Tab:**
- **Organization Profile** - Manage organization settings
 - Organization name
 - Organization slug
 - Timezone selection
 - Full timezone list
 - Organization timezone for scheduling
 - Currency selection
 - Full currency list
 - Default currency for deals
- **Notification Preferences** - Browser notification settings
 - Enable/disable browser push notifications
 - Web Push API support (background notifications)
 - Android support (Chrome, Firefox, Samsung Internet)
 - iOS support (Safari PWA, iOS 16.4+)
 - Permission management
 - Notification status indicator
 - Automatic subscription on login
- **Danger Zone** - Destructive actions
 - Delete all data
 - Confirmation required
 - Type "DELETE ALL DATA" to confirm
 - Deletes: companies, conversations, contacts, deals, tasks, templates, automations, bot flows

**Team Members Tab:**
- **Team Management** - Manage team members
 - View all team members
 - Member details (name, email, role, status)
 - Active/inactive status
- **Invite Members** - Add new team members
 - Email input
 - Role selection (Admin, Agent)
 - Invitation sending
 - Invitation URL generation
 - Auto-copy invitation link
- **Member Roles** (the `app_role` enum has five roles, stored in `user_roles` — never on `profiles`):
 - Owner - Full access
 - Admin - Manage users and settings
 - Agent - Access to conversations and contacts
 - Project Manager - Projects/PM access; excluded from agent auto-assignment and performance reports
 - Team Admin - Manages a sub-team via the **Teams** tab (`team_members`)
- **Member Actions:**
 - Manage permissions
 - Manage availability
 - Remove member
 - View member details
- **Pending Invitations** - Manage invitations
 - View pending invitations
 - Resend invitation email
 - Copy invitation link
 - Cancel invitation
 - Invitation expiration tracking

**Message Templates & Quick Replies Tabs:**
- **Quick Replies** - Reusable canned responses (separate **Quick Replies** tab)
 - Create templates with text and images
 - Edit / delete templates
 - Template search and filtering
 - Template categories (QUICK_REPLY)
 - Template usage in flows and automations
 - Image upload support, preview, usage tracking
- **Message Templates** - Org-level reusable message content (separate **Message Templates** tab)

**WhatsApp Templates Tab:**
- **WhatsApp Business Templates** - Manage Meta-approved message templates
 - Fetch templates from WhatsApp Cloud API
 - View template status (Approved, Pending, Rejected)
 - Template categories and languages
 - Template variables and components
 - Usage in broadcast campaigns
 - Admin only access

**Task Automation** *(dedicated page at `/task-automation`, not a Settings tab):*
- **Automated Task Rules** - Configure task auto-distribution
 - Rule creation with triggers, conditions, and actions
 - Assignment strategies: Round-robin, Workload-based, Skills-matching
 - Execution logs table with status tracking
 - Enable/disable rules
 - Beta feature badge

**Tags & Labels Tab:**
- **Organization Tag Management** - Centralized tag administration
 - View all tags across contacts, deals, companies
 - Create, rename, and delete tags
 - Tag usage counts
 - Bulk tag operations
 - **Custom Labels / white-label terminology** is managed inside this tab (see below)
 - Admin only access

**Lifecycle Stages Tab:**
- **Org-Customizable Contact Lifecycle** - define the stages a contact moves through (Lead → Customer → …)
 - Create, order, and name stages; mark a default
 - Seed common stages in one click
 - Drives the **Update Lifecycle** flow node and **Lifecycle Updated** trigger
 - Admin only access

**Custom Labels** *(inside the **Tags & Labels** tab — not a standalone tab):*
- **White-Label Terminology** - Customize platform labels
 - Rename "Contacts", "Deals", "Companies", "Tasks", "Projects" etc.
 - Multi-language label overrides
 - Per-organization customization
 - Reset to defaults option

**External Pages Tab (Feature Restrictions):**
- **Custom Sidebar Pages** - Add external web pages to navigation
 - Custom page name and URL
 - Icon selection from 30+ Lucide icons
 - Open in iframe or new tab
 - Reorder pages
 - Enable/disable pages
 - Admin-managed visibility

**Channels Tab:**
- **Channel Accounts** - Manage messaging channels
 - View all channels
 - Channel status (Active/Inactive)
 - Channel configuration
 - Channel statistics
- **Add Channels** - Connect new channels
 - Channel type selection
 - Channel configuration
 - OAuth integration (Facebook, Instagram)
 - QR code authentication (WhatsApp Lite)
- **Channel Types Supported:**
 - WhatsApp Lite (AppGain)
 - WhatsApp Cloud (Meta)
 - Facebook Messenger
 - Instagram Direct Messages
 - Telegram
 - Email
 - SMS
 - ShrinkIt Push Notifications
- **Channel Management:**
 - Edit channel settings
 - Delete channels
 - Toggle channel status
 - View channel details
 - Monitor channel health
- **Channel Statistics** - Channel performance metrics
 - Messages sent/received
 - Conversation count
 - Response time
 - Channel performance indicators

**Email Boxes Tab:**
- **Email Account Setup** - Connect email inboxes
 - IMAP/SMTP configuration
 - Email account connection
 - Send and receive email via unified inbox
 - Beta feature badge

**Call Intelligence Tab:**
- **Webhook Configuration** - Configure call recording webhook
 - Webhook URL display with copy button
 - [API key](https://docs.connectgain.cloud/04-use-cases/07-api/api-key-authentication.md) authentication instructions
 - JSON request format documentation
 - Agent mapping rules (email match, phone match, customer contact)
 - Rate limits & quotas reference
 - Supported audio formats reference

**API Keys Tab:**
- **API Key Management** - Manage API keys
 - Generate API keys with `cg_` prefix
 - Revoke API keys
 - View API key details (prefix, created date, last used)
 - API key permissions configuration
 - Expiration date support
 - API documentation links

**Webhooks Tab:**
- **Outgoing Webhook Configuration** - Push events to external systems
 - Create webhooks with name, URL, and secret
 - Event type selection (message received, contact created, deal updated, etc.)
 - Custom headers support
 - Active/inactive toggle
 - Webhook delivery logs with status tracking
 - Log inspection with request/response details
 - Edit and delete webhooks
 - HMAC signature verification

**Settings Organization:**
- **Tabbed Interface** - Organized into 6 categories:
 - **My Preferences:** Notifications, Chat & Contacts, Inbox Layout
 - **Workspace:** Organization, Team Members, Teams, Sidebar Menu
 - **Inbox & Messaging:** Channels, Email Boxes, Message Templates, Quick Replies, WhatsApp Templates, Tags & Labels, Lifecycle Stages, SLA & Escalation, External Pages
 - **AI & Automation:** AI Provider, AI Re-Engagement, AI Summaries, Enrichment Tools, Call Intelligence
 - **Storage & Developer:** Media Storage, Storage Usage & Cleanup, API Keys, Webhooks
 - **Danger Zone:** Delete all data
 - *Note: "Task Automation" is its own page at `/task-automation`, not a Settings tab. "Custom Labels" lives inside the **Tags & Labels** tab. Quick-reply and Meta message templates are split into separate **Quick Replies** and **Message Templates** tabs.*
- **Mobile Responsive** - Mobile-optimized settings
 - Collapsible tabs
 - Mobile-friendly forms
 - Touch-optimized controls

---

### 13. Profile (`/profile`)

**Purpose:** User profile management and subscription management.

#### Key Features:

**Profile Information Tab:**
- **Personal Information** - Manage personal details
 - First name
 - Last name
 - Avatar (initials-based)
 - Email address (read-only in profile tab)
 - Role display
- **Profile Update** - Update profile information
 - Form validation
 - Success notifications
 - Error handling

**Subscription Tab:**
- **Current Plan** - View subscription details
 - Plan name
 - Plan description
 - Plan price
 - Subscription status (Active, Trial, Cancelled)
 - Trial days remaining (if applicable)
 - Next billing date
 - Current period end date
- **Plan Features** - View plan features
 - Feature list
 - Feature checkmarks
 - Plan limits display
- **Usage Statistics** - Track usage
 - Contacts used/total
 - Conversations used/total
 - Team members used/total
 - Usage percentages
 - Progress bars
- **Manage Subscription** - Subscription management
 - Open Stripe customer portal
 - Update payment method
 - Change plan
 - Cancel subscription
 - View billing history

**Email Address Tab:**
- **Change Email** - Update email address
 - New email input
 - Email validation
 - Email change confirmation
 - Warning messages
- **Email Verification** - Email verification process
 - Verification email sending
 - Verification status

**Password Tab:**
- **Change Password** - Update password
 - New password input
 - Confirm password input
 - Password strength requirements
 - Show/hide password toggle
 - Password validation
 - Success notifications

**Profile Organization:**
- **Tabbed Interface** - Organized profile sections
 - Profile Information
 - Subscription
 - Email Address
 - Password
- **Visual Design** - Clean profile interface
 - Avatar display
 - Card-based layout
 - Clear section separation

---

### 15. Onboarding (`/onboarding`)

**Purpose:** Guided setup process for new users.

#### Key Features:

**Onboarding Steps:**
- **Step 1: Email Verification** - Verify email address
 - Email verification check
 - Verification status indicator
 - Verification instructions
- **Step 2: Subscription** - Choose subscription plan
 - Plan selection
 - Trial period information
 - Plan comparison
 - Subscribe button
- **Step 3: Channel Setup** - Connect messaging channels
 - Channel connection
 - Channel configuration
 - Skip option available

**Progress Tracking:**
- **Visual Progress** - Progress indicators
 - Step completion checkmarks
 - Current step highlighting
 - Progress bar
- **Step Status** - Step completion status
 - Completed steps (green checkmark)
 - Current step (blue circle)
 - Pending steps (gray circle)

**Channel Setup:**
- **Connected Channels** - Display connected channels
 - Channel cards
 - Channel status
 - Channel actions (toggle, delete)
- **Add Channels** - Connect new channels
 - Add channel dialog
 - Channel type selection
 - Channel configuration
- **Skip Option** - Skip channel setup
 - Skip button
 - Optional step indication
 - Continue without channels

**Onboarding Completion:**
- **Finish Setup** - Complete onboarding
 - Finish button
 - Onboarding completion tracking
 - Redirect to dashboard
- **Skip for Now** - Skip remaining steps
 - Skip button
 - Later completion option

---

### 16. Attendance (`/attendance`)

**Purpose:** Monitor agent attendance, online status, and track clock in/out times for team management.

#### Key Features:

**Online Agents Panel:**
- **Real-Time Online Status** - Live tracking of online agents
 - Online agent count badge
 - Agent avatars with online indicators
 - Last seen timestamps
 - Real-time updates via WebSocket
- **Agent Information Display:**
 - Agent name and email
 - Profile avatars with initials fallback
 - Green status indicators for online agents
 - Time-ago formatting for last seen
- **Auto-Refresh** - Automatic updates every 60 seconds
 - Real-time subscription to profile changes
 - Debounced updates to prevent excessive queries
 - Throttled fetching (max once per 5 seconds)

**Attendance History Table:**
- **Comprehensive Attendance Records** - Complete attendance tracking
 - Clock in timestamps
 - Clock out timestamps
 - Hours worked calculation
 - Status indicators (ACTIVE/COMPLETED)
- **Advanced Filtering:**
 - Search by agent name or email
 - Filter by status (All, Active, Completed)
 - Date range filtering (Today, Last 7/30/90 days)
 - Real-time search
- **Pagination:**
 - 10 records per page
 - Total count display
 - Page navigation controls
 - Previous/Next buttons
- **Data Display:**
 - Formatted dates and times
 - Duration in hours and minutes
 - Status badges
 - Agent contact information

**Access Control:**
- **Admin/Owner Only** - Restricted access
 - Only ADMIN and OWNER roles can access
 - Automatic redirect for unauthorized users
 - Role-based permission checking
- **Organization-Level Data** - Scoped to organization
 - Only shows attendance for organization members
 - Secure data isolation via RLS policies

**Automatic Tracking:**
- **Clock In/Out Automation** - Automatic attendance logging
 - Clock in on user login
 - Clock out on user logout
 - Automatic duration calculation
 - No manual intervention required

**Bulk Record Management:**
- **Multi-Select** - Select multiple attendance records
 - Checkbox per record row
 - Select all on page
- **Clear Records** - Bulk delete options
 - Delete Selected (selected records only)
 - Delete Filtered (all matching current filters)
 - Delete All (entire date range)
 - Batch processing (100 records at a time for stability)
 - Project Manager records excluded from bulk deletion
- **Confirmation Dialog** - Prevent accidental deletion
 - Clear warning message
 - Record count display
 - Confirm/cancel buttons

---

### 17. Contact Timeline Page (`/contacts/:id/timeline`)

**Purpose:** Dedicated full-page view for a contact's complete activity history and interaction timeline.

#### Key Features:

**Contact Overview:**
- **Contact Header** - Quick contact information
 - Contact name (first + last)
 - Avatar with initials
 - Phone numbers with click-to-call
 - Email addresses with click-to-email
 - Company association badge
 - Tags display
 - Created date
- **Navigation:**
 - Back to contacts button
 - Open full contact details link

**Activity Timeline:**
- **Complete Interaction History** - All contact activities
 - Calls logged (with outcome and duration)
 - Messages sent/received
 - Deals created/updated
 - Tasks assigned/completed
 - Notes added
 - Contact info changes
- **Visual Timeline:**
 - Chronological display
 - Activity type icons
 - Timestamp display
 - Activity details and notes
- **Infinite Scroll** - Load more activities as you scroll

**Quick Actions:**
- **Phone Call** - Click phone numbers to call
- **Email** - Click email addresses to compose
- **Company Link** - Navigate to associated company
- **External Links** - Open in new tab options

---

### 18. Sales Report (`/sales-report`)

**Purpose:** Comprehensive sales pipeline analysis and reporting with detailed deal breakdowns and export capabilities.

#### Key Features:

**Pipeline Selection:**
- **Multiple Pipeline Support** - Analyze any pipeline
 - Pipeline dropdown selector
 - Default pipeline auto-selection
 - Pipeline switching
 - Real-time data refresh

**Summary Metrics:**
- **Total Stages** - Number of stages in pipeline
- **Total Deals** - Count of all deals across stages
- **Total Value** - Sum of all deal values
- **Average Deal Value** - Mean deal value calculation
- **Visual Cards** - Large, prominent metric display

**Stage-by-Stage Analysis:**
- **Collapsible Stage Cards** - Expandable stage sections
 - Color-coded stage headers
 - Stage name and color indicators
 - Deal count per stage
 - Total value per stage
 - Average deal value per stage
 - Average probability per stage
- **Expand/Collapse Controls:**
 - Individual stage toggle
 - Expand All / Collapse All buttons
 - Visual chevron indicators
 - Smooth animations

**Deal Details Table:**
- **Comprehensive Deal Information:**
 - Deal title
 - Contact name and information
 - Company name
 - Description
 - Deal value (formatted currency)
 - Expected close date
 - Probability percentage
- **Quick Actions:**
 - View deal details (navigate to deals page)
 - View conversation (navigate to inbox)
 - External link icons
- **Sortable Columns** - All columns sortable
- **Responsive Design** - Mobile-optimized layout

**Export Capabilities:**
- **CSV Export** - Full report export
 - All stages and deals included
 - Stage summary rows
 - Grand total row
 - Formatted currency values
 - Date-stamped filename
 - Ready for Excel import

**Data Refresh:**
- **Manual Refresh** - Update data on demand
 - Refresh button with loading state
 - Real-time data fetching
 - Error handling and notifications

**Visual Design:**
- **Color-Coded Stages** - Visual stage identification
 - Stage-specific colors
 - Left border accent colors
 - Background tinting
- **Status Badges** - Visual indicators
 - Probability badges
 - Deal count badges
 - Value highlights

---

### 18b. Bookings (`/bookings`)

**Purpose:** Centralized management system for appointments, meetings, and events with Google Calendar integration.

#### Key Features:

**Booking Management:**
- **Create Bookings** - Add new appointments
 - Title and description
 - Contact association
 - User assignment
 - Start and end time
 - Timezone support
 - Location details
 - Meeting link (Zoom, Google Meet, etc.)
 - Status selection (scheduled, confirmed, cancelled, completed)
- **Edit Bookings** - Update existing bookings
 - All fields editable
 - Status updates
 - Time modifications
 - Contact changes
- **Delete Bookings** - Remove bookings
 - Confirmation dialog
 - Permanent deletion
 - Calendar sync removal

**Booking List View:**
- **Comprehensive Table** - All bookings displayed
 - Title
 - Contact information
 - Date and time (formatted)
 - Location
 - Status badges
 - Action menu
- **Status Indicators:**
 - Scheduled (outline badge)
 - Confirmed (green badge)
 - Cancelled (red badge)
 - Completed (secondary badge)
- **Search Functionality:**
 - Search by title
 - Search by description
 - Search by contact name
 - Real-time filtering
- **Status Filtering:**
 - All statuses
 - Scheduled only
 - Confirmed only
 - Cancelled only
 - Completed only

**Google Calendar Integration:**
- **Calendar Event Sync** - Automatic calendar updates
 - Event creation in Google Calendar
 - Event updates on booking changes
 - Event deletion on booking cancellation
 - Google Calendar event ID tracking
- **Quick Actions:**
 - Open in Google Calendar (direct link)
 - Join meeting (meeting link)
 - View event details

**Contact Integration:**
- **Contact Association** - Link bookings to contacts
 - Contact picker
 - Contact information display
 - Contact name formatting
 - Quick contact access

**User Assignment:**
- **Team Member Assignment** - Assign bookings to users
 - User selection dropdown
 - User information display
 - Multi-user support

**Date and Time Management:**
- **Timezone Support** - Timezone-aware scheduling
 - Organization timezone
 - User timezone detection
 - Automatic conversion
- **Date Formatting** - Human-readable dates
 - Month, day, year format
 - Time in 12-hour format
 - Time range display

**Empty States:**
- **No Bookings** - Helpful empty state
 - Calendar icon
 - Encouraging message
 - Create booking button
- **No Search Results** - Search feedback
 - Clear messaging
 - Search term display

**Responsive Design:**
- **Mobile Optimized** - Touch-friendly interface
 - Responsive table layout
 - Mobile-friendly forms
 - Touch-optimized controls

---

### 19. Call Tracking (Native Mobile Integration)

**Purpose:** Track phone calls with contacts using native mobile dialers, with automatic logging and outcome capture.

#### Key Features:

**Click-to-Call:**
- **One-Click Calling** - Call contacts directly from the app
 - Call button in Contact Panel
 - Call button in Contact Timeline
 - Uses native mobile phone dialer
 - Supports `tel:` protocol for all phones
- **Automatic Call Logging** - All calls logged to database
 - Call initiation timestamp
 - Contact association
 - Phone number tracking
 - Call direction (inbound/outbound)

**Call Outcome Tracking:**
- **Follow-Up Dialog** - Capture call results when returning to app
 - Automatic detection using `visibilitychange` API
 - Outcome options: Completed, No Answer, Busy, Voicemail, Failed
 - Duration input (manual or smart estimation)
 - Notes field for call details
- **Smart Detection** - Intelligent timing-based UX
 - Return < 30 seconds: Suggests "Cancelled"
 - Return > 2 minutes: Pre-fills estimated duration
 - Pending call storage in localStorage for persistence

**Call History:**
- **Contact Timeline Integration** - Calls appear in activity log
 - `CALL_LOGGED` activity type
 - Call outcome display
 - Duration display
 - Notes display
 - Phone icon indicator
- **Call Events Table** - Full call history in database
 - Caller information
 - Call status tracking
 - Duration tracking
 - Conversation association

**Call Recording (Manual Upload):**
- **Attach Recording** - Upload audio files recorded on mobile devices
 - Integrated into Post-Call Follow-Up Dialog
 - Supported formats: MP3, M4A, WAV, OGG, WebM, AAC
 - Maximum file size: 50 MB
 - File type and size validation with user-friendly error messages
- **Secure Storage** - Recordings stored in private Supabase bucket (`call-recordings`)
 - Organization-scoped RLS policies
 - Signed URL playback (1-hour expiry)
 - Upsert support for re-uploading
- **Inline Audio Player** - Play recordings directly in contact timeline
 - `CallRecordingPlayer` component with play/pause controls
 - Duration display
 - Secure signed URL generation

**Future Roadmap:**
- Call Bridging (make calls through business number)
- WebRTC Softphone (in-browser calling)
- SIP Trunk Integration (enterprise telephony)

---

### 20. Call Intelligence (`/call-intelligence`)

**Purpose:** AI-powered conversation & revenue intelligence platform that automatically transcribes, diarizes, analyzes, and extracts insights from call recordings, with full support for code-switched Arabic/English. Runs on multi-vendor AI — ConnectGain AI (Google Gemini 2.5 Flash) by default, with optional OpenAI, Anthropic Claude, Google Gemini, Ollama, or GLM/Z.ai, or Bring-Your-Own-Key (BYOK). Tuned for regulated/brokerage use with trade-call compliance surveillance, agent QA scoring, call classification, and topic-trend reporting.

#### Key Features:

**Call Recording Upload (In-App):**
- **Upload Recording Dialog** - Upload audio files for AI analysis
 - Contact search and association
 - Direction selection (inbound/outbound)
 - Caller number input
 - Drag-and-drop file upload
 - Upload progress indicator
 - Supported formats: MP3, M4A, WAV, OGG, WebM, AAC (50 MB max)

**Webhook Integration (External Systems):**
- **Call Recording Webhook** - `POST /functions/v1/call-recording-webhook`
 - API key authentication via `X-API-Key` header
 - JSON payload with `external_call_id` and `recording_url`
 - Optional: `agent_identifier`, `customer_phone`, `duration_seconds`, `call_timestamp`, `direction`, `metadata`
 - Automatic agent matching by email or phone number
 - Customer contact matching by phone number
 - Rate limit: 100 calls/hour
 - Retry support: up to 3 attempts

**Mobile API Integration:**
- **Mobile Call Recorder API** - `POST /functions/v1/mobile-api/call-recording`
 - JWT authentication via login endpoint
 - Direct audio file upload (multipart/form-data, 50 MB limit)
 - Storage in `call-recordings` bucket
 - Automatic trigger of AI transcription pipeline

**AI Processing Pipeline:**
- **Automated Transcription & Diarization** - Multi-language speech-to-text with speaker separation
 - Code-switched Egyptian Arabic/English (each language preserved as spoken, no translation)
 - Exact number/price transcription and EGX ticker/jargon phrase-boosting
 - Multi-vendor AI (ConnectGain AI / Gemini 2.5 Flash default; OpenAI, Anthropic Claude, Google Gemini, Ollama, GLM/Z.ai, or BYOK)
 - **Speaker diarization** - structured, timestamped segments attributed to agent/customer (Broker/Client)
 - Full transcript + segment JSON stored in database
 - Threaded, per-speaker transcript view with RTL/LTR auto-detection
 - Detected language stored per call (Arabic / English / Mixed)
- **Conversation Interaction Stats** - Derived from diarized segments
 - **Talk ratio** (agent vs. customer) with discovery-call benchmark guidance (~43:57)
 - **Longest monologue** per side
 - **Interactivity** (speaker switches per minute)
 - **Agent question rate** (questions asked by the rep)
 - **Patience** (avg wait before the agent responds)
 - Graceful fallback estimates timing from speech volume when per-word timestamps are unavailable
- **Sentiment Analysis** - Emotional tone classification
 - Positive / Neutral / Negative labels
 - Numeric sentiment score (0–1)
 - Color-coded sentiment badges
 - **Sentiment timeline** - how sentiment evolved from call start to end, plotted on a visual track
- **AI Summary** - Concise call overview
 - AI-generated summary of key topics discussed
 - Displayed in call detail dialog
- **Action Items Extraction** - Automatic task identification
 - Extracted action items with priority levels
 - Auto-creation of CRM tasks from call action items
 - Linked to contact via `call_tasks` junction table
- **Keyword Extraction** - Key topic identification
 - Top keywords extracted from transcript
 - Keyword frequency tracking
 - Visual keyword display
- **Call Classification** - Categorization tags
 - AI-generated classification tags
 - Visual tag badges in call records list
- **Resolution Score** - Call resolution quality metric
 - AI-assessed resolution quality (0–100%)
 - Displayed in call detail view
- **Structured Topic Extraction** - Normalized topics beyond flat keywords
 - Each topic carries a canonical label, a category (instrument, order, advisory, account, market, fees, compliance, service, complaint, other), and a per-topic sentiment
 - Label canonicalization merges variants (e.g. "follow-up"/"follow up", plurals)
- **Brokerage Call Classification** - Each call typed into a trading taxonomy (order execution, advisory, market update, account inquiry, complaint, margin call, KYC/onboarding, prospecting, technical support, other)

**Compliance & Surveillance (Trade Calls):**
- **Market-Abuse & Conduct Flags** - AI surveillance of broker–client calls
 - Categories: insider information, market manipulation, front-running, guaranteed returns, pressure selling, unauthorized trading, missing disclosure, suitability concern
 - Each flag records severity (high/medium/low), speaker (Broker/Client), the exact matched phrase, a confidence score, and a one-line rationale
- **Instruction vs. Recommendation** - Classifies whether the call carried a client instruction, a recommendation, general discussion, or none
- **Disclosure Tracking** - Records whether a required risk disclosure was spoken
- **Instruments Captured** - Tickers/securities discussed, stored per call (GIN-indexed)
- **Regulatory Retention** - 7-year retention horizon stamped on each processed call

**Agent Call-Handling QA Scorecard:**
- **Overall Handling Score (0–100)** plus five graded dimensions: Professionalism & Tone, Communication & Clarity, Client Needs Handling, Market/Product Knowledge, Compliance Adherence
- **Coaching Output** - Strengths, coaching points, and a one-line manager summary
- Surfaced per call in the detail dialog and aggregated per agent in the manager report

**Conversation Trackers:**
- **Configurable Trackers** - Track topics across every call transcript
 - Categories: competitor, pricing, objection, feature, custom
 - **Keyword trackers** - deterministic, Unicode-aware (Arabic-safe) whole-word phrase matching
 - **Smart trackers** - AI concept/theme detection that flags a topic even without an exact phrase match
 - Per-call tracker hits with mention counts, matched phrases, and AI badges
 - Managed in Settings (OWNER/ADMIN or `can_manage_call_settings`); re-run a call to apply new trackers
- **Tracker Trends Report** - Cross-call analytics in the Reports tab
 - Top-trackers leaderboard (calls vs. total mentions)
 - Mentions-over-time chart for the top trackers
 - Full tracker table with AI-detection indicators

**Call → Deal Revenue Intelligence:**
- **Call ↔ Deal Linkage** - Associate a call with a deal from the call detail dialog
 - Contact-scoped deal picker with search
 - Linked deal shown on the call record
- **Deal-Level Call Signals** - Surfaced on the deal's activity tab
 - Rollup of avg sentiment, avg resolution, total talk time, last call date
 - Aggregated tracker mentions across the deal's calls
 - Recent linked calls with direction, agent, duration, and sentiment

**Coaching Scorecards:**
- **Scorecard Templates** - Manager-defined coaching rubrics
 - Weighted criteria with per-item max scores (e.g., agenda-setting, objection handling, discovery)
 - Active/inactive toggle; managed in Settings (OWNER/ADMIN or `can_manage_call_settings`)
- **Call Scoring** - Score any completed call against a template
 - Manual scoring with per-criterion notes and an overall coaching comment
 - **AI-suggested scores** generated from the transcript (`suggest-call-scorecard`), fully editable before saving
 - Reviewer attribution, total/max score, and AI-vs-manual badge

**Silence Detection:**
- **Empty Recording Detection** - Prevent unnecessary AI processing
 - Backend regex-based silence pattern detection (`[no speech detected]`)
 - Records marked with `silent` status and `silent-recording` tag
 - Skips AI analysis, task generation, and token billing
 - UI silence warning banner with mute icon (🔇)
 - Web Audio API (AudioContext) analysis during playback

**Call Records List:**
- **Tabular View** - All call records in a sortable table
 - Direction icon (inbound/outbound)
 - Contact name
 - Agent name
 - Date/time
 - Duration
 - Status badge (Completed, Failed, Transcribing, Analyzing, Received, Quota Exceeded, Silent)
 - Sentiment badge with score
 - Classification tags and keywords
 - Mute icon for silent recordings
- **Bulk Selection** - Select multiple records
 - Checkbox selection
 - Select all toggle
 - Bulk delete (admin only)
- **Call Detail Dialog** - Full call details
 - Agent and contact info
 - Date, duration, direction, detected language
 - Status with color-coded indicators
 - Call type with **manual reclassify** dropdown (admin/owner; manual choice survives reprocessing)
 - **Agent Handling (QA) scorecard** — overall score, dimension bars, strengths/coaching
 - Sentiment badge and resolution score
 - **Deal linkage** (link/unlink a deal)
 - **Interaction stats** (talk ratio, monologue, interactivity, questions, patience)
 - **Sentiment timeline** track
 - **Tracker hits** (keyword + smart, with counts)
 - **Compliance & Surveillance** section — flags (category, severity, speaker, matched phrase), instruments, instruction type, disclosure status
 - Inline audio player (signed URL playback)
 - Threaded, diarized transcript (agent/customer, Broker/Client) with RTL/LTR auto-detect
 - AI summary
 - Action items with priority badges
 - Topics (with category) plus tags and keywords display
 - **Coaching scorecards** (view, add manual, or AI-suggest)
 - Hint to re-run older calls that predate advanced analytics
 - Retry button for failed processing (up to 3 attempts)
 - Dialog stays bound to the freshest record (reclassify/reprocess reflected immediately)

**Analytics Dashboard:**
- **Summary Cards:**
 - Total Calls (this month)
 - Average Duration (per call)
 - Average Sentiment (positive score %)
 - Active Agents (with calls this month)
- **Call Minutes Usage Card:**
 - Monthly quota tracking via `check_call_minutes_available` RPC
 - Used / Limit / Bonus minutes display
 - Progress bar with warning (80%) and critical (95%) thresholds
 - Fallback: aggregates `duration_seconds` from `call_records` if quota unavailable
- **AI Token Usage Card:**
 - Monthly token consumption (input / output / total)
 - Cost estimation based on Gemini 2.5 Flash pricing ($0.15/1M input, $0.60/1M output)
 - Data from `call_token_usage` table with fallback to `call_records`
- **Call Volume Chart** - Bar chart of calls per day (last 7 days)
- **Sentiment Distribution** - Donut/pie chart (Positive / Neutral / Negative)
- **Agent Performance Leaderboard** - Per-agent metrics
 - Number of calls
 - Average sentiment score
 - Resolution rate
- **Top Keywords Chart** - Horizontal bar chart of most frequent keywords
- **CSV Export** - One-click export including call type, language, QA score, sentiment, resolution, instruction type, disclosure, instruments, compliance flags (count + categories), topics, and keywords

**Reports (Reports Tab):**
- **Compliance & Surveillance** - Flagged-call volume and rate, high-severity count, disclosure coverage, flags by category, instruction-vs-recommendation split, and a recent-flagged-calls feed
- **Agent Performance (Manager View)** — *admin/owner only* — sortable per-agent table across activity (calls, inbound/outbound, talk time), trading (orders vs. recommendations), quality (QA score, sentiment, resolution, negative rate) and compliance (flagged calls, flag rate, high-severity flags, disclosure coverage), with a team summary and per-agent drill-down (QA dimensions, flag categories, top instruments, call-type mix)
- **Topic & Keyword Trends** - Top topics, topics by category, top-topic trends over time, emerging topics (period-over-period growth), and topics driving negative sentiment
- Plus existing reports: Period Comparison, Call Classification, Resolution Rate, Duration Analysis, Action Items, Peak Hours, Direction Analysis, Negative Call Escalation

**Transcription Engine Validation (ASR Bake-off):**
- Internal harness to compare speech-to-text engines on real call samples before committing
- Reports Word Error Rate split by language (Arabic / English / mixed), number/price accuracy, ticker recall, and an approximate diarization signal
- Gemini is the default engine; optional comparison adapters included

**Reports Tab:**
- Period Comparison, Call Classification, Resolution Rate, Call Duration Analysis, Action Items & Follow-ups, Peak Hours, Direction Analysis, Negative Call Escalation
- **Tracker Trends** - cross-call tracker leaderboard + mentions-over-time (keyword and smart trackers)

**Settings Integration:**
- **Call Intelligence Settings** - Configuration panel in Settings
 - Webhook URL display with copy button
 - API key authentication instructions
 - JSON request format documentation
 - Agent mapping rules (email match, phone match, customer contact match)
 - Rate limits and quotas display
 - Supported formats reference
 - **AI vendor configuration** (ConnectGain AI / Gemini default, plus OpenAI, Anthropic Claude, Google Gemini, Ollama, GLM/Z.ai + BYOK)
 - **Call Trackers management** (keyword + smart, with category and active toggle)
 - **Coaching Scorecard templates** (criteria builder with max scores)
 - Management UIs gated to OWNER/ADMIN or `can_manage_call_settings`

**Demo Mode:**
- **View-Only Demo** - English sample data for guest/unenabled accounts
 - Pre-populated demo call records
 - Demo analytics with sample charts
 - Feature gate with view-only badge
 - Real accounts see empty state + upload interface

---

### 21. Sequences (Drip Campaigns) (`/sequences`)

**Purpose:** Create multi-channel automated message sequences for lead nurturing, onboarding, follow-ups, and marketing automation.

#### Key Features:

**Sequence Builder:**
- **Visual Sequence Editor** - Build multi-step campaigns
 - Sequence name and description
 - Channel selection per sequence: Email, WhatsApp Lite, WhatsApp Cloud
 - Step delays (minutes, hours, days after previous step)
 - Variable substitution (`{{first_name}}`, `{{company}}`, etc.)
 - Reorder steps via drag-and-drop

**Channel Support:**
- **Email** - HTML email sequences
 - Rich HTML editor with variable support
 - Subject line and sender name configuration
 - Open and click tracking
 - Automatic unsubscribe link append
- **WhatsApp Lite** - Free-form text messages via Appgain
 - Dynamic message content (no template approval required)
 - Media URL support by file extension
 - Best for warm conversations and follow-ups
- **WhatsApp Cloud** - Meta-approved template sequences
 - Template selection from approved library
 - Parameter mapping from contact fields
 - 24-hour customer-service window enforcement

**Contact Enrollment:**
- **Manual Enrollment** - Enroll individual contacts or bulk selections
- **Auto-Enrollment** - Via automation action `ENROLL_IN_SEQUENCE`
- **Enrollment Status** - Active, completed, paused, removed, unsubscribed, bounced, exited
- **Re-Enrollment Protection** - Unsubscribed and bounced contacts cannot be re-enrolled (CAN-SPAM/GDPR compliant)

**Compliance & Safety:**
- **Automatic Unsubscribe** - One-click unsubscribe with PBKDF2-secured tokens
- **Opt-Out Honour** - Unsubscribe applies across all sequences for that contact
- **Timezone-Aware Scheduling** - Sends at contact's local timezone
- **Marketing Pressure** - Prevent message fatigue with configurable spacing

**Sequence Management:**
- **Sequence List** - View all sequences with status badges
 - Active / Paused / Draft / Archived states
 - Enrollment counts per sequence
 - Channel indicators
- **Sequence Actions:**
 - Create, edit, duplicate, delete sequences
 - Step-by-step analytics (open rate, click rate, delivery rate)
 - Export performance data

---

---

### 22. Lists (Tag-Based Segmentation)

**Purpose:** Visual interface for managing contact segments based on tags, enabling targeted campaigns and organization.

#### Key Features:

**Tag Overview:**
- **All Tags Display** - View all organization tags
 - Tag name
 - Contact count per tag
 - Visual tag cards
 - Click to drill down

**Tag Filtering:**
- **Search Tags** - Find specific tags
 - Real-time search
 - Tag name matching
- **Contact Drill-Down** - View contacts with tag
 - Contact list view
 - Contact details display
 - Phone and email information
 - Back navigation

**Contact Details:**
- **Tag-Based Contact List** - Contacts filtered by tag
 - Contact name
 - Email addresses
 - Phone numbers
 - All assigned tags
 - Created date

**Integration:**
- **Campaign Targeting** - Use lists for campaigns
 - Target campaigns by tag
 - Combine with broadcast feature
- **Automation Rules** - Trigger automations by tags
 - Tag-based conditions
 - Auto-tag actions

---

### 23. Interest Analysis Dashboard

**Purpose:** Visual analytics dashboard showing conversation interest levels based on AI analysis, helping prioritize hot leads.

#### Key Features:

**Interest Statistics:**
- **Interest Level Breakdown** - Visual summary
 - Hot leads count (high interest, ready to convert)
 - Warm leads count (moderate interest, needs nurturing)
 - Cold leads count (low interest)
 - Total conversations
 - Analyzed vs. not analyzed counts

**Visual Metrics:**
- **Progress Bars** - Visual interest distribution
 - Hot percentage
 - Warm percentage
 - Cold percentage
- **Pie Chart** - Interest breakdown visualization
- **Bar Chart** - Comparative view

**Conversation Lists:**
- **Tabbed Interface** - Browse by interest level
 - Hot conversations tab
 - Warm conversations tab
 - Cold conversations tab
 - All conversations tab
- **Conversation Cards:**
 - Contact name and avatar
 - Interest badge with score
 - Last message preview
 - Time ago indicator
 - Click to open in inbox

**Interest Badge:**
- **Visual Indicators** - Clear interest signals
 - 🔥 Hot (Flame icon) - Score 7-10
 - 🌡️ Warm (Thermometer icon) - Score 4-6
 - ❄️ Cold (Snowflake icon) - Score 1-3
 - Color-coded badges

**AI-Powered Analysis:**
- **Automated Scoring** - No manual input required
 - Sentiment analysis
 - Intent detection
 - Interest level calculation
 - Summary generation
 - Recommended action suggestions

---

### 24. Agent Performance Dashboard

**Purpose:** Comprehensive agent performance tracking with metrics on deals, conversations, tasks, and productivity.

#### Key Features:

**Deal Metrics:**
- **Won Deals** - Track closed-won deals per agent
 - Deal count
 - Total value
 - Win rate percentage
- **Lost Deals** - Track closed-lost deals
 - Deal count
 - Lost value
 - Loss rate percentage
- **Active Deals** - Current pipeline per agent
 - Deal count
 - Pipeline value
 - Stage distribution

**Conversation Metrics:**
- **Assigned Conversations** - Track workload
 - Open conversations count
 - Response time tracking
 - SLA compliance
- **Messages Sent** - Track activity
 - Message volume
 - Response rate

**Task Metrics:**
- **Completed Tasks** - Track productivity
 - Completion count
 - Completion rate
 - On-time percentage
- **Pending Tasks** - Track backlog
 - Pending count
 - Overdue count

**Performance Scores:**
- **Overall Score** - Combined efficiency metric
 - Weighted performance calculation
 - Ranking among team
- **Trend Indicators** - Performance trends
 - Up/down arrows
 - Comparison with previous period

**Leaderboard:**
- **Team Rankings** - Compare agents
 - Sortable columns
 - Filter by time period
 - Export to CSV
- **Performance Badges:**
 - Trophy icons for top performers
 - Progress bars for metrics

**Time Period Selection:**
- **Flexible Periods** - Analyze different timeframes
 - Today
 - This week
 - This month
 - Custom range

**Access Control:**
- **Admin/Owner Only** - Management visibility
 - Role-based access
 - Organization-scoped data

---

### 25. AI Customer Support Bot

**Purpose:** Intelligent WhatsApp chatbot that automatically responds to customer inquiries using a RAG-based knowledge base, with seamless handoff to human agents.

#### Key Features:

**AI Response Generation:**
- **Knowledge Base Integration** - Answer from your content
 - FAQ documents
 - Product information
 - Policy documents
 - Custom knowledge articles
- **Context-Aware Responses** - Understand conversation context
 - Conversation history analysis
 - Customer information integration
 - Personalized responses

**Multi-Channel Support:**
- **Supported Channels:**
 - WhatsApp Lite (AppGain)
 - WhatsApp Cloud (Meta)
 - Facebook Messenger
 - Telegram
- **Automatic Channel Detection** - Route via correct channel

**Channel-Specific Settings:**
- **Per-Channel Configuration** - Customize per WhatsApp channel
 - Bot personality (friendly, professional, etc.)
 - Language setting (Auto-detect, Arabic, English)
 - Response style
 - Welcome message
 - Response delay (typing simulation)
 - Max response length

**Handoff Triggers:**
- **Keyword-Based Handoff** - Transfer on specific words
 - "human", "agent", "representative"
 - Arabic keywords: "بشري", "موظف", "إنسان", "مساعدة بشرية"
 - Custom keywords
- **Sentiment-Based Handoff** - Transfer on negative sentiment
 - Frustration detection
 - Anger detection
 - Escalation triggers
- **Manual Takeover** - Agent intervention
 - "Take Over" button in inbox
 - Immediate AI deactivation
 - Handoff reason logging

**Bot Activation Control:**
- **Per-Conversation Toggle** - Control AI per conversation
 - AI active indicator
 - Toggle switch in inbox
 - Handoff timestamp tracking
- **Channel-Level Toggle** - Enable/disable per channel
 - AI agent settings per channel
 - Default enabled state

**AI Analysis:**
- **Conversation Insights** - Automatic analysis
 - Interest score (1-10)
 - Interest level (Hot/Warm/Cold)
 - Sentiment (Positive/Neutral/Negative)
 - Intent detection
 - Conversation summary
 - Recommended action

---

### 25b. AI Internal Team Assistant (WhatsApp)

**Purpose:** Allow team members to interact with the CRM system via WhatsApp using natural language commands and AI-powered queries.

#### Key Features:

**WhatsApp Access:**
- **Dedicated Business Number** - Team-only access
 - Configure WhatsApp channel for internal use
 - Toggle between "Customer Bot" and "Internal Assistant" modes
 - Phone number authentication (matched to profiles table)

**Role-Based Permissions:**
- **OWNER/ADMIN** - Full access to all tools
 - Query analytics
 - Update deals
 - Manage contacts
 - Run reports
- **AGENT** - Limited access
 - Query own tasks
 - Check inbox stats
 - Create tasks
 - View contacts

**Available Commands (via AI):**
- **Query Deals** - "Show me this week's deals"
 - Filter by status, stage, date range
 - Get deal counts and total values
- **Query Tasks** - "What are my overdue tasks?"
 - Filter by status, assignee, due date
 - Pending/completed/overdue counts
- **Query Contacts** - "Find contact named Ahmed"
 - Search by name, phone, email
 - Filter by tags
- **Get Inbox Stats** - "How many open conversations?"
 - Open/unassigned/closed counts
 - My conversations count
- **Get Analytics** - "Show me this month's analytics"
 - Deal performance
 - Task metrics
 - Conversation stats
- **Create Task** - "Create a task to follow up with client"
 - Task title, due date, assignee
- **Update Deal Stage** - "Move deal X to negotiation"
- **Add Contact Tags** - "Tag this contact as VIP"

**Conversation History:**
- **Persistent Context** - Maintain conversation flow
 - Per-user conversation history
 - Per-channel account separation
 - Message history stored in database

---

### 26. Task Automation & Distribution

**Purpose:** Automated task creation, assignment, and distribution using intelligent assignment strategies.

#### Key Features:

**Assignment Strategies:**
- **Round-Robin** - Rotate among agents
 - Equal distribution
 - Skip offline agents
 - Track assignment order
- **Workload-Based** - Minimize agent workload
 - Count open tasks per agent
 - Assign to least busy agent
 - Real-time workload calculation
- **Availability-Based** - Respect working hours
 - Check agent availability slots
 - Timezone-aware scheduling
 - Skip unavailable agents
- **Skills-Matching** - Match task to expertise
 - Agent skill tags
 - Task category matching
 - Weight multipliers for expertise level

**Automated Task Creation:**
- **Trigger-Based Tasks** - Create tasks automatically
 - Deal stage change triggers
 - Conversation event triggers
 - Time-based triggers
- **Task Configuration:**
 - Task title templates
 - Priority assignment
 - Due date calculation
 - Assignee selection (manual or auto)

**Escalation & Notifications:**
- **Overdue Alerts** - Notify on overdue tasks
 - Escalation rules
 - Manager notifications
 - Assignment reassignment
- **Workload Dashboard** - Monitor team capacity
 - Agent workload view
 - Task distribution charts
 - Bottleneck identification

**Audit Logging:**
- **Task Automation Logs** - Complete audit trail
 - Trigger events
 - Assignment decisions
 - Strategy used
 - Timestamp tracking

---

### 27. Cross-Channel Response

**Purpose:** Flexibility to receive messages on one channel and respond via a different channel, particularly useful for WhatsApp Cloud to WhatsApp Lite routing.

#### Key Features:

**Channel Override:**
- **Response Channel Selection** - Choose reply channel
 - Dropdown in message thread
 - Per-conversation preference
 - Persisted to database
- **Supported Combinations:**
 - Receive WhatsApp Cloud → Respond WhatsApp Lite
 - Receive WhatsApp Lite → Respond WhatsApp Cloud
 - Cross-channel flexibility

**Credential Handling:**
- **Automatic Credential Resolution** - Use correct API keys
 - Response channel takes priority
 - Appgain credentials for WhatsApp Lite
 - Meta credentials for WhatsApp Cloud
- **Cross-Channel Metadata** - Audit trail
 - Original channel ID
 - Response channel ID
 - Sent via channel tracking

**Use Cases:**
- **Cost Optimization** - Use cheaper channel for responses
- **Business Number Consistency** - Respond from business number
- **Backup Channel** - Fallback if primary channel has issues

---

### 28. Internal AI Web Assistant (Admin)

**Purpose:** In-app AI-powered assistant that helps administrators manage the platform with natural language commands and voice input.

#### Key Features:

**AI Assistant Widget:**
- **Floating Chat Widget** - Accessible from anywhere in the app
 - Expandable chat interface
 - Minimizable to icon
 - Admin-only visibility
 - Modern animated UI

**Voice Input:**
- **Speech-to-Text Support** - Speak your commands
 - Microphone button for voice input
 - Real-time transcription
 - Multi-language support
 - Audio recording indicator

**Natural Language Commands:**
- **Platform Management** - Control the platform via chat
 - "Show me today's analytics"
 - "List my open deals"
 - "What's my team's performance?"
 - "Create a new contact named..."
 - "Search for customer..."

**Tool Execution:**
- **Automated Actions** - AI executes platform tasks
 - Query database for information
 - Run analytics queries
 - Fetch deal and contact data
 - Generate reports
 - Access organization settings

**Conversation History:**
- **Persistent Chat** - Maintain conversation context
 - Per-channel account conversations
 - Message history display
 - Markdown rendering support
 - Timestamp display

**Security:**
- **Admin-Only Access** - Restricted to admins
 - Role-based visibility
 - Secure API calls
 - Authentication required

---

### 29. Admin Subscription Sync

**Purpose:** Administrative utility for synchronizing Stripe subscription data with the database to ensure all team members have proper access.

#### Key Features:

**Sync Functionality:**
- **One-Click Sync** - Synchronize all subscriptions
 - Stripe to database sync
 - Update subscription status
 - Ensure access consistency
 - Batch processing

**Results Display:**
- **Sync Results** - Clear feedback on sync operation
 - Number of subscriptions synced
 - Number of errors encountered
 - Success/failure indicators
 - Detailed error messages

**Access Control:**
- **Admin Restricted** - Only accessible by administrators
 - Protected route
 - Role validation
 - Organization scoping

**Use Cases:**
- Fix subscription access issues
- Ensure team members have correct permissions
- Debug billing discrepancies
- Verify subscription status after Stripe changes

---

### 30. Sales Pipeline Report (`/sales-report`)

**Purpose:** Comprehensive sales pipeline analysis with stage-by-stage breakdown, deal metrics, and export capabilities.

#### Key Features:

**Pipeline Selection:**
- **Multi-Pipeline Support** - Analyze any pipeline
 - Dropdown selection for all pipelines
 - Default pipeline auto-selection
 - Real-time data refresh
- **Assignee Filtering** - Filter by deal owner
 - All assignees view
 - Unassigned deals view
 - Individual team member filtering

**Report Metrics:**
- **Summary Cards** - Key performance indicators
 - Total stages count
 - Total deals count
 - Total pipeline value
 - Average deal value
- **Stage-by-Stage Breakdown:**
 - Deals per stage
 - Total value per stage
 - Average probability per stage
 - Visual stage color coding

**Report Presentation:**
- **Collapsible Sections** - Organized view
 - Expand/collapse individual stages
 - Expand All/Collapse All toggle
 - Deal table per stage
- **Deal Details Table:**
 - Deal name
 - Contact name
 - Company name
 - Description
 - Value (formatted currency)
 - Expected close date
 - Probability percentage

**Export Capabilities:**
- **CSV Export** - Download report data
 - Stage summaries
 - Individual deal details
 - Grand total row
 - Timestamped filename
- **Quick Actions:**
 - View deal details
 - Open deal in pipeline
 - View contact conversation

**Access Control:**
- **Admin/Owner Only** - Management visibility
 - CRM access required
 - Agent role excluded
 - Organization-scoped data

---

### 31. Templates (`/templates`)

**Purpose:** Manage reusable message templates for quick replies, broadcast campaigns, and bot flows.

#### Key Features:

**Template Management:**
- **Create Templates** - Build reusable message templates
 - Template name and category
 - Rich text message body
 - Image attachment support
 - Variable placeholders
- **Edit & Delete Templates** - Full CRUD operations
- **Search & Filter** - Find templates by name or category
- **Template Table** - List view with sortable columns
 - Name, category, created date, last updated
 - Quick actions (edit, duplicate, delete)
- **Duplicate Templates** - Copy existing templates
- **Permission-Based Delete** - Role-based deletion control

**Template Categories:**
- Quick Reply templates
- Broadcast templates
- Bot flow message templates

---

### 32. REST APIs & Webhooks

**Purpose:** Comprehensive API layer for external integrations, allowing third-party systems to create leads, deals, and contacts programmatically.

#### Key Features:

**Lead Creation API:**
- **Single Lead** - `POST /functions/v1/create-lead`
 - API key authentication
 - Contact creation with first/last name, email, phone
 - Optional deal creation alongside lead
 - Source and tag assignment
 - Custom fields support
- **Bulk Leads** - `POST /functions/v1/create-leads-bulk`
 - Batch creation of multiple leads
 - Same fields as single lead
 - Error reporting per record

**Bulk Deal Creation API:**
- **Create Deals** - `POST /functions/v1/create-deals-bulk`
 - Create up to 100 deals per request
 - Contact matching by email, phone, or ID
 - Auto-create missing contacts (`create_contact_if_missing`)
 - Skip duplicates (`skip_if_exists`)
 - Default currency and stage settings
 - Contact first/last name for auto-creation

**Message Translation API:**
- **Translate Messages** - `POST /functions/v1/translate-message`
 - Arabic ↔ English translation
 - Auto-detect source language
 - Powered by MyMemory translation API
 - Used in inbox for real-time message translation

**Email Tracking:**
- **Open Tracking** - `GET /functions/v1/email-tracking-pixel`
 - Invisible tracking pixel for email open detection
 - Open count and timestamp logging
- **Click Tracking** - `GET /functions/v1/email-tracking-redirect`
 - Link click tracking with redirect
 - Click count and timestamp logging
 - Original URL preservation

**Service Monitoring:**
- **Health Check** - `GET /functions/v1/service-monitoring`
 - System status endpoint
 - Service availability verification

**Kommo Import:**
- **Import Leads from Kommo** - `POST /functions/v1/import-kommo-leads`
 - Import leads from Kommo CRM
 - Field mapping and data transformation
 - Batch processing

**RAG Knowledge Base Rebuild:**
- **Qdrant Rebuild** - `POST /functions/v1/qdrant-rebuild`
 - Rebuild vector search index for AI knowledge base
 - Re-embed all knowledge base documents
 - Used by AI customer support bot for RAG queries

**n8n Integration:**
- **Flow Deployment** - `POST /functions/v1/n8n-deploy-flow`
 - Deploy bot flows to n8n workflow engine
 - Webhook URL configuration
 - Workflow ID tracking
- **Flow Callback** - `POST /functions/v1/n8n-flow-callback`
 - Receive workflow execution results
 - Update flow session state

---

### 33. Login Schedule & Agent Workload

**Purpose:** Configure team member work schedules and monitor agent capacity in real-time.

#### Key Features:

**Login Schedule:**
- **Per-Agent Work Hours** - Define weekly work schedules
 - Day-by-day schedule configuration
 - Start and end time per day
 - Enable/disable days
 - Applied per team member
 - Used for availability-based task assignment

**Agent Workload Dashboard:**
- **Real-Time Capacity View** - Monitor agent workload
 - Active tasks per agent
 - Open conversations per agent
 - Availability status
 - Capacity percentage
 - Used in task automation for workload-based assignment

---

### 34. Error Monitoring & Reliability

**Purpose:** Production error tracking and application reliability features.

#### Key Features:

**Sentry Integration:**
- **Error Tracking** - Automatic error capture and reporting
 - JavaScript error monitoring
 - React Error Boundary integration
 - Stack trace collection
 - User context attachment
 - Environment-based configuration

**Error Boundary:**
- **Graceful Error Handling** - Prevent full app crashes
 - Component-level error boundaries
 - User-friendly error messages
 - Recovery options (retry, reload)

**Network Status:**
- **Connection Monitoring** - Real-time connectivity status
 - Online/offline detection
 - Visual status indicator
 - Auto-reconnect handling

**Realtime Status:**
- **WebSocket Health** - Supabase realtime connection monitoring
 - Connection state indicator
 - Auto-reconnect on disconnect

---

### 35. Shared Content System (`/shared/:token`)

**Purpose:** Generate secure, shareable links for deals, contacts, companies, tasks, and pipeline reports with password protection and access tracking.

#### Key Features:

**Shareable Entity Types:**
- **Deals** - Share deal details externally
 - Deal title and value
 - Contact and company information
 - Stage and probability
 - Expected close date
 - Products list (if configured)
- **Contacts** - Share contact profiles
 - Name and basic info
 - Phone numbers and emails
 - Company association
 - Tags
- **Companies** - Share company profiles
 - Company details
 - Address information
 - Industry and size
 - Website and social links
- **Tasks** - Share task details
 - Task title and description
 - Status and priority
 - Due date
 - Assignee information
- **Pipeline Reports** - Share sales reports
 - Full pipeline breakdown
 - Stage-by-stage analysis
 - Deal tables
 - Total value summary

**Security Features:**
- **Password Protection** - Optional password requirement
 - Password hash storage
 - Password validation UI
 - Invalid password feedback
- **Expiration Control** - Time-limited access
 - Set expiration date
 - Automatic link expiration
- **Access Tracking** - Monitor link usage
 - View count tracking
 - Access timestamp logging

**Sharing Settings:**
- **Sensitive Data Control** - Privacy options
 - Show/hide sensitive data toggle
 - Contact information masking
 - Financial data visibility
- **Download Permission** - Control downloads
 - Enable/disable download button
 - PDF export (future)

**Public View:**
- **Branded Experience** - Professional presentation
 - Clean, modern UI
 - Entity-specific layouts
 - ConnectGain branding
 - "Get it now" promotion link
- **Mobile Responsive** - Works on all devices
 - Touch-friendly interface
 - Responsive tables
 - Mobile-optimized forms

### 36. Social Media Planner (`/social-media`)

**Purpose:** Schedule, publish, and manage social media content across Facebook, Instagram, and LinkedIn from a unified visual calendar.

#### Key Features:

**Content Calendar:**
- **Visual Calendar View** - Read-only **month** grid
 - Each day shows up to 3 posts (with `+N more`), placed by `scheduled_at`
 - Status indicators: Draft, Scheduled, Publishing, Published, Partially Failed, Failed
 - (No drag-and-drop or click-to-create yet — create/edit via Composer & Library)
- **Content Library** - Searchable list with **status** and **content-type** filters, plus per-post Delete and Publish-now/Retry

**Supported Platforms & Formats:**
- **Facebook Pages** - Publishing via token reuse from Messenger channel
- **Instagram Business** - Publishing via token reuse from Instagram channel
- **LinkedIn** - Publishing via OAuth + v202401 API
- *X (Twitter) and TikTok content formats are selectable in the composer, but the `social-publish` engine currently publishes only to Facebook, Instagram, and LinkedIn — X/TikTok auto-publish is not yet implemented.*
- **11 Content Formats:**
 - Text, Image, Carousel, Video, Reel, Story
 - GIF, Document, Link, Poll, Thread
 - (Each format advertises the platforms it supports; see the app)

**Post Composer:**
- **Editor** - Title, content, comma-separated hashtags
- **Media Upload** - Images/videos/PDF (100 MB) with per-type count/min/max rules
- **Platform Previews** - Live preview of how the post looks on each platform
- **Poll / Thread / Link composers** - Stored on the post (polls & threads are not yet published to platform APIs)
- **Scheduling** - `datetime-local` picker; the chosen local time is stored as a UTC instant

**Publishing Engine:**
- **Token Reuse** - Reuses Facebook/Instagram/LinkedIn tokens from connected channel accounts
- **Auto-Publish** - `social-scheduler` cron runs every minute, atomically claims due posts, and calls `social-publish`
- **Immediate publish & manual Retry** - Publish now from the Composer, or retry failed posts from the Library
- **Per-platform results** - `social_post_platforms` records `external_post_id` / error per platform; final status is `published`, `partially_failed`, or `failed`
- **Actionable errors** - Meta token/permission errors are translated (e.g. reconnect channel, missing `pages_manage_posts` scope)

**Analytics:**
- **Post counts** - Total / Published / Drafts / Failed, plus breakdowns by content type and platform
- *(Platform reach/impressions/engagement are not pulled from platform APIs yet — `engagement_data` is reserved for future use)*
- **Content Library** - Reuse media across posts via the signed-upload storage bucket (or per-org S3/R2)

**Team Collaboration:**
- **Approval Workflow** - Submit for OWNER/ADMIN review with comment threads
- **Role-Based Access** - OWNER/ADMIN full access; AGENT create drafts and view own posts
- **Feature Gated** by `social_media_planner` in organization settings

---

### 37. Products (`/products`)

**Purpose:** Maintain a product catalog that can be attached to deals as line items.

#### Key Features:

**Catalog Management:**
- **Product Table** - List view of all products with search
- **Create & Edit** - Product form dialog for adding and updating products
- **Bulk Import** - Import multiple products at once via a bulk import dialog
- **Deal Linkage** - Products are used as deal line items in the sales pipeline

---

### 38. Inbox Health (`/inbox-health`)

**Purpose:** Monitor messaging delivery health, queue backlog, and channel status across the inbox.

#### Key Features:

**Monitoring:**
- **Delivery Latency** - Message delivery-latency metrics
- **Message Queue** - Message-queue monitoring for backlog visibility
- **Channel Health Grid** - Per-channel health status overview
- **DLQ Monitor** - Dead-letter-queue monitoring for failed deliveries
- **Conversation Pipeline** - Conversation processing pipeline view

---

### 39. Meeting Recordings (`/meeting-recordings`)

**Purpose:** Review synced meeting recordings and their follow-ups in one place.

#### Key Features:

**Recordings:**
- **Synced Recordings** - Meeting recordings synced from connected providers
- **Follow-Ups** - Post-meeting follow-up tracking

---

### Supported Channels

**1. WhatsApp Lite (AppGain)**
- QR code authentication
- Phone number messaging
- Media support (images, videos, documents)
- Delivery and read receipts
- Template messaging
- Link shortening
- Warming campaigns

**2. WhatsApp Cloud (Meta)**
- Meta WhatsApp Business API integration
- OAuth authentication via Facebook
- Approved template messaging
- Rich media support
- Interactive buttons
- Delivery and read receipts
- Business verification

**3. Facebook Messenger**
- Facebook Messenger API integration
- OAuth authentication
- Page connection
- Quick replies
- Buttons and carousels
- Media support
- Typing indicators

**4. Instagram Direct Messages**
- Instagram Graph API integration
- OAuth authentication
- Business account connection
- Media support
- Story mentions
- Direct messaging
- Message requests

**5. Telegram**
- Telegram Bot API integration
- Bot token authentication
- Sticker support
- Poll support
- Media support
- Group messaging
- Channel broadcasting

**6. TikTok**
- TikTok Business Messaging integration
- OAuth authentication (`tiktok-oauth`)
- Direct messaging
- Media support
- Business account features

**7. Email**
- IMAP/SMTP integration
- Email sending (SMTP and Amazon SES)
- Email receiving
- HTML email support
- Attachment support
- Email threading
- Open/click tracking (pixel + redirect)

**8. SMS** *(broadcast / sequences only — not shown in the unified inbox)*
- SMS gateway via Appgain Notify (VictoryLink provider)
- Character limit management (160 / 1600 concatenated)
- Delivery tracking
- Link shortening
- Outbound campaigns and drip sequences only — there is no inbound SMS webhook and SMS conversations do not appear in the inbox

**9. LinkedIn**
- LinkedIn OAuth + messaging webhooks
- v202401 publishing API (Social Media Planner)
- Direct messaging
- Media support

**10. Shopify Inbox**
- Shopify custom-app integration (`shopify-inbox-webhook`)
- Inbound and outbound store-chat messaging
- Media support

**11. Web Push Notifications**
- Web Push API support
- Background notifications (works when app is closed)
- Android support (Chrome, Firefox, Samsung Internet)
- iOS support (Safari PWA, iOS 16.4+)
- Automatic subscription management
- VAPID key authentication
- Service worker integration
- Notification click handling

**12. ShrinkIt Push Notifications** *(channel type `n_PUSH` / `SHRINKIT_PUSH`)*
- Push notification support
- Mobile app integration
- Notification delivery

### Channel Features

**Unified Inbox:**
- All channels in one conversation list
- Channel badges for identification
- Channel-specific formatting
- Channel-specific actions

**Real-Time Sync:**
- Instant message delivery
- Live status updates
- Real-time conversation sync
- Multi-device support

**Channel Management:**
- Multiple channels of same type
- Channel naming
- Channel status (Active/Inactive)
- Channel configuration
- Channel health monitoring

**Channel Statistics:**
- Messages sent/received per channel
- Conversation count per channel
- Response time per channel
- Channel performance metrics

---

## CRM Capabilities

### Contact Management

**Contact Database:**
- Unlimited contacts (plan-dependent)
- Multiple phone numbers per contact
- Multiple email addresses per contact
- Company association
- Custom fields
- Tags system
- Notes and activity timeline

**Contact Organization:**
- Tag-based organization
- Company-based grouping
- Custom field filtering
- Advanced search
- Bulk operations

**Contact Import/Export:**
- CSV import with column mapping
- Kommo CRM import (via integration)
- CSV export
- Data validation and error reporting
- Duplicate detection and merging
- Bulk import progress tracking

### Company Management

**Company Database:**
- Company profiles
- Industry classification
- Company size tracking
- Annual revenue tracking
- Address management
- Contact associations
- Deal associations

**Company Organization:**
- Country-based filtering
- Industry-based filtering
- Tag-based organization
- Search capabilities

### Deal Pipeline Management

**Pipeline Features:**
- Multiple custom pipelines
- Custom stages
- Visual kanban board
- Drag-and-drop deal movement
- Deal value tracking
- Probability tracking
- Expected close dates

**Deal Management:**
- Deal creation from conversations
- Deal creation from contacts
- Deal editing
- Deal deletion
- Deal assignment
- Deal tagging
- Deal notes

**Pipeline Analytics:**
- Stage distribution
- Pipeline value
- Conversion rates
- Average deal value
- Average deal duration
- Win/loss rates

### Task Management

**Task Features:**
- Task creation
- Task assignment
- Priority levels
- Due dates
- Task completion tracking
- Task filtering
- Task search

**Task Organization:**
- Overdue tasks
- Today's tasks
- Upcoming tasks
- Tasks without due dates
- Completed tasks

**Task Views:**
- List view
- Calendar view
- Grouped by status
- Grouped by priority
- Grouped by assignee

---

## Scheduling System

### Overview
ConnectGain Scheduling is a powerful, Calendly-like appointment booking system fully integrated into the ConnectGain platform. It allows team members to manage their availability, create custom event types, and let clients book appointments directly through personalized booking links.

### Key Features

**Event Type Management:**
- Create unlimited event types (e.g., "30-min Demo", "1-hour Consultation")
- Custom duration (5 minutes to 8 hours)
- Unique URL slugs for each event type
- Location options (Google Meet, Zoom, Phone, In-Person, Custom)
- Buffer time between appointments
- Daily booking limits
- Advance notice requirements (e.g., require 24 hours notice)
- Availability window control (e.g., allow bookings up to 60 days in advance)

**Custom Branding Per Event Type:**
- Custom theme colors for booking pages
- Banner image support for visual branding
- Personalized confirmation messages
- Branded booking experience for each event type

**Availability Management:**
- Weekly availability schedules
- Different hours for different days
- Time zone support
- Blocked dates for holidays/time off
- Automatic conflict detection
- Integration with existing calendar events

**Calendar Integrations:**
- **Google Calendar Integration:**
 - OAuth 2.0 secure authentication
 - Automatic event creation with Google Meet links
 - Real-time availability checking
 - Bi-directional sync (checks existing calendar for conflicts)
 - Automatic reminder emails
 - Calendar event updates on rescheduling/cancellation
- **Zoom Integration:**
 - Automatic Zoom meeting creation
 - Join links automatically added to calendar events
 - Meeting details included in booking confirmations
 - Zoom account integration via API
 - Meeting recordings and follow-up capabilities

**Booking Management:**
- Real-time availability calculation
- Guest information collection (name, email, phone, notes)
- Custom booking questions per event type
- Confirmation emails with calendar invites
- Booking confirmation tokens for guest access
- Rescheduling and cancellation support

**Public Booking Pages:**
- Professional public profile pages
- Mobile-responsive booking interface
- Real-time slot availability
- Theme customization per event type
- Clean URLs: `/schedule/username/event-type`
- No login required for guests

**Team Features:**
- Each team member gets their own scheduling profile
- Personalized username slugs
- Individual availability settings
- Personal Google Calendar connections
- Booking notifications and alerts

### Use Cases
- **Sales Teams**: Demo calls and discovery meetings
- **Consultants**: Client consultation bookings
- **Support Teams**: Scheduled support sessions
- **HR Teams**: Interview scheduling
- **Healthcare**: Patient appointment booking
- **Education**: Student office hours
- **Service Businesses**: Service appointment scheduling

### Integration Points
- **CRM Integration**: Automatically create contacts from bookings
- **Deal Creation**: Convert bookings to deals in the pipeline
- **Task Generation**: Create follow-up tasks from appointments
- **Analytics**: Track booking rates and no-shows
- **Automations**: Trigger workflows based on bookings

### Beta Status
The Scheduling System is currently in beta, which means:
- Core functionality is complete and stable
- Some advanced features are still being developed
- User feedback is actively being incorporated
- Regular updates and improvements are being deployed

### Integration Points
- **Zoom Integration** - Automatic Zoom meeting creation with join links
- **Google Calendar Integration** - OAuth 2.0 secure authentication with automatic event creation
- **Microsoft Teams Integration** - Teams meeting integration (coming soon)
- **Calendar Sync** - Bi-directional sync with existing calendar events
- **Meeting Reminders** - Automatic email reminders with calendar invites
- **Timezone Support** - Organization and user timezone handling

### Advanced Features
- **Recurring Appointments** - Recurring booking support (coming soon)
- **Group Events** - Multi-attendee event management (coming soon)
- **Payment Integration** - Payment collection for paid consultations (coming soon)
- **Calendar Feed (iCal)** - iCal feed support (coming soon)
- **SMS Reminders** - SMS notification support (coming soon)
- **Multi-Calendar Support** - Multiple calendar integration (coming soon)
- **Team Round-Robin Scheduling** - Automatic team member rotation (coming soon)

---

## Automation & Workflows

### Bot Flows

**Visual Flow Builder:**
- Drag-and-drop interface
- Node-based design
- Connection management
- Flow validation
- Flow testing
- Flow publishing

**Flow Nodes:**
- 40+ node types
- Conditional logic
- Data transformation
- External API calls
- Database queries
- AI integration
- Error handling

**Flow Management:**
- Version control
- Flow archiving
- Flow duplication
- Flow analytics
- Execution logging

### Automation Rules

**Rule-Based Automation:**
- Event triggers
- Condition matching
- Action execution
- Multi-step workflows
- Error handling

**Trigger Events:**
- Message events
- Contact events
- Deal events
- Conversation events
- Task events

**Actions:**
- Create tasks
- Assign conversations
- Add tags
- Send messages
- HTTP requests
- Update records

**Automation Management:**
- Enable/disable rules
- Rule editing
- Rule deletion
- Execution logging
- Performance tracking

---

## AI-Powered Features

### AI Customer Support Bot

**Automated Response System:**
- Knowledge-base powered responses
- RAG (Retrieval-Augmented Generation) architecture
- Context-aware conversation handling
- Multi-language support (Arabic, English, Auto-detect)

**Handoff Management:**
- Keyword-based handoff triggers
- Sentiment-based escalation
- Manual agent takeover
- Handoff reason tracking
- Conversation context preservation

**Per-Channel Configuration:**
- Individual bot settings per WhatsApp channel
- Personality customization
- Language preferences
- Welcome messages
- Response style configuration

### AI Conversation Analysis

**Automated Insights:**
- Interest scoring (1-10 scale)
- Interest level classification (Hot/Warm/Cold)
- Sentiment analysis (Positive/Neutral/Negative)
- Intent detection
- Conversation summarization
- Recommended next action

**Analysis Triggers:**
- Automatic analysis on conversation activity
- On-demand analysis option
- Batch analysis for existing conversations

**Integration Points:**
- Interest badges in inbox
- Interest analysis dashboard
- Contact enrichment
- Deal prioritization

### AI Web Assistant

**Internal AI Assistant:**
- Chat-based AI assistant for agents
- Knowledge base queries
- Quick information retrieval
- Response suggestions

### Speech-to-Text

**Voice Message Transcription:**
- Automatic transcription of audio messages
- Multi-language support
- Searchable voice content
- Transcription display in inbox

### Call Intelligence AI

**Automated Call Analysis Pipeline:**
- Multi-language transcription (Arabic/English) via Google Gemini 2.5 Flash
- Sentiment analysis with Positive/Neutral/Negative classification and numeric score
- AI-generated call summaries
- Action item extraction with priority levels and auto-task creation
- Keyword extraction and frequency analysis
- Call classification tagging
- Resolution quality scoring
- Silent recording detection (skips billing and analysis)
- Token usage tracking with cost estimation
- Monthly minutes quota management with admin top-up
- Webhook and Mobile API for external system integration

### Message Translation

**Real-Time Translation:**
- Arabic ↔ English message translation
- Auto-detect source language
- In-inbox translation button
- Powered by MyMemory translation API

### Email Tracking

**Open & Click Analytics:**
- Invisible tracking pixel for open detection
- Link click tracking with redirect
- Open and click counts per email
- Timestamp logging for engagement analysis

### AI Re-Engagement

**What it is:**
A paid ConnectGain add-on that uses AI to automatically re-open Messenger and Instagram conversations **before** Meta's 24-hour customer-service window closes.

**What it isn't:**
- Not a way to bypass Meta policy. Nudges are sent strictly **inside** the standard 24h window.
- Not a WhatsApp feature. WhatsApp uses approved templates and is handled separately.
- Not a generic broadcast tool. Each nudge is personalised per conversation.

**Supported Channels:**
- Facebook Messenger
- Instagram Direct
- (WhatsApp, Telegram, TikTok, LinkedIn — not supported)

**Automated Messenger & Instagram Nudges:**
- AI-generated personalised follow-up messages before Meta's 24-hour window closes
- Context-aware drafting based on conversation history, deal stage, and tags
- Tone selection: Friendly, Formal, or Casual
- Configurable trigger threshold: 12–23 hours after customer's last message (default: 20h)
- Hard stop at `last_user_message_at + 24h`
- Max **1 nudge per 24-hour window** per conversation (DB-enforced)
- **3-strike auto-disable safety** — consecutive unanswered nudges pause re-engagement on that conversation
- Customer reply → counter resets, open nudges marked `user_replied`
- Per-conversation kill switch in the inbox
- All nudges logged as `AI_REENGAGEMENT_SENT` activity events

**Agent Approval Mode:**
- Optional require-agent-approval workflow
- AI drafts appear in inbox as review cards
- Actions: Approve, Edit (modify and send), Skip (block for that window)

**AI Provider:**
- Default: **ConnectGain AI** (Lovable AI Gateway, Gemini 2.5 Flash)
- Optional: **BYOK Gemini** — use the org's own Google AI Studio key
 - Scope: "All AI features" or "Re-engagement only"
 - Fallback toggle: temporarily use ConnectGain AI if your key fails

**Roles:**
- **OWNER / ADMIN**: enable, configure, subscribe, set BYOK
- **AGENT**: approve / edit / skip drafts (when approval mode is on)

**Compliance & Data Retention:**
- Uses Meta's standard 24-hour response window — no policy bypass
- BYOK keys encrypted at rest, never returned to the browser
- PII scrubbed from Sentry breadcrumbs
- Nudge drafts and outcomes kept 90 days, then anonymised

**Where to Enable:**
- `Settings → AI & Automation → AI Re-Engagement` (top-level settings tab)
- `Settings → AI & Automation → AI Provider` (for BYOK)

### Reply Assistant

**What it is:**
A paid ConnectGain add-on that suggests **sales-style replies** to agents on demand. In any conversation, the agent clicks **Suggest reply** and gets 2–3 ready-to-send options — grounded in the org's knowledge base + product catalog, written in the org's sales manner, and tuned to the org's **industry**. Designed so a junior agent answers like a seasoned salesperson.

**Works with zero input:**
- Choosing an **industry** is the only required step — it applies a full style preset, a curated built-in best-practice knowledge pack, and the sales playbook.
- Useful from day one; the org's own products/docs only make it more specific.

**Supported industries (extensible):**
- **B2B SaaS** — consultative, ROI-led; objection handling, drive to demo/trial
- **Ecommerce** — recommendation-led; upsell, honest urgency, cart recovery, shipping/returns
- **Tourism & Travel** — experience-led; packages & excursions, deposits/cancellation, seasonality, visas
- **General** — helpful consultative fallback
- Adding industries is additive (one registry entry) — no code branches

**Knowledge base (three ways to fill, all reviewable drafts):**
- **Manual** entry of FAQs / policies / product facts
- **AI auto-seed** — one click drafts entries from products, won deals, and recent customer questions
- **Document upload** — upload KB docs & product-info docs (PDF / TXT / MD / CSV); stored privately, text-extracted, AI-chunked into entries
- Plus a built-in best-practice pack that's always active per industry
- Product names/prices pulled automatically from the products catalog

**Sales manner (admin-configured):**
- Tone, approach, language, "always do" / "never do" rules, signature, suggestions per click
- Pre-filled from the industry preset; every field overridable

**Context-aware (understands the whole relationship):**
- Reads the recent transcript, the conversation AI summary (refreshing it when stale), team notes on the contact/deal, deal stage/value, contact company/tags, and how long ago the customer last wrote
- **Voice notes are transcribed** first, so replies answer what was actually said
- Skips emoji-only, reaction, and sticker messages (nothing to reply to)

**On-demand, cost-controlled:**
- Suggestions are generated only when the agent clicks — no per-message AI spend

**AI Provider:**
- Default: **ConnectGain AI** (Lovable AI Gateway, Gemini 2.5 Flash)
- Optional: **BYOK Gemini** — use the org's own key

**Roles:**
- **OWNER / ADMIN**: subscribe, configure sales manner, manage knowledge base
- **AGENT**: use *Suggest reply* in the inbox

**Where to Enable:**
- `Settings → AI → Reply Assistant`

### BYOK — Bring Your Own Gemini Key

**Use Your Own AI Key:**
- Free to enable — no ConnectGain AI usage charges for that scope
- Get a key from Google AI Studio
- Scope selection:
 - **All AI features** — chatbots, classification, translations, drafts, summaries, re-engagement, call analysis
 - **Re-engagement only**
- Key encrypted at rest, never returned to the browser
- Fallback toggle: temporarily use ConnectGain AI if your key fails
- Full data control and predictable AI costs for high-volume operations

---

## Analytics & Reporting

### Dashboard Analytics

**Real-Time Metrics:**
- Incoming messages
- Ongoing conversations
- Unanswered conversations
- Response times
- Deal metrics
- Task metrics
- Contact growth

**Custom Widgets:**
- Custom metrics
- Database queries
- Aggregations
- Formatting options
- Drag-and-drop positioning

**Performance Charts:**
- 4-week trends
- Conversation trends
- Deal trends
- Contact growth trends

### Detailed Analytics

**Inbox Analytics:**
- Response time metrics
- SLA compliance
- Conversation status
- Unassigned messages
- Overdue conversations

**Sales Analytics:**
- Pipeline performance
- Conversion rates
- Deal value tracking
- Win/loss analysis
- **Sales Pipeline Reports** - Comprehensive reporting
 - Stage-by-stage deal analysis
 - Total value per stage
 - Average deal value calculations
 - Deal count per stage
 - Probability tracking
 - CSV export functionality
 - Collapsible stage sections
 - Deal details with quick actions

**Contact Analytics:**
- Contact growth
- Engagement rates
- Contact sources
- Tag distribution

**AI Conversation Analysis:**
- Automated conversation insights
- Sentiment analysis
- Keyword extraction
- Conversation quality scoring
- Performance recommendations
- Automated tagging and categorization

**Performance Analytics:**
- Task completion rates
- Team productivity
- Overall performance scores

**Attendance Analytics:**
- Agent online status tracking
- Clock in/out times
- Hours worked calculations
- Attendance history
- Real-time status updates

---

## Team Collaboration

### Team Management

**Member Management:**
- Add team members
- Remove team members
- Role assignment
- Permission management
- Availability management
- **Attendance Tracking** - Monitor team attendance
 - Real-time online status
 - Clock in/out tracking
 - Attendance history
 - Hours worked calculations
 - Admin/Owner access only

**Roles & Permissions:**
- Owner role (full access)
- Admin role (manage users)
- Agent role (conversations and contacts)
- Custom permissions
- Permission inheritance

**Invitations:**
- Email invitations
- Invitation links
- Invitation expiration
- Resend invitations
- Cancel invitations

### Collaboration Features

**Conversation Assignment:**
- Assign to team members
- Round-robin assignment
- Auto-assignment based on availability
- Assignment notifications

**Task Assignment:**
- Assign tasks to team members
- Auto-assignment
- Task delegation
- Task collaboration

**Notes & Comments:**
- Internal notes on contacts
- Internal notes on deals
- Activity timeline
- Comment threads

**Availability Management:**
- Set availability slots
- Timezone-aware scheduling
- Availability-based assignment
- Off-hours handling

---

## Integration Capabilities

### API Integration

**REST API:**
- Complete REST API
- Authentication via API keys
- Rate limiting
- API documentation
- Postman collection

**Webhooks:**
- Outbound webhooks
- Event subscriptions
- Webhook retries
- Webhook logging
- Secret key management

**Supported Events:**
- Message events
- Contact events
- Deal events
- Conversation events
- Task events
- Campaign events

### Third-Party Integrations

**AppGain Integration:**
- WhatsApp Lite integration via AppGain platform
- Automatic credential provisioning on user signup
- API key management
- Organization-level credential storage
- Session-based credential access
- Webhook integration for automatic setup

**Kommo CRM Integration:**
- Contact import from Kommo
- Lead import from Kommo
- Data mapping and sync

**Stripe Integration:**
- Subscription management
- Payment processing
- Customer portal
- Webhook handling

**Facebook Integration:**
- OAuth authentication
- Messenger connection
- Instagram connection
- WhatsApp Cloud connection

### Data Import/Export

**Import Capabilities:**
- CSV import (contacts, companies)
- Kommo CRM import (contacts, leads)
- Data validation
- Duplicate detection
- Error reporting
- Import progress tracking

**Export Capabilities:**
- CSV export (contacts, companies)
- Data formatting
- Custom field export
- Bulk export

---

## Security & Compliance

### Security Features

**Authentication:**
- Email/password authentication
- Email verification required
- Password strength requirements
- Password reset functionality
- Session management

**Authorization:**
- Role-based access control
- Permission-based features
- Organization-level isolation
- User-level data access

**Data Security:**
- Encrypted data transmission
- Secure API keys
- Webhook secret keys
- Secure credential storage

### Compliance

**Data Privacy:**
- GDPR considerations
- Data export capabilities
- Data deletion capabilities
- Privacy controls

**Audit Trail:**
- Activity logging
- Change tracking
- User action history
- System event logging

---

## Technical Specifications

### Platform Requirements

**Browser Support:**
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Mobile browsers

**Device Support:**
- Desktop computers
- Tablets
- Mobile phones
- Responsive design
- Touch-optimized

### Performance

**Speed:**
- Fast page loads
- Real-time updates
- Efficient data loading
- Optimized queries
- Caching strategies

**Scalability:**
- Cloud-based infrastructure
- Auto-scaling
- High availability
- Load balancing
- Database optimization

### Reliability

**Uptime & Reliability:**
- Hosted on Supabase (Postgres, Auth, Storage, Realtime) + Lovable/Vercel deployment
- Sentry error monitoring across browser and edge functions
- Health/monitoring edge functions (`service-monitoring`, `token-health-check`) with alerts
- Dead-letter queue + `retry-dlq` cron for webhook resilience
- *(Specific uptime-SLA / disaster-recovery commitments are governed by the hosting providers' SLAs, not a ConnectGain guarantee.)*

---

## Support & Resources

### Documentation

**User Guides:**
- Getting started guide
- Feature documentation
- API documentation
- Integration guides
- Best practices

**Help System:**
- In-app help hotspots
- Contextual tooltips
- Video tutorials
- FAQ section
- Troubleshooting guides

### Support Channels

**Support Options:**
- Email support
- In-app help
- Documentation portal
- Community forum (if available)
- Priority support (plan-dependent)

---

## Industry Use Cases

### Real Estate & Proptech

ConnectGain is perfectly suited for real estate agencies, property management companies, real estate developers, and proptech platforms. The platform streamlines property inquiries, lead management, client communication, and deal tracking.

#### Lead Management & Inquiry Handling

**Property Inquiry Management:**
- **Multi-Channel Property Inquiries** - Receive inquiries from WhatsApp, Messenger, Instagram, Email, and SMS
 - Unified inbox for all property inquiries
 - Instant notifications for new inquiries
 - Channel identification (Instagram for visual properties, WhatsApp for quick questions)
 - Auto-assignment to property agents based on availability
- **Inquiry Qualification** - Automated bot flows to qualify leads
 - Budget range questions
 - Property type preferences (apartment, house, commercial)
 - Location preferences
 - Timeline questions (immediate, 3 months, 6 months)
 - Contact information collection
- **Lead Scoring** - Automatically score leads based on responses
 - High-value leads flagged immediately
 - Follow-up task creation for qualified leads
 - Deal creation from qualified inquiries

**Property Showings & Viewings:**
- **Automated Scheduling** - Bot flows for property viewing appointments
 - Available time slot display
 - Calendar integration
 - Confirmation messages
 - Reminder notifications (24 hours before, 2 hours before)
 - Rescheduling options
 - Cancellation handling
- **Viewing Confirmation** - Automated confirmation workflows
 - SMS/WhatsApp confirmations
 - Property details and address
 - Agent contact information
 - Directions and parking information
 - What to bring checklist

**Follow-Up Automation:**
- **Post-Viewing Follow-Up** - Automated follow-up sequences
 - Thank you message after viewing
 - Feedback request (24 hours after viewing)
 - Additional property suggestions based on preferences
 - Price reduction notifications
 - New listing alerts matching criteria
- **Nurture Campaigns** - Long-term lead nurturing
 - Weekly market updates
 - Neighborhood guides
 - Financing information
 - Property investment tips

#### Client Relationship Management

**Buyer Journey Tracking:**
- **Deal Pipeline Management** - Track buyers through sales process
 - Pipeline stages: Inquiry → Qualified → Viewing Scheduled → Offer Submitted → Under Contract → Closed
 - Deal value tracking (purchase price)
 - Commission tracking
 - Expected close date management
 - Probability tracking based on stage
- **Contact Segmentation** - Organize contacts by buyer type
 - Tags: First-time buyer, Investor, Relocator, Luxury buyer
 - Budget ranges: Under $500K, $500K-$1M, $1M-$2M, $2M+
 - Property types: Residential, Commercial, Land, Investment
 - Location preferences: Downtown, Suburbs, Waterfront, etc.

**Seller Management:**
- **Listing Management** - Track property listings
 - Property details in deal records
 - Listing price tracking
 - Days on market tracking
 - Viewing count tracking
 - Offer tracking
- **Seller Communication** - Automated seller updates
 - Viewing notifications
 - Offer notifications
 - Market activity reports
 - Price adjustment recommendations

**Tenant Management (Property Management):**
- **Tenant Onboarding** - Automated tenant communication
 - Welcome messages with move-in instructions
 - Lease document delivery
 - Payment setup instructions
 - Property access codes
 - Emergency contact information
- **Maintenance Requests** - Handle maintenance inquiries
 - Maintenance request intake via bot flows
 - Priority classification (Emergency, Urgent, Normal)
 - Vendor assignment
 - Status updates to tenants
 - Completion confirmations
- **Rent Collection** - Automated rent reminders
 - Rent due reminders (5 days before, 1 day before)
 - Payment confirmation messages
 - Late payment notifications
 - Payment link delivery

#### Marketing & Campaigns

**Property Marketing Campaigns:**
- **New Listing Announcements** - Broadcast new properties
 - WhatsApp Business campaigns for new listings
 - Rich media (property photos, virtual tours)
 - Property details and pricing
 - Open house announcements
 - Target by buyer preferences (tags, budget, location)
- **Price Reduction Alerts** - Notify interested buyers
 - Automated price drop campaigns
 - Target contacts who viewed property
 - Personalized messages with new price
- **Open House Invitations** - Event marketing
 - SMS/WhatsApp invitations
 - Calendar integration
 - RSVP tracking
 - Reminder messages

**Lead Generation Campaigns:**
- **Social Media Lead Capture** - Convert social media inquiries
 - Instagram DM to CRM integration
 - Facebook Messenger property inquiries
 - Automated lead qualification
- **Referral Programs** - Client referral campaigns
 - Referral request messages
 - Referral tracking
 - Reward notifications

#### Analytics & Performance

**Real Estate Metrics:**
- **Lead Conversion Tracking** - Track inquiry to closing
 - Inquiry source analysis (Instagram, WhatsApp, Website, Referral)
 - Conversion rates by channel
 - Average time to close
 - Lead quality scoring
- **Agent Performance** - Track agent metrics
 - Response time tracking
 - Inquiry handling volume
 - Conversion rates per agent
 - Commission tracking
- **Property Performance** - Analyze property metrics
 - Views per property
 - Inquiries per property
 - Time on market
 - Price reduction impact

**Reporting:**
- **Monthly Reports** - Automated performance reports
 - New leads by source
 - Conversions by stage
 - Revenue tracking
 - Agent performance summaries
- **Market Insights** - Property market analytics
 - Inquiry trends
 - Popular property types
 - Price range preferences
 - Location preferences

#### Integration Use Cases

**Property Management Software Integration:**
- **PMS Integration** - Connect with property management systems
 - Sync tenant information
 - Maintenance request sync
 - Payment status updates
 - Lease renewal reminders
- **CRM Integration** - Connect with real estate CRMs
 - Lead sync
 - Property data sync
 - Activity logging

**Website Integration:**
- **Property Website Chat** - Website chat widget
 - Live chat integration
 - Property inquiry capture
 - Instant bot responses
 - Agent handoff

**Virtual Tour Integration:**
- **Virtual Tour Follow-Up** - Post-tour automation
 - Thank you messages after virtual tours
 - Feedback requests
 - In-person viewing scheduling
 - Additional property suggestions

#### Specific Real Estate Scenarios

**Scenario 1: New Property Listing**
1. Property listed on website and social media
2. Instagram inquiry received → Auto-qualified via bot flow
3. Qualified lead assigned to agent
4. Deal created in pipeline
5. Viewing scheduled via automated flow
6. Post-viewing follow-up automated
7. Offer submitted → Deal moved to "Under Contract"
8. Closing → Deal marked "Closed Won"

**Scenario 2: Property Management Maintenance**
1. Tenant sends WhatsApp message: "AC not working"
2. Bot flow collects details (unit, issue description, urgency)
3. High-priority task created automatically
4. Vendor assigned based on issue type
5. Tenant receives confirmation and ETA
6. Vendor completes work → Status update sent to tenant
7. Follow-up satisfaction survey sent

**Scenario 3: Buyer Lead Nurturing**
1. Website visitor downloads neighborhood guide
2. Contact created with tag "Downloaded Guide"
3. Automated nurture sequence starts:
 - Day 1: Welcome message + market report
 - Day 3: Financing options guide
 - Day 7: Featured properties matching preferences
 - Day 14: Open house invitations
 - Weekly: Market updates and new listings
4. When ready, contact responds → Qualified and assigned to agent

---

### Tourism & Hospitality

ConnectGain empowers tourism businesses, travel agencies, hotels, tour operators, and hospitality companies to deliver exceptional customer experiences through seamless multi-channel communication and automated workflows.

#### Booking Management & Inquiries

**Travel Inquiry Handling:**
- **Multi-Channel Booking Inquiries** - Receive inquiries from all channels
 - WhatsApp for international travelers (most popular)
 - Instagram for visual travel inspiration
 - Facebook Messenger for package inquiries
 - Email for detailed itineraries
 - SMS for booking confirmations
- **Automated Booking Bot** - Intelligent booking assistant
 - Destination questions
 - Travel dates collection
 - Number of travelers
 - Budget range
 - Travel preferences (beach, mountain, city, adventure)
 - Accommodation preferences (hotel, resort, villa, hostel)
 - Meal preferences (all-inclusive, breakfast only, self-catering)
- **Availability Checking** - Real-time availability integration
 - Check hotel availability
 - Flight availability
 - Tour availability
 - Instant availability responses

**Booking Confirmation & Management:**
- **Automated Confirmations** - Instant booking confirmations
 - WhatsApp/SMS confirmation messages
 - Booking reference numbers
 - Itinerary details
 - Payment instructions
 - Cancellation policy
 - Contact information
- **Pre-Travel Communication** - Automated pre-travel sequences
 - 7 days before: Final details and reminders
 - 3 days before: Weather forecast and packing tips
 - 1 day before: Check-in instructions and contact details
 - Day of travel: Real-time updates and support

**Modification & Cancellation:**
- **Booking Changes** - Handle modifications via chat
 - Date changes
 - Guest count changes
 - Room/tour upgrades
 - Special requests
- **Cancellation Handling** - Automated cancellation process
 - Cancellation request intake
 - Refund calculation
 - Cancellation confirmation
 - Future booking incentives

#### Customer Service & Support

**24/7 Customer Support:**
- **Multi-Language Support** - Serve international travelers
 - Bot flows in multiple languages
 - Agent handoff for complex queries
 - Translation capabilities
- **Common Queries Automation** - Handle frequent questions
 - "What's included in the package?"
 - "What are the check-in/check-out times?"
 - "Do you provide airport transfers?"
 - "What documents do I need?"
 - "What's the cancellation policy?"
- **Emergency Support** - Handle urgent situations
 - Priority routing for emergencies
 - 24/7 agent availability
 - Quick response guarantees

**During-Stay Support:**
- **Concierge Services** - Hotel concierge via messaging
 - Restaurant recommendations
 - Activity bookings
 - Transportation arrangements
 - Room service orders
 - Maintenance requests
- **Real-Time Assistance** - Immediate support during travel
 - Lost luggage assistance
 - Medical emergencies
 - Travel disruptions
 - Local recommendations

#### Marketing & Promotions

**Promotional Campaigns:**
- **Seasonal Campaigns** - Targeted seasonal promotions
 - Summer vacation packages
 - Winter getaway deals
 - Holiday specials
 - Last-minute deals
- **Personalized Offers** - Targeted marketing
 - Past traveler specials
 - Birthday offers
 - Anniversary packages
 - Loyalty program benefits
- **Destination Marketing** - Promote specific destinations
 - New destination launches
 - Special event promotions (festivals, sports events)
 - Weather-based promotions

**Upselling & Cross-Selling:**
- **Service Upselling** - Increase booking value
 - Room upgrades
 - Additional services (spa, tours, transfers)
 - Travel insurance
 - Meal plan upgrades
- **Cross-Selling** - Related service promotion
 - Car rentals
 - Travel insurance
 - Excursions and tours
 - Restaurant reservations

#### Post-Travel Engagement

**Feedback Collection:**
- **Automated Feedback Requests** - Collect reviews and feedback
 - Post-checkout feedback request (24 hours after)
 - Review platform integration
 - Photo sharing requests
 - Improvement suggestions
- **Review Management** - Handle reviews
 - Positive review thank you messages
 - Negative review follow-up and resolution
 - Review response automation

**Loyalty & Retention:**
- **Loyalty Program** - Reward repeat customers
 - Points tracking
 - Tier status notifications
 - Exclusive offers for members
 - Birthday rewards
- **Re-Engagement Campaigns** - Win back customers
 - "We miss you" campaigns
 - Special return offers
 - New destination suggestions
 - Anniversary reminders

#### Group Travel Management

**Group Bookings:**
- **Group Inquiry Handling** - Manage group travel
 - Group size collection
 - Special requirements
 - Custom itinerary requests
 - Group discount information
- **Group Communication** - Coordinate with groups
 - Group WhatsApp broadcasts
 - Itinerary updates
 - Meeting point notifications
 - Group activity reminders

**Corporate Travel:**
- **Corporate Account Management** - B2B travel services
 - Corporate account setup
 - Preferred rates
 - Booking approvals workflow
 - Expense reporting integration

#### Analytics & Performance

**Tourism Metrics:**
- **Booking Analytics** - Track booking performance
 - Bookings by channel (WhatsApp, Instagram, Website)
 - Conversion rates by source
 - Average booking value
 - Booking lead time
- **Customer Satisfaction** - Measure satisfaction
 - Response time tracking
 - Customer satisfaction scores
 - Review ratings
 - Repeat booking rate
- **Destination Performance** - Analyze popular destinations
 - Most booked destinations
 - Seasonal trends
 - Package popularity
 - Revenue by destination

**Operational Metrics:**
- **Agent Performance** - Track support team
 - Response times
 - Resolution rates
 - Customer satisfaction per agent
 - Booking conversion per agent
- **Channel Performance** - Optimize channel usage
 - Most effective channels
 - Cost per booking by channel
 - Customer preference by channel

#### Specific Tourism Scenarios

**Scenario 1: Hotel Booking Journey**
1. Instagram ad clicked → DM inquiry received
2. Bot flow collects: dates, guests, preferences
3. Availability checked → Options presented
4. Booking confirmed via WhatsApp
5. Payment link sent → Payment received
6. Confirmation with booking details
7. Pre-arrival sequence (7 days, 3 days, 1 day before)
8. Check-in day: Welcome message + room details
9. During stay: Concierge support available
10. Check-out: Feedback request
11. Post-stay: Thank you + loyalty program enrollment

**Scenario 2: Tour Package Inquiry**
1. Website visitor requests "Adventure Tour Package"
2. Bot flow qualifies: destination, dates, group size, experience level
3. Qualified lead assigned to tour specialist
4. Custom itinerary created and shared via WhatsApp
5. Questions answered → Booking confirmed
6. Pre-tour information sent (what to bring, meeting point)
7. Day before: Final reminders and weather update
8. Tour day: Real-time updates and support
9. Post-tour: Thank you + review request + photo sharing
10. Follow-up: Related tour suggestions

**Scenario 3: Travel Agency Customer Service**
1. Customer sends WhatsApp: "My flight was cancelled"
2. Urgent priority assigned automatically
3. Agent responds within SLA (under 5 minutes)
4. Alternative flight options researched
5. New flight booked → Confirmation sent
6. Hotel notified of late arrival
7. Transfer rescheduled
8. Customer updated with all changes
9. Compensation process initiated
10. Follow-up: Satisfaction check + future booking discount

**Scenario 4: Seasonal Campaign**
1. "Summer Sale" campaign created
2. Target: Contacts tagged "Past Traveler" + "Beach Lover"
3. WhatsApp Business campaign sent with:
 - Beautiful destination images
 - Special package pricing
 - Limited-time offer
 - Booking link
4. Interested contacts click → Bot flow captures interest
5. Qualified leads assigned to agents
6. Follow-up calls scheduled
7. Bookings tracked in deals pipeline
8. Campaign performance analyzed:
 - Open rate, click rate, conversion rate
 - Revenue generated
 - ROI calculation

#### Integration Use Cases

**Booking System Integration:**
- **PMS Integration** - Property Management System
 - Real-time availability sync
 - Booking creation automation
 - Room assignment notifications
- **OTA Integration** - Online Travel Agencies
 - Booking.com, Expedia sync
 - Rate parity management
 - Channel performance tracking

**Payment Gateway Integration:**
- **Payment Processing** - Secure payment handling
 - Payment link generation
 - Payment confirmation
 - Refund processing
 - Invoice generation

**Travel Technology Integration:**
- **Flight APIs** - Flight availability and booking
- **Hotel APIs** - Hotel availability and rates
- **Weather APIs** - Weather forecasts for travelers
- **Currency APIs** - Real-time exchange rates

---

## Conclusion

ConnectGain is a comprehensive, enterprise-ready customer engagement platform that combines multi-channel messaging, CRM, AI-powered automation, scheduling, and analytics into one powerful solution. With support for 11 messaging channels (including Web Push Notifications), advanced AI capabilities, visual automation builders, and comprehensive analytics, ConnectGain empowers businesses to deliver exceptional customer experiences while streamlining operations and driving growth.

**Key Differentiators:**
- Unified multi-channel inbox with cross-channel response
- AI-powered customer support bot with knowledge base
- AI conversation analysis with interest scoring
- AI Call Intelligence with transcription, sentiment analysis, and action item extraction (Arabic/English)
- Call analytics dashboard with minutes quota, token usage, and agent performance
- Native mobile call tracking with recording upload and outcome capture
- Webhook, Mobile API, and Bulk APIs for external system integration
- REST APIs for lead and deal creation (single and bulk)
- Message translation (Arabic ↔ English)
- Email open and click tracking
- Visual bot flow builder with 40+ node types and n8n integration
- Multi-channel sequences (drip campaigns)
- Comprehensive CRM with deal ownership tracking
- Calendly-like scheduling with Google Calendar and Zoom integrations
- Task automation with intelligent assignment (round-robin, workload, skills)
- Agent performance analytics and workload dashboard
- Reusable message templates with template management page
- Outgoing webhooks with event subscriptions and delivery logs
- Custom labels (white-label terminology)
- External pages in sidebar navigation
- Login schedules and agent availability management
- Sentry error monitoring and error boundaries
- Real-time dashboards and analytics
- Team collaboration with attendance tracking
- Enterprise security and compliance
- Scalable infrastructure

**Ideal For:**
- Customer support teams needing AI-assisted automation
- Sales teams requiring pipeline management and call tracking
- Call centers needing AI-powered call analysis and quality monitoring
- Marketing teams running multi-channel campaigns
- Small to large businesses
- Multi-channel businesses
- Businesses requiring intelligent automation
- Teams needing comprehensive CRM capabilities
- Organizations wanting centralized scheduling
- Companies prioritizing data-driven decisions

**New in Version 7.0:**
- AI Call Intelligence with automated transcription, sentiment analysis, and action items
- Call recording upload (in-app + webhook + mobile API)
- Call analytics dashboard (volume, sentiment, agent performance, keywords)
- Call minutes quota tracking and AI token usage monitoring
- Silent/empty recording detection with automatic skip
- Call Intelligence settings page with webhook configuration
- Admin APIs for token usage and minutes top-up
- Demo mode for Call Intelligence (view-only with sample data)
- Templates management page (`/templates`)
- REST APIs: create-lead, create-leads-bulk, create-deals-bulk
- Message translation API (Arabic ↔ English)
- Email open and click tracking (tracking pixel + redirect)
- Outgoing webhook configuration with event subscriptions and logs
- WhatsApp Templates management in settings
- Tag management settings tab
- Custom labels (white-label terminology customization)
- External pages in sidebar navigation
- Login schedule per team member
- Agent workload dashboard
- Sentry error monitoring integration
- n8n workflow engine integration
- Qdrant vector search rebuild for RAG
- Kommo CRM lead import
- Native call tracking with outcome capture and recording attachment
- AI customer support bot (WhatsApp)
- AI conversation analysis and interest scoring
- Cross-channel response capability
- Sequences (drip campaigns) for lead nurturing
- Lists for tag-based segmentation
- Agent performance dashboard
- Task automation distribution system
- Interest analysis dashboard
- Internal AI Web Assistant with voice input (admin)
- Internal WhatsApp Team Assistant
- Admin subscription sync utility
- Sales Pipeline Report with CSV export
- Shared Content System (deals, contacts, companies, tasks, pipeline reports)

**New in Version 7.1:**
- AI Re-Engagement add-on — automated Messenger & Instagram nudges before 24h window closes
- AI Re-Engagement with agent approval workflow (edit, approve, skip drafts)
- BYOK Gemini Key support for all AI features (re-engagement, chatbots, translations, call analysis)
- Social Media Planner — visual calendar with Facebook, Instagram, LinkedIn publishing
- 11 social content formats (text, image, carousel, video, reel, story, link, poll, event, product tag, collaboration)
- Social media token reuse from messaging channel accounts
- Automated social post failure push notifications
- Sequences with WhatsApp Cloud template support
- Sequences with WhatsApp Lite dynamic message support
- Sequence unsubscribe with PBKDF2-secured tokens
- Flow Builder template preview with sample webhook tester
- Bot Flow webhook trigger node (receive external webhooks)
- Multi-teams layer with Team Admin roles
- Per-user channel access controls (`user_channel_access`)
- Shopify Inbox integration
- LinkedIn messaging and publishing integration
- TikTok messaging channel
- Pabbly webhook routing for WhatsApp
- Zoom cloud recording sync via webhooks + Google Calendar polling
- Instagram contact name integrity preservation
- Guest Mode fallback demo account
- Marketing opt-in policy management

---

**Document Version:** 7.1.0
**Last Updated:** June 2026
**For Marketing Use**

## On the website

- [Compare ConnectGain on connectgain.cloud](https://connectgain.cloud/en/compare) — feature overview on the ConnectGain website

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/04-use-cases/index.md)*

---

# ConnectGain Use Cases – Automation, Webhooks & CRM

Source: https://docs.connectgain.cloud/04-use-cases/overview/

# ConnectGain - Comprehensive Use Cases Documentation

## Table of Contents

1. [Automation Use Cases](#automation-use-cases)
2. [Webhook Use Cases](#webhook-use-cases)
3. [Team Management Use Cases](#team-management-use-cases)
5. [AI Features Use Cases](#ai-features-use-cases)
6. [Deal Workflow Use Cases](#deal-workflow-use-cases)
7. [Multi-Channel Inbox Use Cases](#multi-channel-inbox-use-cases)
8. [Task Management Use Cases](#task-management-use-cases)
9. [Scheduling (Calendly-like) Use Cases](#scheduling-calendly-like-use-cases)
10. [Campaigns & Broadcast Use Cases](#campaigns--broadcast-use-cases)
11. [Analytics & Dashboard Use Cases](#analytics--dashboard-use-cases)
12. [Bot Flows Use Cases](#bot-flows-use-cases)
13. [Contact Management Use Cases](#contact-management-use-cases)
14. [Company Management Use Cases](#company-management-use-cases)
15. [Template Management Use Cases](#template-management-use-cases)
16. [Project Management Use Cases](#project-management-use-cases)
17. [Support Tickets Use Cases](#support-tickets-use-cases)
18. [Attendance Tracking Use Cases](#attendance-tracking-use-cases)
19. [Channel Management Use Cases](#channel-management-use-cases)
20. [Message Management Use Cases](#message-management-use-cases)
21. [Profile Management Use Cases](#profile-management-use-cases)
22. [Onboarding Use Cases](#onboarding-use-cases)
23. [Sales Report Use Cases](#sales-report-use-cases)
24. [Call Tracking Use Cases](#call-tracking-use-cases)
25. [CRM Import Use Cases (Kommo & HubSpot)](#crm-import-use-cases-kommo--hubspot)
26. [External Integration Use Cases (via Automation HTTP Requests)](#external-integration-use-cases-via-automation-http-requests)
27. [Real Estate Industry Use Cases](#real-estate-industry-use-cases)
28. [Tourism & Hospitality Industry Use Cases](#tourism--hospitality-industry-use-cases)
29. [Education Centers Industry Use Cases](#education-centers-industry-use-cases)
30. [Hospitals & Healthcare Industry Use Cases](#hospitals--healthcare-industry-use-cases)
31. [Marketing Agencies Industry Use Cases](#marketing-agencies-industry-use-cases)
32. [AI Call Intelligence Use Cases](#ai-call-intelligence-use-cases)
33. [Call Center Automation Use Cases](#call-center-automation-use-cases)
34. [AI Re-Engagement Use Cases](#ai-re-engagement-use-cases)
35. [Retail Industry Use Cases](#retail-industry-use-cases)
36. [E-Commerce Industry Use Cases](#e-commerce-industry-use-cases)
37. [FinTech Industry Use Cases](#fintech-industry-use-cases)
38. [Banking Industry Use Cases](#banking-industry-use-cases)
39. [Insurance Industry Use Cases](#insurance-industry-use-cases)
40. [Automotive Industry Use Cases](#automotive-industry-use-cases)
41. [Restaurants & Food Service Industry Use Cases](#restaurants--food-service-industry-use-cases)
42. [Logistics & Shipping Industry Use Cases](#logistics--shipping-industry-use-cases)
43. [Telecommunications Industry Use Cases](#telecommunications-industry-use-cases)
44. [Government & Public Sector Use Cases](#government--public-sector-use-cases)
45. [Legal Services Industry Use Cases](#legal-services-industry-use-cases)
46. [Fitness & Wellness Industry Use Cases](#fitness--wellness-industry-use-cases)
47. [Tourism & Hospitality (Expanded)](#expanded-tourism--hospitality-use-cases-ai-enhanced)
48. [Social Media Planner Use Cases](#social-media-planner-use-cases)
49. [Sequences Use Cases](#sequences-use-cases)

---

## Automation Use Cases

### UC-AUTO-001: Auto-Assign New Conversations to Available Agents

**Business Scenario:**

A customer support team receives hundreds of inquiries daily. Instead of manually assigning each conversation, they want conversations automatically distributed to available agents based on their current workload and availability.

**Steps:**
1. Admin navigates to **Automations** page
2. Clicks **"Create Automation"**
3. Sets automation name: "Auto-Assign New Conversations"
4. Selects trigger: `conversation.created`
5. Leaves conditions empty (applies to all new conversations)
6. Adds action: `AUTO_ASSIGN_CONVERSATION`
7. Configures assignment method: Round-robin with availability check
8. Activates automation
9. Tests by creating a test conversation
10. Verifies conversation automatically assigned to available agent

**Expected Outcome:**

All new conversations are automatically assigned to available agents, ensuring fair workload distribution and faster response times.

**Business Value:**

- Reduces manual assignment overhead by 90%
- Ensures conversations are handled within SLA
- Improves agent utilization

---

### UC-AUTO-002: Create Task When Deal Moves to Negotiation Stage

**Business Scenario:**

A sales manager wants to ensure that whenever a deal reaches the negotiation stage, a follow-up task is automatically created for the sales rep to prepare negotiation materials.

**Steps:**
1. Sales manager creates automation: "Task on Negotiation Stage"
2. Sets trigger: `deal.stage.changed`
3. Adds condition: `new_stage` equals "Negotiation"
4. Adds condition: `old_stage` not equals "Negotiation" (prevents duplicate tasks)
5. Adds action: `CREATE_TASK`
6. Configures task:
 - Title: "Prepare negotiation materials for {{deal.title}}"
 - Description: "Deal {{deal.title}} moved to negotiation. Prepare pricing proposal and contract terms."
 - Priority: HIGH
 - Assignee: Deal owner ({{deal.owner_id}})
 - Due date: 2 days from now
7. Activates automation
8. Tests by moving a deal to negotiation stage
9. Verifies task created automatically

**Expected Outcome:**

Every time a deal moves to negotiation stage, a high-priority task is automatically created for the deal owner with a 2-day deadline.

**Business Value:**

- Ensures no negotiation opportunity is missed
- Standardizes follow-up process
- Improves deal closure rates

---

### UC-AUTO-003: Auto-Reply to Messages Outside Business Hours

**Business Scenario:**

A business operates Monday-Friday, 9 AM - 6 PM. They want to automatically send a polite response to customers who message outside these hours, letting them know when they can expect a response.

**Steps:**
1. Admin creates automation: "After-Hours Auto-Reply"
2. Sets trigger: `message.received`
3. Adds time condition: Organization time between 18:00 and 09:00
4. Adds day condition: Days of week = Monday, Tuesday, Wednesday, Thursday, Friday
5. Adds action: `REPLY_MESSAGE`
6. Configures message type: Text Message
7. Enters message: "Thank you for your message! Our team is currently offline. We'll respond during business hours (Monday-Friday, 9 AM - 6 PM). For urgent matters, please call us at [phone number]."
8. Activates automation
9. Tests by sending message outside business hours
10. Verifies auto-reply sent

**Expected Outcome:**

Customers receive immediate acknowledgment when messaging outside business hours, setting proper expectations and improving customer satisfaction.

**Business Value:**

- Improves customer experience with immediate acknowledgment
- Sets clear expectations
- Reduces customer frustration

---

### UC-AUTO-004: Tag High-Value Leads Automatically

**Business Scenario:**

A sales team wants to automatically tag contacts as "High-Value Lead" when they mention specific keywords like "enterprise", "budget approved", or "decision maker" in their messages.

**Steps:**
1. Sales manager creates automation: "Tag High-Value Leads"
2. Sets trigger: `message.received`
3. Adds condition: Message content contains "enterprise" OR "budget approved" OR "decision maker"
4. Adds condition: Direction equals "INBOUND"
5. Adds action: `ADD_TAG`
6. Configures tag: "High-Value Lead"
7. Activates automation
8. Tests by sending message with keyword
9. Verifies contact tagged automatically

**Expected Outcome:**

Contacts mentioning enterprise keywords are automatically tagged, making them easy to identify and prioritize in the CRM.

**Business Value:**

- Identifies high-value opportunities automatically
- Enables targeted follow-up campaigns
- Improves conversion rates

---

### UC-AUTO-005: Notify External System When Deal is Won

**Business Scenario:**

A company uses an external accounting system and wants to automatically create an invoice when a deal is marked as "Closed Won" in ConnectGain.

**Steps:**
1. Admin creates automation: "Create Invoice on Deal Win"
2. Sets trigger: `deal.stage.changed`
3. Adds condition: `new_stage` equals "Closed Won"
4. Adds condition: `deal.value` greater than 0
5. Adds action: `HTTP_REQUEST`
6. Configures HTTP request:
 - Method: POST
 - URL: https://api.accounting-system.com/invoices
 - Headers:
 - Authorization: Bearer [API_TOKEN]
 - Content-Type: application/json
 - Body:
 ```json
 {
 "customer_id": "{{deal.contact_id}}",
 "amount": {{deal.value}},
 "deal_id": "{{deal.id}}",
 "description": "Invoice for deal: {{deal.title}}"
 }
 ```
7. Activates automation
8. Tests by closing a deal
9. Verifies invoice created in external system

**Expected Outcome:**

When a deal is won, an invoice is automatically created in the external accounting system, eliminating manual data entry.

**Business Value:**

- Eliminates manual invoice creation
- Reduces errors
- Speeds up billing process

---

### UC-AUTO-006: Auto-Assign Tasks Based on Availability

**Business Scenario:**

A project management team wants tasks automatically assigned to team members based on their availability schedules, ensuring tasks go to people who are actually working.

**Steps:**
1. Admin creates automation: "Auto-Assign Tasks by Availability"
2. Sets trigger: `task.created`
3. Adds condition: Task assignee is NULL (unassigned task)
4. Adds action: `AUTO_ASSIGN_TASK`
5. Configures assignment: Availability-based round-robin
6. Activates automation
7. Creates test task without assignee
8. Verifies task assigned to available team member

**Expected Outcome:**

Unassigned tasks are automatically distributed to available team members, ensuring optimal workload distribution.

**Business Value:**

- Ensures tasks go to available team members
- Prevents task stagnation
- Improves team productivity

---

### UC-AUTO-007: Escalate Overdue Conversations

**Business Scenario:**

A support team wants conversations that haven't been responded to within 24 hours to be automatically escalated to a manager and tagged as "Needs Attention".

**Steps:**
1. Admin creates automation: "Escalate Overdue Conversations"
2. Sets trigger: `conversation.created` (runs periodically via scheduled check)
3. Adds condition: Last message time older than 24 hours
4. Adds condition: Conversation status equals "OPEN"
5. Adds condition: Last message direction equals "INBOUND"
6. Adds action: `ADD_TAG`
 - Tag: "Needs Attention"
7. Adds action: `ASSIGN_CONVERSATION`
 - Assignee: Manager user ID
8. Adds action: `CREATE_TASK`
 - Title: "Follow up on overdue conversation"
 - Priority: HIGH
 - Assignee: Manager
9. Activates automation

**Expected Outcome:**

Overdue conversations are automatically tagged, escalated to managers, and follow-up tasks are created to ensure customer issues are addressed.

**Business Value:**

- Prevents customer complaints
- Ensures SLA compliance
- Improves customer satisfaction

---

### UC-AUTO-008: Auto-Reply with Quick Reply Template

**Business Scenario:**

A customer service team receives frequent "hello" messages. They want to automatically respond with a friendly greeting template.

**Steps:**
1. Admin creates automation: "Auto-Greet Customers"
2. Sets trigger: `message.received`
3. Adds condition: Message content contains "hello" OR "hi" OR "hey"
4. Adds condition: Message direction equals "INBOUND"
5. Adds condition: Conversation message count equals 1 (first message)
6. Adds action: `REPLY_MESSAGE`
7. Configures message type: Quick Reply Template
8. Selects template: "Welcome Greeting"
9. Activates automation
10. Tests by sending "hello" message
11. Verifies template response sent

**Expected Outcome:**

Customers receive an immediate friendly greeting when they initiate contact, improving first impression.

**Business Value:**

- Provides instant acknowledgment
- Sets positive tone
- Reduces agent workload for common greetings

---

### UC-AUTO-009: Create Deal from High-Interest Messages

**Business Scenario:**

A sales team wants deals automatically created when customers express strong buying intent in messages (e.g., "I want to buy", "I'm ready to purchase", "Let's proceed").

**Steps:**
1. Sales manager creates automation: "Auto-Create Deal from Intent"
2. Sets trigger: `message.received`
3. Adds condition: Message content contains "want to buy" OR "ready to purchase" OR "let's proceed" OR "interested in buying"
4. Adds condition: No existing deal for this contact
5. Adds action: `CREATE_DEAL`
6. Configures deal:
 - Title: "Deal from {{contact.first_name}} {{contact.last_name}}"
 - Stage: "Qualified"
 - Value: 0 (to be updated manually)
 - Owner: Contact assignee or auto-assigned
7. Adds action: `ADD_TAG` to contact: "Hot Lead"
8. Activates automation
9. Tests by sending message with buying intent
10. Verifies deal created automatically

**Expected Outcome:**

Deals are automatically created when customers express buying intent, ensuring no sales opportunity is missed.

**Business Value:**

- Captures sales opportunities immediately
- Reduces manual deal creation
- Improves sales pipeline accuracy

---

### UC-AUTO-010: Channel-Specific Automation Rules

**Business Scenario:**

A business wants different automation rules for different channels. WhatsApp messages get immediate response, while email gets a slower, more formal response.

**Steps:**
1. Admin creates automation: "WhatsApp Immediate Response"
2. Sets trigger: `message.received`
3. Adds condition: Channel type equals "WHATSAPP_LITE"
4. Adds action: `REPLY_MESSAGE` with quick response
5. Activates automation
6. Creates second automation: "Email Formal Response"
7. Sets trigger: `message.received`
8. Adds condition: Channel type equals "EMAIL"
9. Adds action: `REPLY_MESSAGE` with formal template
10. Activates automation
11. Tests both channels
12. Verifies channel-specific responses

**Expected Outcome:**

Different channels receive appropriate automated responses based on channel characteristics and customer expectations.

**Business Value:**

- Matches customer expectations per channel
- Improves customer experience
- Optimizes response strategies

---

## Webhook Use Cases

### UC-WEB-001: Sync Contacts to External CRM System

**Business Scenario:**

A company uses ConnectGain for customer communication but maintains their primary CRM in Salesforce. They want all new contacts created in ConnectGain to automatically sync to Salesforce.

**Steps:**
1. Admin navigates to **Settings → Webhooks**
2. Clicks **"Create Webhook"**
3. Enters webhook name: "Salesforce Contact Sync"
4. Enters webhook URL: `https://api.salesforce.com/webhook/contacts`
5. Selects events: `contact.created`, `contact.updated`
6. Enters secret key: `sf_sync_secret_2024`
7. Adds custom headers:
 - Authorization: Bearer [Salesforce API Token]
 - X-Source: ConnectGain
8. Activates webhook
9. Clicks **"Test Webhook"** to verify connection
10. Creates test contact in ConnectGain
11. Verifies contact appears in Salesforce
12. Checks webhook logs for delivery status

**Expected Outcome:**

All contacts created or updated in ConnectGain are automatically synced to Salesforce in real-time, maintaining data consistency across systems.

**Business Value:**

- Eliminates manual data entry
- Ensures data consistency
- Saves time and reduces errors

---

### UC-WEB-002: Notify Slack Channel When High-Value Deal is Won

**Business Scenario:**

A sales team wants to celebrate wins by automatically posting to a Slack channel whenever a deal worth more than $10,000 is closed.

**Steps:**
1. Admin creates webhook: "Slack Deal Wins"
2. Sets URL: `https://hooks.slack.com/services/[SLACK_WEBHOOK_URL]`
3. Selects events: `deal.stage.changed`
4. Configures secret key for security
5. Activates webhook
6. Creates automation rule:
 - Trigger: `deal.stage.changed`
 - Condition: `new_stage` equals "Closed Won"
 - Condition: `deal.value` greater than 10000
 - Action: HTTP Request to webhook endpoint
7. Tests by closing high-value deal
8. Verifies Slack notification received

**Expected Outcome:**

The sales team receives real-time Slack notifications celebrating high-value deal wins, boosting team morale and visibility.

**Business Value:**

- Increases team motivation
- Provides visibility into wins
- Creates celebration culture

---

### UC-WEB-003: Trigger Email Campaign When Contact is Created

**Business Scenario:**

A marketing team wants to automatically add new contacts to their email marketing platform (Mailchimp) and trigger a welcome email sequence.

**Steps:**
1. Marketing manager creates webhook: "Mailchimp Contact Sync"
2. Sets URL: `https://us1.api.mailchimp.com/3.0/lists/[LIST_ID]/members`
3. Selects events: `contact.created`
4. Configures authentication headers:
 - Authorization: Bearer [Mailchimp API Key]
5. Activates webhook
6. Creates test contact
7. Verifies contact added to Mailchimp
8. Checks Mailchimp automation triggers welcome email
9. Reviews webhook logs for delivery confirmation

**Expected Outcome:**

New contacts are automatically added to Mailchimp and receive welcome emails, streamlining the onboarding process.

**Business Value:**

- Automates marketing workflows
- Ensures no contact is missed
- Improves marketing efficiency

---

### UC-WEB-004: Update Inventory System When Deal is Won

**Business Scenario:**

An e-commerce company wants to automatically update their inventory management system when a deal is closed, reserving products for the customer.

**Steps:**
1. Admin creates webhook: "Inventory System Update"
2. Sets URL: `https://inventory.example.com/api/reservations`
3. Selects events: `deal.stage.changed`
4. Configures webhook payload to include deal products
5. Sets up authentication headers
6. Creates automation:
 - Trigger: `deal.stage.changed`
 - Condition: `new_stage` equals "Closed Won"
 - Action: HTTP Request to webhook
7. Tests by closing deal with products
8. Verifies inventory system updated
9. Checks webhook logs

**Expected Outcome:**

When a deal is won, the inventory system is automatically updated, reserving products and preventing overselling.

**Business Value:**

- Prevents inventory errors
- Automates fulfillment process
- Improves operational efficiency

---

### UC-WEB-005: Real-Time Dashboard Updates via Webhooks

**Business Scenario:**

A company wants to build a custom analytics dashboard that updates in real-time when key events occur (new deals, messages, etc.).

**Steps:**
1. Developer creates webhook: "Analytics Dashboard"
2. Sets URL: `https://dashboard.example.com/webhook`
3. Selects all relevant events:
 - `deal.created`, `deal.stage.changed`
 - `message.received`, `message.sent`
 - `conversation.created`
 - `contact.created`
4. Configures HMAC signature for security
5. Activates webhook
6. Builds dashboard to receive webhook events
7. Tests with sample events
8. Verifies dashboard updates in real-time
9. Monitors webhook delivery logs

**Expected Outcome:**

The custom analytics dashboard receives real-time updates via webhooks, providing instant visibility into business metrics.

**Business Value:**

- Real-time business intelligence
- Custom analytics capabilities
- Data-driven decision making

---

### UC-WEB-006: Integrate with Accounting Software

**Business Scenario:**

A business wants to automatically create invoices in QuickBooks when deals are closed, including all deal details and customer information.

**Steps:**
1. Admin creates webhook: "QuickBooks Invoice Creation"
2. Sets URL: `https://quickbooks.api.intuit.com/v3/company/[COMPANY_ID]/invoice`
3. Selects events: `deal.stage.changed`
4. Configures OAuth headers for QuickBooks
5. Creates automation to filter for "Closed Won" deals
6. Tests by closing deal
7. Verifies invoice created in QuickBooks
8. Reviews webhook logs for any errors

**Expected Outcome:**

Invoices are automatically created in QuickBooks when deals are won, streamlining the billing process.

**Business Value:**

- Eliminates manual invoice creation
- Reduces billing errors
- Speeds up cash flow

---

### UC-WEB-007: Notify Customer Success Team on Deal Win

**Business Scenario:**

When a deal is won, the customer success team needs to be notified immediately to begin onboarding the new customer.

**Steps:**
1. Admin creates webhook: "Customer Success Notification"
2. Sets URL: Internal notification system endpoint
3. Selects events: `deal.stage.changed`
4. Configures payload to include:
 - Deal details
 - Contact information
 - Deal value
 - Expected start date
5. Creates automation filter for "Closed Won"
6. Activates webhook
7. Tests by closing deal
8. Verifies customer success team notified
9. Checks notification includes all required information

**Expected Outcome:**

Customer success team receives immediate notifications when deals are won, enabling proactive customer onboarding.

**Business Value:**

- Faster customer onboarding
- Improved customer experience
- Better team coordination

---

### UC-WEB-008: Log All Events to External System

**Business Scenario:**

A company needs to maintain an audit log of all ConnectGain events in their external logging system for compliance purposes.

**Steps:**
1. Admin creates webhook: "Audit Log System"
2. Sets URL: `https://audit.example.com/api/events`
3. Selects all events (comprehensive logging)
4. Configures authentication
5. Sets up webhook to log all events
6. Tests with sample events
7. Verifies events logged correctly
8. Monitors webhook delivery rates
9. Sets up alerts for webhook failures

**Expected Outcome:**

All ConnectGain events are logged to the external audit system, maintaining compliance and audit trails.

**Business Value:**

- Compliance requirements met
- Complete audit trail
- Regulatory compliance

---

## Team Management Use Cases

### UC-TEAM-001: Onboard New Team Member with Proper Permissions

**Business Scenario:**

A company hires a new customer support agent and needs to add them to the team with appropriate permissions to handle conversations but not manage settings.

**Steps:**
1. Admin navigates to **Settings → Team Members**
2. Clicks **"Invite Member"**
3. Enters email: `newagent@company.com`
4. Selects role: **Agent**
5. Clicks **"Send Invitation"**
6. New agent receives invitation email
7. Agent clicks invitation link
8. Agent creates account and sets password
9. Agent logs in and sees agent-appropriate features
10. Admin navigates to team member list
11. Clicks **"Manage Permissions"** for new agent
12. Configures permissions:
 - ✅ Can see assigned conversations
 - ✅ Can access CRM
 - ❌ Can manage users
 - ❌ Can access broadcast
 - ✅ Can access tasks
13. Saves permissions
14. Verifies agent has correct access

**Expected Outcome:**

New team member is onboarded with appropriate permissions, can immediately start working, and only sees features relevant to their role.

**Business Value:**

- Fast onboarding process
- Proper access control
- Security compliance

---

### UC-TEAM-002: Set Agent Availability for Auto-Assignment

**Business Scenario:**

A support team wants to ensure agents only receive auto-assigned conversations during their working hours (Monday-Friday, 9 AM - 5 PM).

**Steps:**
1. Admin navigates to **Settings → Team Members**
2. Selects agent: "John Doe"
3. Clicks **"Manage Availability"**
4. Configures availability slots:
 - Monday: 09:00 - 17:00
 - Tuesday: 09:00 - 17:00
 - Wednesday: 09:00 - 17:00
 - Thursday: 09:00 - 17:00
 - Friday: 09:00 - 17:00
 - Saturday: No availability
 - Sunday: No availability
5. Sets timezone: "America/New_York"
6. Saves availability
7. Creates automation for auto-assignment
8. Tests by creating conversation during business hours
9. Verifies conversation assigned to John
10. Tests outside business hours
11. Verifies conversation assigned to different available agent

**Expected Outcome:**

Agents only receive auto-assigned conversations during their configured availability hours, ensuring fair workload distribution.

**Business Value:**

- Respects agent work-life balance
- Ensures availability-based assignment
- Improves agent satisfaction

---

### UC-TEAM-003: Restrict Agent Login to Business Hours

**Business Scenario:**

A company wants to ensure agents can only log in during their scheduled work hours for security and compliance reasons.

**Steps:**
1. Admin navigates to **Settings → Team Members**
2. Selects agent: "Jane Smith"
3. Clicks **"Manage Permissions"**
4. Enables: **"Restrict login to schedule"**
5. Clicks **"Manage Login Schedule"**
6. Configures weekly schedule:
 - Monday: 08:00 - 18:00
 - Tuesday: 08:00 - 18:00
 - Wednesday: 08:00 - 18:00
 - Thursday: 08:00 - 18:00
 - Friday: 08:00 - 18:00
 - Weekend: No login allowed
7. Sets timezone: Organization timezone
8. Saves schedule
9. Agent tries to login during business hours
10. Verifies login successful
11. Agent tries to login outside business hours
12. Verifies login blocked with message

**Expected Outcome:**

Agents can only log in during their configured schedule, improving security and ensuring compliance with work policies.

**Business Value:**

- Enhanced security
- Policy compliance
- Access control

---

### UC-TEAM-004: Grant Temporary Admin Access

**Business Scenario:**

A regular agent needs temporary admin access for a specific project. After the project, access should be revoked.

**Steps:**
1. Admin navigates to **Settings → Team Members**
2. Selects agent: "Temporary Admin"
3. Clicks **"Manage Permissions"**
4. Temporarily enables: **"Can manage users"**
5. Enables: **"Can see all conversations"**
6. Enables: **"Can see all deals"**
7. Saves permissions
8. Agent now has admin-level access
9. After project completion, admin revokes permissions
10. Removes admin permissions
11. Verifies agent back to regular access level

**Expected Outcome:**

Agent receives temporary admin access for the project duration, then access is properly revoked, maintaining security.

**Business Value:**

- Flexible access management
- Temporary elevated permissions
- Security maintained

---

### UC-TEAM-005: Bulk Invite Multiple Team Members

**Business Scenario:**

A company is expanding and needs to onboard 20 new team members at once.

**Steps:**
1. Admin navigates to **Settings → Team Members**
2. Prepares list of 20 email addresses
3. For each email:
 - Clicks **"Invite Member"**
 - Enters email address
 - Selects appropriate role (Agent/Admin)
 - Sends invitation
4. Tracks invitation status in pending invitations
5. Monitors acceptance rates
6. Resends invitations for non-responders
7. Verifies all team members onboarded

**Expected Outcome:**

All 20 team members receive invitations and can join the organization, streamlining the bulk onboarding process.

**Business Value:**

- Efficient bulk onboarding
- Scalable team growth
- Organized invitation management

---

### UC-TEAM-006: Remove Team Member and Reassign Work

**Business Scenario:**

A team member is leaving the company. Their assigned conversations, deals, and tasks need to be reassigned to other team members.

**Steps:**
1. Admin navigates to **Settings → Team Members**
2. Selects departing team member
3. Reviews their assigned items:
 - Conversations: 15
 - Deals: 8
 - Tasks: 12
4. Uses bulk reassignment feature:
 - Selects all conversations
 - Reassigns to available team members
 - Selects all deals
 - Reassigns to sales manager
 - Selects all tasks
 - Reassigns based on task type
5. Verifies all items reassigned
6. Removes team member from organization
7. Confirms removal

**Expected Outcome:**

All work items are properly reassigned before team member removal, ensuring business continuity.

**Business Value:**

- Smooth team transitions
- No work lost
- Business continuity

---

## AI Features Use Cases

### UC-AI-001: Automatically Analyze Customer Interest Levels

**Business Scenario:**

A sales team receives hundreds of customer conversations daily. They want to automatically identify which leads are "hot" (highly interested), "warm" (moderately interested), or "cold" (low interest) to prioritize follow-ups.

**Steps:**
1. System automatically triggers AI analysis every 3 inbound messages
2. AI analyzes conversation:
 - Message content
 - Sentiment
 - Buying intent
 - Engagement level
3. Generates analysis:
 - Interest score: 85/100
 - Interest level: "Hot"
 - Sentiment: "Positive"
 - Intent: "Interested"
 - Summary: "Customer asking about pricing and availability, ready to purchase"
 - Key topics: ["pricing", "features", "implementation"]
 - Recommended action: "Send pricing proposal immediately"
4. Updates conversation with AI analysis
5. Sales rep opens inbox
6. Sees "Hot" badge on conversation
7. Reviews AI analysis details
8. Takes recommended action
9. Verifies improved conversion rate

**Expected Outcome:**

Conversations are automatically analyzed and tagged with interest levels, enabling sales teams to prioritize high-value opportunities.

**Business Value:**

- 40% improvement in response prioritization
- Higher conversion rates
- Better resource allocation

---

### UC-AI-002: Identify Hot Leads for Immediate Follow-Up

**Business Scenario:**

A sales manager wants to quickly identify all "hot" leads that need immediate attention to maximize conversion opportunities.

**Steps:**
1. Sales manager navigates to **Interest Analysis** page
2. Views dashboard statistics:
 - Hot leads: 12
 - Warm leads: 45
 - Cold leads: 23
3. Clicks **"Hot"** tab
4. Reviews list of hot leads with:
 - Interest score (70-100)
 - Sentiment analysis
 - Intent classification
 - Conversation summary
 - Recommended actions
5. Sorts by interest score (highest first)
6. Selects top 5 hot leads
7. Creates follow-up tasks for each
8. Assigns to sales reps
9. Monitors conversion rates

**Expected Outcome:**

Sales manager quickly identifies and prioritizes hot leads, resulting in faster response times and higher conversion rates.

**Business Value:**

- Faster response to hot leads
- Improved conversion rates
- Better sales performance

---

### UC-AI-003: Analyze Conversation Sentiment for Customer Satisfaction

**Business Scenario:**

A customer support manager wants to monitor customer sentiment across all conversations to identify potential issues and improve service quality.

**Steps:**
1. AI automatically analyzes all conversations
2. Categorizes sentiment:
 - Positive: 65%
 - Neutral: 25%
 - Negative: 10%
3. Support manager reviews negative sentiment conversations
4. Identifies common issues:
 - Slow response times
 - Product defects
 - Billing issues
5. Takes corrective actions:
 - Improves response time SLA
 - Escalates product issues
 - Reviews billing process
6. Monitors sentiment trends over time
7. Verifies sentiment improvement

**Expected Outcome:**

Customer sentiment is automatically tracked, enabling proactive issue identification and service improvement.

**Business Value:**

- Proactive issue detection
- Improved customer satisfaction
- Data-driven service improvements

---

### UC-AI-004: Extract Key Topics from Conversations

**Business Scenario:**

A product team wants to understand what customers are talking about most frequently to inform product roadmap decisions.

**Steps:**
1. AI analyzes all conversations
2. Extracts key topics from each conversation
3. Aggregates topics across all conversations
4. Generates topic frequency report:
 - "Feature Request - Mobile App": 45 mentions
 - "Pricing Questions": 32 mentions
 - "Integration Support": 28 mentions
 - "Bug Reports": 15 mentions
5. Product manager reviews topic analysis
6. Prioritizes product roadmap based on topic frequency
7. Plans new features addressing top topics
8. Communicates roadmap to customers

**Expected Outcome:**

Product team gains insights into customer needs through automated topic extraction, informing data-driven product decisions.

**Business Value:**

- Data-driven product decisions
- Customer-aligned roadmap
- Improved product-market fit

---

### UC-AI-005: Get AI-Powered Response Suggestions

**Business Scenario:**

A support agent receives a complex customer question and wants AI-powered suggestions for the best response.

**Steps:**
1. Support agent opens conversation
2. Reviews customer message: "I'm having trouble with the integration. Can you help?"
3. Clicks **"AI Response Suggestions"** button
4. AI analyzes:
 - Customer message context
 - Conversation history
 - Customer profile
 - Common solutions
5. Generates response suggestions:
 - Suggestion 1: "I'd be happy to help with your integration. Can you tell me which system you're trying to integrate with?"
 - Suggestion 2: "Let me check your account settings. What specific error are you seeing?"
6. Agent selects best suggestion
7. Customizes response
8. Sends to customer
9. Verifies faster response time

**Expected Outcome:**

Agents receive AI-powered response suggestions, enabling faster and more consistent customer support.

**Business Value:**

- Faster response times
- Consistent quality
- Improved agent productivity

---

### UC-AI-006: Trigger Automation Based on AI Analysis

**Business Scenario:**

A sales team wants to automatically create deals and assign tasks when AI identifies a hot lead.

**Steps:**
1. AI analyzes conversation
2. Identifies hot lead (interest score > 70)
3. Triggers automation rule:
 - Condition: AI interest level equals "Hot"
 - Action 1: Create deal
 - Title: "Hot Lead - {{contact.name}}"
 - Stage: "Qualified"
 - Value: Estimated from conversation
 - Action 2: Create task
 - Title: "Follow up with hot lead"
 - Priority: HIGH
 - Assignee: Sales manager
 - Action 3: Add tag to contact: "Hot Lead"
4. Sales manager receives notification
5. Reviews automatically created deal
6. Follows up with customer
7. Verifies improved conversion

**Expected Outcome:**

Hot leads automatically trigger deal creation and task assignment, ensuring no opportunity is missed.

**Business Value:**

- No missed opportunities
- Automated workflow
- Improved conversion rates

---

## Deal Workflow Use Cases

### UC-DEAL-001: Convert Conversation to Deal

**Business Scenario:**

A sales rep is chatting with a potential customer via WhatsApp. The customer expresses interest in purchasing. The rep wants to convert this conversation into a tracked deal.

**Steps:**
1. Sales rep opens conversation in inbox
2. Reviews conversation history
3. Identifies buying intent
4. Clicks **"Create Deal"** button in conversation
5. Deal creation dialog opens with pre-filled data:
 - Contact: Auto-selected from conversation
 - Title: "Deal from Conversation - [Contact Name]"
 - Conversation: Linked automatically
6. Sales rep fills in deal details:
 - Pipeline: "Sales Pipeline"
 - Stage: "Qualified"
 - Value: $15,000 (based on discussion)
 - Probability: 40%
 - Expected close date: 30 days from now
 - Tags: ["WhatsApp", "Hot Lead"]
7. Saves deal
8. Deal appears in kanban board
9. Conversation shows deal link
10. Sales rep continues conversation with deal context

**Expected Outcome:**

Conversation seamlessly converts to a tracked deal, maintaining context and enabling proper sales pipeline management.

**Business Value:**

- Seamless conversion process
- Context preservation
- Better sales tracking

---

### UC-DEAL-002: Move Deal Through Pipeline Stages

**Business Scenario:**

A sales rep needs to track a deal as it progresses from initial contact through qualification, proposal, negotiation, and finally to closed won.

**Steps:**
1. Sales rep creates deal in "Lead" stage
2. Qualifies customer needs
3. Drags deal card from "Lead" to "Qualified" stage
4. System automatically:
 - Updates stage
 - Updates probability (10% → 30%)
 - Records stage change in history
5. Sales rep prepares proposal
6. Drags deal to "Proposal" stage
7. Probability updates to 50%
8. Customer negotiates terms
9. Drags deal to "Negotiation" stage
10. Probability updates to 70%
11. Customer accepts offer
12. Drags deal to "Closed Won" stage
13. Probability updates to 100%
14. Deal marked as won
15. Sales manager reviews pipeline metrics

**Expected Outcome:**

Deal progresses through pipeline stages with automatic probability updates and complete history tracking.

**Business Value:**

- Clear sales process visibility
- Accurate forecasting
- Complete audit trail

---

### UC-DEAL-003: Forecast Revenue Based on Pipeline

**Business Scenario:**

A sales manager needs to forecast next quarter's revenue based on current deals in the pipeline.

**Steps:**
1. Sales manager opens **Deals** page
2. Filters deals:
 - Excludes "Closed Lost" deals
 - Includes all active stages
 - Current quarter deals
3. Reviews pipeline view:
 - Lead: 10 deals, $50,000 total value
 - Qualified: 8 deals, $80,000 total value
 - Proposal: 5 deals, $75,000 total value
 - Negotiation: 3 deals, $60,000 total value
4. Calculates weighted forecast:
 - Lead: $50,000 × 10% = $5,000
 - Qualified: $80,000 × 30% = $24,000
 - Proposal: $75,000 × 50% = $37,500
 - Negotiation: $60,000 × 70% = $42,000
 - Total forecast: $108,500
5. Adds closed won deals: $45,000
6. Total revenue projection: $153,500
7. Compares to target: $200,000
8. Identifies gap: $46,500
9. Takes action to fill pipeline

**Expected Outcome:**

Sales manager has accurate revenue forecast based on weighted pipeline values, enabling data-driven planning.

**Business Value:**

- Accurate revenue forecasting
- Data-driven planning
- Target achievement

---

### UC-DEAL-004: Reassign Deal to Different Sales Rep

**Business Scenario:**

A sales rep is leaving the company. Their deals need to be reassigned to other team members to ensure continuity.

**Steps:**
1. Sales manager opens **Deals** page
2. Filters deals by owner: "Departing Rep"
3. Reviews 15 assigned deals
4. Selects all deals (bulk selection)
5. Clicks **"Bulk Assign"**
6. Selects new owner: "Senior Sales Rep"
7. Confirms reassignment
8. System updates all deals:
 - Owner changed
 - Ownership history logged
 - Duration with previous owner calculated
 - New owner notified
9. Verifies all deals reassigned
10. New owner reviews assigned deals
11. Continues sales process

**Expected Outcome:**

All deals are smoothly reassigned to new owner with complete history tracking, ensuring business continuity.

**Business Value:**

- Smooth transitions
- No lost deals
- Complete audit trail

---

### UC-DEAL-005: Track Deal Ownership History

**Business Scenario:**

A sales manager wants to understand how long deals spend with each sales rep and identify bottlenecks in the sales process.

**Steps:**
1. Sales manager opens deal details
2. Clicks **"Ownership History"** tab
3. Reviews ownership timeline:
 - Rep A: Jan 1 - Jan 15 (14 days)
 - Rep B: Jan 15 - Feb 1 (17 days)
 - Rep C: Feb 1 - Feb 20 (19 days) - Current
4. Calculates average ownership duration: 16.7 days
5. Identifies deals stuck with same owner > 30 days
6. Reviews reasons for ownership changes
7. Identifies patterns:
 - Rep A: Quick initial qualification
 - Rep B: Extended negotiation
 - Rep C: Closing phase
8. Takes action on stuck deals
9. Optimizes sales process

**Expected Outcome:**

Sales manager gains insights into deal ownership patterns, enabling process optimization and bottleneck identification.

**Business Value:**

- Process optimization
- Bottleneck identification
- Performance improvement

---

### UC-DEAL-006: Filter Deals by Value Range

**Business Scenario:**

A sales manager wants to focus on high-value deals ($10,000+) to maximize revenue impact.

**Steps:**
1. Sales manager opens **Deals** page
2. Applies value filter:
 - Minimum value: $10,000
 - Maximum value: (no limit)
3. Views filtered deals:
 - 8 deals shown
 - Total value: $125,000
4. Reviews each high-value deal
5. Prioritizes follow-ups
6. Assigns to top performers
7. Tracks progress closely
8. Verifies improved focus on high-value opportunities

**Expected Outcome:**

Sales manager focuses on high-value deals, maximizing revenue impact and resource allocation.

**Business Value:**

- Revenue maximization
- Better resource allocation
- Strategic focus

---

### UC-DEAL-007: Create Deal from Contact Profile

**Business Scenario:**

A sales rep is reviewing a contact's profile and wants to create a new deal opportunity for that contact.

**Steps:**
1. Sales rep opens **Contacts** page
2. Selects contact: "ABC Corporation"
3. Reviews contact details and history
4. Clicks **"Create Deal"** button
5. Deal creation dialog opens:
 - Contact: Pre-filled (ABC Corporation)
 - Company: Pre-filled (if linked)
6. Fills in deal details:
 - Title: "ABC Corp - Enterprise License"
 - Pipeline: "Enterprise Sales"
 - Stage: "Lead"
 - Value: $50,000
 - Probability: 20%
 - Expected close: 60 days
7. Saves deal
8. Deal appears in pipeline
9. Contact profile shows linked deal
10. Sales rep tracks deal progress

**Expected Outcome:**

Deal is created directly from contact profile, maintaining relationship context and enabling easy tracking.

**Business Value:**

- Context preservation
- Easy deal creation
- Relationship tracking

---

### UC-DEAL-008: Auto-Reassign Inactive Deals

**Business Scenario:**

A sales manager wants deals that haven't been updated in 7 days to be automatically reassigned to prevent stagnation.

**Steps:**
1. System runs automatic check daily
2. Identifies deals not updated in 7+ days
3. Finds 5 inactive deals
4. Automatically reassigns to available sales reps:
 - Round-robin distribution
 - Only assigns to active users
 - Logs reassignment reason: "Auto-reassigned - Inactive"
5. Notifies new owners
6. Sales manager reviews reassignment log
7. Verifies deals moving forward
8. Monitors deal activity

**Expected Outcome:**

Inactive deals are automatically reassigned, preventing stagnation and ensuring continuous sales activity.

**Business Value:**

- Prevents deal stagnation
- Fair workload distribution
- Improved sales velocity

---

## Multi-Channel Inbox Use Cases

### UC-INBOX-001: Respond to Customer Across Multiple Channels

**Business Scenario:**

A customer contacts the business via WhatsApp, then sends an email, and later messages on Instagram. The support agent needs to see all conversations in one place and respond appropriately.

**Steps:**
1. Customer sends WhatsApp message: "I need help with my order"
2. Support agent opens **Inbox**
3. Sees new WhatsApp conversation
4. Responds via WhatsApp
5. Customer sends email with order details
6. Agent sees new email conversation in same inbox
7. System identifies same contact across channels
8. Agent views unified contact profile showing all channels
9. Customer sends Instagram DM
10. Agent sees Instagram conversation
11. Agent responds via customer's preferred channel (WhatsApp)
12. All interactions tracked in unified view

**Expected Outcome:**

Agent manages all customer interactions across multiple channels in a [unified inbox](https://docs.connectgain.cloud/04-use-cases/02-user-guide/inbox.md), providing consistent support experience.

**Business Value:**

- Unified customer view
- Consistent experience
- Efficient support

---

### UC-INBOX-002: Assign Conversation to Team Member

**Business Scenario:**

A customer inquiry comes in that requires specialized knowledge. The receiving agent needs to assign it to the appropriate specialist.

**Steps:**
1. Agent receives technical support inquiry
2. Reviews conversation and contact details
3. Determines needs specialist assistance
4. Clicks **"Assign"** button
5. Views team member list with:
 - Online/offline status
 - Current workload
 - Specializations
6. Selects specialist: "Technical Support Specialist"
7. Confirms assignment
8. Specialist receives notification
9. Specialist sees conversation in "Assigned to Me" filter
10. Specialist responds with expertise
11. Customer receives accurate solution

**Expected Outcome:**

Conversation is assigned to the right specialist, ensuring customers receive expert assistance quickly.

**Business Value:**

- Expert routing
- Faster resolution
- Better customer satisfaction

---

### UC-INBOX-003: Use Quick Reply Templates

**Business Scenario:**

A support agent frequently receives the same questions. They want to use pre-written templates to respond quickly and consistently.

**Steps:**
1. Support agent opens conversation
2. Customer asks: "What are your business hours?"
3. Agent types "/" in message composer
4. Quick reply menu appears
5. Agent searches: "hours"
6. Finds template: "Our business hours are Monday-Friday, 9 AM - 6 PM EST"
7. Selects template
8. Message auto-fills
9. Agent customizes if needed
10. Sends message
11. Customer receives instant response
12. Agent moves to next conversation

**Expected Outcome:**

Agent responds quickly using templates, improving response time and maintaining consistency.

**Business Value:**

- Faster responses
- Consistent messaging
- Improved productivity

---

### UC-INBOX-004: Create Deal from High-Value Conversation

**Business Scenario:**

A sales rep is chatting with a potential enterprise customer. The conversation indicates strong buying intent. The rep wants to convert this to a deal for tracking.

**Steps:**
1. Sales rep opens WhatsApp conversation
2. Customer expresses interest: "We're looking for an enterprise solution"
3. Rep qualifies customer needs
4. Customer mentions budget: "$100,000"
5. Rep clicks **"Create Deal"** in conversation
6. Deal dialog opens with:
 - Contact: Pre-filled
 - Conversation: Linked
 - Title: "Enterprise Deal - [Company Name]"
7. Rep fills in details:
 - Value: $100,000
 - Stage: "Qualified"
 - Pipeline: "Enterprise Sales"
8. Saves deal
9. Deal appears in pipeline
10. Rep continues conversation with deal context
11. Tracks deal progress

**Expected Outcome:**

High-value conversation converts to tracked deal, enabling proper sales pipeline management.

**Business Value:**

- Opportunity capture
- Sales tracking
- Revenue management

---

### UC-INBOX-005: Close Conversation After Resolution

**Business Scenario:**

A support agent resolves a customer issue and wants to close the conversation to keep the inbox organized.

**Steps:**
1. Support agent resolves customer issue
2. Confirms customer satisfaction
3. Clicks **"Close Conversation"** button
4. Conversation status changes to "Closed"
5. Conversation moves to "Closed" filter
6. Inbox shows only open conversations
7. Customer sends new message later
8. Conversation automatically reopens
9. Agent receives notification
10. Agent responds to new inquiry

**Expected Outcome:**

Resolved conversations are closed, keeping inbox organized while allowing easy reopening for follow-ups.

**Business Value:**

- Organized inbox
- Focus on active conversations
- Easy follow-up handling

---

### UC-INBOX-006: Filter Conversations by Channel

**Business Scenario:**

A support team has dedicated agents for different channels. An Instagram specialist wants to see only Instagram conversations.

**Steps:**
1. Instagram specialist opens **Inbox**
2. Applies channel filter: "Instagram"
3. Views only Instagram conversations:
 - 12 active conversations
 - All Instagram DMs
4. Reviews each conversation
5. Responds to Instagram messages
6. Switches to "WhatsApp" filter
7. Sees WhatsApp conversations (if has access)
8. Returns to Instagram filter
9. Continues Instagram support work

**Expected Outcome:**

Specialist focuses on their channel, improving efficiency and expertise application.

**Business Value:**

- Channel specialization
- Improved efficiency
- Better service quality

---

### UC-INBOX-007: Search Conversations and Messages

**Business Scenario:**

A support agent remembers a previous conversation with a customer but can't find it. They need to search for it.

**Steps:**
1. Support agent opens **Inbox**
2. Clicks search bar
3. Types customer name: "John Smith"
4. Search results show:
 - 3 conversations with John Smith
 - Across WhatsApp and Email
5. Agent selects relevant conversation
6. Reviews conversation history
7. Finds previous context
8. Continues support with full context
9. Uses message search within conversation
10. Finds specific message about issue

**Expected Outcome:**

Agent quickly finds previous conversations and messages, enabling context-aware support.

**Business Value:**

- Quick information retrieval
- Context preservation
- Better customer service

---

### UC-INBOX-008: Bulk Assign Multiple Conversations

**Business Scenario:**

A team lead receives 20 unassigned conversations and needs to distribute them evenly among team members.

**Steps:**
1. Team lead opens **Inbox**
2. Filters: "Unassigned"
3. Views 20 unassigned conversations
4. Selects all conversations (bulk selection)
5. Clicks **"Bulk Assign"**
6. Chooses assignment method: "Round-robin"
7. System distributes:
 - 5 conversations to Agent A
 - 5 conversations to Agent B
 - 5 conversations to Agent C
 - 5 conversations to Agent D
8. Confirms assignment
9. All conversations assigned
10. Agents receive notifications
11. Agents see assigned conversations

**Expected Outcome:**

Conversations are evenly distributed among team members, ensuring fair workload and faster response times.

**Business Value:**

- Fair workload distribution
- Faster response times
- Better team utilization

---

## Task Management Use Cases

### UC-TASK-001: Create Follow-Up Task from Conversation

**Business Scenario:**

A support agent resolves a customer issue but needs to follow up in 3 days to ensure everything is working. They want to create a task to remember.

**Steps:**
1. Support agent resolves customer issue
2. Clicks **"Create Task"** in conversation
3. Task creation dialog opens:
 - Contact: Pre-filled from conversation
 - Conversation: Linked
4. Fills in task details:
 - Title: "Follow up with [Customer Name]"
 - Description: "Verify issue resolution and customer satisfaction"
 - Priority: Medium
 - Due date: 3 days from now
 - Assignee: Self
5. Saves task
6. Task appears in task list
7. Agent receives reminder on due date
8. Agent completes follow-up
9. Marks task as completed
10. Updates conversation with follow-up results

**Expected Outcome:**

Follow-up task is created and completed, ensuring customer satisfaction and issue resolution.

**Business Value:**

- No missed follow-ups
- Better customer service
- Organized workflow

---

### UC-TASK-002: Assign Task to Team Member

**Business Scenario:**

A sales manager needs to assign a task to a specific sales rep for a high-priority deal follow-up.

**Steps:**
1. Sales manager opens **Tasks** page
2. Clicks **"Create Task"**
3. Fills in task details:
 - Title: "Prepare proposal for ABC Corp deal"
 - Description: "Deal value: $50,000. Customer needs proposal by Friday"
 - Priority: High
 - Due date: Friday
 - Related deal: Links to deal
4. Selects assignee: "Sales Rep John"
5. Saves task
6. Sales rep receives notification
7. Sales rep sees task in "Assigned to Me"
8. Sales rep completes task
9. Marks task as completed
10. Deal updated with proposal status

**Expected Outcome:**

Task is assigned and completed, ensuring important follow-ups are handled by the right person.

**Business Value:**

- Clear task ownership
- Accountability
- Task completion tracking

---

### UC-TASK-003: Filter Tasks by Priority

**Business Scenario:**

A team member wants to focus on high-priority tasks first to ensure urgent items are handled.

**Steps:**
1. Team member opens **Tasks** page
2. Applies priority filter: "High"
3. Views only high-priority tasks:
 - 8 high-priority tasks shown
4. Reviews each task
5. Sorts by due date (earliest first)
6. Completes tasks in priority order
7. Marks tasks as completed
8. Switches to "Medium" priority
9. Continues with medium-priority tasks
10. Verifies all high-priority tasks completed

**Expected Outcome:**

Team member focuses on high-priority tasks first, ensuring urgent items are handled promptly.

**Business Value:**

- Priority-based work
- Urgent task completion
- Better time management

---

### UC-TASK-004: Create Recurring Task

**Business Scenario:**

A sales manager wants to create a weekly task for sales reps to review their pipeline every Monday.

**Steps:**
1. Sales manager opens **Tasks** page
2. Clicks **"Create Task"**
3. Fills in task details:
 - Title: "Weekly Pipeline Review"
 - Description: "Review all deals in pipeline and update stages"
 - Priority: Medium
 - Recurrence: Weekly, every Monday
4. Assigns to: "All Sales Reps" or specific rep
5. Saves task
6. Task appears every Monday
7. Sales rep completes task
8. Task automatically recreates for next Monday
9. Continues weekly cycle
10. Manager tracks completion rates

**Expected Outcome:**

Recurring task ensures consistent weekly pipeline reviews, maintaining sales discipline.

**Business Value:**

- Consistent processes
- Sales discipline
- Regular reviews

---

### UC-TASK-005: Link Task to Deal

**Business Scenario:**

A sales rep creates a task related to a specific deal and wants to link them for context.

**Steps:**
1. Sales rep opens deal details
2. Clicks **"Create Task"** from deal
3. Task creation dialog opens:
 - Deal: Pre-linked
 - Contact: Pre-filled from deal
4. Fills in task:
 - Title: "Send contract to customer"
 - Description: "Deal: $25,000. Customer requested contract"
 - Priority: High
 - Due date: Tomorrow
5. Saves task
6. Task appears in task list
7. Task also visible in deal details
8. Sales rep completes task
9. Updates deal with contract status
10. Deal shows completed task

**Expected Outcome:**

Task is linked to deal, maintaining context and enabling easy tracking of deal-related activities.

**Business Value:**

- Context preservation
- Deal activity tracking
- Better organization

---

### UC-TASK-006: View Overdue Tasks

**Business Scenario:**

A team manager wants to identify all overdue tasks to ensure nothing is missed.

**Steps:**
1. Team manager opens **Tasks** page
2. Applies filter: "Overdue"
3. Views overdue tasks:
 - 5 overdue tasks shown
 - Red overdue indicators
 - Days overdue displayed
4. Reviews each overdue task:
 - Task 1: 2 days overdue
 - Task 2: 5 days overdue
 - Task 3: 1 day overdue
5. Contacts task assignees
6. Reassigns if needed
7. Updates due dates if appropriate
8. Tracks completion
9. Verifies all overdue tasks addressed

**Expected Outcome:**

Manager identifies and addresses all overdue tasks, ensuring nothing falls through the cracks.

**Business Value:**

- Task accountability
- Nothing missed
- Better task management

---

### UC-TASK-007: Bulk Complete Tasks

**Business Scenario:**

A team member completes multiple related tasks and wants to mark them all as done at once.

**Steps:**
1. Team member opens **Tasks** page
2. Filters tasks: "Assigned to Me"
3. Completes several tasks
4. Selects completed tasks (bulk selection)
5. Clicks **"Mark as Completed"**
6. All selected tasks marked complete
7. Tasks move to completed view
8. Team member continues with remaining tasks
9. Reviews completion statistics
10. Verifies productivity improvement

**Expected Outcome:**

Multiple tasks are completed efficiently, improving productivity and task management.

**Business Value:**

- Time savings
- Improved productivity
- Better task tracking

---

## Scheduling (Calendly-like) Use Cases

### UC-SCHED-001: Create Event Type for Customer Consultations

**Business Scenario:**

A sales consultant wants to allow customers to book 30-minute consultation calls directly through a booking link.

**Steps:**
1. Consultant navigates to **Scheduling** page
2. Clicks **"New Event Type"**
3. Fills in event details:
 - Title: "30-Minute Sales Consultation"
 - Duration: 30 minutes
 - Description: "Discuss your business needs and how we can help"
 - Location: Google Meet (auto-generates link)
4. Configures availability:
 - Monday-Friday: 9 AM - 5 PM
 - Timezone: America/New_York
5. Sets booking settings:
 - Advance notice: 2 hours
 - Booking window: 60 days ahead
 - Buffer time: 15 minutes between meetings
6. Saves event type
7. Receives booking link: `connectgain.io/schedule/john/consultation`
8. Shares link with customers
9. Customer books appointment
10. Consultant receives notification

**Expected Outcome:**

Consultant has a professional booking page where customers can schedule consultations, eliminating back-and-forth emails.

**Business Value:**

- Eliminates scheduling emails
- Professional booking experience
- Time savings

---

### UC-SCHED-002: Customer Books Appointment via Public Link

**Business Scenario:**

A potential customer receives a booking link and wants to schedule a meeting with a sales rep.

**Steps:**
1. Customer clicks booking link
2. Views event details:
 - Event: "30-Minute Sales Consultation"
 - Duration: 30 minutes
 - Consultant name and photo
3. Views available time slots (calendar view)
4. Selects preferred date: Next Tuesday
5. Sees available times: 10:00 AM, 11:00 AM, 2:00 PM, 3:00 PM
6. Selects time: 2:00 PM
7. Fills in information:
 - Name: "Jane Doe"
 - Email: "jane@example.com"
 - Phone: "+1234567890"
 - Notes: "Interested in enterprise plan"
8. Confirms booking
9. Receives confirmation email with:
 - Meeting details
 - Google Meet link
 - Calendar invite (.ics file)
10. Consultant receives notification
11. Meeting appears in consultant's calendar

**Expected Outcome:**

Customer easily books appointment, receives confirmation, and both parties have calendar events created automatically.

**Business Value:**

- Easy booking process
- Automatic calendar sync
- Professional experience

---

### UC-SCHED-003: Integrate with Google Calendar

**Business Scenario:**

A consultant uses Google Calendar and wants booking slots to automatically check calendar availability and create events.

**Steps:**
1. Consultant navigates to **Scheduling → Integrations**
2. Clicks **"Connect Google Calendar"**
3. Authorizes ConnectGain access to Google Calendar
4. Selects primary calendar
5. Connection confirmed
6. Creates event type
7. System checks Google Calendar for busy times
8. Available slots exclude:
 - Existing calendar events
 - Busy times
 - All-day events
9. Customer books appointment
10. System creates Google Calendar event:
 - Title: "30-Minute Sales Consultation - Jane Doe"
 - Time: Selected slot
 - Attendees: Consultant + Customer
 - Google Meet link: Auto-added
 - Description: Customer notes included
11. Consultant sees event in Google Calendar
12. Customer receives calendar invite

**Expected Outcome:**

Booking system integrates seamlessly with Google Calendar, preventing double-booking and automatically creating events.

**Business Value:**

- No double-booking
- Automatic calendar sync
- Seamless integration

---

### UC-SCHED-004: Set Different Availability for Different Event Types

**Business Scenario:**

A consultant offers both quick 15-minute calls and longer 60-minute consultations. They want different availability for each.

**Steps:**
1. Consultant creates first event type: "Quick 15-Min Call"
2. Sets availability:
 - Monday-Friday: 2 PM - 4 PM (quick calls only)
3. Creates second event type: "60-Minute Deep Dive"
4. Sets different availability:
 - Monday, Wednesday, Friday: 10 AM - 12 PM
 - Tuesday, Thursday: 2 PM - 4 PM
5. Both event types active
6. Customers see appropriate availability for each
7. Quick calls available in afternoon slots
8. Deep dives available in morning/afternoon slots
9. Consultant manages both schedules
10. Verifies no conflicts

**Expected Outcome:**

Consultant offers different event types with appropriate availability, optimizing their schedule for different meeting types.

**Business Value:**

- Flexible scheduling
- Optimized time usage
- Better service offerings

---

### UC-SCHED-005: Block Dates for Time Off

**Business Scenario:**

A consultant is taking a week off and needs to block those dates so customers can't book appointments.

**Steps:**
1. Consultant navigates to **Scheduling**
2. Opens event type settings
3. Goes to **"Blocked Dates"** section
4. Adds blocked dates:
 - December 23-27 (Holiday week)
5. Saves blocked dates
6. System removes those dates from availability
7. Customers trying to book see:
 - Dates unavailable
 - No time slots shown
8. Consultant returns from time off
9. Removes blocked dates
10. Availability restored

**Expected Outcome:**

Consultant blocks time off dates, preventing bookings during unavailable periods.

**Business Value:**

- Work-life balance
- Clear availability
- Professional boundaries

---

### UC-SCHED-006: Reschedule Existing Booking

**Business Scenario:**

A customer needs to reschedule their appointment due to a conflict.

**Steps:**
1. Customer receives booking confirmation email
2. Clicks **"Reschedule"** link in email
3. Views current booking:
 - Date: Tuesday, 2:00 PM
 - Event: 30-Minute Consultation
4. Views new available slots
5. Selects new date: Thursday
6. Selects new time: 3:00 PM
7. Confirms reschedule
8. Old booking cancelled
9. New booking created
10. Consultant receives reschedule notification
11. Google Calendar event updated automatically
12. Both parties receive updated calendar invites

**Expected Outcome:**

Customer easily reschedules appointment, and both parties receive updated calendar events automatically.

**Business Value:**

- Easy rescheduling
- Automatic updates
- Better customer experience

---

### UC-SCHED-007: Cancel Booking

**Business Scenario:**

A customer needs to cancel their appointment.

**Steps:**
1. Customer opens booking confirmation email
2. Clicks **"Cancel Booking"** link
3. Confirms cancellation
4. Booking status changes to "Cancelled"
5. Time slot becomes available again
6. Consultant receives cancellation notification
7. Google Calendar event removed/cancelled
8. Customer receives cancellation confirmation
9. Consultant can see cancelled bookings in history
10. Slot available for other customers

**Expected Outcome:**

Booking is cancelled smoothly, time slot freed up, and both parties notified appropriately.

**Business Value:**

- Easy cancellation
- Slot availability
- Clear communication

---

### UC-SCHED-008: Customize Booking Page Branding

**Business Scenario:**

A company wants their booking pages to match their brand colors and include their logo.

**Steps:**
1. Admin opens event type settings
2. Navigates to **"Branding"** tab
3. Uploads company logo
4. Sets theme colors:
 - Primary: Company blue (#0066CC)
 - Secondary: Company gray (#666666)
5. Uploads banner image (optional)
6. Customizes confirmation message
7. Saves branding
8. Views preview of booking page
9. Verifies branding applied
10. Shares booking link
11. Customers see branded booking page
12. Professional brand experience

**Expected Outcome:**

Booking pages reflect company branding, providing consistent brand experience to customers.

**Business Value:**

- Brand consistency
- Professional appearance
- Brand recognition

---

## Campaigns & Broadcast Use Cases

### UC-CAMP-001: Send SMS Campaign to All Contacts

**Business Scenario:**

A retail business wants to send a promotional SMS to all customers announcing a flash sale.

**Steps:**
1. Marketing manager navigates to **Broadcast** page
2. Clicks **"Create Campaign"**
3. Selects campaign type: **SMS**
4. Selects SMS channel account
5. Composes message:
 - Text: "Flash Sale! 50% off all items today only. Use code FLASH50. Shop now: [link]"
 - Character count: 98/160 (within limit)
6. Configures targeting:
 - Target: **All Contacts**
 - Recipient count: 1,250 contacts
7. Sets scheduling:
 - Send: **Immediately**
8. Reviews preview
9. Confirms campaign
10. Campaign starts sending
11. Monitors delivery status:
 - Sent: 1,250
 - Delivered: 1,245
 - Failed: 5
12. Reviews campaign analytics

**Expected Outcome:**

SMS campaign is sent to all contacts, reaching customers instantly with promotional message.

**Business Value:**

- Instant customer reach
- High open rates (SMS)
- Direct communication

---

### UC-CAMP-002: Send WhatsApp Campaign to Tagged Contacts

**Business Scenario:**

A business wants to send a WhatsApp message only to contacts tagged as "VIP Customers" with a special offer.

**Steps:**
1. Marketing manager creates campaign
2. Selects campaign type: **[WhatsApp Lite](https://docs.connectgain.cloud/04-use-cases/05-integrations/whatsapp-lite-api.md)**
3. Selects WhatsApp channel
4. Composes message:
 - Text: "Exclusive VIP Offer! 30% off your next purchase. Valid until [date]. Use code VIP30"
 - Includes image: Special offer graphic
5. Configures targeting:
 - Target: **By Tags**
 - Selected tags: "VIP Customers"
 - Recipient count: 85 contacts
6. Sets scheduling:
 - Send: **Schedule for Later**
 - Date: Tomorrow, 10:00 AM
 - Timezone: Organization timezone
7. Saves campaign
8. Campaign scheduled
9. Campaign sends at scheduled time
10. Monitors delivery:
 - Sent: 85
 - Delivered: 83
 - Read: 78
11. Tracks engagement

**Expected Outcome:**

VIP customers receive exclusive WhatsApp offer, maintaining personalized communication with high-value customers.

**Business Value:**

- Targeted messaging
- VIP customer engagement
- Higher conversion rates

---

### UC-CAMP-003: Send Email Campaign with Personalization

**Business Scenario:**

A company wants to send a personalized email newsletter to all contacts with variable substitution for names and companies.

**Steps:**
1. Marketing manager creates campaign
2. Selects campaign type: **Email**
3. Selects email channel account
4. Composes email:
 - Subject: "Hello {{first_name}}, Monthly Newsletter"
 - Body: HTML email with:
 - Personalized greeting: "Hi {{first_name}},"
 - Company mention: "We noticed you're with {{company}}"
 - Personalized content based on contact data
5. Includes images and formatting
6. Configures targeting:
 - Target: **All Contacts**
 - Recipient count: 2,500 contacts
7. Sets scheduling:
 - Send: **Schedule for Later**
 - Date: First of month, 9:00 AM
8. Reviews email preview with sample data
9. Confirms campaign
10. Campaign sends at scheduled time
11. Each recipient receives personalized email
12. Tracks:
 - Sent: 2,500
 - Delivered: 2,485
 - Opened: 1,250 (50% open rate)
 - Clicked: 375 (15% click rate)

**Expected Outcome:**

Personalized email campaign is sent to all contacts, improving engagement through personalization.

**Business Value:**

- Personalization improves engagement
- Higher open and click rates
- Better campaign performance

---

### UC-CAMP-004: Target Specific Individual Contacts

**Business Scenario:**

A sales manager wants to send a follow-up message to 10 specific high-value prospects who attended a webinar.

**Steps:**
1. Sales manager creates campaign
2. Selects campaign type: **WhatsApp Business**
3. Selects WhatsApp Business channel
4. Composes message:
 - Uses approved WhatsApp template
 - Template: "webinar_followup"
 - Variables: {{name}}, {{company}}
5. Configures targeting:
 - Target: **Individual Contacts**
 - Selects 10 specific contacts from list
 - Recipient preview shows all 10 contacts
6. Sets scheduling:
 - Send: **Immediately**
7. Reviews each contact in preview
8. Confirms campaign
9. Campaign sends to 10 contacts
10. Monitors delivery:
 - Sent: 10
 - Delivered: 10
 - Read: 9
11. Tracks responses

**Expected Outcome:**

Targeted message is sent to specific high-value prospects, enabling personalized follow-up.

**Business Value:**

- Targeted outreach
- High-value prospect engagement
- Personalized communication

---

### UC-CAMP-005: Schedule Campaign for Optimal Time

**Business Scenario:**

A business wants to send a campaign at the optimal time when their audience is most likely to engage (Tuesday, 10 AM).

**Steps:**
1. Marketing manager creates campaign
2. Composes message content
3. Configures targeting
4. Sets scheduling:
 - Send: **Schedule for Later**
 - Date: Next Tuesday
 - Time: 10:00 AM
 - Timezone: Organization timezone (matches audience)
5. Saves campaign
6. Campaign status: "Scheduled"
7. Campaign appears in scheduled campaigns list
8. On Tuesday at 10 AM:
 - Campaign automatically starts
 - Status changes to "Sending"
9. Monitors real-time sending progress
10. Campaign completes
11. Status: "Completed"
12. Reviews performance metrics

**Expected Outcome:**

Campaign is scheduled and sent at optimal time, maximizing engagement and open rates.

**Business Value:**

- Optimal timing
- Better engagement rates
- Strategic campaign execution

---

### UC-CAMP-006: Track Campaign Performance

**Business Scenario:**

A marketing manager wants to analyze campaign performance to understand what works and optimize future campaigns.

**Steps:**
1. Marketing manager opens **Broadcast** page
2. Views campaign list
3. Selects completed campaign
4. Reviews campaign analytics:
 - **Delivery Stats:**
 - Sent: 1,000
 - Delivered: 985
 - Failed: 15
 - Delivery rate: 98.5%
 - **Engagement (WhatsApp):**
 - Read: 750
 - Read rate: 76.1%
 - **Engagement (Email):**
 - Opened: 450
 - Clicked: 120
 - Open rate: 45%
 - Click rate: 12%
 - **Cost Analysis:**
 - SMS cost: $0.05 per message
 - Total cost: $50
 - Cost per delivery: $0.051
5. Compares to previous campaigns
6. Identifies best-performing:
 - Message content
 - Send times
 - Target segments
7. Applies insights to next campaign
8. Improves future performance

**Expected Outcome:**

Marketing manager gains insights into campaign performance, enabling data-driven optimization of future campaigns.

**Business Value:**

- Data-driven decisions
- Campaign optimization
- Improved ROI

---

### UC-CAMP-007: Send Multi-Channel Campaign

**Business Scenario:**

A business wants to send the same promotional message via both SMS and WhatsApp to maximize reach.

**Steps:**
1. Marketing manager creates first campaign
2. Campaign type: **SMS**
3. Composes SMS message (160 characters)
4. Targets all contacts
5. Schedules for 10 AM
6. Creates second campaign
7. Campaign type: **WhatsApp Lite**
8. Composes WhatsApp message (same content, can be longer)
9. Includes image
10. Targets same contacts
11. Schedules for 10:15 AM (15 minutes after SMS)
12. Both campaigns scheduled
13. SMS sends first at 10 AM
14. WhatsApp sends at 10:15 AM
15. Customers receive both messages
16. Tracks engagement across both channels
17. Compares performance:
 - SMS: Higher delivery, lower engagement
 - WhatsApp: Higher engagement, richer content

**Expected Outcome:**

Multi-channel campaign reaches customers through multiple touchpoints, maximizing message visibility and engagement.

**Business Value:**

- Maximum reach
- Multi-channel engagement
- Better campaign coverage

---

### UC-CAMP-008: Use WhatsApp Business Templates

**Business Scenario:**

A business wants to send a WhatsApp campaign using an approved WhatsApp Business template for compliance.

**Steps:**
1. Marketing manager creates campaign
2. Selects campaign type: **WhatsApp Business**
3. Selects WhatsApp Business channel account
4. Chooses **"Use Template"** option
5. Browses approved templates:
 - Selects: "promotional_offer"
6. Fills template variables:
 - {{1}}: Customer name
 - {{2}}: Discount percentage
 - {{3}}: Expiry date
7. Previews template with sample data
8. Configures targeting
9. Sets scheduling
10. Confirms campaign
11. Campaign sends using approved template
12. All messages comply with WhatsApp Business policies
13. High delivery rate (template messages prioritized)
14. Tracks template message performance

**Expected Outcome:**

Campaign uses approved WhatsApp Business template, ensuring compliance and high delivery rates.

**Business Value:**

- Policy compliance
- Higher delivery rates
- Professional messaging

---

### UC-CAMP-009: Segment Campaign by Contact Tags

**Business Scenario:**

A business wants to send different messages to different customer segments based on their interests and behavior.

**Steps:**
1. Marketing manager creates campaign for "Enterprise Customers"
2. Selects campaign type: **Email**
3. Composes enterprise-focused message
4. Targets: **By Tags**
 - Tags: "Enterprise", "High-Value"
 - Recipient count: 150
5. Schedules campaign
6. Creates second campaign for "Small Business"
7. Composes SMB-focused message
8. Targets: **By Tags**
 - Tags: "Small Business", "SMB"
 - Recipient count: 500
9. Schedules campaign
10. Both campaigns send to appropriate segments
11. Each segment receives relevant messaging
12. Tracks segment-specific performance
13. Compares engagement rates:
 - Enterprise: 60% open rate
 - SMB: 45% open rate
14. Optimizes messaging per segment

**Expected Outcome:**

Segmented campaigns deliver relevant messages to each customer group, improving engagement and conversion rates.

**Business Value:**

- Targeted messaging
- Higher engagement
- Better conversion rates

---

### UC-CAMP-010: Link Shortening for SMS Campaigns

**Business Scenario:**

A business wants to include a link in an SMS campaign but needs to save characters and track clicks.

**Steps:**
1. Marketing manager creates SMS campaign
2. Composes message with long URL:
 - "Check out our sale: https://example.com/sale/flash-sale-2024"
3. Enables **"Shorten Links"** option
4. System shortens URL:
 - Original: 45 characters
 - Shortened: 20 characters
 - Saves: 25 characters
5. Message fits within 160-character limit
6. Campaign sends with shortened link
7. Customers receive SMS with short link
8. System tracks link clicks:
 - Total clicks: 250
 - Unique clicks: 200
 - Click-through rate: 20%
9. Analytics show:
 - Which contacts clicked
 - Click timestamps
 - Device information
10. Marketing manager reviews click analytics

**Expected Outcome:**

SMS campaign uses shortened links, saving characters and providing click tracking analytics.

**Business Value:**

- Character savings
- Click tracking
- Campaign analytics

---

## Analytics & Dashboard Use Cases

### UC-ANALYTICS-001: Monitor Weekly Team Performance

**Business Scenario:**

A sales manager needs to review weekly team performance metrics to identify areas for improvement and recognize top performers.

**Steps:**
1. Manager navigates to **Analytics** page
2. Selects time range: "Last 7 days"
3. Reviews overview metrics:
 - Total Messages: 1,250 (+12.5% vs previous week)
 - Average Response Time: 2.5 hours (-5.2% improvement)
 - SLA Compliance: 95.5% (+2.1% improvement)
 - Total Contacts: 5,420 (+8.3% growth)
4. Switches to **Inbox** tab:
 - Reviews average response time: 2.5 hours
 - Checks SLA compliance: 95.5%
 - Identifies resolved conversations: 450
 - Notes unassigned messages: 12
 - Reviews overdue conversations: 5
5. Switches to **Deals** tab:
 - Reviews active deals: 125
 - Checks pipeline value: $2,500,000
 - Analyzes conversion rate: 25.5%
 - Reviews stage distribution
6. Switches to **Performance** tab:
 - Reviews task completion: 85% (340/400 tasks)
 - Checks overall performance score: A-
7. Compares metrics with previous period
8. Exports report for team meeting

**Expected Outcome:**

Manager has comprehensive weekly performance data with period-over-period comparisons, enabling data-driven decisions and team feedback.

**Business Value:**

- Identifies performance trends
- Enables data-driven management
- Improves team accountability
- Supports strategic planning

---

### UC-ANALYTICS-002: Track Monthly Business Metrics for Executive Review

**Business Scenario:**

An executive needs monthly business metrics for a board meeting presentation.

**Steps:**
1. Executive navigates to **Analytics** page
2. Selects time range: "Last 30 days"
3. Reviews all key metrics across tabs
4. Notes period comparisons:
 - Message volume trends
 - Response time improvements
 - Contact growth rate
 - Deal conversion metrics
5. Takes screenshots of key metrics
6. Exports data to CSV for further analysis
7. Prepares presentation slides with insights
8. Shares dashboard link with board members

**Expected Outcome:**

Executive has all necessary metrics and insights for board presentation, demonstrating business growth and operational efficiency.

**Business Value:**

- Executive visibility into operations
- Data-driven decision making
- Stakeholder transparency
- Performance accountability

---

### UC-DASHBOARD-001: Create Custom Metric Widget for High-Value Deals

**Business Scenario:**

A sales director wants to track high-value deals (>$10,000) as a custom metric on the dashboard.

**Steps:**
1. User navigates to **Dashboard** page
2. Clicks **"Add Widget"** button
3. Selects **"Custom Widget"** option
4. Configures widget:
 - Title: "High-Value Deals"
 - Query: `SELECT COUNT(*) FROM deals WHERE value > 10000 AND status = 'OPEN'`
 - Aggregation: COUNT
 - Format: Number
5. Sets widget position: 5th widget
6. Saves widget
7. Verifies widget appears on dashboard
8. Checks widget updates in real-time
9. Monitors metric daily

**Expected Outcome:**

Custom metric widget displays count of high-value deals, updating automatically as deals are created or updated.

**Business Value:**

- Custom business metric tracking
- Real-time visibility
- Focus on high-value opportunities
- Data-driven sales strategy

---

### UC-DASHBOARD-002: Monitor Daily Performance with Dashboard Widgets

**Business Scenario:**

A team lead wants to monitor daily team performance using dashboard widgets.

**Steps:**
1. Team lead opens **Dashboard**
2. Sets date range to "Today"
3. Reviews widget metrics:
 - Incoming Messages: 42 (target: < 50)
 - Ongoing Conversations: 28
 - Unanswered Conversations: 3 (needs attention)
 - Median Reply Time: 1.5 hours
 - Longest Awaiting Reply: 4 hours (urgent)
4. Checks **Sales & Deals** widgets:
 - Won Leads: 5 deals, $125,000
 - Active Leads: 45 deals
 - Active Deals: $850,000 pipeline value
5. Reviews **Tasks & Contacts** widgets:
 - Tasks Overview: 12 completed, 3 overdue
 - Total Contacts: 5,420
 - Total Companies: 1,250
6. Checks **4-Week Performance Overview** chart
7. Reviews **Recent Activity Feed** for latest events
8. Takes action on overdue conversations
9. Assigns tasks based on insights

**Expected Outcome:**

Team lead has real-time visibility into daily performance and can quickly identify areas needing attention.

**Business Value:**

- Real-time performance monitoring
- Quick issue identification
- Proactive management
- Improved team efficiency

---

## Bot Flows Use Cases

### UC-BOTFLOWS-001: Create Welcome Bot Flow for New Conversations

**Business Scenario:**

A business wants to automatically welcome new customers and route them to appropriate departments based on their inquiry.

**Steps:**
1. Admin navigates to **Bot Flows** page
2. Clicks **"Create Flow"**
3. Names flow: "Welcome & Routing Flow"
4. Adds **Start Node** (trigger: message.received)
5. Adds **Send Message Node**:
 - Message: "Hello! Welcome to {{company_name}}. How can we help you today?"
6. Adds **Collect Input Node**:
 - Prompt: "Please describe what you need help with"
 - Input type: Text
 - Variable name: `user_inquiry`
7. Adds **Condition Node**:
 - Condition: `user_inquiry` contains "order" OR "purchase"
 - True branch: Sales flow
 - False branch: Continue to next condition
8. Adds **Condition Node**:
 - Condition: `user_inquiry` contains "support" OR "help" OR "issue"
 - True branch: Support flow
 - False branch: General inquiry
9. For Sales branch:
 - Adds **Send Message Node**: "Great! Let me connect you with our sales team."
 - Adds **Assign Conversation Node**: Assign to Sales team
10. For Support branch:
 - Adds **Send Message Node**: "I'll connect you with our support team."
 - Adds **Assign Conversation Node**: Assign to Support team
11. For General branch:
 - Adds **Send Message Node**: "A team member will assist you shortly."
 - Adds **Handoff Node**: Transfer to human agent
12. Publishes flow
13. Tests flow with sample messages
14. Verifies flow executes correctly

**Expected Outcome:**

New conversations automatically receive welcome message, collect inquiry information, and route to appropriate team based on keywords.

**Business Value:**

- Improved first response time
- Automatic routing
- Better customer experience
- Reduced manual workload

---

### UC-BOTFLOWS-002: Create FAQ Bot Flow with AI Responses

**Business Scenario:**

A business wants to automate responses to common questions using AI, while escalating complex queries to human agents.

**Steps:**
1. Admin creates new flow: "FAQ Bot Flow"
2. Adds **Start Node** (trigger: message.received)
3. Adds **Send Message Node**: "Hi! I'm here to help. What would you like to know?"
4. Adds **Collect Input Node**: Collects user question in variable `user_question`
5. Adds **AI Response Node**:
 - Model: Gemini 2.5 Flash (the platform LLM; via Lovable Gateway or BYOK Gemini)
 - Prompt template: "You are a helpful customer service assistant. Answer this question about our products: {{user_question}}. Keep responses under 200 words."
 - Temperature: 0.7
 - Max tokens: 300
6. Adds **Condition Node**:
 - Condition: AI response confidence > 0.8
 - True branch: Send AI response
 - False branch: Handoff to human
7. For AI response branch:
 - Adds **Send Message Node**: Sends AI-generated response
 - Adds **Collect Input Node**: "Was this helpful? Type 'yes' or 'no'"
 - Adds **Condition Node**: If "no", handoff to human
8. For handoff branch:
 - Adds **Send Message Node**: "Let me connect you with a team member."
 - Adds **Handoff Node**: Transfer to human agent
9. Publishes flow
10. Tests with various FAQ questions
11. Monitors AI response quality
12. Adjusts prompt template based on feedback

**Expected Outcome:**

Bot automatically answers common questions using AI, while seamlessly transferring complex queries to human agents when needed.

**Business Value:**

- 24/7 automated support
- Reduced support workload
- Faster response times
- Improved customer satisfaction

---

### UC-BOTFLOWS-003: Create Lead Qualification Flow

**Business Scenario:**

A sales team wants to automatically qualify leads through a structured conversation flow, collecting information and creating deals.

**Steps:**
1. Admin creates flow: "Lead Qualification Flow"
2. Adds **Start Node** (trigger: message.received AND contact has tag "lead")
3. Adds **Send Message Node**: "Hi {{contact.first_name}}! I'd like to learn more about your needs. Can you tell me about your company?"
4. Adds **Collect Input Node**: Collects company name → `company_name`
5. Adds **Send Message Node**: "What industry are you in?"
6. Adds **Collect Input Node**: Collects industry → `industry`
7. Adds **Send Message Node**: "What's your approximate budget for this project?"
8. Adds **Collect Input Node**: Collects budget → `budget` (number input)
9. Adds **Send Message Node**: "When are you looking to get started?"
10. Adds **Collect Input Node**: Collects timeline → `timeline` (date input)
11. Adds **Condition Node**:
 - Condition: `budget` > 10000 AND `timeline` < 90 days
 - True branch: Hot lead
 - False branch: Warm lead
12. For Hot lead:
 - Adds **Send Message Node**: "Great! You're a perfect fit. Let me connect you with our sales team."
 - Adds **Create Deal Node**:
 - Title: "{{company_name}} - {{industry}}"
 - Value: `budget`
 - Stage: "Qualified"
 - Priority: HIGH
 - Adds **Add Tag Node**: Add tag "hot_lead"
 - Adds **Assign Conversation Node**: Assign to senior sales rep
13. For Warm lead:
 - Adds **Send Message Node**: "Thanks for the information! A team member will follow up soon."
 - Adds **Create Deal Node**: Lower priority deal
 - Adds **Add Tag Node**: Add tag "warm_lead"
14. Publishes flow
15. Tests with sample lead conversations
16. Verifies deals created automatically

**Expected Outcome:**

Leads are automatically qualified through structured conversation, with deals created and assigned based on qualification criteria.

**Business Value:**

- Automated lead qualification
- Consistent qualification process
- Automatic deal creation
- Improved lead conversion

---

## Contact Management Use Cases

### UC-CONTACTS-001: Import 5,000 Contacts from CSV

**Business Scenario:**

A company wants to migrate their existing customer database from Excel to ConnectGain.

**Steps:**
1. Admin navigates to **Contacts** page
2. Clicks **"Import"** button
3. Selects CSV file with 5,000 contacts
4. Reviews column mapping:
 - First Name → first_name
 - Last Name → last_name
 - Email → emails
 - Phone → phones
 - Company → company_name
 - Tags → tags
5. Configures duplicate handling: Merge duplicates by email
6. Reviews import preview (first 10 rows)
7. Starts import process
8. Monitors import progress (progress bar)
9. Reviews import results:
 - Successfully imported: 4,850
 - Duplicates merged: 100
 - Errors: 50
10. Downloads error report
11. Fixes errors in CSV
12. Re-imports failed contacts
13. Verifies all contacts in contact list
14. Checks auto-tagging by country (if enabled)

**Expected Outcome:**

5,000 contacts successfully imported with proper field mapping, duplicates handled, and errors resolved.

**Business Value:**

- Rapid database migration
- Data consolidation
- Time savings
- Improved data quality

---

### UC-CONTACTS-002: Find Contact by Phone Number During Customer Call

**Business Scenario:**

A customer calls, and an agent needs to quickly find their contact record to view history and provide personalized service.

**Steps:**
1. Agent receives phone call
2. Customer provides phone number: +1-234-567-8900
3. Agent navigates to **Contacts** page
4. Enters phone number in search: "2345678900" (various formats work)
5. Search returns matching contact instantly
6. Agent clicks on contact
7. Views contact details:
 - Full name, email, company
 - All phone numbers
 - Communication history
 - Related deals
 - Related tasks
 - Notes timeline
8. Reviews recent conversation history
9. Checks open deals
10. Provides personalized service based on history
11. Updates contact notes with call details

**Expected Outcome:**

Agent finds contact instantly by phone number and accesses complete history for personalized service.

**Business Value:**

- Faster customer service
- Personalized interactions
- Complete context
- Improved customer satisfaction

---

### UC-CONTACTS-003: Tag Contacts for Targeted Campaign

**Business Scenario:**

Marketing team wants to send a campaign to VIP customers (deals > $10,000) only.

**Steps:**
1. Marketing manager navigates to **Contacts** page
2. Applies filter: "Open Deals" = "10+ deals"
3. Reviews filtered contacts (shows contacts with high-value deals)
4. Selects all filtered contacts (bulk selection)
5. Clicks **"Bulk Actions"** → **"Add Tags"**
6. Adds tag: "VIP Customer"
7. Confirms tag assignment
8. Verifies all contacts tagged
9. Navigates to **Campaigns** page
10. Creates new campaign
11. Selects target: "Tag: VIP Customer"
12. Reviews recipient preview (shows all VIP customers)
13. Composes campaign message
14. Sends campaign to VIP customers only

**Expected Outcome:**

VIP customers tagged and targeted campaign sent only to high-value customers.

**Business Value:**

- Targeted marketing
- Higher campaign ROI
- Customer segmentation
- Personalized messaging

---

### UC-CONTACTS-004: Merge Duplicate Contacts

**Business Scenario:**

System has duplicate contact entries that need to be merged into a single record.

**Steps:**
1. Admin navigates to **Contacts** page
2. Clicks **"Find Duplicates"** option
3. System scans and identifies duplicate contacts:
 - Contact A: "John Doe", +1234567890, john@example.com
 - Contact B: "John Doe", +1234567890, john.doe@example.com
4. Admin reviews duplicate suggestions
5. Selects contacts to merge: Contact A and Contact B
6. Chooses primary contact: Contact A
7. Reviews merge preview:
 - Primary: Contact A
 - Merged data: All phone numbers, emails, notes, deals, tasks
8. Confirms merge
9. Verifies merged contact has all data:
 - Both phone numbers preserved
 - Both email addresses preserved
 - All deals linked
 - All tasks linked
 - All notes preserved
10. Verifies duplicate contact deleted

**Expected Outcome:**

Duplicate contacts merged into single record with all data preserved and relationships maintained.

**Business Value:**

- Clean database
- No data loss
- Improved data quality
- Better reporting accuracy

---

## Company Management Use Cases

### UC-COMPANIES-001: Import Companies from HubSpot

**Business Scenario:**

A B2B company wants to migrate 1,000 companies from HubSpot to ConnectGain.

**Steps:**
1. Admin navigates to **Companies** page
2. Clicks **"Import"** → **"Import from HubSpot"**
3. Authenticates with HubSpot OAuth
4. Selects companies to import (1,000 companies)
5. Maps HubSpot fields to ConnectGain fields:
 - Company Name → name
 - Industry → industry
 - Website → website
 - Address → address fields
 - Phone → phones
 - Annual Revenue → annual_revenue
6. Reviews import preview
7. Configures duplicate handling: Merge by company name
8. Starts import process
9. Monitors import progress
10. Reviews import results:
 - Successfully imported: 950
 - Duplicates merged: 30
 - Errors: 20
11. Fixes errors and re-imports
12. Verifies all companies imported
13. Links contacts to companies
14. Creates deals linked to companies

**Expected Outcome:**

1,000 companies successfully imported from HubSpot with proper field mapping and relationships maintained.

**Business Value:**

- Seamless CRM migration
- Data preservation
- Relationship maintenance
- Time savings

---

### UC-COMPANIES-002: Find Companies by Country for Regional Sales

**Business Scenario:**

Sales team wants to find all companies in a specific country for regional outreach.

**Steps:**
1. Sales manager navigates to **Companies** page
2. Opens country filter dropdown
3. Selects country: "United States"
4. Views filtered companies (only US companies shown)
5. Reviews company list:
 - Company cards with key info
 - Industry tags
 - Website links
 - Contact counts
6. Switches to table view for detailed comparison
7. Exports filtered list to CSV
8. Uses list for targeted sales campaign
9. Creates deals for selected companies

**Expected Outcome:**

All companies in selected country displayed and exported for regional sales activities.

**Business Value:**

- Geographic segmentation
- Targeted sales
- Regional analysis
- Export capabilities

---

### UC-COMPANIES-003: Create Company and Deal Simultaneously

**Business Scenario:**

Sales rep discovers a new company and wants to create both company record and initial deal in one action.

**Steps:**
1. Sales rep navigates to **Companies** page
2. Clicks **"Add Company"**
3. Fills company information:
 - Name: "Acme Corporation"
 - Industry: "Technology"
 - Website: "https://acme.com"
 - Country: "United States"
 - Address: Complete address
4. Checks **"Create Deal"** option
5. Fills deal information:
 - Deal Title: "Acme Corporation - Initial Engagement"
 - Contact: Selects or creates contact
 - Pipeline: "Sales Pipeline"
 - Stage: "Lead"
 - Value: $50,000
6. Saves company and deal
7. Verifies both created:
 - Company appears in companies list
 - Deal appears in deals pipeline
 - Deal linked to company
 - Contact linked to company

**Expected Outcome:**

Company and deal created simultaneously with proper relationships established.

**Business Value:**

- Faster data entry
- Relationship establishment
- Workflow efficiency
- Complete records

---

## Template Management Use Cases

### UC-TEMPLATES-001: Create WhatsApp Template with Variables

**Business Scenario:**

A business wants to create a personalized welcome template for WhatsApp campaigns.

**Steps:**
1. Admin navigates to **Templates** page
2. Clicks **"Create Template"**
3. Enters template name: "Welcome Message"
4. Selects category: GENERAL
5. Selects channel: WhatsApp
6. Configures template components:
 - **Header**: "Welcome to {{company_name}}!"
 - **Body**: "Hello {{name}}, thank you for joining us! We're excited to have you. Your account is ready to use."
 - **Footer**: "Thank you for choosing us"
 - **Buttons**:

 - "Get Started" (call-to-action)
 - "Learn More" (URL button)
7. Adds variables:
 - {{name}} - Contact first name
 - {{company_name}} - Company name
8. Previews template with sample data
9. Submits template for approval
10. Waits for WhatsApp approval
11. Uses template in campaigns after approval
12. Tracks template usage and performance

**Expected Outcome:**

WhatsApp template created with variables, approved by WhatsApp, and available for use in campaigns.

**Business Value:**

- Consistent messaging
- Personalization at scale
- WhatsApp compliance
- Professional communication

---

### UC-TEMPLATES-002: Create Quick Reply Template for Support

**Business Scenario:**

Support team wants quick reply templates for common customer questions.

**Steps:**
1. Support manager navigates to **Templates** page
2. Clicks **"Create Template"**
3. Enters template name: "Order Status Inquiry"
4. Selects category: QUICK_REPLY
5. Enters message: "Hi {{name}}! I'll check your order status right away. Your order number is {{order_number}}. I'll get back to you within 5 minutes."
6. Adds variables: {{name}}, {{order_number}}
7. Saves template
8. Creates additional quick reply templates:
 - "Refund Request"
 - "Product Information"
 - "Technical Support"
9. Goes to **Settings** → **Quick Replies**
10. Adds templates to quick replies
11. Tests in inbox conversation:
 - Types "/" to open quick replies
 - Selects template
 - Variables auto-filled
 - Sends message

**Expected Outcome:**

Quick reply templates available in inbox for fast, consistent customer responses.

**Business Value:**

- Faster response times
- Consistent messaging
- Reduced typing
- Improved efficiency

---

### UC-TEMPLATES-003: Test Template Before Campaign Send

**Business Scenario:**

Marketing manager wants to test a template before sending to 10,000 contacts.

**Steps:**
1. Marketing manager creates new template
2. Configures template with variables
3. Clicks **"Send Test"** button
4. Enters test phone number: Own phone number
5. Fills test variables:
 - name: "John"
 - company: "Acme Inc"
6. Sends test message
7. Receives test message on phone
8. Reviews message:
 - Formatting correct
 - Variables substituted correctly
 - Buttons working
 - Links functional
9. Makes adjustments if needed
10. Sends another test
11. Approves template after testing
12. Uses template in campaign

**Expected Outcome:**

Template tested and verified before campaign send, ensuring quality and correctness.

**Business Value:**

- Quality assurance
- Error prevention
- Professional messaging
- Campaign success

---

## Project Management Use Cases

### UC-PROJECTS-001: Create Project with Milestones and Deliverables

**Business Scenario:**

A project manager wants to track a client project with clear milestones and deliverables.

**Steps:**
1. Project manager navigates to **Projects** page
2. Clicks **"New Project"**
3. Fills project details:
 - Name: "Website Redesign"
 - Description: "Complete website redesign for Acme Corp"
 - Type: DELIVERY
 - Start Date: January 15, 2025
 - End Date: April 15, 2025
 - Budget: $50,000
 - Customer Contact: Links to Acme Corp contact
4. Saves project
5. Adds milestones:
 - Milestone 1: "Design Phase" (Due: February 1)
 - Milestone 2: "Development Phase" (Due: March 15)
 - Milestone 3: "Testing Phase" (Due: April 1)
 - Milestone 4: "Launch" (Due: April 15)
6. Adds deliverables for each milestone:
 - Design Phase: "Homepage Mockup", "Product Page Design"
 - Development Phase: "Frontend Development", "Backend Integration"
 - Testing Phase: "QA Testing", "Performance Testing"
 - Launch: "Production Deployment", "Documentation"
7. Assigns team members to project
8. Views project in timeline view
9. Tracks progress as milestones complete

**Expected Outcome:**

Project created with structured milestones and deliverables, enabling clear tracking and client visibility.

**Business Value:**

- Clear project structure
- Progress tracking
- Client transparency
- Team alignment

---

### UC-PROJECTS-002: Share Public Project Timeline with Client

**Business Scenario:**

A business wants to share project progress with a client without requiring them to log in.

**Steps:**
1. Project manager opens project details
2. Clicks **"Share"** button
3. Generates public sharing token
4. Copies public URL: `https://connectgain.com/projects/public/[token]`
5. Shares URL with client via email
6. Client opens URL (no login required)
7. Client views public timeline:
 - Project timeline visualization
 - All milestones visible
 - Deliverables listed
 - Progress indicators
 - Status updates
8. Client can see:
 - Completed milestones (green checkmarks)
 - Upcoming milestones (scheduled dates)
 - Deliverable status
 - Overall progress percentage
9. Project manager updates project status
10. Client sees updates in real-time

**Expected Outcome:**

Client can view project timeline publicly without login, improving transparency and communication.

**Business Value:**

- Client transparency
- Reduced support requests
- Professional presentation
- Real-time updates

---

### UC-PROJECTS-003: Track Project Progress with Timeline View

**Business Scenario:**

Project manager wants to visualize all projects and their timelines in a Gantt-style view.

**Steps:**
1. Project manager navigates to **Projects** page
2. Switches to **Timeline View**
3. Views all projects on timeline:
 - Projects displayed as horizontal bars
 - Start and end dates visible
 - Milestone markers shown
 - Deliverable markers shown
4. Identifies project overlaps
5. Checks resource allocation
6. Reviews milestone dates
7. Zooms in/out on timeline
8. Filters by project status
9. Exports timeline view
10. Uses timeline for resource planning

**Expected Outcome:**

Visual timeline showing all projects, milestones, and deliverables for comprehensive project oversight.

**Business Value:**

- Visual project management
- Resource planning
- Timeline optimization
- Overlap identification

---

## Support Tickets Use Cases

### UC-SUPPORT-001: Create Support Ticket with SLA Tracking

**Business Scenario:**

A customer reports an issue, and support agent creates a ticket with SLA tracking.

**Steps:**
1. Support agent receives customer issue report
2. Navigates to **Support Project**
3. Clicks **"Create Ticket"**
4. Fills ticket details:
 - Title: "Login Issue"
 - Description: "Customer cannot login to account. Error message: 'Invalid credentials'"
 - Priority: HIGH
 - Customer Contact: Links to customer contact
5. Assigns ticket to support agent
6. Saves ticket
7. System generates ticket number: "CUS-001" (based on project prefix)
8. SLA tracking begins:
 - Response time: 4 hours (business hours)
 - Resolution time: 24 hours (business hours)
9. Agent works on ticket
10. Updates ticket status: IN_PROGRESS
11. Provides solution to customer
12. Updates ticket status: RESOLVED
13. Adds resolution notes
14. Customer confirms resolution
15. Closes ticket
16. System records SLA compliance

**Expected Outcome:**

Support ticket created with automatic numbering and SLA tracking, ensuring timely resolution.

**Business Value:**

- Structured support process
- SLA compliance
- Customer satisfaction
- Performance tracking

---

### UC-SUPPORT-002: Configure SLA for Support Project

**Business Scenario:**

Admin wants to configure SLA requirements for a support project.

**Steps:**
1. Admin navigates to **Support Project** settings
2. Opens **SLA Configuration**
3. Configures SLA settings:
 - Response Time: 4 hours
 - Resolution Time: 24 hours
 - Business Hours Only: Yes
 - Business Hours Start: 9:00 AM
 - Business Hours End: 5:00 PM
 - Business Days: Monday, Tuesday, Wednesday, Thursday, Friday
4. Saves SLA configuration
5. Creates test ticket
6. Verifies SLA tracking:
 - Response deadline calculated correctly
 - Resolution deadline calculated correctly
 - Business hours respected
 - Weekend/holiday exclusion
7. Monitors SLA compliance dashboard
8. Reviews SLA violation reports

**Expected Outcome:**

SLA configured and tracking correctly for all support tickets, ensuring service level compliance.

**Business Value:**

- Service level management
- Customer expectations
- Performance standards
- Compliance tracking

---

### UC-SUPPORT-003: Track SLA Compliance Across Team

**Business Scenario:**

Support manager wants to monitor SLA compliance across the support team.

**Steps:**
1. Support manager navigates to **Support Project**
2. Views ticket list with SLA indicators
3. Filters by SLA status:
 - On track (green)
 - At risk (yellow)
 - Violated (red)
4. Reviews overdue tickets
5. Checks response times:
 - Average response time: 2.5 hours (target: 4 hours)
 - Compliance rate: 95%
6. Checks resolution times:
 - Average resolution time: 18 hours (target: 24 hours)
 - Compliance rate: 92%
7. Identifies tickets at risk
8. Reassigns tickets if needed
9. Provides team feedback
10. Exports SLA compliance report

**Expected Outcome:**

Support manager has visibility into SLA compliance and can take proactive action to maintain service levels.

**Business Value:**

- SLA monitoring
- Proactive management
- Team performance
- Customer satisfaction

---

## Attendance Tracking Use Cases

### UC-ATTENDANCE-001: Monitor Online Agents in Real-Time

**Business Scenario:**

A manager wants to see which agents are currently online and available for customer support.

**Steps:**
1. Manager navigates to **Attendance** page (Admin/Owner only)
2. Views **Online Agents Panel** on left:
 - Sees all online agents listed
 - Online count badge: "5 agents online"
 - Agent names and avatars displayed
 - Green status indicators
 - Last seen timestamps
3. Real-time updates:
 - Agent logs in → appears in online list
 - Agent logs out → removed from online list
 - Updates every 60 seconds automatically
4. Checks agent availability:
 - Reviews who's available
 - Sees last activity times
 - Identifies agents for assignment
5. Uses information for:
 - Conversation assignment
 - Task distribution
 - Workload balancing

**Expected Outcome:**

Manager has real-time visibility into online agents for effective team management and workload distribution.

**Business Value:**

- Real-time team visibility
- Efficient assignment
- Workload balancing
- Team management

---

### UC-ATTENDANCE-002: Review Attendance History for Payroll

**Business Scenario:**

HR manager needs attendance records for payroll processing.

**Steps:**
1. HR manager navigates to **Attendance** page
2. Views **Attendance History Table** on right
3. Applies filters:
 - Date Range: "Last 30 days"
 - Status: "Completed" (clocked out)
4. Reviews attendance records:
 - Agent name and email
 - Clock in time
 - Clock out time
 - Hours worked (calculated)
 - Status: COMPLETED
5. Exports attendance data to CSV
6. Calculates total hours per agent
7. Reviews for anomalies:
 - Missing clock outs
 - Unusual hours
 - Overtime hours
8. Uses data for payroll processing
9. Generates attendance report

**Expected Outcome:**

Complete attendance history exported for payroll processing with accurate hours worked calculations.

**Business Value:**

- Accurate payroll
- Compliance
- Attendance tracking
- HR reporting

---

### UC-ATTENDANCE-003: Track Active Sessions and Hours Worked

**Business Scenario:**

Manager wants to identify agents with active sessions (clocked in but not clocked out).

**Steps:**
1. Manager navigates to **Attendance** page
2. Filters attendance history:
 - Status: "Active"
3. Views active sessions:
 - Agents currently clocked in
 - Clock in time displayed
 - No clock out time (active session)
 - Hours worked: Calculated from clock in to now
4. Identifies long sessions:
 - Sessions > 8 hours
 - Potential forgotten clock outs
5. Contacts agents to verify:
 - Confirms they're still working
 - Reminds to clock out when done
6. Reviews patterns:
 - Frequent active sessions
 - Agents forgetting to clock out
7. Provides training if needed
8. Monitors compliance

**Expected Outcome:**

Manager identifies active sessions and ensures accurate attendance tracking.

**Business Value:**

- Accurate time tracking
- Compliance monitoring
- Team management
- Payroll accuracy

---

## Channel Management Use Cases

### UC-CHANNELS-001: Connect WhatsApp Lite Channel

**Business Scenario:**

A business wants to connect WhatsApp Lite channel for customer communication.

**Steps:**
1. Admin navigates to **Settings** → **Channels**
2. Clicks **"Add Channel"**
3. Selects channel type: "WhatsApp Lite"
4. Enters channel name: "Sales WhatsApp"
5. Configures channel settings:
 - Sender ID: Company phone number
 - Phone Number: +1234567890
6. Initiates QR code authentication
7. Scans QR code with WhatsApp mobile app
8. Verifies connection status: "Connected"
9. Activates channel
10. Tests channel:
 - Sends test message
 - Receives test message
 - Verifies delivery receipts
11. Monitors channel statistics
12. Configures warming campaigns (if needed)

**Expected Outcome:**

WhatsApp Lite channel connected, authenticated, and active for customer communication.

**Business Value:**

- WhatsApp communication
- Customer reach
- Multi-channel support
- Business messaging

---

### UC-CHANNELS-002: Connect Facebook Messenger via OAuth

**Business Scenario:**

A business wants to connect Facebook Messenger for customer support.

**Steps:**
1. Admin navigates to **Settings** → **Channels**
2. Clicks **"Add Channel"**
3. Selects channel type: "Facebook Messenger"
4. Enters channel name: "Support Messenger"
5. Clicks **"Connect via Facebook"**
6. Redirected to Facebook OAuth
7. Authorizes ConnectGain app
8. Selects Facebook Page: "Acme Business Page"
9. Grants permissions:
 - Manage pages
 - Read page messages
 - Send messages
10. Returns to ConnectGain
11. Verifies connection: "Connected"
12. Activates channel
13. Tests channel:
 - Receives test message from Facebook
 - Responds via ConnectGain
 - Verifies message delivery
14. Monitors channel performance

**Expected Outcome:**

Facebook Messenger connected via OAuth and active for customer communication.

**Business Value:**

- Facebook integration
- Social media support
- Customer convenience
- Multi-channel presence

---

### UC-CHANNELS-003: Configure Multiple WhatsApp Channels for Departments

**Business Scenario:**

A business wants separate WhatsApp channels for Sales and Support departments.

**Steps:**
1. Admin adds first channel:
 - Name: "Sales WhatsApp"
 - Type: WhatsApp Lite
 - Phone: +1234567890
 - Connects and activates
2. Admin adds second channel:
 - Name: "Support WhatsApp"
 - Type: WhatsApp Lite
 - Phone: +0987654321
 - Connects and activates
3. Verifies both channels active:
 - Both appear in channels list
 - Independent statistics
 - Separate phone numbers
4. Configures routing:
 - Sales inquiries → Sales WhatsApp
 - Support issues → Support WhatsApp
5. Tests both channels independently
6. Monitors performance separately
7. Manages channels individually

**Expected Outcome:**

Multiple WhatsApp channels configured independently for different departments with separate management.

**Business Value:**

- Department separation
- Specialized routing
- Independent management
- Better organization

---

## Message Management Use Cases

### UC-MESSAGES-001: Send Text Message with Status Tracking

**Business Scenario:**

An agent wants to send a text message to a customer and track delivery status.

**Steps:**
1. Agent opens conversation in **Inbox**
2. Types message in composer: "Hi! Your order has been shipped. Tracking number: ABC123"
3. Clicks **Send**
4. Message appears in thread with status: **Sent ✓**
5. Waits for delivery confirmation
6. Status updates to: **Delivered ✓✓**
7. Customer reads message
8. Status updates to: **Read ✓✓** (blue, WhatsApp)
9. Agent sees read receipt
10. Customer responds
11. Agent replies with follow-up

**Expected Outcome:**

Message sent with complete status tracking from sent → delivered → read, providing visibility into message delivery.

**Business Value:**

- Message delivery confirmation
- Read receipt tracking
- Customer engagement visibility
- Communication reliability

---

### UC-MESSAGES-002: Send Media Message with Image

**Business Scenario:**

An agent wants to send a product image to a customer.

**Steps:**
1. Agent opens conversation
2. Clicks **Attach** button
3. Selects **Image** option
4. Chooses image file: "product-photo.jpg"
5. Adds caption: "Here's the product you asked about!"
6. Clicks **Send**
7. Image uploads (progress indicator)
8. Message sent with image
9. Verifies image displays correctly
10. Checks delivery status
11. Customer views image
12. Customer responds with questions

**Expected Outcome:**

Image message sent successfully with proper formatting and delivery confirmation.

**Business Value:**

- Visual communication
- Product showcasing
- Rich media support
- Customer engagement

---

### UC-MESSAGES-003: Schedule Message for Later Delivery

**Business Scenario:**

An agent wants to send a follow-up message tomorrow morning at 9 AM.

**Steps:**
1. Agent composes message: "Good morning! Just following up on our conversation yesterday."
2. Clicks **Schedule** button
3. Selects date: Tomorrow
4. Selects time: 9:00 AM
5. Confirms schedule
6. Message shows as "Scheduled" status
7. Agent continues with other work
8. Tomorrow at 9 AM:
 - Message automatically sends
 - Status changes to "Sent"
 - Delivery tracking begins
9. Agent receives notification of sent message
10. Customer receives message at scheduled time

**Expected Outcome:**

Message scheduled and sent automatically at specified time, enabling timely follow-ups.

**Business Value:**

- Timely communication
- Follow-up automation
- Time management
- Customer engagement

---

## Profile Management Use Cases

### UC-PROFILE-001: Update Profile Information

**Business Scenario:**

A user wants to update their name and profile information.

**Steps:**
1. User navigates to **Profile** page
2. Clicks **"Profile Information"** tab
3. Updates fields:
 - First Name: "John"
 - Last Name: "Smith"
4. Clicks **"Update Profile"**
5. Receives success notification
6. Verifies changes saved
7. Checks avatar updates (initials-based)
8. Verifies name appears correctly throughout app

**Expected Outcome:**

Profile information updated successfully and reflected across the application.

**Business Value:**

- Accurate user information
- Professional presentation
- Team identification
- User management

---

### UC-PROFILE-002: View Subscription Details and Usage

**Business Scenario:**

A user wants to check their subscription status and usage limits.

**Steps:**
1. User navigates to **Profile** page
2. Clicks **"Subscription"** tab
3. Views subscription details:
 - Plan Name: "Professional Plan"
 - Price: $99/month
 - Status: Active
 - Next Billing Date: February 15, 2025
 - Trial Days Remaining: None (trial completed)
4. Reviews plan features:
 - Feature list with checkmarks
 - Plan limits displayed
5. Checks usage statistics:
 - Contacts: 2,500 / 10,000 (25% used)
 - Conversations: 500 / 5,000 (10% used)
 - Team Members: 3 / 10 (30% used)
6. Reviews progress bars
7. Plans upgrade if approaching limits

**Expected Outcome:**

User has complete visibility into subscription status, features, and usage limits.

**Business Value:**

- Subscription transparency
- Usage monitoring
- Plan management
- Cost optimization

---

### UC-PROFILE-003: Manage Subscription via Stripe Portal

**Business Scenario:**

A user wants to upgrade their subscription plan.

**Steps:**
1. User navigates to **Profile** → **Subscription** tab
2. Clicks **"Manage Subscription"** button
3. Redirected to Stripe Customer Portal
4. Views subscription options:
 - Current plan highlighted
 - Upgrade options available
 - Downgrade options available
5. Selects upgrade: "Professional → Enterprise"
6. Reviews new plan features
7. Updates payment method (if needed)
8. Confirms upgrade
9. Returns to ConnectGain
10. Verifies subscription updated:
 - Plan name changed
 - Features updated
 - Limits increased
 - Billing updated

**Expected Outcome:**

Subscription upgraded successfully through Stripe portal with immediate feature access.

**Business Value:**

- Self-service upgrades
- Flexible plans
- Immediate access
- Seamless billing

---

## Onboarding Use Cases

### UC-ONBOARDING-001: Complete New User Onboarding

**Business Scenario:**

A new user signs up and completes the onboarding process.

**Steps:**
1. User signs up with email: user@example.com
2. Receives verification email
3. Clicks verification link
4. Email verified
5. Redirected to **Onboarding** page
6. **Step 1: Email Verification** - ✅ Completed
7. **Step 2: Subscription** - Redirected to pricing page
8. Selects plan: "Starter Plan"
9. Completes Stripe checkout
10. Returns to onboarding
11. **Step 2: Subscription** - ✅ Completed
12. **Step 3: Channel Setup** - Optional step
13. User clicks **"Skip for Now"**
14. Clicks **"Finish Setup"**
15. Onboarding marked complete
16. Redirected to Dashboard
17. Can access all features

**Expected Outcome:**

New user successfully completes onboarding and gains access to the platform.

**Business Value:**

- Smooth user onboarding
- Feature discovery
- Setup completion
- User activation

---

### UC-ONBOARDING-002: Connect Channel During Onboarding

**Business Scenario:**

A new user wants to connect WhatsApp during onboarding.

**Steps:**
1. User completes email verification
2. User completes subscription
3. Reaches **Channel Setup** step
4. Views channel options
5. Clicks **"Add Channel"** → **"WhatsApp Lite"**
6. Enters channel name: "Main WhatsApp"
7. Scans QR code with WhatsApp
8. Channel connected
9. Activates channel
10. Channel appears in connected channels list
11. Clicks **"Finish Setup"**
12. Onboarding complete
13. Can immediately start receiving messages

**Expected Outcome:**

User connects channel during onboarding and can start using the platform immediately.

**Business Value:**

- Immediate functionality
- Setup completion
- Channel configuration
- Quick start

---

## Sales Report Use Cases

### UC-SALESREPORT-001: Generate Weekly Pipeline Report

**Business Scenario:**

A sales manager needs a comprehensive pipeline report for weekly team meeting.

**Steps:**
1. Sales manager navigates to **Sales Report** page
2. Selects pipeline: "Sales Pipeline" (default selected)
3. Report automatically generates
4. Reviews summary metrics:
 - Total Stages: 6
 - Total Deals: 125
 - Total Value: $2,500,000
 - Average Deal Value: $20,000
5. Expands each stage:
 - **Lead**: 30 deals, $600,000
 - **Qualified**: 25 deals, $500,000
 - **Proposal**: 20 deals, $400,000
 - **Negotiation**: 15 deals, $300,000
 - **Closed Won**: 35 deals, $700,000
6. Reviews deal details in each stage:
 - Deal titles
 - Contact names
 - Company names
 - Deal values
 - Expected close dates
 - Probability percentages
7. Identifies bottlenecks:
 - Negotiation stage has low conversion
 - Some deals stuck in Proposal stage
8. Clicks **"Export CSV"**
9. Downloads report file
10. Uses report for team meeting
11. Shares insights with team

**Expected Outcome:**

Comprehensive pipeline report generated and exported for team analysis and decision-making.

**Business Value:**

- Pipeline visibility
- Data-driven decisions
- Team alignment
- Performance tracking

---

### UC-SALESREPORT-002: Analyze Stage-by-Stage Performance

**Business Scenario:**

A sales director wants to analyze performance at each pipeline stage.

**Steps:**
1. Sales director opens **Sales Report**
2. Selects pipeline
3. Expands all stages using **"Expand All"** button
4. Analyzes each stage:
 - **Lead Stage**: 30 deals, average value $20,000
 - **Qualified Stage**: 25 deals, average value $20,000
 - **Proposal Stage**: 20 deals, average value $20,000
 - **Negotiation Stage**: 15 deals, average value $20,000
 - **Closed Won**: 35 deals, average value $20,000
5. Calculates conversion rates:
 - Lead → Qualified: 83% (25/30)
 - Qualified → Proposal: 80% (20/25)
 - Proposal → Negotiation: 75% (15/20)
 - Negotiation → Closed: 233% (35/15) - includes historical
6. Identifies issues:
 - Drop-off at Proposal → Negotiation stage
 - Low conversion at Negotiation stage
7. Reviews individual deals in problematic stages
8. Creates action plan:
 - Focus on Proposal stage deals
 - Improve negotiation process
 - Follow up on stuck deals
9. Exports report for analysis
10. Tracks improvements over time

**Expected Outcome:**

Stage-by-stage analysis reveals conversion bottlenecks and opportunities for improvement.

**Business Value:**

- Conversion analysis
- Bottleneck identification
- Process improvement
- Performance optimization

---

## Call Tracking Use Cases

### UC-CALL-001: Initiate Call from Contact Card

**Business Scenario:**

An agent wants to call a customer directly from their contact card and track the call.

**Steps:**
1. Agent opens contact card in **Contacts** page
2. Clicks phone icon next to contact's phone number
3. System records call event:
 - Contact ID
 - Phone number
 - Call type: OUTBOUND
 - Status: INITIATED
 - Timestamp recorded
4. Device dialer opens automatically (`tel:` link)
5. Agent makes call
6. After call completes, agent updates call status:
 - Status: COMPLETED
 - Duration: 5 minutes
 - Notes: "Discussed pricing, customer interested"
7. Call history saved to contact record
8. Call appears in contact's activity timeline

**Expected Outcome:**

Call initiated and tracked with complete history, enabling call analytics and follow-up management.

**Business Value:**

- Call tracking and analytics
- Complete contact history
- Performance monitoring
- Follow-up management

---

### UC-CALL-002: Track Call History per Contact

**Business Scenario:**

A sales rep wants to review all calls made to a specific contact.

**Steps:**
1. Sales rep opens contact details
2. Navigates to **Call History** section
3. Views all call events:
 - Date and time of each call
 - Call type (INBOUND/OUTBOUND)
 - Call status (INITIATED, CONNECTED, COMPLETED, MISSED, FAILED)
 - Duration (for completed calls)
 - Notes (if added)
4. Reviews call patterns:
 - Frequency of calls
 - Average call duration
 - Success rate (completed vs missed)
5. Uses history for:
 - Follow-up planning
 - Relationship building
 - Performance analysis

**Expected Outcome:**

Complete call history visible per contact, enabling relationship management and performance tracking.

**Business Value:**

- Relationship tracking
- Call analytics
- Performance insights
- Follow-up planning

---

### UC-CALL-003: Link Call to Conversation

**Business Scenario:**

An agent makes a call during an active conversation and wants to link the call to the conversation thread.

**Steps:**
1. Agent has active conversation open
2. Clicks phone icon in conversation header
3. System initiates call:
 - Records call event
 - Links to conversation ID
 - Links to contact ID
4. Agent makes call
5. Updates call status after completion
6. Call appears in:
 - Contact's call history
 - Conversation activity log
 - Contact's activity timeline
7. Other team members can see call in conversation context

**Expected Outcome:**

Call linked to conversation, providing complete context for team collaboration.

**Business Value:**

- Context preservation
- Team collaboration
- Complete conversation history
- Better customer service

---

**Note:** This is basic call tracking functionality that opens the device dialer. Full VOIP integration (in-app calling) is not currently implemented.

---

## CRM Import Use Cases (Kommo & HubSpot)

### UC-IMPORT-001: Import Contacts from Kommo CRM

**Business Scenario:**

A business wants to migrate all contacts, deals, notes, and companies from Kommo CRM to ConnectGain.

**Steps:**
1. Admin exports data from Kommo:
 - Goes to Kommo dashboard → Leads
 - Exports leads to CSV format
 - Downloads CSV file
2. Admin navigates to **Contacts** page
3. Clicks **"Import"** → **"Import from Kommo"**
4. Uploads Kommo CSV file
5. Reviews import options:
 - Overwrite existing contacts: Yes/No
 - Import deals: Yes (automatic)
 - Import notes: Yes (automatic)
 - Import companies: Yes (automatic)
6. Starts import process
7. System processes import in background:
 - Parses Kommo CSV format
 - Maps Kommo fields to ConnectGain fields:
 - Name → first_name, last_name
 - Phone → phones array
 - Email → emails array
 - Company → company record
 - Deal → deal record
 - Notes → notes
 - Creates contacts, deals, companies, notes
 - Handles duplicates
8. Receives notification when import completes:
 - Contacts created: 1,250
 - Deals created: 450
 - Companies created: 320
 - Notes created: 890
 - Duplicates merged: 50
 - Errors: 5
9. Reviews import report
10. Fixes any errors
11. Verifies imported data in ConnectGain

**Expected Outcome:**

All Kommo data successfully imported to ConnectGain with proper field mapping and relationships maintained.

**Business Value:**

- Seamless CRM migration
- Data preservation
- Relationship maintenance
- Time savings

---

### UC-IMPORT-002: Import Contacts from HubSpot

**Business Scenario:**

A business wants to import contacts from HubSpot to ConnectGain.

**Steps:**
1. Admin exports contacts from HubSpot:
 - Goes to HubSpot → Contacts
 - Exports contacts to CSV
 - Downloads CSV file
2. Admin navigates to **Contacts** page
3. Clicks **"Import"** → **"Import from HubSpot"**
4. Uploads HubSpot CSV file
5. System automatically detects HubSpot format:
 - Recognizes HubSpot column names
 - Maps fields:
 - "First Name" → first_name
 - "Last Name" → last_name
 - "Email" → emails
 - "Phone Number" → phones
 - "Mobile Phone Number" → phones (additional)
 - "Company name" → custom_fields.company
 - "Job Title" → custom_fields.job_title
 - "Lead Status" → tags
 - "Lifecycle Stage" → tags
6. Starts import process
7. System processes import:
 - Parses HubSpot CSV format
 - Creates contacts with proper mapping
 - Handles duplicates
 - Preserves custom fields
8. Receives notification when complete:
 - Contacts imported: 2,500
 - Duplicates handled: 120
 - Errors: 8
9. Reviews import report
10. Verifies imported contacts

**Expected Outcome:**

HubSpot contacts successfully imported with proper field mapping and custom fields preserved.

**Business Value:**

- CRM migration
- Data preservation
- Custom field mapping
- Efficient import process

---

### UC-IMPORT-003: Import Companies from HubSpot

**Business Scenario:**

A B2B company wants to import companies from HubSpot.

**Steps:**
1. Admin exports companies from HubSpot
2. Navigates to **Companies** page
3. Clicks **"Import"** → **"Import from HubSpot"**
4. Uploads HubSpot companies CSV
5. System maps HubSpot fields:
 - Company Name → name
 - Industry → industry
 - Website → website
 - Address fields → address
 - Phone → phones
 - Annual Revenue → annual_revenue
6. Reviews import preview
7. Starts import
8. System creates companies:
 - Handles duplicates
 - Preserves relationships
 - Links to contacts (if imported)
9. Receives completion notification
10. Verifies imported companies

**Expected Outcome:**

Companies imported from HubSpot with proper field mapping and relationships maintained.

**Business Value:**

- B2B data migration
- Company database setup
- Relationship preservation
- Efficient import

---

**Note:** Commission management is mentioned in business use case documentation but is NOT currently implemented as a feature. The system tracks deal values and ownership, which could be used for commission calculations, but there is no built-in commission calculation or management system.

---

## External Integration Use Cases (via Automation HTTP Requests)

### UC-INTEGRATION-001: Initiate VOIP Call via Automation HTTP Request

**Business Scenario:**

A business wants to automatically initiate a VOIP call when a high-priority deal is created, using a third-party VOIP service API.

**Steps:**
1. Admin navigates to **Automations** page
2. Creates automation: "VOIP Call on High-Priority Deal"
3. Sets trigger: `deal.created`
4. Adds condition:
 - Field: `deal.value`
 - Operator: Greater than
 - Value: `10000`
5. Adds condition:
 - Field: `deal.priority`
 - Operator: Equals
 - Value: `HIGH`
6. Adds action: `HTTP_REQUEST`
7. Configures HTTP request:
 - **Method**: POST
 - **URL**: `https://api.voip-provider.com/v1/calls/initiate`
 - **Headers**:
 - `Authorization`: `Bearer {{voip_api_key}}`
 - `Content-Type`: `application/json`
 - **Body**:
 ```json
 {
 "from": "{{organization.phone_number}}",
 "to": "{{contact.phones[0]}}",
 "contact_id": "{{contact.id}}",
 "deal_id": "{{deal.id}}",
 "deal_title": "{{deal.title}}",
 "deal_value": "{{deal.value}}"
 }
 ```
8. Tests automation with test deal
9. Verifies VOIP call initiated
10. Activates automation

**Expected Outcome:**

When a high-priority deal over $10,000 is created, a VOIP call is automatically initiated to the contact's phone number via the external VOIP service API.

**Business Value:**

- Automated VOIP calling
- Integration with VOIP providers
- Immediate high-value deal follow-up
- Seamless external service integration

---

### UC-INTEGRATION-002: Create Shopify Order via Automation HTTP Request

**Business Scenario:**

A business wants to automatically create a Shopify order when a deal is marked as "Closed Won".

**Steps:**
1. Admin creates automation: "Create Shopify Order on Deal Win"
2. Sets trigger: `deal.stage.changed`
3. Adds condition:
 - Field: `new_stage`
 - Operator: Equals
 - Value: `closed_won`
4. Adds action: `HTTP_REQUEST`
5. Configures HTTP request:
 - **Method**: POST
 - **URL**: `https://{{shop_name}}.myshopify.com/admin/api/2024-01/orders.json`
 - **Headers**:
 - `X-Shopify-Access-Token`: `{{shopify_access_token}}`
 - `Content-Type`: `application/json`
 - **Body**:
 ```json
 {
 "order": {
 "line_items": [
 {
 "title": "{{deal.title}}",
 "price": "{{deal.value}}",
 "quantity": 1
 }
 ],
 "customer": {
 "first_name": "{{contact.first_name}}",
 "last_name": "{{contact.last_name}}",
 "email": "{{contact.emails[0]}}",
 "phone": "{{contact.phones[0]}}"
 },
 "financial_status": "pending",
 "note": "Deal ID: {{deal.id}}"
 }
 }
 ```
6. Tests automation
7. Verifies order created in Shopify
8. Activates automation

**Expected Outcome:**

When a deal is marked as "Closed Won", a Shopify order is automatically created with deal details and customer information.

**Business Value:**

- Automated order creation
- Shopify integration
- Seamless e-commerce workflow
- Reduced manual data entry

---

### UC-INTEGRATION-003: Sync Contact to Odoo CRM via Automation HTTP Request

**Business Scenario:**

A business wants to automatically sync new contacts to their Odoo CRM system.

**Steps:**
1. Admin creates automation: "Sync Contact to Odoo"
2. Sets trigger: `contact.created`
3. Adds action: `HTTP_REQUEST`
4. Configures HTTP request:
 - **Method**: POST
 - **URL**: `https://{{odoo_instance}}.odoo.com/api/v1/contacts/create`
 - **Headers**:
 - `Authorization`: `Bearer {{odoo_api_token}}`
 - `Content-Type`: `application/json`
 - **Body**:
 ```json
 {
 "name": "{{contact.first_name}} {{contact.last_name}}",
 "email": "{{contact.emails[0]}}",
 "phone": "{{contact.phones[0]}}",
 "mobile": "{{contact.phones[1]}}",
 "company_id": "{{company.id}}",
 "tags": "{{contact.tags}}",
 "custom_fields": "{{contact.custom_fields}}",
 "external_id": "{{contact.id}}"
 }
 ```
5. Tests automation
6. Verifies contact created in Odoo
7. Activates automation

**Expected Outcome:**

Every new contact created in ConnectGain is automatically synced to Odoo CRM with all relevant information.

**Business Value:**

- Automated CRM sync
- Odoo integration
- Data consistency
- Reduced manual work

---

### UC-INTEGRATION-004: Update Odoo Sales Order When Deal Stage Changes

**Business Scenario:**

A business wants to update Odoo sales order status when a deal stage changes in ConnectGain.

**Steps:**
1. Admin creates automation: "Update Odoo Order on Deal Stage Change"
2. Sets trigger: `deal.stage.changed`
3. Adds action: `HTTP_REQUEST`
4. Configures HTTP request:
 - **Method**: PUT
 - **URL**: `https://{{odoo_instance}}.odoo.com/api/v1/sales/orders/{{deal.external_id}}`
 - **Headers**:
 - `Authorization`: `Bearer {{odoo_api_token}}`
 - `Content-Type`: `application/json`
 - **Body**:
 ```json
 {
 "state": "{{deal.stage}}",
 "amount_total": "{{deal.value}}",
 "note": "Deal stage changed to {{deal.stage}}"
 }
 ```
5. Maps ConnectGain stages to Odoo states:
 - `lead` → `draft`
 - `qualified` → `sent`
 - `proposal` → `sale`
 - `closed_won` → `done`
6. Tests automation
7. Verifies Odoo order updated
8. Activates automation

**Expected Outcome:**

When a deal stage changes in ConnectGain, the corresponding Odoo sales order is automatically updated with the new status.

**Business Value:**

- Bi-directional sync
- Odoo integration
- Real-time updates
- System consistency

---

### UC-INTEGRATION-005: Create Shopify Customer When Contact Created

**Business Scenario:**

A business wants to automatically create a Shopify customer when a new contact is added to ConnectGain.

**Steps:**
1. Admin creates automation: "Create Shopify Customer"
2. Sets trigger: `contact.created`
3. Adds condition:
 - Field: `contact.emails`
 - Operator: Contains
 - Value: (not empty)
4. Adds action: `HTTP_REQUEST`
5. Configures HTTP request:
 - **Method**: POST
 - **URL**: `https://{{shop_name}}.myshopify.com/admin/api/2024-01/customers.json`
 - **Headers**:
 - `X-Shopify-Access-Token`: `{{shopify_access_token}}`
 - `Content-Type`: `application/json`
 - **Body**:
 ```json
 {
 "customer": {
 "first_name": "{{contact.first_name}}",
 "last_name": "{{contact.last_name}}",
 "email": "{{contact.emails[0]}}",
 "phone": "{{contact.phones[0]}}",
 "tags": "{{contact.tags.join(',')}}",
 "note": "Synced from ConnectGain - Contact ID: {{contact.id}}"
 }
 }
 ```
6. Tests automation
7. Verifies customer created in Shopify
8. Activates automation

**Expected Outcome:**

Every new contact with an email address is automatically created as a customer in Shopify.

**Business Value:**

- Automated customer sync
- Shopify integration
- Unified customer database
- E-commerce workflow automation

---

### UC-INTEGRATION-006: Trigger VOIP Callback When Conversation Assigned

**Business Scenario:**

A business wants to automatically trigger a VOIP callback request when a conversation is assigned to an agent.

**Steps:**
1. Admin creates automation: "VOIP Callback on Assignment"
2. Sets trigger: `conversation.assigned`
3. Adds condition:
 - Field: `conversation.status`
 - Operator: Equals
 - Value: `OPEN`
4. Adds action: `HTTP_REQUEST`
5. Configures HTTP request:
 - **Method**: POST
 - **URL**: `https://api.voip-provider.com/v1/callbacks/schedule`
 - **Headers**:
 - `Authorization`: `Bearer {{voip_api_key}}`
 - `Content-Type`: `application/json`
 - **Body**:
 ```json
 {
 "agent_phone": "{{assignee.phone}}",
 "customer_phone": "{{contact.phones[0]}}",
 "conversation_id": "{{conversation.id}}",
 "contact_id": "{{contact.id}}",
 "priority": "{{conversation.priority}}",
 "scheduled_time": "{{now + 5 minutes}}"
 }
 ```
6. Tests automation
7. Verifies callback scheduled
8. Activates automation

**Expected Outcome:**

When a conversation is assigned to an agent, a VOIP callback is automatically scheduled to connect the agent with the customer.

**Business Value:**

- Automated callback scheduling
- VOIP integration
- Improved response times
- Better customer service

---

**Note:** These integrations use the Automation HTTP Request action to call external APIs. The HTTP Request action supports:
- **Methods**: GET, POST, PUT, PATCH, DELETE
- **Custom Headers**: For authentication and [API keys](https://docs.connectgain.cloud/04-use-cases/07-api/api-key-authentication.md)
- **Dynamic Body**: Using template variables ({{variable}})
- **Event Data**: Automatically merged into request body
- **Error Handling**: Logged for debugging

All external integrations require:
1. API credentials stored securely (as environment variables or in organization settings)
2. Proper API authentication (API keys, OAuth tokens, etc.)
3. Correct API endpoint URLs
4. Valid request body format matching the external service's API requirements

---

## Real Estate Industry Use Cases

### UC-REALESTATE-001: Property Inquiry to Deal Conversion

**Business Scenario:**

A real estate agency receives property inquiries via Instagram and WhatsApp. They need to qualify leads, schedule viewings, and convert inquiries into closed deals.

**Steps:**
1. Potential buyer sees property listing on Instagram
2. Buyer sends DM: "Interested in this property"
3. **Bot Flow** automatically responds:
 - Collects buyer information (name, phone, email)
 - Asks budget range
 - Asks property type preference
 - Asks timeline (immediate, 3 months, 6 months)
 - Asks location preferences
4. Bot qualifies lead based on responses
5. **Automation Rule** triggers:
 - Creates **Contact** record
 - Creates **Deal** in pipeline (stage: "Lead")
 - Tags contact: "Property Inquiry", "Budget: $500K-$1M"
 - Assigns to available agent
6. Agent receives notification
7. Agent reviews lead information
8. Agent contacts buyer via WhatsApp:
 - Sends property details
 - Answers questions
 - Schedules property viewing
9. **Scheduling System** used:
 - Agent creates event type: "Property Viewing"
 - Buyer books viewing slot via public link
 - Google Calendar event created
 - Reminder sent 24 hours before
10. Viewing completed
11. **Automation** triggers post-viewing follow-up:
 - Thank you message sent
 - Feedback request after 24 hours
 - Additional property suggestions sent
12. Buyer submits offer
13. Deal moved to "Offer Submitted" stage
14. Negotiation happens
15. Deal moved to "Under Contract" stage
16. Deal closed as "Closed Won"
17. **Sales Report** shows conversion metrics

**Expected Outcome:**

Property inquiry converted to closed deal with complete tracking through pipeline stages, automated follow-ups, and scheduling integration.

**Business Value:**

- Automated lead qualification
- Reduced response time
- Complete buyer journey tracking
- Increased conversion rates
- Commission tracking ready

---

### UC-REALESTATE-002: Property Management Maintenance Request Handling

**Business Scenario:**

A property management company needs to handle tenant maintenance requests efficiently, assign vendors, and track completion.

**Steps:**
1. Tenant sends WhatsApp message: "AC not working in unit 205"
2. **Bot Flow** collects details:
 - Unit number: 205
 - Issue description: AC not working
 - Urgency level: Emergency/Urgent/Normal
 - Preferred contact time
3. **Automation Rule** triggers:
 - Creates **Support Ticket** (if support project exists)
 - OR creates **Task** with HIGH priority
 - Links to tenant contact
 - Links to property (via company/deal)
4. System assigns based on issue type:
 - HVAC issues → HVAC vendor
 - Plumbing → Plumber vendor
 - Electrical → Electrician vendor
5. Vendor receives notification
6. Vendor accepts task
7. **Automation** sends update to tenant:
 - "Your maintenance request has been assigned. Vendor will contact you within 2 hours."
8. Vendor completes work
9. Vendor updates task status: "Completed"
10. **Automation** sends completion notification to tenant:
 - "Your maintenance request has been completed. Please confirm if everything is working."
11. Tenant confirms completion
12. **Automation** sends satisfaction survey
13. Task closed
14. **Analytics** tracks:
 - Average response time
 - Average resolution time
 - Vendor performance
 - Tenant satisfaction

**Expected Outcome:**

Maintenance requests handled efficiently with automated assignment, tracking, and tenant communication.

**Business Value:**

- Faster response times
- Automated vendor assignment
- Complete audit trail
- Tenant satisfaction
- Vendor performance tracking

---

### UC-REALESTATE-003: New Property Listing Campaign

**Business Scenario:**

A real estate agency wants to broadcast a new luxury property listing to qualified buyers via WhatsApp Business.

**Steps:**
1. Property manager creates new property listing
2. Creates **Campaign**:
 - Type: WhatsApp Business
 - Name: "Luxury Villa Listing - Beachfront"
3. Configures targeting:
 - Tags: "Luxury Buyer", "Beachfront Interest", "Budget: $2M+"
 - Location: Specific cities/regions
 - Excludes: "Do Not Contact"
4. Composes campaign message:
 - Header: Property image
 - Body: "Exclusive beachfront villa now available! 5 bedrooms, ocean views, private pool. Price: $2.5M"
 - Footer: "Contact us to schedule a private viewing"
 - Button: "Schedule Viewing" (links to booking page)
5. Reviews recipient preview: 150 qualified contacts
6. Schedules campaign: Sends immediately
7. Campaign sends to 150 contacts
8. **Analytics** tracks:
 - Messages sent: 150
 - Messages delivered: 148
 - Messages read: 120
 - Click-through rate: 45 contacts clicked "Schedule Viewing"
9. Interested buyers click button
10. **Bot Flow** captures interest:
 - Collects viewing preferences
 - Schedules viewing appointment
 - Creates deal in pipeline
11. Agent follows up with scheduled viewings
12. Campaign ROI calculated:
 - Cost: $X
 - Leads generated: 45
 - Viewings scheduled: 20
 - Deals created: 8
 - Potential revenue: $20M

**Expected Outcome:**

New property listing broadcasted to qualified buyers, generating leads and scheduled viewings with complete campaign analytics.

**Business Value:**

- Targeted marketing
- Lead generation
- Campaign ROI tracking
- Automated follow-up
- Increased property visibility

---

### UC-REALESTATE-004: Seller Communication & Listing Updates

**Business Scenario:**

A real estate agent needs to keep property sellers informed about viewing activity, offers, and market updates.

**Steps:**
1. Agent links property listing to seller contact (via Company or Deal)
2. **Automation Rule** created: "Notify Seller on Viewing"
3. When viewing scheduled:
 - Automation triggers
 - Sends WhatsApp message to seller:
 - "Property viewing scheduled for [date/time]"
 - "Buyer profile: [budget, timeline]"
4. After viewing completed:
 - Agent adds note: "Buyer very interested, considering offer"
 - **Automation** sends update to seller
5. When offer received:
 - Deal created/updated with offer details
 - **Automation** sends WhatsApp to seller:
 - "New offer received: $X"
 - "Buyer: [name]"
 - "Terms: [details]"
6. Seller responds via WhatsApp
7. Agent updates deal with seller response
8. **Automation** sends market updates:
 - Weekly market activity report
 - Comparable property sales
 - Price adjustment recommendations
9. When property sold:
 - Deal moved to "Closed Won"
 - **Automation** sends congratulations message
 - Closing details shared

**Expected Outcome:**

Sellers stay informed throughout the listing process with automated updates and real-time communication.

**Business Value:**

- Transparent communication
- Seller satisfaction
- Reduced inquiries
- Professional service
- Relationship building

---

## Tourism & Hospitality Industry Use Cases

### UC-TOURISM-001: Hotel Booking Journey from Inquiry to Checkout

**Business Scenario:**

A hotel receives booking inquiries via Instagram and WhatsApp. They need to qualify leads, check availability, confirm bookings, and provide pre-arrival communication.

**Steps:**
1. Potential guest sees hotel Instagram post
2. Guest sends DM: "Interested in booking for next month"
3. **Bot Flow** collects information:
 - Check-in date
 - Check-out date
 - Number of guests
 - Room type preference
 - Special requirements
4. Bot checks availability (via HTTP Request to PMS)
5. Bot presents available options:
 - Room types available
 - Pricing
 - Package options
6. Guest selects option
7. Bot collects:
 - Guest details (name, email, phone)
 - Payment method
 - Special requests
8. **Automation** creates:
 - **Contact** record
 - **Deal** in "Booking" pipeline (stage: "Inquiry")
 - **Task** for confirmation
9. Booking confirmed
10. **Automation** sends confirmation:
 - WhatsApp confirmation message
 - Booking reference number
 - Check-in details
 - Payment instructions
11. Deal moved to "Confirmed" stage
12. **Automation** triggers pre-arrival sequence:
 - 7 days before: Final details reminder
 - 3 days before: Weather forecast + packing tips
 - 1 day before: Check-in instructions + contact details
13. Check-in day:
 - Welcome message sent
 - Room number shared
 - WiFi password provided
 - Concierge services offered
14. During stay:
 - Guest can message for:
 - Room service
 - Restaurant reservations
 - Activity recommendations
 - Maintenance requests
15. Check-out day:
 - Check-out reminder sent
 - Feedback request sent
16. Post-checkout:
 - Thank you message
 - Review request
 - Loyalty program enrollment
 - Future booking offers
17. Deal moved to "Completed" stage

**Expected Outcome:**

Complete hotel booking journey from inquiry to checkout with automated communication at every stage.

**Business Value:**

- Automated booking process
- Reduced manual work
- Improved guest experience
- Increased repeat bookings
- Complete booking tracking

---

### UC-TOURISM-002: Tour Package Customization & Booking

**Business Scenario:**

A tour operator receives inquiries for custom tour packages. They need to qualify leads, create custom itineraries, and manage group bookings.

**Steps:**
1. Traveler sends WhatsApp: "Looking for adventure tour"
2. **Bot Flow** qualifies:
 - Destination preferences
 - Travel dates
 - Group size
 - Experience level
 - Budget range
 - Activity preferences
3. Bot creates **Deal** in "Tour Bookings" pipeline
4. Qualified lead assigned to tour specialist
5. Tour specialist reviews inquiry
6. Tour specialist creates custom itinerary:
 - Day-by-day schedule
 - Activities included
 - Accommodation options
 - Pricing breakdown
7. Itinerary shared via WhatsApp
8. Traveler reviews and asks questions
9. Tour specialist answers questions
10. Traveler confirms booking
11. **Automation** creates:
 - Booking confirmation
 - Payment link sent
 - Pre-tour information package
12. Payment received
13. **Automation** sends:
 - Payment confirmation
 - Detailed itinerary
 - Packing list
 - Meeting point details
14. Pre-tour communication:
 - 1 week before: Final details
 - 1 day before: Weather update + reminders
15. Tour day:
 - Real-time updates sent
 - Meeting point confirmation
 - Emergency contact shared
16. During tour:
 - Daily updates
 - Photo sharing
 - Support available
17. Post-tour:
 - Thank you message
 - Review request
 - Photo sharing request
 - Related tour suggestions
18. Deal moved to "Completed"

**Expected Outcome:**

Custom tour package created and booked with complete communication throughout the journey.

**Business Value:**

- Personalized service
- Automated communication
- Complete booking tracking
- Customer satisfaction
- Upselling opportunities

---

### UC-TOURISM-003: Travel Agency Emergency Support

**Business Scenario:**

A travel agency needs to handle emergency situations during travel, such as flight cancellations, lost luggage, or medical emergencies.

**Steps:**
1. Traveler sends urgent WhatsApp: "My flight was cancelled!"
2. **Automation** detects urgency keywords:
 - "cancelled", "emergency", "urgent", "help"
3. **Automation** triggers:
 - Sets conversation priority: URGENT
 - Assigns to senior agent immediately
 - Creates **Task** with HIGH priority
 - Sends acknowledgment: "We're on it! An agent will respond within 5 minutes."
4. Agent receives immediate notification
5. Agent responds within SLA (under 5 minutes)
6. Agent reviews traveler's booking:
 - Current itinerary
 - Flight details
 - Hotel reservations
 - Transfers booked
7. Agent researches alternatives:
 - Checks alternative flights
 - Contacts airline
 - Finds replacement flights
8. Agent books new flight
9. **Automation** updates all related bookings:
 - Hotel notified of late arrival
 - Transfer rescheduled
 - Activity bookings adjusted
10. Agent sends comprehensive update:
 - New flight details
 - Updated itinerary
 - Hotel confirmation
 - Transfer details
11. **Automation** sends compensation offer:
 - Apology message
 - Compensation details
 - Future booking discount
12. Traveler confirms all changes
13. **Automation** sends:
 - Final confirmation
 - Emergency contact details
 - Support available 24/7
14. During travel:
 - Real-time support available
 - Updates sent proactively
15. Post-travel:
 - Follow-up satisfaction check
 - Compensation processed
 - Future booking discount applied

**Expected Outcome:**

Emergency situation handled efficiently with immediate response, alternative arrangements made, and traveler kept informed throughout.

**Business Value:**

- Crisis management
- Customer retention
- Brand reputation
- Customer satisfaction
- Competitive advantage

---

### UC-TOURISM-004: Seasonal Campaign for Tourism Business

**Business Scenario:**

A tourism business wants to run a seasonal campaign targeting past travelers with special offers.

**Steps:**
1. Marketing manager creates **Campaign**:
 - Name: "Summer Sale 2025"
 - Type: WhatsApp Business
2. Configures targeting:
 - Tags: "Past Traveler", "Beach Lover"
 - Excludes: "Do Not Contact"
 - Location: Specific regions
3. Composes campaign message:
 - Header: Beautiful beach destination image
 - Body: "Summer Sale! 30% off beach packages. Limited time offer. Book now!"
 - Footer: "Valid until [date]"
 - Button: "View Packages" (links to website)
4. Reviews recipient preview: 2,500 contacts
5. Schedules campaign: Sends immediately
6. Campaign sends to 2,500 contacts
7. **Analytics** tracks:
 - Sent: 2,500
 - Delivered: 2,480
 - Read: 1,950
 - Clicked: 650 (33% CTR)
8. Interested travelers click button
9. **Bot Flow** captures interest:
 - Collects destination preferences
 - Travel dates
 - Budget range
10. Qualified leads assigned to agents
11. Agents follow up with personalized offers
12. Bookings created in pipeline
13. Campaign performance analyzed:
 - Open rate: 78%
 - Click-through rate: 33%
 - Conversion rate: 12%
 - Revenue generated: $450,000
 - ROI: 450%

**Expected Outcome:**

Seasonal campaign successfully executed with high engagement, lead generation, and revenue tracking.

**Business Value:**

- Targeted marketing
- High engagement rates
- Lead generation
- Revenue tracking
- Campaign optimization

---

## Education Centers Industry Use Cases

### UC-EDUCATION-001: Student Enrollment & Onboarding

**Business Scenario:**

An education center receives enrollment inquiries via WhatsApp and needs to guide prospective students through the enrollment process.

**Steps:**
1. Prospective student sends WhatsApp: "Interested in enrolling"
2. **Bot Flow** collects information:
 - Student name and age
 - Parent/guardian contact
 - Course interest
 - Preferred schedule
 - Previous education background
3. Bot provides course information:
 - Available courses
 - Schedule options
 - Pricing
 - Curriculum overview
4. **Automation** creates:
 - **Contact** record (student)
 - **Contact** record (parent/guardian)
 - **Deal** in "Enrollments" pipeline (stage: "Inquiry")
 - Links parent to student
5. Student/parent selects course
6. **Automation** sends enrollment form link
7. Enrollment form completed
8. **Automation** creates:
 - **Task** for document verification
 - **Task** for payment processing
9. Documents verified
10. Payment received
11. **Automation** sends:
 - Enrollment confirmation
 - Welcome package
 - Course schedule
 - Student portal access
 - Orientation date
12. Deal moved to "Enrolled" stage
13. Pre-course communication:
 - Orientation reminder
 - Course materials list
 - First day instructions
14. Course starts
15. **Automation** sends:
 - Welcome message
 - Class schedule
 - Instructor contact
 - Student resources
16. Ongoing communication:
 - Assignment reminders
 - Class updates
 - Progress reports
 - Parent updates

**Expected Outcome:**

Student enrollment process automated from inquiry to course start with complete communication and documentation.

**Business Value:**

- Streamlined enrollment
- Reduced manual work
- Better student experience
- Parent engagement
- Complete records

---

### UC-EDUCATION-002: Parent-Teacher Communication

**Business Scenario:**

A school needs to communicate with parents about student progress, events, announcements, and emergencies.

**Steps:**
1. School admin creates **Campaign**:
 - Type: WhatsApp Broadcast
 - Target: Parents tagged by class/grade
2. Sends announcement:
 - "Parent-Teacher Meeting scheduled for [date]"
 - "Please confirm your attendance"
 - Button: "RSVP"
3. Parents receive message
4. Parents click RSVP button
5. **Bot Flow** collects:
 - Parent name
 - Student name
 - Preferred time slot
6. **Automation** creates:
 - **Task** for teacher preparation
 - **Booking** for meeting slot
7. Meeting scheduled
8. **Automation** sends:
 - Confirmation message
 - Meeting details
 - Reminder 24 hours before
9. Student progress update:
 - Teacher creates progress report
 - **Automation** sends to parent via WhatsApp
 - Includes:
 - Academic performance
 - Behavior notes
 - Areas for improvement
 - Recommendations
10. Parent responds with questions
11. Teacher responds via conversation
12. Emergency notification:
 - School admin creates urgent campaign
 - Sends to all parents via SMS + WhatsApp
 - "School closed due to weather. Check website for updates."
13. Event announcements:
 - School events
 - Field trips
 - Exam schedules
 - Holiday notices
14. **Analytics** tracks:
 - Message delivery rates
 - Response rates
 - Engagement levels

**Expected Outcome:**

Effective parent-teacher communication with automated announcements, progress updates, and emergency notifications.

**Business Value:**

- Improved communication
- Parent engagement
- Emergency preparedness
- Student support
- Administrative efficiency

---

### UC-EDUCATION-003: Course Registration & Payment

**Business Scenario:**

An education center needs to handle course registrations, collect payments, and send confirmations.

**Steps:**
1. Student/parent sends WhatsApp: "Want to register for Python course"
2. **Bot Flow** provides:
 - Course details
 - Schedule options
 - Pricing information
3. Student selects course and schedule
4. **Bot Flow** collects:
 - Student information
 - Parent/guardian details
 - Payment method preference
5. **Automation** creates:
 - **Contact** records
 - **Deal** in "Registrations" pipeline
6. Payment link sent via WhatsApp
7. Payment received
8. **Automation** triggers:
 - Payment confirmation sent
 - Enrollment confirmation sent
 - Course materials access provided
 - Student portal credentials sent
9. Deal moved to "Registered" stage
10. Pre-course communication:
 - Welcome message
 - Course schedule
 - Materials list
 - Instructor introduction
11. Course starts
12. Ongoing communication:
 - Class reminders
 - Assignment deadlines
 - Progress updates
13. Course completion:
 - Completion certificate sent
 - Feedback survey
 - Next course recommendations

**Expected Outcome:**

Course registration and payment process automated with complete communication and documentation.

**Business Value:**

- Streamlined registration
- Automated payment processing
- Better student experience
- Reduced administrative work
- Complete records

---

## Hospitals & Healthcare Industry Use Cases

### UC-HOSPITAL-001: Patient Appointment Scheduling

**Business Scenario:**

A hospital needs to manage patient appointments, send reminders, handle cancellations, and provide post-appointment follow-ups.

**Steps:**
1. Patient sends WhatsApp: "Need to book appointment"
2. **Bot Flow** collects:
 - Patient name and ID
 - Reason for visit
 - Preferred date/time
 - Doctor preference (if any)
 - Insurance information
3. Bot checks doctor availability (via HTTP Request to hospital system)
4. Bot presents available slots
5. Patient selects slot
6. **Automation** creates:
 - **Contact** record (if new patient)
 - **Booking** in scheduling system
 - **Task** for appointment preparation
 - Links to patient's medical record
7. Appointment confirmed
8. **Automation** sends confirmation:
 - Appointment details
 - Doctor name
 - Location/room number
 - Preparation instructions (if needed)
9. **Automation** triggers reminders:
 - 48 hours before: "Your appointment is in 2 days"
 - 24 hours before: "Reminder: Appointment tomorrow at [time]"
 - 2 hours before: "Your appointment is in 2 hours. Please arrive 15 minutes early."
10. Patient confirms or requests reschedule
11. If reschedule requested:
 - Bot shows available alternative slots
 - Patient selects new slot
 - Appointment updated
 - Confirmation sent
12. Appointment day:
 - Check-in reminder sent
 - Waiting time updates (if delayed)
13. Appointment completed
14. **Automation** sends:
 - Post-appointment follow-up
 - Prescription details (if applicable)
 - Next steps
 - Feedback request
15. **Analytics** tracks:
 - Appointment booking rate
 - No-show rate
 - Cancellation rate
 - Patient satisfaction

**Expected Outcome:**

Patient appointment scheduling automated with reminders, confirmations, and follow-ups, reducing no-shows and improving patient experience.

**Business Value:**

- Reduced no-shows
- Better appointment management
- Improved patient experience
- Administrative efficiency
- Patient satisfaction

---

### UC-HOSPITAL-002: Patient Follow-Up & Care Management

**Business Scenario:**

A hospital needs to follow up with patients after procedures, send medication reminders, and track recovery progress.

**Steps:**
1. Patient completes procedure/surgery
2. **Automation** creates follow-up sequence:
 - Day 1: "Hope you're recovering well. Any concerns?"
 - Day 3: "How are you feeling? Any pain or discomfort?"
 - Day 7: "Recovery check-in. Please update us on your progress."
 - Day 14: "Follow-up appointment reminder"
3. Patient responds with updates
4. **Automation** creates **Task** if concerns reported
5. Healthcare provider reviews responses
6. Provider responds with guidance
7. Medication reminders:
 - **Automation** sends daily medication reminders
 - "Time to take your [medication name]"
 - Includes dosage instructions
8. Follow-up appointment scheduled
9. **Automation** sends:
 - Appointment confirmation
 - Preparation instructions
 - What to bring
10. Post-appointment:
 - Recovery progress tracked
 - Additional instructions sent
 - Next steps communicated
11. Patient recovery complete
12. **Automation** sends:
 - Discharge summary
 - Final instructions
 - Follow-up care guidelines
 - Satisfaction survey

**Expected Outcome:**

Complete patient follow-up and care management with automated check-ins, medication reminders, and progress tracking.

**Business Value:**

- Better patient outcomes
- Reduced readmissions
- Medication adherence
- Patient satisfaction
- Care continuity

---

### UC-HOSPITAL-003: Emergency Notification System

**Business Scenario:**

A hospital needs to send emergency notifications to staff, patients, and families during critical situations.

**Steps:**
1. Hospital admin identifies emergency situation
2. Creates urgent **Campaign**:
 - Type: SMS + WhatsApp Broadcast
 - Target: All staff members
 - Message: "Code Blue - Emergency Protocol Activated"
3. Campaign sends immediately
4. Staff receives notification
5. Staff responds with acknowledgment
6. Patient families notified:
 - **Campaign** created for affected patients' families
 - Personalized message: "Your family member [name] is receiving emergency care. Updates will follow."
7. Regular updates sent:
 - Status updates every hour
 - Progress reports
 - Next steps communicated
8. Situation resolved
9. Final update sent:
 - Resolution details
 - Next steps
 - Contact information
10. **Analytics** tracks:
 - Notification delivery
 - Response rates
 - Communication effectiveness

**Expected Outcome:**

Emergency notifications sent efficiently to all relevant parties with regular updates and complete communication tracking.

**Business Value:**

- Emergency preparedness
- Rapid communication
- Family peace of mind
- Staff coordination
- Crisis management

---

### UC-HOSPITAL-004: Health Campaign & Preventive Care

**Business Scenario:**

A hospital wants to run preventive health campaigns, vaccination reminders, and health check-up notifications.

**Steps:**
1. Hospital admin creates **Campaign**:
 - Type: WhatsApp Broadcast
 - Name: "Annual Health Check-up Reminder"
 - Target: Patients tagged "Annual Check-up Due"
2. Campaign message:
 - "Annual health check-up reminder"
 - "Book your appointment now"
 - Button: "Book Appointment"
3. Campaign sends to 5,000 patients
4. **Analytics** tracks:
 - Sent: 5,000
 - Delivered: 4,950
 - Read: 3,800
 - Clicked: 1,200 (32% CTR)
5. Patients click "Book Appointment"
6. **Bot Flow** collects:
 - Preferred date/time
 - Doctor preference
 - Reason for visit
7. Appointments scheduled
8. **Automation** sends:
 - Appointment confirmation
 - Preparation instructions
 - Reminders
9. Vaccination reminders:
 - **Automation** sends vaccination due reminders
 - "Your [vaccine name] is due. Book your appointment."
10. Health tips campaigns:
 - Weekly health tips sent
 - Seasonal health advice
 - Preventive care information
11. Campaign performance:
 - Appointments booked: 800
 - Vaccinations scheduled: 400
 - Health check-ups completed: 600

**Expected Outcome:**

Preventive health campaigns successfully executed with high engagement and appointment bookings.

**Business Value:**

- Preventive care promotion
- Patient engagement
- Health outcomes improvement
- Appointment bookings
- Public health impact

---

## Marketing Agencies Industry Use Cases

### UC-MARKETING-001: Client Campaign Management

**Business Scenario:**

A marketing agency manages multiple client campaigns. They need to track campaign performance, communicate with clients, and report results.

**Steps:**
1. Agency receives new client
2. **Company** record created for client
3. **Deal** created in "Client Pipeline":
 - Stage: "Proposal"
 - Value: Campaign budget
 - Linked to client company
4. Agency creates campaign proposal
5. Proposal sent to client via WhatsApp
6. Client reviews and approves
7. Deal moved to "Active Campaign" stage
8. **Project** created:
 - Type: DELIVERY
 - Name: "[Client] - [Campaign Name]"
 - Linked to client company
 - Milestones: Campaign setup, Launch, Optimization, Reporting
9. Campaign setup:
 - **Campaign** created in ConnectGain
 - Target audience configured
 - Message content approved
 - Schedule set
10. Campaign launched
11. **Automation** sends client update:
 - "Campaign launched successfully"
 - Initial performance metrics
12. Ongoing updates:
 - Daily performance reports sent
 - Key metrics shared
 - Optimization recommendations
13. Campaign performance tracked:
 - Opens, clicks, conversions
 - ROI calculated
 - Client dashboard updated
14. Campaign completed
15. **Automation** generates final report
16. Report sent to client
17. Deal moved to "Completed" stage
18. **Project** marked complete
19. Follow-up:
 - Client feedback requested
 - Next campaign discussion
 - Renewal opportunity

**Expected Outcome:**

Complete client campaign management from proposal to completion with automated updates and performance tracking.

**Business Value:**

- Client satisfaction
- Campaign transparency
- Performance tracking
- Client retention
- Upselling opportunities

---

### UC-MARKETING-002: Lead Generation & Qualification

**Business Scenario:**

A marketing agency receives leads from multiple sources and needs to qualify them, assign to account managers, and convert to clients.

**Steps:**
1. Lead submits inquiry via website form
2. **Automation** creates:
 - **Contact** record
 - **Deal** in "Lead Pipeline" (stage: "Inquiry")
3. **Bot Flow** automatically responds:
 - Thanks for inquiry
 - Collects additional information:
 - Company name
 - Industry
 - Budget range
 - Campaign goals
 - Timeline
4. Bot qualifies lead based on responses
5. **Automation** triggers:
 - Tags contact: "Qualified Lead", "Budget: $50K+"
 - Assigns to available account manager
 - Creates **Task** for follow-up
6. Account manager receives notification
7. Account manager reviews lead information
8. Account manager contacts lead:
 - Sends personalized message
 - Schedules discovery call
9. Discovery call scheduled via **Scheduling**
10. Call completed
11. Account manager updates deal:
 - Moves to "Qualified" stage
 - Updates probability
 - Adds notes
12. Proposal created
13. Proposal sent to client
14. Client reviews proposal
15. Client approves
16. Deal moved to "Closed Won"
17. **Automation** triggers:
 - Client onboarding sequence
 - Welcome message
 - Onboarding checklist
 - Kickoff meeting scheduled
18. **Analytics** tracks:
 - Lead source performance
 - Conversion rates
 - Sales cycle length
 - Account manager performance

**Expected Outcome:**

Lead generation and qualification process automated with complete tracking from inquiry to client conversion.

**Business Value:**

- Faster lead response
- Better qualification
- Higher conversion rates
- Complete tracking
- Performance insights

---

### UC-MARKETING-003: Multi-Client Campaign Execution

**Business Scenario:**

A marketing agency needs to execute campaigns for multiple clients simultaneously, track performance, and report results.

**Steps:**
1. Agency has 10 active client campaigns
2. Each client has **Project** with campaign milestones
3. Campaign execution:
 - **Campaigns** created for each client
 - Target audiences configured
 - Messages customized per client
 - Schedules set
4. Campaigns launched
5. **Automation** sends client updates:
 - Daily performance summaries
 - Key metrics
 - Optimization recommendations
6. Performance monitoring:
 - Real-time campaign analytics
 - Client dashboards updated
 - Alerts for underperforming campaigns
7. Campaign optimization:
 - A/B testing results analyzed
 - Optimizations implemented
 - Client notified of changes
8. Weekly client reports:
 - **Automation** generates reports
 - Reports sent via WhatsApp/Email
 - Includes:
 - Performance metrics
 - ROI calculations
 - Recommendations
9. Client meetings scheduled:
 - **Scheduling** used for client calls
 - Meeting notes added to **Deal**
 - Action items created as **Tasks**
10. Campaign completion:
 - Final reports generated
 - Results presented to clients
 - Next campaign discussions
11. **Analytics** tracks:
 - Agency-wide performance
 - Client satisfaction
 - Campaign ROI
 - Team performance

**Expected Outcome:**

Multiple client campaigns executed simultaneously with automated updates, performance tracking, and client reporting.

**Business Value:**

- Scalable operations
- Client satisfaction
- Performance optimization
- Time savings
- Business growth

---

### UC-MARKETING-004: Client Communication & Relationship Management

**Business Scenario:**

A marketing agency needs to maintain strong client relationships through regular communication, updates, and proactive support.

**Steps:**
1. Agency creates **Company** record for each client
2. **Contacts** linked to client companies
3. **Deals** track active campaigns/projects
4. Regular communication:
 - Weekly performance updates
 - Monthly strategy reviews
 - Quarterly business reviews
5. **Automation** sends:
 - Weekly campaign summaries
 - Monthly reports
 - Quarterly reviews
6. Proactive communication:
 - Industry insights shared
 - Competitor analysis
 - Market trends
 - Optimization opportunities
7. Client inquiries handled:
 - Questions answered promptly
 - Concerns addressed
 - Requests fulfilled
8. Client feedback collected:
 - Satisfaction surveys
 - NPS scores
 - Improvement suggestions
9. Relationship building:
 - Birthday wishes
 - Anniversary celebrations
 - Holiday greetings
 - Industry event invitations
10. Upselling opportunities:
 - Additional services offered
 - Campaign expansion discussed
 - New service introductions
11. **Analytics** tracks:
 - Client engagement levels
 - Response times
 - Satisfaction scores
 - Retention rates

**Expected Outcome:**

Strong client relationships maintained through regular communication, proactive support, and relationship building activities.

**Business Value:**

- Client retention
- Upselling opportunities
- Client satisfaction
- Referral generation
- Business growth

---

## AI Call Intelligence Use Cases

### UC-CALLAI-001: Automated Call Recording Upload & AI Transcription

**Business Scenario:**

A sales team records all outbound calls and needs automatic transcription with Arabic/English support for compliance and training purposes.

**Steps:**
1. Agent completes sales call using mobile app
2. Call recording uploaded via **Mobile API** (`POST /call-recording`) or **Webhook API** (`POST /call-recording-webhook`)
3. System stores audio in `call-recordings` storage bucket
4. **AI Pipeline** automatically triggered:
 - Status set to "transcribing"
 - Audio converted to base64 and sent to Google Gemini 2.5 Flash
 - Full transcript generated (Arabic/English bilingual support)
5. Transcript saved to call record
6. Agent views transcript in **[Call Intelligence](https://docs.connectgain.cloud/04-use-cases/02-user-guide/call-intelligence.md)** dashboard
7. Manager searches transcripts for specific keywords
8. Compliance team reviews flagged calls

**Expected Outcome:**

Every call automatically transcribed within minutes, searchable and accessible from the Call Intelligence dashboard.

**Business Value:**

- 100% call documentation coverage
- Arabic-first AI transcription
- Compliance and audit readiness
- Training material generation
- Eliminates manual note-taking

---

### UC-CALLAI-002: AI Sentiment Analysis & Call Scoring

**Business Scenario:**

A customer service manager wants to monitor agent performance and customer satisfaction across hundreds of daily calls without listening to every recording.

**Steps:**
1. Call recording processed by AI pipeline
2. After transcription, **AI Analysis** generates:
 - Sentiment score (-1 to +1)
 - Sentiment label (positive/neutral/negative/mixed)
 - Resolution score (0-100)
 - Call classification (type, category, sub-category)
3. Manager opens **Call Intelligence** dashboard
4. Views aggregate metrics:
 - Average sentiment across all calls
 - Sentiment trends over time
 - Agent-level sentiment comparison
5. Filters calls by negative sentiment
6. Reviews flagged calls with low resolution scores
7. Identifies agents needing coaching
8. Creates training tasks from insights

**Expected Outcome:**

Real-time visibility into customer satisfaction and agent performance without manual call review.

**Business Value:**

- Proactive quality management
- Data-driven coaching decisions
- Early detection of customer issues
- Agent performance benchmarking
- Customer satisfaction tracking

---

### UC-CALLAI-003: Auto-Generated Action Items from Calls

**Business Scenario:**

After sales or support calls, agents often forget follow-up items. The AI automatically extracts action items and creates tasks.

**Steps:**
1. Call recording processed by AI pipeline
2. AI extracts action items with:
 - Title and description
 - Priority level (high/medium/low)
3. System auto-creates up to 5 **Tasks** per call:
 - Assigned to the agent who handled the call
 - Linked to the contact
 - Priority set based on AI analysis
4. **Call Tasks** link table connects call record to tasks
5. Agent receives task notifications
6. Agent views tasks in **Task Management**
7. Agent completes follow-up actions
8. Manager tracks task completion rates per agent

**Expected Outcome:**

Zero dropped follow-ups — every commitment made during a call is tracked as a task.

**Business Value:**

- No missed follow-ups
- Automated task creation saves 15+ minutes per call
- Improved customer satisfaction
- Accountability tracking
- Deal acceleration

---

### UC-CALLAI-004: Call Intelligence Dashboard & Analytics

**Business Scenario:**

Operations manager needs a real-time overview of call center performance including volume, duration, sentiment trends, and agent utilization.

**Steps:**
1. Navigate to **Call Intelligence** page
2. View real-time KPI cards:
 - Total calls (this period)
 - Average duration
 - Overall sentiment score
 - Top performing agents
3. Filter by date range, agent, sentiment, or tags
4. Drill into individual call records
5. View call timeline with:
 - Recording playback
 - Full transcript
 - AI summary
 - Sentiment indicators
 - Action items
 - Keywords and tags
6. Export call data for reporting
7. Compare agent performance side-by-side
8. Track usage against monthly minute quotas

**Expected Outcome:**

Complete call center visibility with AI-powered insights, enabling data-driven management decisions.

**Business Value:**

- Real-time operational visibility
- Performance benchmarking
- Resource optimization
- Cost tracking (minutes & AI tokens)
- Trend identification

---

### UC-CALLAI-005: Call Recording via External System Webhook

**Business Scenario:**

A business uses a third-party PBX/VoIP system and wants call recordings automatically ingested into ConnectGain for AI analysis.

**Steps:**
1. Admin generates **API Key** in Settings
2. Configures PBX system to send webhook on call completion
3. PBX sends `POST /functions/v1/call-recording-webhook` with:
 - `x-api-key` header for authentication
 - `recording_url` (public URL to audio file)
 - `customer_phone` for contact matching
 - `duration_seconds`, `direction`, `call_timestamp`
 - Optional `metadata` for custom fields
4. System downloads recording from URL
5. Stores in `call-recordings` bucket
6. Auto-matches or creates contact by phone number
7. Triggers AI processing pipeline
8. Results available in Call Intelligence dashboard

**Expected Outcome:**

Seamless integration with any VoIP/PBX system — all calls automatically analyzed by AI.

**Business Value:**

- Works with any phone system
- Zero manual upload effort
- Automatic contact matching
- Complete call history per contact
- API-key based security

---

### UC-CALLAI-006: Silent Recording Detection & Cost Optimization

**Business Scenario:**

Some uploaded recordings are silent (missed calls, voicemail beeps, accidental recordings). The system should detect these to avoid wasting AI analysis tokens.

**Steps:**
1. Recording uploaded and transcription attempted
2. AI returns transcription result
3. System checks against silence patterns:
 - "[no speech detected]"
 - Empty/blank audio indicators
 - Transcripts shorter than 5 characters
4. If silent detected:
 - Status set to "silent"
 - No analysis performed (saves tokens)
 - Tagged with "silent-recording"
 - Summary set to "This recording contains no audible speech"
5. Non-silent recordings proceed to full analysis
6. Dashboard excludes silent recordings from metrics
7. Admin can review silent recordings separately

**Expected Outcome:**

Silent recordings detected automatically, saving AI processing costs while maintaining complete records.

**Business Value:**

- Cost optimization (no wasted AI tokens)
- Accurate metrics (silent calls excluded)
- Complete audit trail maintained
- Automatic classification

---

### UC-CALLAI-007: Call Minutes Quota Management & Usage Tracking

**Business Scenario:**

Organization has a monthly call minutes quota. System tracks usage per agent and alerts when approaching limits.

**Steps:**
1. Admin sets monthly minutes allocation in **Settings**
2. Each processed call increments usage counter via `increment_call_minutes` RPC
3. Token usage tracked via `increment_call_tokens` RPC
4. Dashboard displays:
 - Minutes used vs. allocated
 - Per-agent breakdown
 - Cost estimation (based on token pricing)
5. **Automation** sends alerts at 80% and 95% usage
6. Admin can add bonus minutes via top-up
7. Top-up history logged in `call_minutes_topup_log`
8. Monthly usage resets automatically

**Expected Outcome:**

Complete visibility into call processing costs with proactive quota management.

**Business Value:**

- Budget control
- Fair usage distribution
- Cost transparency
- Proactive alerts prevent service interruption

---

### UC-CALLAI-008: AI-Powered Call Keyword Extraction & Auto-Tagging

**Business Scenario:**

Marketing team wants to understand what topics customers discuss most frequently across all calls.

**Steps:**
1. AI analysis extracts 3-8 keywords per call
2. AI generates auto-tags (e.g., "escalation", "follow-up needed", "complaint", "upsell opportunity")
3. Keywords and tags stored on call record
4. Marketing team filters calls by keywords
5. Identifies trending topics across time periods
6. Cross-references with deal outcomes
7. Creates targeted campaigns based on customer language
8. Adjusts messaging based on common objections

**Expected Outcome:**

Deep understanding of customer language, concerns, and opportunities extracted automatically from calls.

**Business Value:**

- Voice-of-customer insights at scale
- Objection pattern identification
- Campaign message optimization
- Product feedback aggregation
- Competitive intelligence

---

### UC-CALLAI-009: Webhook Notification on Call Processing Complete

**Business Scenario:**

External systems (BI tools, CRM, ticketing) need to be notified when a call has been fully processed with AI insights.

**Steps:**
1. Call processing completes (transcription + analysis)
2. System dispatches `call.processed` webhook via **webhook-dispatcher**
3. Webhook payload includes:
 - `call_record_id`
 - `organization_id`
 - `sentiment` label
 - `action_items_count`
4. External BI tool receives webhook
5. Updates real-time dashboard with new call data
6. Triggers downstream workflows (e.g., escalation for negative sentiment)
7. Syncs call insights to external CRM

**Expected Outcome:**

Real-time notification to external systems when call AI analysis completes, enabling integrated workflows.

**Business Value:**

- Real-time data flow to external systems
- Automated escalation workflows
- Integrated analytics
- No polling required

---

### UC-CALLAI-010: Failed Call Processing Retry & Error Handling

**Business Scenario:**

Occasionally AI processing fails due to network issues or temporary API errors. The system should retry automatically.

**Steps:**
1. Call processing encounters error (transcription or analysis)
2. System increments `retry_count` on call record
3. Status set to "failed"
4. If retry count < 3 (MAX_RETRIES):
 - Call can be reprocessed manually or via scheduled retry
 - Previous transcription preserved if available
5. If retry count >= 3:
 - Call marked as permanently failed
 - Admin notified
 - Manual review required
6. Admin views failed calls in dashboard
7. Can trigger manual reprocessing
8. Error details logged for debugging

**Expected Outcome:**

Resilient processing pipeline with automatic retry and graceful failure handling.

**Business Value:**

- High processing reliability
- No lost recordings
- Transparent error handling
- Admin visibility into failures

---

### UC-CALLAI-011: Trade-Call Compliance Surveillance (Market-Abuse Detection)

**Business Scenario:**

A brokerage must monitor broker–client calls for conduct and market-abuse risks (regulatory requirement). Listening to every call is impossible, so the AI flags risky calls for the compliance team.

**Steps:**
1. Broker–client call is recorded and processed by the AI pipeline
2. **AI Analysis** scans the transcript for market-abuse and conduct risks and emits `compliance_flags`, each with:
 - Category — `insider_information`, `market_manipulation`, `front_running`, `guaranteed_returns`, `pressure_selling`, `unauthorized_trading`, `missing_disclosure`, `suitability_concern`
 - Severity (high/medium/low), the speaker (Broker/Client), the exact matched phrase, a confidence score, and a one-line rationale
3. The call also records the **instruction type** (client instruction vs. recommendation vs. discussion) and whether a required **risk disclosure** was spoken
4. A regulatory **retention horizon** (7 years) is stamped on the record
5. Compliance officer opens the **Compliance & Surveillance** report:
 - Flagged-call volume and % of calls flagged
 - High-severity flag count
 - Disclosure coverage over order/advice calls
 - Flags by category and a recent-flagged-calls feed
6. Officer clicks a flagged call, reads the matched phrase in context, and reviews the recording
7. Genuine issues are escalated; false positives are dismissed

**Expected Outcome:**

Risky calls surface automatically with the exact triggering phrase, turning unscalable 100%-listening into targeted review.

**Business Value:**

- Scalable trade-surveillance coverage
- Auditable, explainable flags (phrase + speaker + rationale)
- Disclosure-coverage tracking
- Regulatory retention built in
- Faster compliance review cycles

---

### UC-CALLAI-012: Agent Call-Handling Quality (QA) Scoring & Coaching

**Business Scenario:**

A team lead wants an objective measure of *how well each agent handled the client* on a call — not just sentiment — to drive coaching.

**Steps:**
1. Call processed by the AI pipeline
2. **AI Analysis** produces an `agent_quality` scorecard:
 - Overall handling score (0–100)
 - Five graded dimensions: Professionalism & Tone, Communication & Clarity, Client Needs Handling, Market/Product Knowledge, Compliance Adherence
 - Strengths, coaching points, and a one-line summary for the manager
3. Agent or manager opens the **Call Detail** dialog and sees the scorecard (overall score, colored dimension bars, strengths vs. coaching)
4. Manager opens the **Agent Performance (Manager View)** report and sorts agents by **QA Score**
5. Drill-down shows each agent's per-dimension averages — e.g., strong knowledge but weak compliance
6. Manager builds targeted coaching from the lowest dimensions

**Expected Outcome:**

Every call is objectively scored on handling quality, with concrete coaching points, without manual QA review.

**Business Value:**

- Objective, consistent QA at 100% coverage
- Dimension-level coaching targets
- Identifies systemic weaknesses across the team
- Reference "excellent call" examples for training

---

### UC-CALLAI-013: Brokerage Call Classification & Manual Reclassification

**Business Scenario:**

Management wants to know what each call was *about* — order execution, advice, complaint, margin call, etc. — and to correct the AI when it gets it wrong.

**Steps:**
1. AI classifies each call into a brokerage taxonomy: Order Placement/Execution, Investment Advice, Market Update, Account/Portfolio Inquiry, Complaint/Dispute, Margin Call, KYC/Onboarding, Prospecting/Cold Outreach, Platform/Technical Support, Other
2. The **Type** appears as a column in the call records list and in the call detail dialog
3. A manager (admin/owner) can **manually reclassify** a call from a dropdown in the detail dialog
4. Manual classifications are tagged `manual` and **survive reprocessing** (the AI will not overwrite them)
5. Reports break calls down by type and by per-agent call-type mix

**Expected Outcome:**

Every call is categorized for reporting, with a human override that sticks.

**Business Value:**

- Call-mix visibility per agent and team
- Human-in-the-loop accuracy
- Stable categorization across reprocessing
- Better routing and staffing decisions

---

### UC-CALLAI-014: Topic & Keyword Trend Tracking

**Business Scenario:**

A desk head wants to know which instruments and themes clients are calling about, what's growing, and which topics make clients unhappy.

**Steps:**
1. AI extracts structured **topics** per call — each with a normalized label, a category (instrument, order, advisory, account, market, fees, compliance, service, complaint), and a per-topic sentiment
2. The detected **language** (Arabic / English / Mixed) is recorded per call
3. Topic labels are canonicalized so variants merge (e.g. "follow-up"/"follow up", "fees"/"fee")
4. Manager opens the **Topic & Keyword Trends** report:
 - Top topics and topics by category
 - Top-topic trends over time
 - **Emerging topics** (period-over-period growth)
 - **Topics driving negative sentiment** (recurring topics ranked by lowest average sentiment)
5. Findings feed product, pricing, and coaching decisions
6. Topic/language data is included in the analytics **CSV export** for offline pivoting

**Expected Outcome:**

Leadership sees what clients are talking about and what's trending, not just a flat keyword cloud.

**Business Value:**

- Early signal on emerging issues and demand
- Root-cause of dissatisfaction by topic
- Instrument-level interest tracking
- Exportable for BI tools

---

### UC-CALLAI-015: Manager Agent-Level KPI Reporting

**Business Scenario:**

A branch manager needs one detailed view of every agent's activity, quality, trading, and compliance KPIs.

**Steps:**
1. Manager (admin/owner only) opens the **Agent Performance (Manager View)** report
2. A sortable table shows per agent: calls (inbound/outbound), talk time, orders vs. recommendations, QA score, sentiment, resolution, flagged calls, flag rate, high-severity flags, and disclosure coverage
3. A team-summary strip shows active agents, total calls, team flag rate, and disclosure coverage
4. Manager sorts by any column (e.g., flag rate, QA score) to find outliers
5. Drill-down per agent reveals QA dimension averages, flag categories, top instruments, and call-type mix
6. The report is **gated to Owners/Admins**; demo data is shown in view-only preview

**Expected Outcome:**

A single, sortable command-center view of agent performance across every dimension.

**Business Value:**

- Holistic agent benchmarking
- Surfaces compliance and quality outliers fast
- Admin-restricted sensitive KPIs
- Drives targeted coaching and recognition

---

### UC-CALLAI-016: Code-Switched (Arabic/English) Transcription, Diarization & Engine Validation

**Business Scenario:**

Egyptian broker–client calls mix Arabic and English in the same sentence, with prices and ticker symbols that must be transcribed exactly. The firm needs accurate transcripts and a way to verify the chosen engine before relying on it.

**Steps:**
1. The transcription prompt is tuned for code-switched Egyptian Arabic/English: it preserves each language as spoken, transcribes numbers/prices exactly, boosts EGX tickers and trading jargon, and labels speakers as **Broker:** / **Client:**
2. The transcript viewer parses those labels (including single-line, inline-labeled transcripts) into a **threaded, per-speaker diarized view** with RTL/LTR auto-detection
3. Before committing to an engine, the team runs the **ASR bake-off harness** on real call samples with hand-checked references
4. The harness reports **WER split by language** (Arabic / English / mixed), **number/price accuracy**, **ticker recall**, and an approximate diarization signal
5. The team picks/validates the engine (Gemini by default) on the metrics that matter for trading

**Expected Outcome:**

Accurate, diarized transcripts of mixed-language trading calls, with an objective way to validate transcription quality.

**Business Value:**

- Reliable transcripts for dialect + code-switching
- Correct prices and tickers (a wrong digit changes a trade)
- Clear who-said-what attribution for compliance
- Evidence-based engine selection

---

## Call Center Automation Use Cases

### UC-CALLCENTER-001: Inbound Call Routing with AI Pre-Screening

**Business Scenario:**

A call center receives high volumes of inbound calls. Before connecting to an agent, the system pre-screens via WhatsApp bot, and when calls do connect, AI records and routes based on topic.

**Steps:**
1. Customer calls company main number
2. IVR/PBX routes call to available agent (or SIP softphone in browser)
3. **Call automatically recorded** via SIP integration or mobile app
4. During the call, agent tags the topic manually or lets AI auto-classify post-call
5. Call ends → recording uploaded automatically:
 - SIP calls: automatic via call event logging
 - Mobile calls: via **Mobile API** (`POST /call-recording`)
 - External PBX: via **Webhook** (`POST /call-recording-webhook`)
6. **AI Pipeline** processes recording:
 - Transcription (Arabic/English)
 - Classification: `{ type: "complaint", category: "billing", sub_category: "overcharge" }`
 - Sentiment analysis
 - Action items extracted
7. **Automation** triggers based on classification:
 - Billing issues → task for billing team
 - Technical issues → task for tech support
 - Complaints → escalation to supervisor
 - Sales inquiries → deal created in pipeline
8. Supervisor reviews call quality in **Call Intelligence** dashboard
9. **Analytics** tracks:
 - Call volume by category
 - First-call resolution rate
 - Average handle time
 - Agent utilization

**Expected Outcome:**

Every inbound call automatically classified and routed to the right team with AI-generated follow-up tasks.

**Business Value:**

- Zero manual call logging
- Automatic routing by topic
- 100% call documentation
- Supervisor quality oversight
- Data-driven staffing decisions

---

### UC-CALLCENTER-002: Outbound Sales Call Campaign with AI Analysis

**Business Scenario:**

Sales team runs outbound calling campaigns. Every call is recorded, transcribed, and analyzed to optimize the sales pitch and track conversion.

**Steps:**
1. **Campaign** created targeting lead segment
2. Lead list loaded as **Contacts** with tags
3. **Tasks** auto-created: "Call {{contact.name}} — Sales Outreach"
4. Agent opens contact → clicks **Click-to-Call** (SIP or mobile)
5. Call connected → **recording starts automatically**
6. Agent delivers sales pitch, handles objections
7. Call ends → recording uploaded
8. **AI Pipeline** processes:
 - Full transcription of conversation
 - Sentiment tracking (customer interest level)
 - Keywords extracted: product mentions, competitor names, objections
 - Action items: "Send pricing to Ahmed", "Schedule demo for Thursday"
 - Auto-tags: "interested", "price-sensitive", "competitor-mentioned"
9. **Deal** auto-created or updated based on call outcome:
 - Interested → "Qualified" stage
 - Needs follow-up → "Follow-Up" stage
 - Not interested → "Lost" with reason
10. **Automation** sends post-call follow-up:
 - Interested: Product brochure via WhatsApp
 - Price-sensitive: Special offer email
 - Demo requested: Scheduling link
11. Manager reviews campaign performance:
 - Calls made vs. connected
 - Sentiment distribution across calls
 - Top objections (from keyword extraction)
 - Agent conversion rates
 - Best performing pitch patterns
12. **Analytics** dashboard shows:
 - Campaign ROI
 - Cost per acquisition
 - Call-to-deal conversion funnel
 - Agent leaderboard

**Expected Outcome:**

AI-analyzed outbound campaign with automatic deal creation, follow-up automation, and objection pattern analysis.

**Business Value:**

- Sales pitch optimization from AI insights
- Automatic CRM updates after every call
- Objection handling training from real data
- Agent performance benchmarking
- Campaign ROI tracking

---

### UC-CALLCENTER-003: Call Quality Monitoring & Agent Coaching

**Business Scenario:**

Call center supervisor needs to monitor agent quality across hundreds of daily calls, identify coaching opportunities, and track improvement over time.

**Steps:**
1. All agent calls recorded and processed by AI
2. Supervisor opens **Call Intelligence** dashboard
3. Views agent performance metrics:
 - Average sentiment score per agent
 - Resolution score per agent
 - Average handle time
 - Calls per hour
4. Filters by low sentiment or low resolution scores
5. Reviews specific call transcripts and AI summaries
6. Identifies patterns:
 - Agent X has low sentiment on complaint calls
 - Agent Y frequently misses follow-up commitments
 - Agent Z has highest resolution scores — best practices
7. Creates **Task** for coaching: "1:1 coaching with Agent X on complaint handling"
8. **Scheduling** for coaching session
9. Shares example transcripts (positive and negative) as training material
10. Post-coaching: tracks improvement over next 30 days
11. **Automation** alerts supervisor when:
 - Any call sentiment drops below -0.5
 - Resolution score below 30
 - Customer uses escalation keywords ("manager", "complaint", "lawsuit")
12. Monthly quality report generated:
 - Agent rankings
 - Improvement trends
 - Training effectiveness
 - Customer satisfaction correlation

**Expected Outcome:**

Data-driven agent coaching program powered by AI call analysis with measurable improvement tracking.

**Business Value:**

- Objective quality measurement (no sampling bias)
- 100% call coverage (not just random samples)
- Targeted coaching saves time
- Measurable improvement tracking
- Best practice identification and sharing

---

### UC-CALLCENTER-004: Multi-Language Call Transcription & Translation

**Business Scenario:**

A MENA-based call center handles calls in Arabic (multiple dialects) and English. AI transcribes all calls with bilingual support for team collaboration.

**Steps:**
1. Customer calls and speaks in Arabic (Egyptian dialect)
2. Call recorded and uploaded
3. **AI Transcription** (Google Gemini 2.5 Flash):
 - Detects language automatically
 - Transcribes Arabic speech accurately
 - Handles code-switching (Arabic/English mix)
 - Includes punctuation and speaker turns
4. Transcript stored on call record
5. Team members who don't speak Arabic can:
 - Read AI summary (generated in English)
 - Search calls by English keywords
 - View action items in English
6. **AI Analysis** generates:
 - Summary in the organization's primary language
 - Classification labels in English
 - Keywords in original language + English
7. **Automation** routes based on language:
 - Arabic calls → Arabic-speaking team
 - English calls → English team
 - Mixed → bilingual team
8. **Analytics** tracks:
 - Call volume by language
 - Sentiment by language/dialect
 - Resolution rates by language
 - Agent language proficiency utilization

**Expected Outcome:**

Seamless bilingual call center operations with AI bridging the language gap for management and analytics.

**Business Value:**

- Arabic-first AI (competitive advantage in MENA)
- Cross-language team collaboration
- Unified analytics regardless of call language
- Efficient resource allocation by language

---

### UC-CALLCENTER-005: Automated Post-Call Survey & CSAT Tracking

**Business Scenario:**

After every support call, the system automatically sends a satisfaction survey and correlates results with AI sentiment analysis.

**Steps:**
1. Call ends → AI processes recording
2. **Automation** triggers 10 minutes after call:
 - WhatsApp message: "Thank you for calling! How was your experience?"
 - Quick reply buttons: ⭐ 1-5
3. Customer responds with rating
4. Rating stored on **Contact** and linked to call record
5. Low ratings (1-2) trigger:
 - **Task** for supervisor: "Review negative call experience for {{contact.name}}"
 - Priority re-contact within 24 hours
 - AI sentiment from call cross-referenced with survey score
6. **Bot Flow** follows up on low ratings:
 - "We're sorry about your experience. Can you tell us more?"
 - Collects specific feedback
 - Offers callback from manager
7. High ratings (4-5) trigger:
 - Thank you message
 - Review request (Google/Trustpilot)
 - Referral program invitation
8. **Analytics** correlates:
 - CSAT scores vs. AI sentiment scores
 - Agent CSAT rankings
 - CSAT trends over time
 - Call topics with lowest satisfaction
 - Prediction: AI sentiment as leading indicator of CSAT

**Expected Outcome:**

Automated CSAT collection with AI sentiment correlation, enabling predictive quality management.

**Business Value:**

- 100% survey distribution (vs. random sampling)
- AI sentiment validates survey scores
- Proactive recovery for dissatisfied customers
- Predictive quality indicators
- Agent performance transparency

---

### UC-CALLCENTER-006: IVR Deflection to WhatsApp Bot

**Business Scenario:**

Call center wants to reduce call volume by deflecting simple inquiries to WhatsApp bot before they reach an agent.

**Steps:**
1. Customer calls company number
2. IVR message: "For faster service, message us on WhatsApp! We'll text you a link now."
3. Customer opts in → **Automation** sends WhatsApp link via SMS
4. Customer opens WhatsApp conversation
5. **Bot Flow** handles inquiry:
 - Account balance → API lookup
 - Order status → tracking info
 - Payment → payment link
 - FAQ → knowledge base answer
6. If bot can't resolve → offers callback:
 - "Would you like an agent to call you back?"
 - **Scheduling** for callback slot
 - **Task** created for agent
7. Agent calls back at scheduled time:
 - **Call recorded** with full context from bot conversation
 - Agent has conversation history before calling
 - AI transcription captures resolution
8. If customer stays on phone instead:
 - Call handled normally → recorded and analyzed
 - AI compares resolution with bot-deflectable topics
9. **Analytics** tracks:
 - Deflection rate (calls → WhatsApp)
 - Bot resolution rate
 - Callback completion rate
 - Cost savings (bot vs. agent)
 - Topics that deflect well vs. need human touch

**Expected Outcome:**

Significant call volume reduction through intelligent WhatsApp deflection with AI-optimized topic routing.

**Business Value:**

- 30-50% call volume reduction
- Lower cost per interaction
- Faster resolution for simple queries
- Agents focus on complex issues
- Continuous optimization from AI data

---

### UC-CALLCENTER-007: Real-Time Escalation Detection from Live Calls

**Business Scenario:**

Supervisor needs to be alerted immediately when a call shows signs of escalation so they can intervene or prepare for a follow-up.

**Steps:**
1. All calls processed by AI pipeline after completion
2. AI analysis detects escalation signals:
 - Sentiment score below -0.7
 - Keywords: "manager", "supervisor", "complaint", "lawyer", "cancel"
 - Tags: "escalation", "threat-to-leave"
3. **Automation** triggers on `call.processed` webhook:
 - Checks sentiment and tags
 - If escalation detected → immediate actions
4. Escalation actions:
 - **Task** created for supervisor: "URGENT: Escalated call from {{contact.name}}"
 - WhatsApp notification to supervisor with AI summary
 - Contact flagged with "escalation" tag
 - Deal moved to "At Risk" stage (if exists)
5. Supervisor reviews:
 - Listens to recording
 - Reads AI summary and transcript
 - Reviews action items
6. Supervisor calls customer within 2 hours:
 - **Call recorded** — AI tracks recovery
 - Sentiment compared: original call vs. recovery call
 - Resolution documented
7. **Analytics** tracks:
 - Escalation frequency
 - Root causes (from classification)
 - Recovery success rate
 - Time to escalation response
 - Agent escalation rates

**Expected Outcome:**

Automatic escalation detection and supervisor alerting with AI-tracked recovery outcomes.

**Business Value:**

- Prevents customer churn from bad experiences
- Supervisor awareness without listening to all calls
- Measurable recovery effectiveness
- Agent coaching on escalation prevention
- Root cause analysis

---

### UC-CALLCENTER-008: Call Recording Compliance & Audit Trail

**Business Scenario:**

Regulated industry (banking, insurance, healthcare) requires complete call recording with searchable transcripts for compliance audits.

**Steps:**
1. All calls recorded automatically (SIP, mobile, or webhook)
2. Recordings stored in secure `call-recordings` bucket
3. AI transcription creates searchable text records
4. Each call record maintains:
 - Recording file path
 - Full transcript
 - AI summary
 - Timestamp and duration
 - Agent and contact identification
 - Classification and keywords
5. Compliance officer needs to audit:
 - Searches transcripts for regulatory phrases
 - Filters by date range, agent, or contact
 - Exports call records with transcripts
6. **API** provides programmatic access:
 - `GET /rest/v1/call_records` with filters
 - Download recordings via signed URLs
7. Retention policy:
 - Recordings retained per regulatory requirement
 - Auto-archival after retention period
8. Audit report generation:
 - Calls per agent
 - Compliance keyword mentions
 - Customer consent verification
 - Disclosure statement delivery
9. **Analytics** for compliance:
 - Percentage of calls with required disclosures
 - Agents missing compliance steps
 - Audit readiness score

**Expected Outcome:**

Complete compliance-ready call archive with AI-searchable transcripts and automated audit reporting.

**Business Value:**

- Regulatory compliance (GDPR, PCI-DSS, MiFID II)
- Instant audit response
- Risk reduction
- Training on compliance gaps
- Legal protection

---

### UC-CALLCENTER-009: Workforce Management & Call Volume Forecasting

**Business Scenario:**

Call center manager uses AI call data to forecast call volumes, optimize staffing, and manage agent schedules.

**Steps:**
1. **Analytics** aggregates historical call data:
 - Call volume by hour, day, week
 - Average handle time by category
 - Agent availability patterns
2. **AI Call Intelligence** provides:
 - Call category distribution trends
 - Seasonal patterns
 - Campaign-driven volume spikes
3. Manager uses insights for staffing:
 - **Attendance Tracking** monitors agent presence
 - **Scheduling** manages shift assignments
 - **Availability Slots** track agent capacity
4. **Automation** triggers alerts:
 - Queue length exceeds threshold
 - Average wait time rising
 - Agent utilization above 90%
5. Real-time adjustments:
 - Break schedules shifted
 - Backup agents activated
 - IVR deflection increased
6. **Tasks** for workforce optimization:
 - Hire for predicted growth
 - Cross-train agents on trending topics
 - Schedule training during low-volume periods
7. Monthly workforce report:
 - Staffing efficiency
 - Cost per call
 - Service level achievement
 - Forecast accuracy
8. **Call minutes quota** tracked:
 - Usage vs. allocation
 - Cost projections
 - Top-up planning

**Expected Outcome:**

Data-driven workforce management with AI-powered volume forecasting and real-time optimization.

**Business Value:**

- Optimal staffing levels
- Reduced overtime costs
- Service level maintenance
- Predictive hiring
- Budget forecasting

---

### UC-CALLCENTER-010: Omnichannel Handoff — Chat to Call to Follow-Up

**Business Scenario:**

Customer starts on WhatsApp, escalates to phone call, and receives automated follow-up — all tracked in one unified conversation.

**Steps:**
1. Customer messages via WhatsApp: "I have a billing issue"
2. **Bot Flow** attempts resolution:
 - Checks account balance
 - Shows recent transactions
 - Bot can't resolve complex dispute
3. Bot offers: "Would you like to speak with an agent?"
4. Customer agrees → agent notified in **Inbox**
5. Agent reviews full WhatsApp conversation history
6. Agent calls customer via **Click-to-Call** (SIP softphone)
7. **Call recorded** — AI has context from prior chat:
 - Transcription includes billing details discussed
 - Sentiment tracked across both channels
 - Resolution documented
8. Call ends → AI generates:
 - Summary combining chat + call context
 - Action items from call
 - Resolution classification
9. **Automation** sends post-call follow-up via WhatsApp:
 - "As discussed, here's a summary of the changes..."
 - Confirmation of any credits/adjustments
 - "Reply here if you need anything else"
10. **Contact timeline** shows complete journey:
 - WhatsApp messages
 - Bot interactions
 - Agent chat
 - Phone call with transcript
 - Follow-up messages
11. **Analytics** tracks omnichannel metrics:
 - Channel escalation rates
 - Resolution by channel combination
 - Customer effort score
 - First-contact resolution vs. multi-touch

**Expected Outcome:**

Seamless omnichannel experience where context flows from chat to call and back, fully documented by AI.

**Business Value:**

- No context loss between channels
- Reduced customer effort
- Complete interaction history
- True omnichannel analytics
- Agent efficiency (no repeat questions)

---

### UC-CALLCENTER-011: PBX/VoIP Integration via Call Recording Webhook

**Business Scenario:**

Organization uses an existing PBX system (Asterisk, FreePBX, 3CX, etc.) and wants all calls automatically analyzed by ConnectGain AI.

**Steps:**
1. Admin generates **API Key** in ConnectGain settings
2. PBX configured to trigger webhook on call completion:
 ```
 POST /functions/v1/call-recording-webhook
 Headers: X-API-Key: cg_xxxxx
 Body: {
 "external_call_id": "pbx-call-12345",
 "recording_url": "https://pbx.company.com/recordings/12345.mp3",
 "customer_phone": "+201001234567",
 "agent_identifier": "agent@company.com",
 "duration_seconds": 245,
 "direction": "inbound",
 "call_timestamp": "2026-03-25T10:30:00Z"
 }
 ```
3. ConnectGain receives webhook:
 - Downloads recording from URL
 - Stores in secure storage
 - Matches contact by phone number (or creates new)
 - Identifies agent by email
4. AI Pipeline processes:
 - Transcription → Analysis → Classification
 - Results linked to contact timeline
5. PBX system receives `call.processed` webhook back:
 - Sentiment, action items count
 - Can update PBX CRM integration
6. **Analytics** combines PBX data with AI insights:
 - Call volume from PBX
 - AI quality scores per agent
 - Topic distribution
 - Customer satisfaction predictions
7. No changes to existing PBX workflow required

**Expected Outcome:**

Any PBX/VoIP system connected to ConnectGain AI in minutes, with zero workflow disruption.

**Business Value:**

- Works with any phone system
- No rip-and-replace
- AI layer on top of existing infrastructure
- Quick deployment (API key + webhook)
- Full call analytics without new hardware

---

### UC-CALLCENTER-012: Mobile Call Recording App for Field Teams

**Business Scenario:**

Field sales reps and service technicians make calls from personal phones. A mobile app records and uploads calls for AI analysis.

**Steps:**
1. Field agent installs ConnectGain mobile recorder app
2. Agent logs in via **Mobile API** (`POST /mobile-api/login`)
3. Agent browses contacts (`GET /mobile-api/contacts`)
4. Agent makes call from mobile phone
5. App records the call locally
6. After call ends, app uploads recording:
 ```
 POST /mobile-api/call-recording
 Content-Type: multipart/form-data
 - file: recording.m4a
 - customer_phone: +201001234567
 - duration_seconds: 180
 - direction: outbound
 - notes: "Discussed service renewal"
 ```
7. Server stores recording and triggers AI pipeline
8. Agent can view AI summary on mobile immediately:
 - Transcription
 - Action items (pushed as tasks)
 - Next steps
9. Back in office, manager views all field calls:
 - **Call Intelligence** dashboard
 - Per-agent activity reports
 - Customer visit frequency
10. **Automation** creates follow-up tasks from field calls
11. **Analytics** tracks:
 - Field team call activity
 - Customer coverage
 - Sentiment from field interactions
 - Follow-up completion rates

**Expected Outcome:**

Complete field team call documentation with AI analysis, eliminating the "black hole" of untracked mobile calls.

**Business Value:**

- 100% field call documentation
- AI-generated follow-ups from field visits
- Manager visibility into field activities
- Customer relationship continuity
- No expensive hardware needed

---

## Retail Industry Use Cases

### UC-RETAIL-001: In-Store Customer Engagement via WhatsApp

**Business Scenario:**

A retail chain wants to capture in-store visitors' contact info and continue engagement via WhatsApp for promotions, loyalty programs, and feedback.

**Steps:**
1. QR codes placed at checkout counters and product displays
2. Customer scans QR → opens WhatsApp conversation with store
3. **Bot Flow** greets customer and collects:
 - Name and phone number
 - Preferred product categories
 - Loyalty program opt-in
4. **Contact** auto-created with tags: "in-store", "walk-in", store location
5. **Automation** triggers welcome sequence:
 - Welcome message with store benefits
 - Digital loyalty card link
 - Current promotions
6. **Deal** created in "Customer Acquisition" pipeline
7. Post-visit follow-up (next day):
 - "How was your shopping experience?" survey
 - Product recommendations based on stated interests
8. **AI Call Intelligence** used for phone inquiries:
 - Customer calls store → recorded and transcribed
 - Sentiment tracked per interaction
 - Action items auto-created for staff
9. Weekly **Campaign** sends personalized offers
10. **Analytics** tracks:
 - In-store to digital conversion rate
 - Repeat purchase rates
 - Customer lifetime value

**Expected Outcome:**

Seamless bridge between in-store and digital engagement, building a customer database with ongoing personalized communication.

**Business Value:**

- Captures 30-50% more customer data
- Automated post-visit engagement
- Loyalty program digitization
- Measurable ROI on in-store traffic
- Customer lifetime value increase

---

### UC-RETAIL-002: Product Return & Exchange Management

**Business Scenario:**

Retail business handles product returns and exchanges through WhatsApp, tracking each case from request to resolution.

**Steps:**
1. Customer messages store via WhatsApp: "I want to return an item"
2. **Bot Flow** initiates return process:
 - Collects order number or receipt photo
 - Asks return reason
 - Checks return policy eligibility
3. If eligible, bot provides return instructions
4. **Task** created for store staff: "Process return for {{contact.name}}"
5. Conversation assigned to returns specialist
6. Agent coordinates pickup or drop-off
7. **Deal** in "Returns" pipeline tracks status:
 - Return Requested → Item Received → Inspected → Refund/Exchange Processed
8. **Automation** sends status updates at each stage
9. **AI Call Intelligence** handles phone returns:
 - Customer calls to complain → sentiment analyzed
 - Negative sentiment triggers priority escalation
 - Action items created for resolution team
10. Resolution confirmed → satisfaction survey sent
11. **Analytics** tracks return rates, reasons, and resolution times

**Expected Outcome:**

Streamlined return/exchange process with full tracking, automated updates, and sentiment-aware escalation.

**Business Value:**

- Faster return processing
- Customer satisfaction during returns
- Return reason analytics for product improvement
- Reduced call center load
- AI-detected dissatisfaction triggers proactive recovery

---

### UC-RETAIL-003: Seasonal Sale Campaign with AI Call Follow-Up

**Business Scenario:**

A retail chain launches a seasonal sale and uses multi-channel campaigns with AI-powered call follow-up for high-value leads.

**Steps:**
1. **Campaign** created for "Summer Sale 2026"
2. Customer segments defined:
 - VIP customers (high spend)
 - Dormant customers (no purchase 90+ days)
 - New subscribers
3. Multi-channel campaign executed:
 - WhatsApp: Rich media with product images
 - SMS: Short promotional links
 - Email: Full catalog with HTML design
4. **Bot Flow** handles responses:
 - Product inquiries → agent handoff
 - "Not interested" → tagged for exclusion
5. High-value leads flagged for personal call:
 - Agent calls VIP customers
 - **Call recording** uploaded automatically
 - AI transcribes and analyzes each call
 - Action items created (e.g., "Send VIP pricing to Ahmed")
6. **Deals** created for interested leads
7. **Automation** sends abandoned cart reminders
8. Post-sale follow-up:
 - Delivery tracking updates
 - Review requests
 - Cross-sell recommendations
9. **Analytics** dashboard shows:
 - Campaign ROI
 - Channel performance comparison
 - Call conversion rates
 - Customer acquisition cost

**Expected Outcome:**

Integrated seasonal campaign with AI-enhanced personal outreach driving maximum conversion.

**Business Value:**

- 3-5x ROI on campaign spend
- Personal touch for VIP customers
- AI-powered call insights improve future campaigns
- Complete attribution tracking

---

### UC-RETAIL-004: Inventory Inquiry & Stock Notification

**Business Scenario:**

Customers inquire about product availability across multiple store locations.

**Steps:**
1. Customer asks via WhatsApp: "Do you have Nike Air Max in size 42?"
2. **Bot Flow** collects:
 - Product name/SKU
 - Preferred size/color
 - Preferred store location
3. Bot checks availability via **HTTP Action** to inventory API
4. If in stock → provides store location and directions
5. If out of stock:
 - Offers to notify when available
 - Suggests alternatives
 - Creates **Task** for procurement team
6. Customer opts for notification → **Automation** monitors stock
7. Stock arrives → automatic WhatsApp notification sent
8. Customer confirms interest → **Deal** created
9. **AI Call Intelligence** handles phone stock inquiries:
 - Common product requests extracted as keywords
 - Demand patterns identified from call analysis
10. **Analytics** tracks most requested products and stockout rates

**Expected Outcome:**

Instant stock checking with automated restock notifications and demand intelligence from calls.

**Business Value:**

- Reduced lost sales from stockouts
- Demand forecasting from call keywords
- Customer convenience
- Procurement optimization

---

### UC-RETAIL-005: Multi-Branch Staff Communication & Coordination

**Business Scenario:**

A retail chain with multiple branches needs centralized staff communication, shift management, and performance tracking.

**Steps:**
1. Each branch set up as **Team** with agents
2. **Attendance Tracking** for clock-in/clock-out per branch
3. **Internal AI Assistant** used for:
 - Staff policy questions
 - Procedure lookups
 - Training material access
4. **Tasks** assigned across branches for:
 - Visual merchandising updates
 - Price change implementations
 - Promotional setup
5. **Scheduling** for staff meetings and training sessions
6. **AI Call Intelligence** monitors customer service calls per branch:
 - Branch-level sentiment comparison
 - Agent performance ranking
 - Common complaint identification per location
7. **Projects** track store renovation/refit activities
8. **Analytics** compares branch performance

**Expected Outcome:**

Centralized multi-branch operations with AI-powered performance insights.

**Business Value:**

- Operational consistency across branches
- Performance benchmarking
- AI-driven staff coaching
- Reduced coordination overhead

---

## E-Commerce Industry Use Cases

### UC-ECOM-001: Order Tracking & Delivery Updates via WhatsApp

**Business Scenario:**

An e-commerce business wants to provide real-time order updates through WhatsApp, reducing "Where is my order?" support tickets.

**Steps:**
1. Customer places order on website
2. **Webhook** receives order event from e-commerce platform
3. **Contact** matched or created by phone/email
4. **Automation** sends order confirmation via WhatsApp template
5. Order status changes trigger automated updates:
 - Order confirmed → template message
 - Shipped → tracking link sent
 - Out for delivery → estimated time
 - Delivered → confirmation + review request
6. Customer replies with questions → routed to **Inbox**
7. **Bot Flow** handles common queries:
 - "Where is my order?" → pulls tracking info via HTTP
 - "Cancel order" → checks eligibility, routes to agent
 - "Change address" → collects new address, creates task
8. **AI Call Intelligence** for phone order inquiries:
 - Transcription captures order numbers mentioned
 - Auto-links call to contact and relevant deal
 - Action items for unresolved delivery issues
9. **Analytics** tracks:
 - WISMO (Where Is My Order) reduction rate
 - Bot resolution rate
 - Customer satisfaction post-delivery

**Expected Outcome:**

Proactive order communication reducing support tickets by 60-80%.

**Business Value:**

- Dramatic reduction in support inquiries
- Higher customer satisfaction
- Automated tracking without agent involvement
- AI insights from escalated calls

---

### UC-ECOM-002: Abandoned Cart Recovery Campaign

**Business Scenario:**

E-commerce business loses 70% of carts to abandonment. Automated recovery through WhatsApp and SMS with personalized follow-up.

**Steps:**
1. **Webhook** receives cart abandonment event
2. **Contact** identified by phone or email
3. **Automation** triggers recovery sequence:
 - 1 hour: WhatsApp message "You left items in your cart!"
 - 6 hours: SMS reminder with discount code
 - 24 hours: WhatsApp with social proof ("12 others bought this today")
 - 48 hours: Final offer with limited-time discount
4. Customer responds → conversation in **Inbox**
5. **Bot Flow** handles common objections:
 - "Too expensive" → offers payment plans
 - "Found it cheaper" → price match workflow
 - "Just browsing" → adds to nurture sequence
6. High-value carts ($500+) flagged for personal call:
 - Agent calls customer
 - **Call recorded and analyzed** by AI
 - Sentiment tracked (hesitation vs. objection)
 - Specific objections captured as keywords
7. **Deal** tracks cart recovery through pipeline
8. Recovered → order confirmation flow initiated
9. **Analytics** tracks recovery rate by channel and sequence step

**Expected Outcome:**

15-25% cart recovery rate with multi-channel automated sequences and AI-powered personal outreach for high-value carts.

**Business Value:**

- Recovers lost revenue automatically
- AI call analysis reveals common objections
- Optimized messaging from sentiment data
- Personalized high-value recovery

---

### UC-ECOM-003: Product Launch Campaign with Influencer Coordination

**Business Scenario:**

E-commerce business launching a new product line, coordinating with influencers and running a multi-channel launch campaign.

**Steps:**
1. **Project** created: "Summer Collection Launch"
2. **Tasks** for preparation:
 - Product photography
 - Description writing
 - Inventory preparation
 - Influencer outreach
3. Influencers managed as **Contacts** with tag "influencer"
4. **Companies** for influencer agencies
5. **Deals** track influencer partnerships:
 - Outreach → Negotiation → Agreement → Content Creation → Published
6. **Campaign** planned:
 - Pre-launch teaser (WhatsApp to VIP list)
 - Launch day blast (all channels)
 - Post-launch follow-up
7. **Bot Flow** handles product inquiries:
 - Size guide
 - Material details
 - Shipping estimates
8. **AI Call Intelligence** for launch day support calls:
 - High volume call transcription
 - Trending keywords identify common questions
 - Auto-tag calls as "product-launch" related
 - Sentiment monitoring for product reception
9. **Analytics** tracks launch metrics:
 - Channel attribution
 - Conversion rates
 - Revenue per channel

**Expected Outcome:**

Coordinated product launch with influencer management, multi-channel campaign, and real-time AI insights.

**Business Value:**

- Organized launch execution
- Influencer ROI tracking
- Real-time customer feedback from calls
- Channel performance optimization

---

### UC-ECOM-004: Customer Review & Feedback Collection

**Business Scenario:**

E-commerce business wants to systematically collect and analyze customer feedback across channels.

**Steps:**
1. **Automation** triggers post-delivery (3 days after):
 - WhatsApp: "How would you rate your purchase?"
 - Quick reply buttons: ⭐1-5
2. Positive reviews (4-5 stars):
 - Thank you message
 - Request to leave review on Google/website
 - Referral program invitation
3. Negative reviews (1-2 stars):
 - Apology message
 - Agent assigned immediately
 - **Task** created: "Resolve complaint for {{contact.name}}"
4. Agent calls dissatisfied customer:
 - **Call recorded and analyzed**
 - AI extracts specific issues
 - Resolution score tracked
 - Action items for product team
5. **Webhook** sends feedback data to analytics platform
6. **AI Call Intelligence** aggregates:
 - Most common product complaints
 - Sentiment trends over time
 - Resolution effectiveness
7. **Analytics** dashboard shows:
 - NPS score trends
 - Product-level satisfaction
 - Agent resolution performance

**Expected Outcome:**

Systematic feedback collection with AI-powered analysis of customer calls for product and service improvement.

**Business Value:**

- Higher review collection rates
- Proactive complaint resolution
- Product improvement insights from call data
- Customer retention improvement

---

### UC-ECOM-005: Supplier & Vendor Communication Management

**Business Scenario:**

E-commerce business manages relationships with multiple suppliers, tracking orders, negotiations, and quality issues.

**Steps:**
1. Each supplier created as **Company** with contacts
2. **Deals** track purchase orders:
 - RFQ Sent → Quote Received → Negotiation → PO Issued → Shipped → Received → QC Passed
3. Communication via **Inbox** (WhatsApp/Email)
4. **Bot Flow** for supplier self-service:
 - PO status inquiries
 - Invoice submission
 - Delivery schedule updates
5. Quality issues tracked as **Tasks**:
 - Defect reports with photos
 - Return requests
 - Credit note requests
6. Supplier calls managed via **Call Intelligence**:
 - Price negotiation calls recorded
 - Key terms and commitments extracted as action items
 - Sentiment analysis for relationship health
7. **Automation** sends:
 - Payment reminders
 - Reorder alerts when stock low
 - Quality report summaries
8. **Analytics** tracks:
 - Supplier performance scores
 - Lead time trends
 - Quality metrics

**Expected Outcome:**

Organized supplier management with AI-powered call insights for better negotiations and quality tracking.

**Business Value:**

- Better supplier relationships
- Negotiation intelligence from call analysis
- Quality management automation
- Procurement efficiency

---

## FinTech Industry Use Cases

### UC-FINTECH-001: KYC Onboarding & Document Collection via WhatsApp

**Business Scenario:**

A fintech company needs to collect KYC documents from customers during onboarding through a secure, conversational flow.

**Steps:**
1. Customer signs up on fintech app
2. **Webhook** triggers WhatsApp onboarding sequence
3. **Bot Flow** guides document collection:
 - Step 1: Welcome + explain requirements
 - Step 2: Request national ID (front/back)
 - Step 3: Request proof of address
 - Step 4: Request selfie with ID
 - Step 5: Confirmation of submission
4. Documents received as media messages → stored securely
5. **Contact** updated with KYC status tags
6. **Deal** in "KYC Pipeline":
 - Documents Submitted → Under Review → Approved/Rejected
7. **Automation** sends status updates:
 - "Documents received, under review"
 - "Additional document needed: [specific document]"
 - "KYC approved! Account activated"
8. **AI Call Intelligence** for support calls:
 - Customers calling about KYC status → transcribed
 - Common issues extracted (missing documents, blurry photos)
 - Action items for compliance team
 - Sentiment tracking for onboarding experience
9. **Task** auto-created for compliance officer review
10. **Analytics** tracks:
 - Onboarding completion rates
 - Average onboarding time
 - Drop-off points
 - Call volume for KYC issues

**Expected Outcome:**

Streamlined KYC collection via WhatsApp with AI-powered call support and complete audit trail.

**Business Value:**

- 50% faster onboarding
- Reduced compliance review time
- Better customer experience
- Call insights improve the process
- Complete audit trail

---

### UC-FINTECH-002: Loan Application Status Tracking

**Business Scenario:**

Fintech lender wants to provide real-time loan application status updates and handle inquiries across channels.

**Steps:**
1. Loan application submitted → **Webhook** creates **Deal** in "Loan Pipeline"
2. Pipeline stages:
 - Application Received → Document Verification → Credit Check → Underwriting → Approved/Declined → Disbursed
3. **Contact** tagged with loan product type
4. **Automation** sends updates at each stage change:
 - WhatsApp template: "Your loan application status has been updated to: {{stage}}"
5. **Bot Flow** handles inquiries:
 - "What's my application status?" → checks deal stage
 - "What documents do I need?" → lists requirements
 - "When will I get the money?" → estimated timeline
6. Complex queries routed to loan officer in **Inbox**
7. **AI Call Intelligence** for phone inquiries:
 - Applicants calling for status → transcribed
 - Urgency and frustration detected via sentiment
 - Common questions aggregated (keywords: "delay", "documents", "rejected")
 - Auto-tasks created for loan officers
8. Declined applications:
 - Empathetic message with reasons
 - Alternative products suggested
 - Callback option offered
9. **Scheduling** for callback appointments with loan officers
10. **Analytics** tracks:
 - Application-to-approval conversion
 - Average processing time
 - Call volume per pipeline stage
 - Sentiment correlation with conversion

**Expected Outcome:**

Transparent loan processing with proactive updates and AI-powered phone support.

**Business Value:**

- Reduced "status inquiry" calls by 70%
- Better applicant experience
- Sentiment-driven process improvements
- Faster loan processing

---

### UC-FINTECH-003: Payment Failure & Collection Management

**Business Scenario:**

Fintech company handles payment failures and collections through automated multi-channel outreach with AI call analytics.

**Steps:**
1. **Webhook** receives payment failure event
2. **Contact** identified and tagged "payment-overdue"
3. **Automation** triggers collection sequence:
 - Day 0: WhatsApp "Payment failed, please update payment method"
 - Day 3: SMS reminder with payment link
 - Day 7: Email with account details
 - Day 14: WhatsApp "Important: Account at risk"
4. Customer responds → conversation in **Inbox**
5. **Bot Flow** handles payment-related queries:
 - "How do I pay?" → payment link
 - "I can't pay right now" → routes to agent for payment plan
 - "I already paid" → agent verification
6. High-risk accounts flagged for personal call:
 - Agent calls customer
 - **Call recorded and AI-analyzed**
 - Sentiment tracks customer financial stress
 - Payment commitments captured as action items
 - Classification: "payment plan request", "dispute", "hardship"
7. **Deal** in "Collections Pipeline":
 - Overdue → Contacted → Payment Plan → Partial Payment → Resolved
8. **Task** tracks follow-ups for each commitment
9. **Analytics** tracks:
 - Collection rate by channel
 - Payment plan adherence
 - Agent effectiveness
 - Sentiment trends in collection calls

**Expected Outcome:**

Automated collection with empathetic AI-powered call handling and multi-channel outreach.

**Business Value:**

- Higher collection rates
- Reduced delinquency
- Empathetic approach (sentiment-aware)
- Regulatory compliance (recorded calls)
- Payment plan tracking

---

### UC-FINTECH-004: Investment Advisory & Portfolio Updates

**Business Scenario:**

A wealth-tech platform provides portfolio updates and investment advice through WhatsApp with AI-enhanced advisory calls.

**Steps:**
1. **Webhook** receives market/portfolio events
2. **Automation** sends personalized alerts:
 - Portfolio performance summaries (daily/weekly)
 - Significant market movements
 - Investment opportunity alerts
3. Clients respond with questions → **Inbox**
4. **Bot Flow** handles FAQs:
 - "What's my balance?" → API lookup
 - "Show my returns" → generates summary
 - "I want to invest more" → routes to advisor
5. Advisory calls managed via **Call Intelligence**:
 - All advisory calls recorded (regulatory compliance)
 - AI transcribes investment discussions
 - Key decisions captured as action items
 - Risk tolerance inferred from sentiment
 - Keywords: specific fund names, amounts, concerns
6. **Deal** tracks investment decisions:
 - Interest → Consultation → Proposal → Commitment → Executed
7. **Scheduling** for client advisory meetings
8. **Analytics** tracks:
 - Client engagement rates
 - Advisory call effectiveness
 - Investment conversion rates
 - Client sentiment trends

**Expected Outcome:**

Proactive portfolio communication with AI-powered advisory call compliance and insights.

**Business Value:**

- Regulatory compliance (call recordings)
- Client engagement improvement
- Advisory quality monitoring
- Proactive client management

---

### UC-FINTECH-005: Fraud Alert & Account Security

**Business Scenario:**

Fintech detects suspicious activity and needs to alert customers instantly across channels while tracking resolution.

**Steps:**
1. Fraud detection system triggers **Webhook**
2. **Automation** sends immediate alerts:
 - WhatsApp: "⚠️ Suspicious activity detected on your account"
 - SMS: "Urgent: Verify recent transaction. Call us at [number]"
3. **Task** created: "Investigate fraud alert for {{contact.name}}"
4. Customer responds → priority conversation in **Inbox**
5. **Bot Flow** for initial triage:
 - "Yes, it was me" → unblock account
 - "No, I don't recognize it" → escalate to fraud team
6. Fraud team calls customer:
 - **Call recorded** for evidence
 - AI transcription for case documentation
 - Key details extracted (transaction amounts, dates, locations)
 - Sentiment analysis for customer distress
7. **Deal** in "Fraud Cases" pipeline:
 - Alert → Investigation → Customer Verified → Resolved/Escalated
8. Resolution:
 - Account secured → confirmation sent
 - Refund processed → status updates
9. **Analytics** tracks:
 - Fraud detection accuracy
 - Response time
 - Resolution time
 - Customer satisfaction post-fraud

**Expected Outcome:**

Instant fraud alerting with AI-documented investigation calls and complete case tracking.

**Business Value:**

- Rapid customer protection
- Complete investigation documentation
- Evidence from AI-transcribed calls
- Regulatory compliance
- Customer trust maintenance

---

## Banking Industry Use Cases

### UC-BANK-001: Account Opening Journey via WhatsApp

**Business Scenario:**

A bank offers account opening through WhatsApp, guiding customers through the process with minimal branch visits.

**Steps:**
1. Customer initiates via WhatsApp: "I want to open an account"
2. **Bot Flow** qualifies and guides:
 - Account type selection (savings, current, salary)
 - Eligibility check (nationality, age, employment)
 - Document requirements explained
 - Document upload (ID, proof of address, salary certificate)
3. **Contact** created with "account-opening" tag
4. **Deal** in "Account Opening" pipeline:
 - Inquiry → Documents Submitted → Verification → Approved → Account Active
5. **Task** for operations: "Verify documents for {{contact.name}}"
6. **Automation** sends updates:
 - "Documents received, verification in progress"
 - "Please visit branch for signature (appointment scheduled)"
 - "Account opened! Your details: IBAN [xxx]"
7. **Scheduling** for branch appointment
8. **AI Call Intelligence** for support:
 - Customers call with questions during process
 - Common blockers identified (missing documents, eligibility)
 - Action items for relationship managers
9. Post-opening engagement:
 - Welcome package sent via WhatsApp
 - Card activation instructions
 - Digital banking setup guide
10. **Analytics** tracks:
 - Application completion rates
 - Branch visit reduction
 - Time-to-activation

**Expected Outcome:**

Digital-first account opening with minimal branch visits, AI-supported phone assistance.

**Business Value:**

- Reduced branch footfall
- Faster account opening
- Better customer experience
- AI insights improve process bottlenecks

---

### UC-BANK-002: Credit Card Dispute Resolution

**Business Scenario:**

Bank handles credit card transaction disputes through multi-channel communication with AI-documented resolution process.

**Steps:**
1. Customer contacts bank: "I see a charge I don't recognize"
2. **Bot Flow** collects dispute details:
 - Card last 4 digits
 - Transaction amount and date
 - Merchant name (if visible)
 - Is card lost/stolen?
3. If card compromised → immediate block + new card issuance
4. **Task** created: "Investigate dispute for {{contact.name}}"
5. **Deal** in "Disputes" pipeline:
 - Filed → Under Investigation → Provisional Credit → Resolved
6. Investigation team calls customer:
 - **Call recorded** for compliance
 - AI transcribes detailed transaction discussion
 - Key evidence captured as action items
 - Classification: "unauthorized transaction", "merchant dispute", "billing error"
7. **Automation** sends updates at each stage
8. Provisional credit issued → notification sent
9. Final resolution:
 - Dispute upheld → permanent credit
 - Dispute denied → explanation sent with appeal options
10. **Analytics** tracks:
 - Dispute volume and types
 - Resolution times
 - Customer satisfaction
 - Fraud pattern detection from call keywords

**Expected Outcome:**

Streamlined dispute resolution with AI-documented investigation and compliance-ready call records.

**Business Value:**

- Regulatory compliance (documented calls)
- Faster resolution times
- Fraud pattern detection
- Customer satisfaction during disputes

---

### UC-BANK-003: Loan Restructuring & Hardship Programs

**Business Scenario:**

Bank offers loan restructuring for customers facing financial hardship, with empathetic AI-monitored communication.

**Steps:**
1. Customer contacts bank about payment difficulty
2. **Bot Flow** assesses situation:
 - Current loan details
 - Nature of hardship
 - Preferred resolution (lower payments, extension, etc.)
3. **Contact** tagged "hardship-request"
4. **Deal** in "Restructuring" pipeline
5. Relationship manager assigned via **Auto-Assignment**
6. Manager calls customer:
 - **Call recorded** (regulatory requirement)
 - AI monitors sentiment throughout conversation
 - Financial commitments captured as action items
 - Classification: "job loss", "medical", "business downturn"
7. Restructuring options presented:
 - Extended tenure
 - Reduced installments
 - Grace period
8. Customer agrees → documents sent via WhatsApp
9. **Automation** tracks new payment schedule
10. Monthly check-in calls:
 - Sentiment tracked over time
 - Recovery trajectory monitored
 - Additional support triggered if sentiment drops
11. **Analytics** tracks:
 - Restructuring success rates
 - Customer sentiment trajectory
 - Default prevention rate

**Expected Outcome:**

Empathetic hardship management with AI sentiment monitoring throughout the recovery journey.

**Business Value:**

- Default prevention
- Regulatory compliance
- Customer retention during hardship
- Sentiment-driven intervention
- Portfolio risk management

---

### UC-BANK-004: Branch Appointment & Queue Management

**Business Scenario:**

Bank reduces walk-in crowds by offering appointment scheduling via WhatsApp with intelligent routing.

**Steps:**
1. Customer messages: "I need to visit the branch"
2. **Bot Flow** qualifies purpose:
 - Account opening
 - Loan application
 - Document submission
 - Complaint resolution
3. **Scheduling** offers available time slots at nearest branch
4. Appointment confirmed via WhatsApp template
5. **Automation** sends reminders:
 - Day before: confirmation + required documents list
 - 2 hours before: "Your appointment is coming up"
6. **Task** created for branch staff: "Prepare for {{contact.name}} appointment"
7. No-show management:
 - If customer doesn't arrive → follow-up message
 - Rescheduling option offered
8. Post-visit:
 - Satisfaction survey sent
 - Follow-up tasks from visit
9. **AI Call Intelligence** for branch complaints:
 - Calls about branch experience analyzed
 - Common complaints per branch identified
 - Branch-level sentiment comparison
10. **Analytics** tracks:
 - Appointment booking rates
 - No-show rates
 - Branch load balancing
 - Customer satisfaction per branch

**Expected Outcome:**

Organized branch visits with reduced wait times and AI-powered service quality monitoring.

**Business Value:**

- Reduced branch congestion
- Better customer experience
- Staff preparation for appointments
- Branch performance insights

---

### UC-BANK-005: Wealth Management Client Communication

**Business Scenario:**

Private banking division manages high-net-worth client relationships with premium, personalized communication.

**Steps:**
1. HNW clients managed as **Contacts** with "premium" tag
2. Each client has **Company** record with financial profile
3. **Deal** tracks investment opportunities per client
4. Relationship manager communication:
 - Market updates via WhatsApp
 - Investment proposals sent
 - Portfolio reviews scheduled
5. **Scheduling** for quarterly portfolio reviews
6. All advisory calls via **AI Call Intelligence**:
 - Full compliance recording
 - Investment recommendations documented
 - Client risk appetite tracked via sentiment
 - Action items: "Client requested allocation to emerging markets"
 - Keywords track investment interests
7. **Automation** sends:
 - Monthly portfolio summaries
 - Regulatory disclosure reminders
 - Event invitations (exclusive banking events)
8. **Projects** track complex investment structures:
 - Multi-asset portfolios
 - Estate planning
 - Tax optimization
9. **Analytics** for wealth management:
 - Assets under management growth
 - Client engagement frequency
 - Advisory call quality scores
 - Revenue per relationship manager

**Expected Outcome:**

Premium client management with full compliance call recording and AI-powered advisory insights.

**Business Value:**

- Regulatory compliance (MiFID II, etc.)
- Superior client experience
- Advisory quality improvement
- AUM growth tracking
- Risk management

---

## Insurance Industry Use Cases

### UC-INSURANCE-001: Claims Processing & Communication

**Business Scenario:**

Insurance company handles claims from filing to settlement through WhatsApp with AI-analyzed phone assessments.

**Steps:**
1. Policyholder reports claim via WhatsApp: "I had a car accident"
2. **Bot Flow** collects initial details:
 - Policy number
 - Date and location of incident
 - Photos/videos of damage
 - Police report number (if applicable)
3. **Contact** updated, tagged "active-claim"
4. **Deal** in "Claims Pipeline":
 - Reported → Documentation → Assessment → Approval → Settlement → Closed
5. **Task** for claims adjuster: "Assess claim #{{deal.id}}"
6. Adjuster calls policyholder:
 - **Call recorded** for evidence
 - AI transcribes incident details
 - Key facts extracted as action items
 - Classification: "auto-accident", "property-damage", "health-claim"
7. **Automation** sends updates at each stage
8. Assessment complete → settlement offer via WhatsApp
9. Policyholder accepts/negotiates → tracked in deal
10. Settlement processed → confirmation sent
11. **Analytics** tracks:
 - Average claim processing time
 - Settlement amounts
 - Customer satisfaction
 - Fraud indicators from call sentiment

**Expected Outcome:**

Fast, transparent claims processing with AI-documented assessments and continuous customer communication.

**Business Value:**

- Faster claims processing
- Evidence documentation (call recordings)
- Fraud detection from sentiment/keywords
- Customer satisfaction during stressful events

---

### UC-INSURANCE-002: Policy Renewal & Upsell Campaign

**Business Scenario:**

Insurance company proactively manages policy renewals and identifies upsell opportunities through automated campaigns and personal calls.

**Steps:**
1. **Automation** identifies policies expiring in 30 days
2. Renewal campaign triggered:
 - Day 30: WhatsApp reminder with renewal benefits
 - Day 15: Email with policy comparison (current vs. upgraded)
 - Day 7: SMS "Your policy expires soon, renew now"
 - Day 1: Urgent WhatsApp "Last day to renew!"
3. **Bot Flow** handles responses:
 - "Renew same plan" → payment link
 - "What's new?" → plan comparison
 - "I want to cancel" → routes to retention agent
4. Retention calls for at-risk customers:
 - **Call recorded and analyzed**
 - Reasons for cancellation captured
 - Counter-offers documented as action items
 - Sentiment analysis tracks customer loyalty
5. Upsell opportunities:
 - Life insurance to auto insurance customers
 - Add-on riders suggested
 - Family bundle offers
6. **Deal** tracks renewal/upsell:
 - Reminder Sent → Engaged → Renewed/Upgraded/Churned
7. **Analytics** tracks:
 - Renewal rates
 - Upsell conversion
 - Churn reasons (from call keywords)
 - Campaign effectiveness

**Expected Outcome:**

Proactive renewal management with AI-powered retention insights from customer calls.

**Business Value:**

- Higher renewal rates
- Increased policy value (upsell)
- Churn prevention with AI insights
- Revenue optimization

---

## Automotive Industry Use Cases

### UC-AUTO-DEALER-001: Vehicle Inquiry to Test Drive to Sale

**Business Scenario:**

Car dealership manages the complete customer journey from initial inquiry to vehicle delivery.

**Steps:**
1. Customer inquires via WhatsApp: "Interested in Toyota Camry 2026"
2. **Bot Flow** qualifies:
 - New or pre-owned preference
 - Budget range
 - Trade-in vehicle details
 - Preferred color/features
3. **Contact** created with tags: "camry", "new-vehicle", budget range
4. **Deal** in "Vehicle Sales" pipeline:
 - Inquiry → Test Drive Scheduled → Visited → Negotiation → Contract → Delivered
5. **Scheduling** for test drive appointment
6. **Automation** sends pre-visit info:
 - Vehicle specs and photos
 - Financing options
 - Trade-in value estimate
7. Post-test drive:
 - Agent calls to follow up
 - **Call recorded** — AI captures preferences, objections
 - Action items: "Customer wants leather seats option pricing"
8. Negotiation tracked in deal with notes
9. Sale closed → delivery scheduling
10. Post-delivery:
 - Service reminders scheduled
 - Insurance renewal tracking
 - Referral program invitation
11. **AI Call Intelligence** aggregates:
 - Most requested vehicles
 - Common objections (price, features)
 - Negotiation patterns
 - Agent closing effectiveness

**Expected Outcome:**

Complete vehicle sales journey with AI-powered follow-up insights and objection analysis.

**Business Value:**

- Higher test drive conversion
- Objection pattern analysis
- Agent coaching from call data
- Customer lifecycle management

---

### UC-AUTO-DEALER-002: Service Center Appointment & Follow-Up

**Business Scenario:**

Dealership service center manages maintenance appointments, service updates, and post-service follow-up.

**Steps:**
1. Customer messages: "My car needs service"
2. **Bot Flow** collects:
 - Vehicle make/model/year
 - Service type (routine, repair, recall)
 - Preferred date/time
 - Description of issue
3. **Scheduling** for service appointment
4. **Automation** sends:
 - Confirmation with checklist
 - Morning-of reminder
 - Drop-off instructions
5. **Task** for service advisor: "Prepare bay for {{contact.name}}"
6. During service:
 - Status updates via WhatsApp ("Diagnosis complete")
 - Approval requests for additional work
 - Cost estimates sent for approval
7. Service advisor calls for complex repairs:
 - **Call recorded** — AI captures repair decisions
 - Customer approval documented
 - Action items for parts ordering
8. Service complete → pickup notification
9. Post-service:
 - Satisfaction survey
 - Next service reminder scheduled
10. **Analytics** tracks:
 - Service revenue per advisor
 - Customer satisfaction
 - Common repair types
 - Recall response rates

**Expected Outcome:**

Seamless service experience with transparent communication and AI-documented repair approvals.

**Business Value:**

- Service revenue optimization
- Customer retention
- Repair approval documentation
- Predictive maintenance insights

---

### UC-AUTO-DEALER-003: Used Car Trade-In Valuation & Negotiation

**Business Scenario:**

Car dealership manages trade-in inquiries from initial valuation through negotiation to deal closure, with AI-analyzed negotiation calls.

**Steps:**
1. Customer messages via WhatsApp: "I want to trade in my car"
2. **Bot Flow** collects vehicle details:
 - Make, model, year
 - Mileage
 - Condition (excellent/good/fair/poor)
 - Photos of exterior, interior, dashboard
3. **Contact** created with tag "trade-in"
4. **Deal** in "Trade-In Pipeline":
 - Inquiry → Preliminary Valuation → Inspection Scheduled → Inspected → Offer Made → Accepted/Declined
5. Bot provides preliminary estimate range via API lookup
6. **Scheduling** for in-person inspection appointment
7. **Automation** sends:
 - Appointment confirmation
 - Required documents list (registration, insurance, service history)
 - Directions to dealership
8. Inspection complete → valuation determined
9. Negotiation call:
 - **Call recorded** — AI captures counter-offers
 - Price expectations documented
 - Customer sentiment tracked (satisfied vs. frustrated)
 - Action items: "Customer wants +5K — check manager approval"
 - Keywords: competitor offers, market prices mentioned
10. If accepted:
 - Trade-in credited toward new vehicle
 - **Deal** linked to new vehicle sale deal
 - Paperwork initiated via WhatsApp document sharing
11. If declined:
 - Follow-up offer scheduled
 - Market updates sent periodically
 - Re-engagement when prices change
12. **Analytics** tracks:
 - Trade-in conversion rates
 - Average negotiation gap (offer vs. ask)
 - Most traded vehicle models
 - Negotiation success patterns from AI call data

**Expected Outcome:**

Streamlined trade-in process with AI-powered negotiation insights and automated follow-up for declined offers.

**Business Value:**

- Higher trade-in conversion
- Negotiation pattern optimization
- Competitive pricing intelligence from call keywords
- Customer re-engagement automation
- Inventory acquisition insights

---

### UC-AUTO-DEALER-004: Vehicle Financing & Loan Application Support

**Business Scenario:**

Dealership helps customers apply for vehicle financing, guiding them through the process and managing bank communications.

**Steps:**
1. Customer interested in financing → **Bot Flow** pre-qualifies:
 - Employment status
 - Monthly income range
 - Down payment available
 - Credit history (self-reported)
2. **Deal** in "Financing Pipeline":
 - Pre-Qualification → Application → Bank Submission → Approved/Declined → Disbursed
3. Required documents collected via WhatsApp:
 - Salary certificates
 - Bank statements
 - ID documents
4. **Task** for finance manager: "Submit finance application for {{contact.name}}"
5. Finance manager calls customer to discuss options:
 - **Call recorded** — AI captures:
 - Preferred monthly payment
 - Loan term preferences
 - Questions about insurance bundling
 - Concerns about interest rates
 - Action items: "Send comparison of 3 bank offers"
6. Bank responses managed:
 - **Automation** updates customer on approval status
 - Multiple bank offers compared
 - Best offer recommended
7. Approval received → **Automation** sends:
 - Congratulations message
 - Contract signing appointment
 - Insurance options
8. **Analytics** tracks:
 - Financing approval rates by bank
 - Average loan amounts
 - Processing times
 - Agent performance on finance deals

**Expected Outcome:**

End-to-end financing support with AI-documented customer preferences and automated multi-bank application tracking.

**Business Value:**

- Higher financing conversion
- Better bank offer matching
- Customer preference insights from calls
- Faster processing time
- Finance department efficiency

---

### UC-AUTO-DEALER-005: New Vehicle Launch & Pre-Order Campaign

**Business Scenario:**

Dealership launches a new vehicle model with a pre-order campaign, managing interest from inquiry to delivery.

**Steps:**
1. **Campaign** created: "2026 Model X Launch"
2. Target segments:
 - Existing owners of previous model
 - Customers who inquired about competitors
 - VIP loyalty members
3. Multi-channel launch:
 - WhatsApp: Teaser images + video
 - SMS: Launch event invitation
 - Email: Full specs and pricing
4. **Bot Flow** handles responses:
 - "Tell me more" → detailed specs sent
 - "Price?" → pricing packages shared
 - "Pre-order" → reservation process started
5. Pre-order **Deal** pipeline:
 - Interest → Reserved (deposit) → Configured → Allocated → Delivery Scheduled → Delivered
6. Configuration calls for custom orders:
 - **Call recorded** — AI captures:
 - Color, trim, options selected
 - Accessory requests
 - Expected delivery timeline discussed
 - Action items: "Confirm metallic blue with premium package availability"
7. **Task** for each pre-order milestone
8. **Automation** sends updates:
 - Factory status updates
 - Delivery date confirmation
 - Pre-delivery inspection photos
9. Launch event:
 - **Scheduling** for VIP preview events
 - Attendee management
 - Post-event follow-up
10. **Analytics** tracks:
 - Pre-order conversion funnel
 - Most popular configurations
 - Campaign channel effectiveness
 - Revenue pipeline from launch

**Expected Outcome:**

Organized vehicle launch with pre-order management, AI-documented customer preferences, and automated delivery tracking.

**Business Value:**

- Maximized launch revenue
- Customer preference data for inventory planning
- VIP engagement and loyalty
- Configuration accuracy from AI call documentation
- Demand forecasting

---

### UC-AUTO-DEALER-006: Insurance Renewal & Cross-Sell Management

**Business Scenario:**

Dealership tracks customer vehicle insurance renewals and cross-sells dealership insurance products and extended warranties.

**Steps:**
1. **Contacts** enriched with vehicle purchase date and insurance expiry
2. **Automation** triggers 45 days before insurance expiry:
 - WhatsApp: "Your vehicle insurance expires on {{date}}. We have competitive renewal options!"
 - Comparison with dealership insurance offer
3. **Bot Flow** handles responses:
 - "Send me a quote" → collects current coverage details
 - "I already renewed" → updates record, exits sequence
 - "Call me" → schedules callback
4. Insurance advisor calls interested customers:
 - **Call recorded** — AI captures:
 - Current coverage and premium
 - Coverage gaps identified
 - Customer concerns (price, coverage, claims history)
 - Action items: "Send comprehensive quote with roadside assistance add-on"
5. **Deal** in "Insurance Pipeline":
 - Reminder Sent → Quote Requested → Quote Sent → Negotiation → Closed Won/Lost
6. Cross-sell extended warranty:
 - Vehicles approaching warranty expiry identified
 - Extended warranty options sent via WhatsApp
 - Benefits explained through bot
7. **Analytics** tracks:
 - Insurance renewal capture rate
 - Revenue from insurance commissions
 - Extended warranty attach rate
 - Most effective selling points from call keywords

**Expected Outcome:**

Proactive insurance and warranty management with AI-powered sales insights from advisory calls.

**Business Value:**

- Recurring revenue from insurance
- Customer retention through service
- Cross-sell revenue growth
- Competitive intelligence from call data
- Reduced customer churn to external insurers

---

### UC-AUTO-DEALER-007: Customer Recall & Safety Notice Management

**Business Scenario:**

Manufacturer issues a vehicle recall. Dealership must contact all affected customers urgently and manage the repair process.

**Steps:**
1. Recall notice received → affected vehicle list identified
2. **Campaign** sends urgent notifications:
 - WhatsApp: "Important safety recall for your {{vehicle_model}}"
 - SMS: "Urgent: Your vehicle requires a safety update. Contact us."
 - Email: Detailed recall information with FAQ
3. **Bot Flow** handles responses:
 - "Schedule repair" → **Scheduling** for service appointment
 - "What's the issue?" → explanation + FAQ
 - "Is it safe to drive?" → safety guidance
4. Customers who don't respond:
 - Follow-up calls by service team
 - **Call recorded** — AI tracks:
 - Customer awareness of issue
 - Concerns about safety
 - Scheduling preferences
 - Action items: "Customer traveling, schedule for next week"
5. **Task** for each affected vehicle: "Recall repair for VIN {{vin}}"
6. **Deal** in "Recall Pipeline":
 - Notified → Scheduled → In Service → Completed → Verified
7. **Automation** sends:
 - Appointment reminders
 - Repair completion confirmation
 - Post-repair quality check follow-up
8. **Analytics** tracks:
 - Customer notification reach rate
 - Response rate by channel
 - Repair completion percentage
 - Outstanding recalls

**Expected Outcome:**

100% customer reach for safety recalls with complete tracking and AI-documented follow-up calls.

**Business Value:**

- Regulatory compliance
- Customer safety
- Brand reputation protection
- Complete audit trail
- Efficient recall management

---

### UC-AUTO-DEALER-008: Post-Sale Customer Lifecycle Management

**Business Scenario:**

Dealership manages the complete post-sale relationship from delivery through years of ownership with automated touchpoints and AI-enhanced service.

**Steps:**
1. Vehicle delivered → **Automation** triggers lifecycle sequence:
 - Day 1: Welcome + delivery satisfaction survey
 - Week 1: "How's your new car?" check-in
 - Month 1: Service reminder setup
 - Month 3: Accessories recommendation
2. Periodic service reminders:
 - 5,000 km service → WhatsApp reminder
 - 10,000 km service → email with booking link
 - Annual inspection → SMS + WhatsApp
3. **Scheduling** for all service appointments
4. Between services:
 - Driving tips and car care content
 - Seasonal maintenance reminders (winter tires, AC check)
 - Loyalty reward points updates
5. Customer calls with any issue:
 - **Call recorded** — AI builds ownership experience profile
 - Satisfaction tracked over vehicle lifetime
 - Common issues per model identified
 - Keywords reveal product improvement opportunities
6. Year 3-4: Trade-in/upgrade outreach:
 - New model announcements personalized
 - Trade-in valuation offers
 - Financing pre-approval
7. **Analytics** tracks:
 - Customer lifetime value
 - Service revenue per customer
 - Retention rate
 - Trade-in cycle timing
 - NPS score over ownership period

**Expected Outcome:**

Automated multi-year customer relationship with AI-powered sentiment tracking throughout the ownership journey.

**Business Value:**

- Maximized customer lifetime value
- Service revenue capture
- Trade-in/upgrade conversion
- Brand loyalty building
- Product quality insights from call data

---

## Restaurants & Food Service Industry Use Cases

### UC-RESTAURANT-001: Reservation & Event Booking Management

**Business Scenario:**

Restaurant chain manages reservations, private events, and catering inquiries through WhatsApp with AI-powered phone booking support.

**Steps:**
1. Customer messages: "I'd like to reserve a table"
2. **Bot Flow** collects:
 - Date and time
 - Party size
 - Occasion (birthday, business, casual)
 - Seating preference (indoor/outdoor/private)
 - Dietary requirements
3. **Scheduling** checks availability and confirms
4. **Automation** sends:
 - Confirmation with menu preview
 - Day-before reminder
 - Special occasion prep (birthday cake, decorations)
5. For large events/catering:
 - **Deal** in "Events Pipeline"
 - Event coordinator assigned
 - Custom menu proposed via WhatsApp
6. Coordinator calls for planning:
 - **Call recorded** — AI captures menu selections
 - Budget and requirements documented
 - Action items for kitchen and setup teams
7. Post-dining:
 - Thank you message
 - Review request
 - Special offer for next visit
8. **Analytics** tracks:
 - Reservation volume and no-shows
 - Event revenue
 - Customer satisfaction
 - Peak hour optimization

**Expected Outcome:**

Automated reservation management with AI-documented event planning calls.

**Business Value:**

- Reduced no-shows
- Event revenue growth
- Customer loyalty
- Operational efficiency

---

### UC-RESTAURANT-002: Customer Complaint & Recovery

**Business Scenario:**

Restaurant handles customer complaints from food quality to service issues with AI-powered call analysis for quality improvement.

**Steps:**
1. Customer sends complaint via WhatsApp with photos
2. **Bot Flow** categorizes:
 - Food quality
 - Service issue
 - Billing error
 - Hygiene concern
3. Priority routing based on severity
4. Manager reviews and responds in **Inbox**
5. For serious complaints → manager calls:
 - **Call recorded and analyzed**
 - Specific issues documented
 - Customer emotion tracked (angry → satisfied)
 - Recovery action items created
6. Recovery offer sent (discount, complimentary meal)
7. Follow-up after next visit
8. **AI Call Intelligence** aggregates:
 - Complaint categories trending
 - Kitchen/service issues by location
 - Recovery effectiveness (sentiment before vs. after)
9. **Analytics** for quality management:
 - Complaint rates per location
 - Resolution times
 - Repeat complaint rates
 - Staff performance

**Expected Outcome:**

Rapid complaint resolution with AI insights driving continuous quality improvement.

**Business Value:**

- Customer recovery and retention
- Quality improvement from AI insights
- Location-level benchmarking
- Staff training priorities

---

## Logistics & Shipping Industry Use Cases

### UC-LOGISTICS-001: Shipment Tracking & Exception Management

**Business Scenario:**

Logistics company provides real-time shipment tracking with automated exception handling and AI-powered phone support.

**Steps:**
1. **Webhook** receives shipment events from TMS
2. **Automation** sends tracking updates via WhatsApp:
 - Picked up → In transit → Out for delivery → Delivered
3. Exception events trigger alerts:
 - Delay notification with new ETA
 - Address issue → customer contacted for correction
 - Delivery attempt failed → reschedule options
4. Customer inquires about shipment → **Bot Flow**:
 - "Track my shipment" → real-time status
 - "Reschedule delivery" → date selection
 - "File damage claim" → routes to agent
5. Damage claims via **Deal** pipeline:
 - Reported → Photos Received → Assessed → Approved → Refund
6. Customer calls about critical shipments:
 - **Call recorded** — AI captures urgency
 - Specific shipment issues documented
 - Action items for operations team
 - High-value shipment calls flagged
7. **Analytics** tracks:
 - Delivery success rates
 - Exception types and frequency
 - Customer satisfaction scores
 - Call volume correlation with exceptions

**Expected Outcome:**

Proactive shipment communication with AI-powered exception handling for critical situations.

**Business Value:**

- Reduced "where's my shipment" calls
- Faster exception resolution
- Customer satisfaction improvement
- Operational insights from call data

---

### UC-LOGISTICS-002: B2B Client Account Management

**Business Scenario:**

Logistics company manages enterprise shipping accounts with dedicated support and AI-monitored service quality.

**Steps:**
1. Enterprise clients as **Companies** with multiple contacts
2. **Deals** track shipping contracts and renewals
3. **Projects** for onboarding new enterprise accounts
4. Dedicated account manager assigned
5. Regular service review calls:
 - **Call recorded** — AI tracks service commitments
 - SLA discussions documented
 - Volume forecasts captured
 - Action items for operations
6. **Automation** sends:
 - Weekly shipping summaries
 - Monthly performance reports
 - Rate change notifications
7. **Bot Flow** for client self-service:
 - Bulk shipment booking
 - Invoice inquiries
 - Rate quotes
8. **Analytics** tracks:
 - Revenue per client
 - SLA compliance
 - Client satisfaction trends
 - Volume forecasts

**Expected Outcome:**

Enterprise-grade account management with AI-documented service commitments.

**Business Value:**

- Client retention
- Revenue growth per account
- SLA compliance tracking
- Proactive service improvements

---

## Telecommunications Industry Use Cases

### UC-TELECOM-001: Plan Upgrade & Retention Campaign

**Business Scenario:**

Telecom operator identifies customers with expiring contracts or high data usage for upgrade campaigns with AI-powered retention calls.

**Steps:**
1. **Webhook** identifies eligible customers:
 - Contract ending in 30 days
 - High data usage (>80% of plan)
 - Recent complaint history
2. Segmented **Campaign**:
 - Low-risk: Automated WhatsApp upgrade offers
 - Medium-risk: SMS + WhatsApp sequence
 - High-risk: Personal call by retention agent
3. **Bot Flow** handles upgrade inquiries:
 - Plan comparison
 - Device bundle options
 - Special offer details
4. Retention calls for high-risk customers:
 - **Call recorded and analyzed**
 - Churn reasons captured (price, coverage, service)
 - Counter-offers documented
 - Sentiment tracks customer likelihood to stay
 - Keywords: "competitor", "cheaper", "switching"
5. **Deal** in "Retention Pipeline":
 - At-Risk → Contacted → Offer Made → Accepted/Churned
6. **Automation** tracks contract renewal
7. **Analytics**:
 - Churn rate by segment
 - Save rate from retention calls
 - Most effective counter-offers
 - Competitor mentions in calls

**Expected Outcome:**

Data-driven retention with AI-analyzed churn reasons from customer calls.

**Business Value:**

- Reduced churn rate
- ARPU increase via upgrades
- Competitive intelligence from calls
- Retention strategy optimization

---

### UC-TELECOM-002: Technical Support & Network Issue Resolution

**Business Scenario:**

Telecom handles technical support for connectivity and service issues with AI-triaged phone support.

**Steps:**
1. Customer messages: "My internet is not working"
2. **Bot Flow** troubleshoots:
 - Identifies service type (mobile, broadband, TV)
 - Guided troubleshooting (restart router, check connections)
 - Automated diagnostics via API
 - If unresolved → escalate to agent
3. Agent assists in **Inbox**
4. Complex issues → phone support:
 - **Call recorded** — AI captures technical details
 - Issue classification: "connectivity", "speed", "intermittent"
 - Affected area/equipment documented
 - Resolution steps tracked
5. **Task** for field technician if needed
6. **Scheduling** for technician visit
7. **Automation** sends:
 - Ticket status updates
 - Technician ETA
 - Post-resolution survey
8. **AI Call Intelligence** aggregates:
 - Common technical issues by area
 - Equipment failure patterns
 - Resolution time by issue type
 - Customer frustration hotspots
9. **Analytics** for network operations:
 - Ticket volume trends
 - First-call resolution rate
 - Repeat issue rates
 - Area-based issue heatmap

**Expected Outcome:**

Multi-tier technical support with AI-powered issue pattern detection from call data.

**Business Value:**

- Higher first-contact resolution
- Network issue pattern detection
- Reduced repeat calls
- Proactive maintenance triggers

---

## Government & Public Sector Use Cases

### UC-GOV-001: Citizen Service Request Management

**Business Scenario:**

Government agency manages citizen service requests (permits, licenses, complaints) through WhatsApp with AI-documented phone interactions.

**Steps:**
1. Citizen contacts agency via WhatsApp
2. **Bot Flow** categorizes request:
 - New permit/license application
 - Existing application status
 - Complaint or feedback
 - General inquiry
3. Application process guided conversationally:
 - Required documents listed
 - Document upload via WhatsApp
 - Application form fields collected
4. **Deal** in "Applications Pipeline":
 - Submitted → Under Review → Additional Info Required → Approved/Rejected → Issued
5. **Task** for department staff
6. Citizen calls for status:
 - **Call recorded** for audit trail
 - AI transcribes request details
 - Department and service type classified
 - Action items for processing team
7. **Automation** sends:
 - Acknowledgment receipt
 - Status updates
 - Collection notification
8. **Analytics** tracks:
 - Service delivery times
 - Department workload
 - Citizen satisfaction
 - Common request types from calls

**Expected Outcome:**

Digital-first citizen services with full audit trail and AI-documented phone interactions.

**Business Value:**

- Reduced wait times
- 24/7 service availability
- Complete audit trail
- Data-driven service improvement
- Citizen satisfaction improvement

---

### UC-GOV-002: Emergency Communication & Coordination

**Business Scenario:**

Government agency needs to send mass notifications during emergencies and coordinate response teams.

**Steps:**
1. Emergency event triggered
2. **Campaign** sends mass notifications:
 - WhatsApp: Area-specific alerts
 - SMS: Critical information
 - Web Push: Immediate notification
3. **Bot Flow** handles citizen inquiries:
 - Evacuation routes
 - Shelter locations
 - Emergency contact numbers
4. Response team coordination:
 - **Tasks** assigned to field teams
 - **Projects** track response operations
 - Team communication via **Internal AI Assistant**
5. Citizen calls during emergency:
 - **Call recorded** for incident documentation
 - Location and situation captured
 - Priority assessment via sentiment (panic vs. information seeking)
 - Resource requests documented as action items
6. Post-emergency:
 - Recovery information sent
 - Damage assessment surveys
 - Aid application guidance
7. **Analytics** for emergency management:
 - Response time metrics
 - Citizen reach rate
 - Resource deployment effectiveness
 - Call volume patterns

**Expected Outcome:**

Rapid mass communication with AI-documented emergency response interactions.

**Business Value:**

- Life-saving communication speed
- Coordinated response
- Complete incident documentation
- Response effectiveness analysis

---

## Legal Services Industry Use Cases

### UC-LEGAL-001: Client Intake & Case Management

**Business Scenario:**

Law firm manages client intake, case progress communication, and appointment scheduling through WhatsApp with AI-documented consultations.

**Steps:**
1. Potential client inquires via WhatsApp
2. **Bot Flow** for initial intake:
 - Case type (family, corporate, criminal, civil)
 - Brief description of matter
 - Urgency level
 - Contact information
3. **Contact** created with case type tags
4. **Deal** in "Case Pipeline":
 - Inquiry → Consultation → Engaged → Discovery → Trial/Settlement → Closed
5. **Scheduling** for initial consultation
6. Consultation call:
 - **Call recorded** (client consent obtained)
 - AI transcribes case details
 - Key facts extracted as action items
 - Privileged information secured
7. **Tasks** for legal team:
 - Document requests
 - Research assignments
 - Court date preparations
8. **Automation** sends client updates:
 - Case status changes
 - Court date reminders
 - Document request notifications
9. **Projects** for complex cases:
 - Multi-phase litigation tracking
 - Team collaboration
 - Deadline management
10. **Analytics** tracks:
 - Case conversion rates
 - Revenue per case type
 - Client satisfaction
 - Attorney workload

**Expected Outcome:**

Organized case management with AI-documented client consultations and automated status updates.

**Business Value:**

- Efficient client intake
- Documented consultations
- Better client communication
- Workload management
- Revenue tracking per practice area

---

## Fitness & Wellness Industry Use Cases

### UC-FITNESS-001: Membership & Class Booking Management

**Business Scenario:**

Gym/wellness center manages memberships, class bookings, and personal training through WhatsApp with AI-analyzed phone consultations.

**Steps:**
1. Prospect inquires via WhatsApp: "What memberships do you offer?"
2. **Bot Flow** presents options:
 - Membership tiers with pricing
 - Class schedules
 - Personal training packages
 - Trial offer
3. **Deal** in "Membership Sales" pipeline
4. **Scheduling** for:
 - Free trial session
 - Facility tour
 - Fitness assessment
5. Sales call for premium packages:
 - **Call recorded** — AI captures fitness goals
 - Budget and commitment level assessed
 - Action items: "Send custom training plan"
6. Membership activated → **Automation** triggers:
 - Welcome series
 - App download link
 - First week schedule
7. Ongoing engagement:
 - Class reminders via WhatsApp
 - Progress check-ins
 - Nutrition tips
8. Renewal management:
 - 30-day reminder sequence
 - Retention calls for at-risk members
 - AI tracks reasons for cancellation
9. **Analytics** tracks:
 - Membership growth
 - Class attendance rates
 - Retention rates
 - Revenue per member

**Expected Outcome:**

Complete membership lifecycle management with AI-powered retention insights.

**Business Value:**

- Higher conversion from inquiries
- Improved retention
- Cancellation reason analysis
- Revenue optimization

---

## Expanded Tourism & Hospitality Use Cases (AI-Enhanced)

### UC-TOURISM-005: AI-Powered Concierge Service

**Business Scenario:**

Luxury hotel provides 24/7 AI-powered concierge services via WhatsApp with human escalation and call intelligence for premium guests.

**Steps:**
1. Guest checks in → WhatsApp welcome message with concierge number
2. **Bot Flow** handles common requests:
 - Restaurant reservations
 - Spa bookings
 - Room service ordering
 - Local attraction information
 - Transportation arrangements
3. Complex requests → human concierge in **Inbox**
4. Premium guest calls front desk:
 - **Call recorded** — AI captures preferences
 - Room preferences, dietary requirements documented
 - Special occasion details noted as action items
 - Guest sentiment tracked throughout stay
5. **AI Support Bot** with hotel knowledge base:
 - WiFi instructions
 - Checkout procedures
 - Policy queries
6. Pre-checkout:
 - Satisfaction survey via WhatsApp
 - Folio review
 - Airport transfer confirmation
7. Post-checkout:
 - Thank you message
 - Review request
 - Loyalty program update
 - Future stay offer
8. **Analytics**:
 - Guest satisfaction trends
 - Most requested services
 - Revenue per guest
 - Concierge response times

**Expected Outcome:**

Premium concierge experience with AI-powered guest preference tracking from calls and messages.

**Business Value:**

- Elevated guest experience
- Guest preference memory
- Operational efficiency
- Revenue from upsell
- Loyalty and repeat bookings

---

### UC-TOURISM-006: Tour Operator Group Booking & Communication

**Business Scenario:**

Tour operator manages group bookings for corporate retreats and tour groups with multi-participant communication.

**Steps:**
1. Group leader inquires about corporate retreat
2. **Bot Flow** collects:
 - Group size and demographics
 - Dates and duration
 - Budget range
 - Activity preferences
 - Accommodation requirements
3. **Deal** in "Group Bookings" pipeline
4. Tour planner calls group leader:
 - **Call recorded** — AI captures all requirements
 - Itinerary preferences documented
 - Budget constraints and priorities noted
 - Action items: "Send 3 itinerary options"
5. Itinerary proposed via WhatsApp (with media)
6. Group leader confirms → participant list collected
7. **Campaign** to all participants:
 - Booking confirmation
 - Payment links (individual)
 - Packing list and pre-trip info
8. **Automation** sends trip updates:
 - Weather forecast
 - Meeting point details
 - Daily schedules
9. During trip → real-time WhatsApp support
10. Post-trip:
 - Group photo sharing
 - Review requests to each participant
 - Corporate feedback report
11. **Analytics**:
 - Group booking revenue
 - Participant satisfaction
 - Repeat booking rates

**Expected Outcome:**

Organized group travel management with AI-documented planning calls and multi-participant communication.

**Business Value:**

- Higher group booking value
- Participant satisfaction
- Repeat corporate business
- Efficient planning from AI call documentation

---

## AI Re-Engagement Use Cases

### UC-RE-001: Recover Abandoned Messenger Carts

**Business Scenario:**

An e-commerce store receives product inquiries via Messenger. Shoppers ask about items, receive options, then go silent. The store wants to nudge them back before Meta's 24-hour window closes.

**Steps:**
1. Admin navigates to **Settings → AI & Automation → [AI Re-Engagement](https://docs.connectgain.cloud/04-use-cases/02-user-guide/ai-reengagement.md)**
2. Starts 7-day free trial (or subscribes to the add-on)
3. Toggles **Enable**
4. Sets threshold to **20 hours**
5. Selects **Messenger** channel
6. Chooses **Friendly** tone
7. Saves settings
8. A customer messages about a navy linen dress
9. 20 hours later, AI generates personalised nudge:
 > Hi Sara — still thinking about the navy linen dress? I can hold your size for the next few hours if you'd like. Want me to send the checkout link?
10. Message sent automatically (or appears for agent approval if enabled)
11. Customer replies, window resets, conversation stays active

**Expected Outcome:**

15–25% of abandoned Messenger carts recovered through AI nudges sent within Meta's 24-hour window.

**Business Value:**

- Recovers lost revenue without manual follow-up
- Stays fully compliant with Meta messaging policy
- Zero additional ad spend

---

### UC-RE-002: Instagram Lead Qualification Follow-Up

**Business Scenario:**

A B2B company runs Instagram ads. Followers DM "info?" but many never reply after the first agent response. The company wants to rescue these leads.

**Steps:**
1. Enable AI Re-Engagement
2. Set threshold to **18 hours**
3. Select **Instagram** channel
4. Set tone to **Casual**
5. Turn on **Require agent approval** for high-value leads
6. Lead DM's "info?" on a sponsored post
7. Agent replies with pricing
8. Lead goes silent
9. 18 hours later, AI draft appears in inbox:
 > Hey Jamal 👋 just wanted to make sure you saw the pricing I sent. Happy to set up a quick call or share the demo link — whichever works?
10. Agent reviews and approves
11. Message sent before 24h window closes

**Expected Outcome:**

+30% qualified-lead conversion from Instagram DMs.

**Business Value:**

- Maximises Instagram ad ROI
- No leads fall through the cracks
- Agent-reviewed messaging maintains brand voice

---

### UC-RE-003: Real-Estate Viewing Rescue

**Business Scenario:**

A real estate agency receives listing inquiries via Messenger. Hot leads sometimes go quiet after the initial inquiry. Agents want to rescue these before the window closes.

**Steps:**
1. Enable AI Re-Engagement
2. Set threshold to **22 hours**
3. Select **Messenger**
4. Set tone to **Formal**
5. Conversation auto-tagged `hot_lead` via automation
6. Buyer asks about 3-bedroom in Sheikh Zayed, then silent
7. 22 hours later, AI sends:
 > Hi Ahmed — the 3-bedroom in Sheikh Zayed is still available, and there's a viewing slot tomorrow at 5pm. Want me to book it for you?
8. Buyer replies and books viewing

**Expected Outcome:**

+20% viewing bookings rescued from silent inquiries.

**Business Value:**

- Every inquiry gets a second chance
- Viewing bookings increased without extra agent hours
- Faster deal pipeline velocity

---

### UC-RE-004: Support Warm Reminder Before SLA Breach

**Business Scenario:**

A SaaS support team resolves tickets but customers sometimes don't confirm the fix. Tickets get reopened or CSAT drops. AI nudges close the loop.

**Steps:**
1. Enable AI Re-Engagement
2. Set threshold to **21 hours**
3. Tag conversation `awaiting_customer` via automation
4. Support sends reset link; customer silent
5. 21 hours later, AI nudge:
 > Hi Lina, just checking in — did the reset link I sent earlier solve the login issue? If not, I can hop on a quick call.
6. Customer confirms resolution
7. Ticket closed; CSAT survey sent

**Expected Outcome:**

Fewer reopened tickets, higher CSAT scores.

**Business Value:**

- Proactive resolution confirmation
- Reduced support workload from reopened tickets
- Improved customer satisfaction metrics

---

### UC-RE-005: Sequence Safety-Net on Meta Channels

**Business Scenario:**

A marketing team runs Messenger drip sequences. Some contacts stop responding mid-sequence. AI re-engagement recovers them without breaking Meta policy.

**Steps:**
1. Enable both **Sequences** and **AI Re-Engagement**
2. Set re-engagement threshold to **20 hours**
3. Enable **Messenger** channel
4. Contact mid-way through drip sequence stops responding
5. Sequence pauses; AI re-engagement triggers
6. AI sends contextual nudge:
 > Hey Omar — wanted to circle back on what we discussed. Any questions I can answer before our next step?
7. Customer replies; sequence resumes

**Expected Outcome:**

~12% of dropped sequences recovered.

**Business Value:**

- Maximises sequence ROI
- No policy violations (stays inside 24h window)
- Fully automated recovery layer

---

### UC-RE-006: BYOK Cost Control

**Business Scenario:**

A large agency wants to use AI re-engagement across 50+ conversations daily but wants to control AI costs by using their own Gemini key.

**Steps:**
1. Obtain Google AI Studio API key
2. Go to **Settings → AI → AI Provider**
3. Select **My Google Gemini key (BYOK)**
4. Paste key, select model, click **Test**
5. Set scope to **Re-engagement only**
6. Enable fallback to ConnectGain AI (optional)
7. Save
8. Key encrypted at rest; never displayed again
9. All re-engagement nudges use agency's own key
10. Zero ConnectGain AI token usage for re-engagement

**Expected Outcome:**

Full AI re-engagement functionality at no per-nudge cost from ConnectGain.

**Business Value:**

- Predictable AI costs for high-volume operations
- Full data control with own API key
- Fallback ensures zero downtime

---

## Social Media Planner Use Cases

### UC-SMP-001: Weekly Content Calendar Batch Scheduling

**Business Scenario:**

A marketing team spends 2 hours every Monday scheduling the week's social posts. They want a visual calendar to batch-schedule across Facebook, Instagram, and LinkedIn.

**Steps:**
1. Go to **[Social Media Planner](https://docs.connectgain.cloud/04-use-cases/02-user-guide/social-media-planner.md) → Calendar**
2. Click Monday slot → Create Instagram image post with product photo
3. Schedule for Monday 10:00 AM
4. Click Wednesday slot → Create Facebook video tutorial
5. Schedule for Wednesday 2:00 PM
6. Click Friday slot → Create LinkedIn thought-leadership post
7. Schedule for Friday 9:00 AM
8. Review full week in calendar view
9. All posts auto-publish at scheduled times

**Expected Outcome:**

Full week of social content planned in one session; zero manual publishing.

**Business Value:**

- 80% reduction in daily publishing time
- Consistent posting schedule
- Cross-platform coordination

---

### UC-SMP-002: Product Launch Coordination

**Business Scenario:**

Business launches new product and needs simultaneous posts across all platforms with consistent messaging.

**Steps:**
1. Create Instagram carousel post (product images + features)
2. Schedule for launch day 09:00
3. Create Facebook video post (demo reel)
4. Schedule for launch day 09:05
5. Create LinkedIn announcement (B2B angle)
6. Schedule for launch day 09:10
7. All posts use same campaign hashtag
8. Monitor real-time publish status
9. Analyse cross-platform engagement post-launch

**Expected Outcome:**

Synchronised multi-platform launch with unified brand message.

**Business Value:**

- Maximum launch impact
- No platform left behind
- Unified analytics for ROI measurement

---

### UC-SMP-003: Evergreen Content Recycling

**Business Scenario:**

Business has top-performing posts from 6 months ago and wants to re-share them with fresh context.

**Steps:**
1. Review Social Media Planner analytics
2. Identify top 5 posts by engagement rate
3. Duplicate each post
4. Update captions with new context
5. Set recurring schedule: monthly
6. Monitor recycled post performance
7. Adjust based on new engagement data

**Expected Outcome:**

Sustained engagement from proven content without constant creation.

**Business Value:**

- Content library ROI maximised
- Reduced creative burnout
- Consistent audience engagement

---

## Sequences Use Cases

### UC-SEQ-001: Welcome Email Drip Series

**Business Scenario:**

SaaS company wants to onboard new email subscribers with a 5-message welcome series over 7 days.

**Steps:**
1. Create sequence: "Welcome Series"
2. Set channel to **Email**
3. Add steps:
 - Step 1 (immediate): Welcome + product overview
 - Step 2 (1 day): Customer success stories
 - Step 3 (3 days): Tutorial invitation
 - Step 4 (5 days): Feature deep-dive
 - Step 5 (7 days): Exclusive upgrade offer
4. Set automation trigger: when contact tagged "Newsletter Subscriber", enroll in sequence
5. Activate sequence
6. New subscriber automatically receives timed emails
7. Track open rates and click-throughs in analytics

**Expected Outcome:**

Automated onboarding sequence improves activation rate by 25%.

**Business Value:**

- Scalable onboarding without manual sends
- Measurable engagement at each step
- Clear path to conversion

---

### UC-SEQ-002: WhatsApp Quote Follow-Up

**Business Scenario:**

B2B sales team sends proposals then manually follows up. They want automated WhatsApp follow-ups.

**Steps:**
1. Create sequence: "Quote Follow-Up"
2. Set channel to **WhatsApp Lite**
3. Add steps:
 - Step 1 (2 hours): "Hi {{first_name}}, just following up on your quote request."
 - Step 2 (2 days): "Hey {{first_name}}, any questions about the proposal?"
 - Step 3 (5 days): "Final reminder — your quote expires in 2 days."
4. Sales rep enrolls lead after quote sent
5. Lead responses appear in unified inbox
6. If lead replies, conversation continues naturally

**Expected Outcome:**

+20% quote response rate through automated follow-up.

**Business Value:**

- No quotes forgotten
- Faster sales cycles
- Agent time saved for closing

---

### UC-SEQ-003: Post-Purchase WhatsApp Updates

**Business Scenario:**

E-commerce store wants branded post-purchase communication on WhatsApp.

**Steps:**
1. Create sequence: "Post-Purchase"
2. Set channel to **[WhatsApp Cloud](https://docs.connectgain.cloud/04-use-cases/05-integrations/whatsapp-cloud-system-user.md)** (templates)
3. Select Meta-approved templates:
 - Step 1 (immediate): Order confirmation
 - Step 2 (1 day): Shipping update
 - Step 3 (3 days): Delivery confirmation
 - Step 4 (7 days): Feedback request
4. Automation trigger: when deal closed, enroll contact
5. All messages sent automatically via WhatsApp Cloud API

**Expected Outcome:**

Professional, branded post-purchase experience on WhatsApp.

**Business Value:**

- Improved customer experience
- Higher review submission rate
- Reduced "where is my order" support volume

---

## Conclusion

This comprehensive use cases document covers all major features of ConnectGain, providing detailed scenarios for:

- **Automation**: 10 use cases covering auto-assignment, task creation, auto-replies, and integrations
- **Webhooks**: 8 use cases covering CRM sync, notifications, and external integrations
- **Team Management**: 6 use cases covering onboarding, permissions, and availability
- **AI Features**: 6 use cases covering interest analysis, sentiment tracking, and AI-powered responses
- **Deal Workflow**: 8 use cases covering deal creation, pipeline management, and forecasting
- **Multi-Channel Inbox**: 8 use cases covering unified messaging, assignment, and quick replies
- **Task Management**: 7 use cases covering task creation, assignment, and tracking
- **Scheduling**: 8 use cases covering event types, bookings, and calendar integration
- **Campaigns & Broadcast**: 10 use cases covering SMS, WhatsApp, and email campaigns
- **AI Call Intelligence**: 10 use cases covering transcription, sentiment, action items, dashboards, webhooks, quotas
- **Call Center Automation**: 12 use cases covering inbound routing, outbound campaigns, quality monitoring, multi-language, CSAT, IVR deflection, escalation detection, compliance, workforce management, omnichannel handoff, PBX integration, mobile recording
- **AI Re-Engagement**: 6 use cases covering abandoned cart recovery, lead follow-up, real-estate rescue, support reminders, sequence safety-net, and BYOK cost control
- **Retail**: 5 use cases covering in-store engagement, returns, campaigns, inventory, multi-branch
- **E-Commerce**: 5 use cases covering order tracking, cart recovery, product launch, feedback, supplier management
- **FinTech**: 5 use cases covering KYC, loan tracking, collections, investment advisory, fraud alerts
- **Banking**: 5 use cases covering account opening, disputes, loan restructuring, branch management, wealth management
- **Insurance**: 2 use cases covering claims processing and policy renewal
- **Automotive / Car Dealers**: 8 use cases covering vehicle sales, service center, trade-in valuation, financing, new vehicle launch, insurance cross-sell, recall management, post-sale lifecycle
- **Restaurants & Food Service**: 2 use cases covering reservations and complaint management
- **Logistics & Shipping**: 2 use cases covering shipment tracking and B2B account management
- **Telecommunications**: 2 use cases covering plan upgrades and technical support
- **Government & Public Sector**: 2 use cases covering citizen services and emergency communication
- **Legal Services**: 1 use case covering client intake and case management
- **Fitness & Wellness**: 1 use case covering membership management
- **Tourism & Hospitality (Expanded)**: 2 additional use cases covering AI concierge and group bookings
- **Social Media Planner**: 3 use cases covering batch scheduling, product launch coordination, and content recycling
- **Sequences**: 3 use cases covering welcome drips, WhatsApp follow-up, and post-purchase updates

Each use case includes:
- Business scenario
- Detailed step-by-step process
- Expected outcome
- Business value
- **AI Call Intelligence integration** and **AI Re-Engagement** where applicable

This document serves as a comprehensive guide for users, administrators, and stakeholders to understand how ConnectGain can be used to solve real-world business challenges across **all major industries**.

---

**Document Version:** 2.3
**Last Updated:** June 2026
**Total Use Cases:** 164

## On the website

- [Use cases on connectgain.cloud](https://connectgain.cloud/en/use-cases) — feature overview on the ConnectGain website

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/04-use-cases/index.md)*

---

# AI Reply Assistant Use Cases – Sales Reply Suggestions

Source: https://docs.connectgain.cloud/04-use-cases/reply-assistant-use-cases/

# Reply Assistant — Use Cases

The Reply Assistant suggests 2–3 sales-style replies on demand when an agent is
in a conversation, grounded in the org's knowledge base + product catalog and
tuned to the org's **industry**. Each case below shows the industry, the
incoming customer message, and a sample suggested reply a junior agent could pick
and send.

> Setup is one step: choose your industry and it works. Generating/uploading a
> knowledge base makes the answers more specific.

---

## B2B SaaS

### 1. Price objection on a trial
**Customer:** "Looks good but $49/user is steep for a team of 12."

**Suggested reply (Consultative):**
> Totally fair to weigh it up, Omar. Most teams your size find it pays for itself
> by cutting ~5 hours/week of manual follow-up — that's the lens I'd use rather
> than the sticker price. Want me to set you up on a 14-day trial so you can
> measure the time saved with your own data before deciding?

**Why it works:** reframes price around ROI and pushes to a low-risk next step.

### 2. "We already use a competitor"
**Customer:** "We're already on Intercom, why switch?"

**Suggested reply (Differentiate):**
> Intercom's solid — I won't try to talk you out of it. Quick question: what's the
> one thing it *doesn't* do well for your team today? If it's omnichannel + the
> sales pipeline in one place, that's exactly where we shine, and we handle the
> migration for you. Happy to show a side-by-side on a 20-min call.

### 3. Security-conscious buyer
**Customer:** "Before we go further — how is our data handled?"

**Suggested reply (Reassure):**
> Great question to lead with. At a high level: org-isolated data, role-based
> access, and encrypted storage. I can share our security overview and connect you
> with someone who can answer specifics for your compliance team — want me to send
> that across?

---

## Ecommerce

### 4. Hesitant shopper
**Customer:** "Is the navy linen dress worth it for the price?"

**Suggested reply (Recommend):**
> It's one of our best-loved pieces, Sara — breathable linen that holds its shape,
> and it pairs perfectly with the tan belt a lot of customers add. We've only a few
> left in your size. Want me to drop the checkout link so you don't miss it?

**Why it works:** specific product, gentle upsell, honest urgency, easy next step.

### 5. Shipping worry blocking checkout
**Customer:** "Will it arrive before the weekend?"

**Suggested reply (Reassure):**
> If you order today it typically ships same-day and arrives in 2–3 business days,
> so you'd be cutting it close for the weekend — let me confirm the exact date for
> your area before you pay. Want me to check?

### 6. Returns reassurance
**Customer:** "What if it doesn't fit?"

**Suggested reply (De-risk):**
> No stress — returns are easy within our returns window, so you can try it at home
> and send it back if the fit isn't right. Most people keep theirs, but it's good to
> know you're covered. Shall I add it to your cart?

---

## Tourism & Travel

### 7. Selling the experience
**Customer:** "Tell me about the Cappadocia trip."

**Suggested reply (Experience-led):**
> Picture floating over the fairy chimneys at sunrise in a hot-air balloon — it's the
> moment everyone remembers. Our 4-night package includes the cave-hotel stay,
> airport transfers, and a guided valley tour. Are you thinking a couples' getaway or
> travelling with family? I'll match you to the right option.

### 8. Price reaction
**Customer:** "That's more than I expected."

**Suggested reply (Value framing):**
> I hear you — it's worth seeing what's inside that number: accommodation, all
> transfers, the guided tours, and breakfast daily, so there are no surprise costs on
> the ground. If it helps, I can show a shorter 3-night option or our payment plan.
> Which would you prefer?

### 9. Cancellation worry
**Customer:** "What if my plans change?"

**Suggested reply (Reassure):**
> Good to check before booking. You'd secure the dates with a deposit, and our
> cancellation window gives you flexibility if plans shift — I'll send the exact terms
> so it's clear. Want me to hold these dates while you decide? They're filling up for
> the season.

---

## How agents use it

1. Open the conversation, click **Suggest reply**.
2. Skim the 2–3 angles, click the best fit to load it into the composer.
3. Personalize a word or two, then send.

The more complete the knowledge base (generated, uploaded, or manual), the more
specific and accurate the suggestions — but the built-in best-practice pack means
it's useful from day one.

## See also

- [Inbox user guide](https://docs.connectgain.cloud/04-use-cases/02-user-guide/inbox.md)
- [Message templates](https://docs.connectgain.cloud/04-use-cases/02-user-guide/templates.md)
- [AI Re-Engagement — use cases](https://docs.connectgain.cloud/04-use-cases/reply-assistant-use-cases/ai-reengagement-use-cases.md)
- [BYOK — Bring Your Own Gemini Key](https://docs.connectgain.cloud/04-use-cases/05-integrations/ai-byok-gemini.md)
- [Marketing fact sheet](https://docs.connectgain.cloud/04-use-cases/reply-assistant-use-cases/marketing-fact-sheet.md)

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/04-use-cases/index.md)*

---

# Integrations – WhatsApp, Meta, Zoom & AI – ConnectGain

Source: https://docs.connectgain.cloud/05-integrations/

# Integrations

Connect ConnectGain to the rest of your stack.

## Messaging channels

- [Channels overview](https://docs.connectgain.cloud/05-integrations/channels.md) — all supported channels, configuration, status, statistics and troubleshooting.
- [Multi-channel messaging](https://docs.connectgain.cloud/05-integrations/multi-channel-messaging.md) — per-channel setup, features and best practices for the unified inbox.
- [WhatsApp Cloud — manual connection with a system user](https://docs.connectgain.cloud/05-integrations/whatsapp-cloud-system-user.md) — connect a WhatsApp Cloud number with a Meta System User token when it doesn't appear in the Facebook wizard.
- [WhatsApp Lite API guide](https://docs.connectgain.cloud/05-integrations/whatsapp-lite-api.md) — `whatsapp-lite-send` edge function reference plus direct Appgain API curl examples.
- [WhatsApp webhook troubleshooting](https://docs.connectgain.cloud/05-integrations/whatsapp-webhook-troubleshooting.md) — diagnose missing WhatsApp Cloud webhook events (marketing clicks, message status).

## Platforms

- [Appgain](https://docs.connectgain.cloud/05-integrations/appgain.md) — how Appgain API keys are provisioned, stored and used.

## AI

- [Bring Your Own Key — Gemini](https://docs.connectgain.cloud/05-integrations/ai-byok-gemini.md) — use your organization's own Google Gemini API key for ConnectGain AI features.

## See also

- [Inbox guide](https://docs.connectgain.cloud/02-user-guide/inbox.md)
- [Campaigns guide](https://docs.connectgain.cloud/02-user-guide/campaigns.md)
- [Webhooks](https://docs.connectgain.cloud/08-webhooks/README.md)
- [API reference](https://docs.connectgain.cloud/07-api/README.md)

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/index.md)*

---

# Bring Your Own Gemini API Key (BYOK) – ConnectGain

Source: https://docs.connectgain.cloud/05-integrations/ai-byok-gemini/

# Bring Your Own Gemini Key (BYOK)

Use your organization's own Google Gemini [API key](https://docs.connectgain.cloud/05-integrations/07-api/api-key-authentication.md) instead of ConnectGain AI for any or all AI features.

## Why BYOK?
- **Zero ConnectGain AI cost** — Google bills you directly.
- **Data residency / compliance** — calls go from our edge functions straight to Google.
- **Higher quota** if your Google account has a paid Gemini plan.

## 1. Get a key
1. Go to [Google AI Studio](https://aistudio.google.com/app/apikey).
2. Click **Create API key** and copy the value (it starts with `AIza…`).

## 2. Paste it in ConnectGain
1. Navigate to **Settings → AI & Automation → AI Provider**.
2. Select **My Google Gemini key (BYOK)**.
3. Paste the key, choose a model (`gemini-2.5-flash` recommended).
4. Pick a **scope**:
 - **All AI features** — chatbots, classification, internal assistant, web assistant, translations, auto-tag, call analysis, re-engagement.
 - **Re-engagement only** — only the AI Re-Engagement add-on uses your key; everything else stays on ConnectGain AI.
5. Decide on the **fallback toggle**:
 - **On (default):** if your key returns 401 / 403 / 429, ConnectGain AI handles that request so your operations don't stop. You see a warning banner.
 - **Off:** the AI feature returns an error and the UI explains what to fix. Use this if you must guarantee that data only ever leaves through your key.
6. Click **Test key**. A green badge confirms it works.

## 3. Supported models
- `gemini-2.5-flash` (default — best price/perf, recommended)
- `gemini-2.5-pro` (heavier reasoning)
- `gemini-2.5-flash-lite` (cheapest, simple classification)

> Gemini 3.x models (3.5-flash, 3.5-pro, 3.1-flash-lite) are intentionally **not** supported. They are agentic/thinking models that don't reliably follow the JSON-output prompts our AI features (re-engagement, classification, auto-tag, analyze-conversation, etc.) rely on.

## Security model
- The key is encrypted at rest using AES-GCM with a per-deployment `BYOK_ENCRYPTION_KEY`.
- It is **never** returned to the browser. The UI only shows a masked preview (`AIza••••1234`).
- Only OWNER / ADMIN can set, change, or clear the key.
- Every set / clear / scope-change / validation is audited.
- Sentry breadcrumbs scrub the key and message body.

## Billing
- Google bills the account that owns the key.
- The ConnectGain **AI Re-Engagement add-on** is unaffected — it's an orchestration fee, not an AI fee.
- Cancelling the add-on stops the scanner; your key remains configured for other AI features.

## Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| `invalid` badge | Key revoked or typo | Generate a new key and paste again |
| `quota` badge | Free tier rate-limited | Upgrade Google billing or enable fallback |
| `network` badge | Transient Google outage | Retry; fallback handled it if enabled |
| Re-engagement uses ConnectGain AI even though BYOK is on | Scope set to "Re-engagement only" — that's correct, but check the right feature | n/a |
| AI feature errors after key revoked + fallback off | Expected | Re-enable fallback or paste a new key |

## How to switch back
**Settings → AI & Automation → AI Provider → ConnectGain AI (default) → Save.** Your key is cleared from the encrypted store.

## See also

- [AI Re-Engagement guide](https://docs.connectgain.cloud/05-integrations/02-user-guide/ai-reengagement.md)
- [Call Intelligence](https://docs.connectgain.cloud/05-integrations/02-user-guide/call-intelligence.md)
- [Bot flows](https://docs.connectgain.cloud/05-integrations/02-user-guide/bot-flows.md)
- [Integrations overview](https://docs.connectgain.cloud/05-integrations/ai-byok-gemini/README.md)
- [AI Intelligence on connectgain.cloud](https://connectgain.cloud/en/ai-intelligence) — feature overview on the ConnectGain website

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/05-integrations/index.md)*

---

# Appgain Integration – Credentials & Setup – ConnectGain

Source: https://docs.connectgain.cloud/05-integrations/appgain/

# Appgain Integration Documentation

## Overview

This document explains how the Appgain integration works in ConnectGain, including how [API keys](https://docs.connectgain.cloud/05-integrations/07-api/api-key-authentication.md) are obtained and stored. [Appgain](https://www.appgain.io/) powers WhatsApp Lite messaging, the campaign scheduler, and CDN storage for recordings.

**Contents:** [Integration Flow](#integration-flow) · [Webhook Configuration](#webhook-configuration) · [Error Handling](#error-handling) · [Usage in Campaigns](#usage-in-campaigns) · [Testing](#testing) · [Troubleshooting](#troubleshooting) · [Security Considerations](#security-considerations) · [Existing Users Support](#existing-users-support) · [Session-Based Credential System](#session-based-credential-system)

## Integration Flow

### 1. User Signup Process

When a new user signs up for ConnectGain:

1. **Frontend Collection**: User fills out signup form including:
 - Email (required)
 - Password (required)
 - Organization Name (required)
 - First Name (optional)
 - Last Name (optional)
 - Phone Number (optional, but recommended for WhatsApp integration)

2. **Appgain Webhook Call**: Before creating the user account, the frontend calls the Appgain signup webhook:
 ```typescript
 const appgainPayload = {
 platform: 'connectGain',
 phone: signUpData.phone || '',
 email: signUpData.email,
 name: formatUserName(signUpData.firstName, signUpData.lastName),
 org: formatOrgName(signUpData.organizationName)
 };

 const appgainCredentials = await callAppgainSignupWebhook(appgainPayload);
 ```

3. **Webhook Response**: The Appgain webhook returns:
 ```json
 {
 "apiKey": "your-appgain-api-key"
 }
 ```

4. **User Account Creation**: The user account is created with Appgain credentials stored in user metadata as backup.

5. **Database Trigger**: The `handle_new_user` database trigger:
 - Creates the organization
 - Checks for Appgain credentials in user metadata
 - If not found, calls the webhook again from the database
 - Stores credentials in organization settings

### 2. Credential Storage

Appgain credentials are stored in two places:

1. **Organization Settings** (Primary): `organizations.settings` JSONB column
 ```json
 {
 "appgain_api_key": "your-api-key"
 }
 ```

2. **User Metadata** (Backup): `auth.users.raw_user_meta_data`
 ```json
 {
 "appgain_api_key": "your-api-key"
 }
 ```

### 3. Credential Retrieval

**Session-Based Credentials (Recommended):**
Credentials are now automatically loaded into the user session on login and available throughout the app:

```typescript
// In any component, access credentials from session
const { appgainCredentials } = useAuth;

if (appgainCredentials) {
 const { apiKey } = appgainCredentials;
 // Use credentials directly
}
```

**Database Fallback (Legacy):**
For backward compatibility, credentials can still be retrieved from organization settings:

```typescript
const { data: orgSettings } = await supabase.from('organizations').select('settings').eq('id', organizationId).single;

const settings = orgSettings?.settings || {};
const apiKey = settings.appgain_api_key;

```

## Webhook Configuration

### Webhook URL
```
https://n8n.instabackend.io/webhook/connectGain-onSignup
```

**Note**: This is a test webhook that requires manual activation in the n8n canvas. Click "Execute workflow" button before testing.

### Webhook Payload Format
```json
{
 "platform": "connectGain",
 "phone": "+201234567890",
 "email": "user@example.com",
 "name": "Jane Doe",
 "password": "EXAMPLE_PASSWORD",
 "org": "example-org"
}
```

### Example cURL Command
```bash
curl --location 'https://n8n.instabackend.io/webhook/connectGain-onSignup' \
--header 'Content-Type: application/json' \
--data-raw '{
 "platform": "connectGain",
 "phone": "+201234567890",
 "email": "user@example.com",
 "name": "Jane Doe",
 "password": "EXAMPLE_PASSWORD",
 "org": "example-org"
}'
```

### Expected Response Format
```json
{
 "apiKey": "your-appgain-api-key"
}
```

## Error Handling

### Frontend Error Handling
- If webhook call fails, user account is still created
- Warning message is shown to user
- User can configure Appgain integration later in settings

### Database Error Handling
- Webhook failures don't prevent user creation
- Errors are logged as warnings
- Graceful fallback to manual configuration

## Usage in Campaigns

When sending campaigns, the system now:

1. **Uses session credentials** (faster, no database query needed)
2. **Extracts `apiKey` from session**
3. **Uses these credentials to authenticate with Appgain services**
4. **Constructs API URLs**: `https://notify.appgain.io/{organizationId}/send` (path provisioned automatically per organization)

```typescript
// Campaign system now uses session credentials
const { appgainCredentials } = useAuth;

if (!appgainCredentials) {
 throw new Error('Appgain credentials not available. Please log in again.');
}

const { apiKey } = appgainCredentials;
// Use credentials for API calls
```

## Testing

### Test the Webhook
Use the example cURL command above (with placeholder values) to call the signup webhook directly and confirm it returns an `apiKey`.

### Manual Testing
1. Sign up a new user with phone number
2. Check browser console for webhook response
3. Verify credentials are stored in organization settings
4. Test campaign sending functionality

## Troubleshooting

### Common Issues

1. **Webhook Returns 404**
 - Check if using test URL (requires manual activation)
 - Verify webhook endpoint is correct
 - Ensure n8n workflow is active

2. **Missing Credentials**
 - Check organization settings in database
 - Verify webhook response format
 - Check database trigger logs

3. **Campaign Sending Fails**
 - Verify credentials exist in organization settings
 - Check API key format
 - Test webhook endpoint manually

### Database Queries

Check organization settings:
```sql
SELECT settings FROM organizations WHERE id = 'your-org-id';
```

Check user metadata:
```sql
SELECT raw_user_meta_data FROM auth.users WHERE id = 'your-user-id';
```

## Security Considerations

1. **API Keys**: Stored encrypted in database
2. **Webhook Security**: Use HTTPS endpoints only
3. **Access Control**: Only organization owners can view/update settings
4. **Logging**: Sensitive data is masked in logs

## Existing Users Support

For existing users who signed up before the Appgain integration was implemented:

### Automatic Credential Assignment
- All existing organizations automatically receive the default Appgain credentials
- Credentials are added via database migration when the system is updated
- No action required from existing users

### Login Process for Existing Users
When existing users log in, they will receive their Appgain credentials:

```typescript
// After successful login, credentials are available via:
const { data: loginData } = await supabase.rpc('get_user_login_data', { _user_id: user.id });

// Returns:
{
 "user_id": "user-uuid",
 "email": "user@example.com",
 "organization_name": "User Organization",
 "appgain_credentials": {
 "apiKey": "YOUR_APPGAIN_API_KEY"
 }
}
```

### Credential provisioning
Appgain credentials (API key) are provisioned automatically for each organization and delivered to the app at login via the `get_user_login_data` RPC — you never paste them in by hand. Treat the API Key as a secret: it is used server-side only and is never exposed in the browser. Use placeholders such as `YOUR_APPGAIN_API_KEY` in any example or request.

## Session-Based Credential System

### How It Works
1. **On Login**: User credentials are automatically fetched from the database and stored in the React context
2. **In Components**: Any component can access credentials via `useAuth` hook
3. **No Database Queries**: Campaign sending and other operations use session credentials directly
4. **Automatic Updates**: Credentials are refreshed when user logs in/out

### Benefits
- **Performance**: No database queries needed for each campaign send
- **Consistency**: Credentials are always available when user is logged in
- **Security**: Credentials are stored in memory, not persisted in browser storage
- **Simplicity**: Single source of truth for credentials

### Implementation
```typescript
// In any component
import { useAuth } from '@/hooks/useAuth';

function MyComponent {
 const { appgainCredentials, loading } = useAuth;

 if (loading) return <div>Loading...</div>;

 if (!appgainCredentials) {
 return <div>Please log in to access Appgain features</div>;
 }

 const { apiKey } = appgainCredentials;
 // Use credentials for API calls
}
```

## Future Enhancements

1. **Credential Rotation**: Implement automatic key rotation
2. **Multiple Providers**: Support for multiple Appgain accounts
3. **Webhook Retry**: Implement retry logic for failed webhook calls
4. **Settings UI**: Add UI for manual credential configuration
5. **Per-User Credentials**: Allow individual users to have their own Appgain credentials

## See also

- [WhatsApp Lite API guide](https://docs.connectgain.cloud/05-integrations/appgain/whatsapp-lite-api.md)
- [Channels overview](https://docs.connectgain.cloud/05-integrations/appgain/channels.md)
- [Multi-channel messaging](https://docs.connectgain.cloud/05-integrations/appgain/multi-channel-messaging.md)
- [Campaigns guide](https://docs.connectgain.cloud/05-integrations/02-user-guide/campaigns.md)
- [Appgain WhatsApp Business API](https://www.appgain.io/WhatsApp) — the service behind WhatsApp Lite
- [Appgain omnichannel messaging](https://www.appgain.io/omni-channel-messaging) — SMS, Email, WhatsApp and push infrastructure
- [Appgain WhatsApp getting started](https://docs.appgain.io/Omni-channels/WhatsApp%20Business/gettingStarted/) — Appgain-side setup docs

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/05-integrations/index.md)*

---

# Messaging Channel Management & Setup – ConnectGain

Source: https://docs.connectgain.cloud/05-integrations/channels/

# Channel Management Feature

## Overview

Channel Management enables businesses to connect and configure multiple messaging channels (WhatsApp, Messenger, Instagram, Telegram, TikTok, Email, LinkedIn, Shopify Inbox) in one place. SMS is supported for outbound broadcasts and [sequences](https://docs.connectgain.cloud/05-integrations/02-user-guide/sequences.md) only. Channels can be added, configured, activated/deactivated, and monitored for performance.

**Contents:** [Features](#features) · [Use Cases](#use-cases) · [Test Cases](#test-cases) · [API Integration](#api-integration) · [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting)

---

## Features

### 1. Supported Channels

**1. [WhatsApp Lite](https://docs.connectgain.cloud/05-integrations/channels/whatsapp-lite-api.md) (AppGain):**
- QR code authentication
- Phone number messaging
- Media support (images, videos, documents)
- Delivery and read receipts
- Template messaging
- Link shortening
- Warming campaigns

**2. WhatsApp Cloud (Meta):**
- Meta WhatsApp Business API integration
- OAuth authentication via Facebook **or** manual entry with a System User token
- Approved template messaging
- Rich media support
- Interactive buttons
- Delivery and read receipts
- Business verification

> **Connecting a number that doesn't show in the Facebook wizard?** It is almost
> always a system-user / partner WABA. See
> [WhatsApp Cloud — manual connection with a system user](https://docs.connectgain.cloud/05-integrations/channels/whatsapp-cloud-system-user.md).

**3. Facebook Messenger:**
- Facebook Messenger API integration
- OAuth authentication
- Page connection
- Quick replies
- Buttons and carousels
- Media support
- Typing indicators

**4. Instagram Direct Messages:**
- Instagram Graph API integration
- OAuth authentication
- Business account connection
- Media support
- Story mentions
- Direct messaging
- Message requests

**5. Telegram:**
- Telegram Bot API integration
- Bot token authentication
- Sticker support
- Poll support
- Media support
- Group messaging
- Channel broadcasting

**6. TikTok:**
- TikTok Business API integration
- OAuth 2.0 authentication
- Video messaging
- Media support
- Business account features
- Automatic token management

**7. Email:**
- SMTP integration
- Email sending
- Email receiving
- HTML email support
- Attachment support
- Email threading

**8. LinkedIn:**
- OAuth authentication
- Direct messaging (inbound and outbound)
- Post publishing via the LinkedIn v202401 API
- Business/organization account connection

**9. Shopify Inbox:**
- Custom Shopify app integration
- Store chat handled in the unified inbox
- Inbound messages via the Shopify Inbox webhook
- Outbound replies from ConnectGain

**10. SMS:** *(outbound broadcast / sequences only — not in the unified inbox)*
- SMS gateway via Appgain Notify (VictoryLink provider)
- Character limit management (160 / 1600 concatenated)
- Delivery tracking
- Link shortening

**11. Web Push Notifications:**
- Web Push API support
- Background notifications (works when app is closed)
- Android support (Chrome, Firefox, Samsung Internet)
- iOS support (Safari PWA, iOS 16.4+)
- Automatic subscription management
- VAPID key authentication
- Service worker integration
- Notification click handling

**12. ShrinkIt Push Notifications:**
- Push notification support
- Mobile app integration
- Notification delivery

### 2. Channel Configuration

**Configuration Options:**
- Channel name
- Channel-specific settings
- API credentials
- Webhook URLs
- OAuth integration (Facebook, Instagram)
- QR code authentication (WhatsApp Lite)

### 3. Channel Status

**Status Management:**
- **Active** - Channel enabled and receiving messages
- **Inactive** - Channel disabled
- **Connected** - Channel authenticated
- **Disconnected** - Channel not authenticated

### 4. Channel Statistics

**Statistics Display:**
- Messages sent/received
- Conversation count
- Response time
- Channel performance
- Status indicators

### 5. OAuth Integration

**OAuth Channels:**
- Facebook Messenger
- Instagram
- WhatsApp Cloud (via Facebook)

**OAuth Flow:**
- Initiate OAuth connection
- Redirect to provider
- Handle callback
- Store credentials
- Verify connection

### 6. WhatsApp Lite Setup

**Setup Features:**
- QR code authentication
- Phone number configuration
- Sender ID configuration
- Warming campaigns
- Connection status

### 7. Channel Management

**Management Features:**
- Add new channels
- Edit channel settings
- Delete channels
- Toggle channel status
- View channel details
- Monitor channel health

### 8. Multiple Channel Support

**Multi-Channel Features:**
- Multiple channels of same type
- Channel-specific naming
- Independent configuration
- Separate statistics
- Individual status control

---

## Use Cases

### Use Case 1: Connect WhatsApp Lite

**Scenario:**
Business wants to connect WhatsApp Lite channel.

**Steps:**
1. Go to Settings → Channels
2. Click "Add Channel"
3. Select "WhatsApp Lite"
4. Enter channel name
5. Configure sender ID and phone number
6. Scan QR code or enter credentials
7. Verify connection
8. Activate channel
9. Test by sending message

**Expected Outcome:**
WhatsApp Lite channel connected and active.

### Use Case 2: Connect Facebook Messenger

**Scenario:**
Business wants to connect Facebook Messenger via OAuth.

**Steps:**
1. Go to Settings → Channels
2. Click "Add Channel"
3. Select "Facebook Messenger"
4. Click "Connect via Facebook"
5. Authorize ConnectGain
6. Select Facebook Page
7. Verify connection
8. Activate channel
9. Test by receiving message

**Expected Outcome:**
Facebook Messenger connected via OAuth.

### Use Case 3: Configure Multiple WhatsApp Channels

**Scenario:**
Business wants multiple WhatsApp Lite channels for different departments.

**Steps:**
1. Add first WhatsApp Lite channel: "Sales WhatsApp"
2. Configure and activate
3. Add second WhatsApp Lite channel: "Support WhatsApp"
4. Configure and activate
5. Verify both channels active
6. Check channel statistics separately
7. Test messages on both channels

**Expected Outcome:**
Multiple WhatsApp channels configured independently.

### Use Case 4: Monitor Channel Performance

**Scenario:**
Business wants to monitor channel statistics.

**Steps:**
1. Go to Settings → Channels
2. View channel statistics
3. Check messages sent/received
4. Review response times
5. Monitor channel status
6. Identify performance issues
7. Take corrective action

**Expected Outcome:**
Channel performance monitored and optimized.

---

## Test Cases

### Test Case 1: Add Channel

**Test:** Verify channel addition

**Steps:**
1. Go to Settings → Channels
2. Click "Add Channel"
3. Select channel type
4. Enter channel name
5. Configure settings
6. Save channel
7. Verify channel appears in list
8. Verify channel status

**Expected Result:**
Channel added successfully

### Test Case 2: Activate/Deactivate Channel

**Test:** Verify channel toggle

**Steps:**
1. Add channel
2. Verify default status
3. Toggle channel active
4. Verify status changed
5. Toggle channel inactive
6. Verify status changed
7. Check channel behavior

**Expected Result:**
Channel activation toggle works correctly

### Test Case 3: OAuth Connection

**Test:** Verify OAuth flow

**Steps:**
1. Add Facebook Messenger channel
2. Initiate OAuth
3. Complete authorization
4. Select page
5. Verify connection
6. Check credentials stored
7. Test message receiving

**Expected Result:**
OAuth connection successful

### Test Case 4: Channel Statistics

**Test:** Verify statistics display

**Steps:**
1. Add channel
2. Send test messages
3. Receive test messages
4. View channel statistics
5. Verify counts correct
6. Check response times
7. Monitor updates

**Expected Result:**
Statistics display correctly

### Test Case 5: Delete Channel

**Test:** Verify channel deletion

**Steps:**
1. Add channel
2. Verify channel exists
3. Delete channel
4. Confirm deletion
5. Verify channel removed
6. Check related data

**Expected Result:**
Channel deleted successfully

---

## API Integration

### Create Channel

**Endpoint:** `POST /rest/v1/channel_accounts`

**Request:**
```json
{
 "organization_id": "org-uuid",
 "name": "Sales WhatsApp",
 "type": "WHATSAPP_LITE",
 "settings": {
 "sender_id": "123456",
 "phone_number": "+1234567890"
 },
 "is_active": true
}
```

### Update Channel

**Endpoint:** `PATCH /rest/v1/channel_accounts/{id}`

**Request:**
```json
{
 "is_active": false
}
```

### Get Channels

**Endpoint:** `GET /rest/v1/channel_accounts`

**Query Parameters:**
- `organization_id` - Filter by organization
- `type` - Filter by channel type
- `is_active` - Filter by status

---

## Best Practices

1. **Channel Setup**
 - Use descriptive channel names
 - Configure settings completely
 - Test connections before activating
 - Verify webhook configuration

2. **Channel Management**
 - Monitor channel status
 - Review statistics regularly
 - Update credentials when needed
 - Deactivate unused channels

3. **Security**
 - Store credentials securely
 - Use OAuth when available
 - Rotate credentials regularly
 - Monitor for unauthorized access

4. **Performance**
 - Monitor channel performance
 - Optimize message delivery
 - Handle errors gracefully
 - Maintain channel health

---

## Troubleshooting

### Channel Not Connecting

**Issue:** Channel fails to connect

**Solutions:**
- Verify credentials correct
- Check API permissions
- Review connection logs
- Test credentials manually

### Messages Not Receiving

**Issue:** Messages not appearing in inbox

**Solutions:**
- Verify webhook configured
- Check channel status (must be active)
- Review webhook logs
- Test webhook endpoint

### OAuth Errors

**Issue:** OAuth connection fails

**Solutions:**
- Verify app permissions
- Check redirect URLs
- Review OAuth logs
- Re-authorize if needed

---

## Related Documentation

- [Multi-channel messaging](https://docs.connectgain.cloud/05-integrations/channels/multi-channel-messaging.md)
- [Messages Feature](https://docs.connectgain.cloud/05-integrations/02-user-guide/messages.md)
- [Inbox Feature](https://docs.connectgain.cloud/05-integrations/02-user-guide/inbox.md)
- [Webhooks Feature](https://docs.connectgain.cloud/05-integrations/08-webhooks/README.md)
- [API Documentation](https://docs.connectgain.cloud/05-integrations/07-api/complete-api.md)
- [Channels on connectgain.cloud](https://connectgain.cloud/en/channels) — feature overview on the ConnectGain website
- [Integrations on connectgain.cloud](https://connectgain.cloud/en/integrations) — feature overview on the ConnectGain website

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/05-integrations/index.md)*

---

# Multi-Channel Messaging Setup Guide – ConnectGain

Source: https://docs.connectgain.cloud/05-integrations/multi-channel-messaging/

# Multi-Channel Messaging Guide

## Overview

ConnectGain supports 9 messaging channels — [WhatsApp Lite](https://docs.connectgain.cloud/05-integrations/multi-channel-messaging/whatsapp-lite-api.md), WhatsApp Cloud, Facebook Messenger, Instagram, Telegram, TikTok, Shopify Inbox, Bulk Email, and LinkedIn — allowing businesses to communicate with customers through their preferred channels. All channels are unified in a single inbox, providing a seamless customer communication experience.

In addition, SMS is available for outbound broadcasts and [sequences](https://docs.connectgain.cloud/05-integrations/02-user-guide/sequences.md) only (not in the unified inbox), and Web Push / ShrinkIt Push handle notification delivery.

**Contents:** [Supported Channels](#supported-channels) · [Unified Inbox](#unified-inbox) · [Channel-Specific Features](#channel-specific-features) · [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting)

---

## Supported Channels

### 1. WhatsApp Lite (AppGain)

**Authentication:**
- QR code authentication
- Phone number messaging
- Session-based connection

**Features:**
- Media support (images, videos, documents)
- Delivery and read receipts
- Template messaging
- Link shortening (optional)
- Warming campaigns
- Phone number messaging

**Use Cases:**
- Customer support
- Order confirmations
- Appointment reminders
- Marketing campaigns

**Setup:**
1. Go to Settings → Channels
2. Click "Add Channel"
3. Select "WhatsApp Lite"
4. Scan QR code with WhatsApp
5. Channel connected

---

### 2. WhatsApp Cloud (Meta)

**Authentication:**
- OAuth authentication via Facebook
- Business verification required
- Meta Business Account connection

**Features:**
- Approved template messaging (required for outbound)
- Rich media support
- Interactive buttons
- Delivery and read receipts
- Business verification
- Template approval workflow

**Use Cases:**
- Official business communications
- Marketing campaigns
- Transactional messages
- Customer notifications

**Setup:**
1. Go to Settings → Channels
2. Click "Add Channel"
3. Select "[WhatsApp Cloud](https://docs.connectgain.cloud/05-integrations/multi-channel-messaging/whatsapp-cloud-system-user.md)"
4. Connect via Facebook OAuth
5. Select Meta Business Account
6. Complete business verification

---

### 3. Facebook Messenger

**Authentication:**
- OAuth authentication
- Facebook Page connection
- Page permissions required

**Features:**
- Quick replies
- Buttons and carousels
- Media support
- Typing indicators
- Read receipts
- Page messaging

**Use Cases:**
- Customer support
- Social media engagement
- Marketing campaigns
- Lead generation

**Setup:**
1. Go to Settings → Channels
2. Click "Add Channel"
3. Select "Facebook Messenger"
4. Connect via Facebook OAuth
5. Select Facebook Page
6. Grant permissions

---

### 4. Instagram Direct Messages

**Authentication:**
- OAuth authentication
- Instagram Business Account required
- Facebook Page connection

**Features:**
- Media support (images, videos)
- Story mentions
- Direct messaging
- Message requests handling
- Business account features

**Use Cases:**
- Visual product inquiries
- Social media customer service
- Influencer communication
- Brand engagement

**Setup:**
1. Go to Settings → Channels
2. Click "Add Channel"
3. Select "Instagram"
4. Connect via Facebook OAuth
5. Select Instagram Business Account
6. Grant permissions

---

### 5. Telegram

**Authentication:**
- Bot token authentication
- Telegram Bot API
- Bot creation required

**Features:**
- Sticker support
- Poll support
- Media support
- Group messaging
- Channel broadcasting
- Bot commands

**Use Cases:**
- Community management
- Group communications
- Automated notifications
- Customer support bots

**Setup:**
1. Create Telegram bot via @BotFather
2. Get bot token
3. Go to Settings → Channels
4. Click "Add Channel"
5. Select "Telegram"
6. Enter bot token
7. Channel connected

---

### 6. TikTok

**Authentication:**
- OAuth 2.0 authentication
- TikTok Business API integration
- Automatic token management

**Features:**
- Video messaging
- Media support
- Business account features

**Use Cases:**
- Social commerce inquiries
- Creator and brand engagement
- Customer support for TikTok audiences

**Setup:**
1. Go to Settings → Channels
2. Click "Add Channel"
3. Select "TikTok"
4. Connect via TikTok OAuth
5. Authorize the business account
6. Channel connected

---

### 7. Shopify Inbox

**Authentication:**
- Custom Shopify app integration
- Store connection via webhook

**Features:**
- Store chat handled in the unified inbox
- Inbound messages via the Shopify Inbox webhook
- Outbound replies from ConnectGain

**Use Cases:**
- E-commerce customer support
- Pre-sale product questions
- Order and shipping inquiries

**Setup:**
1. Go to Settings → Channels
2. Click "Add Channel"
3. Select "Shopify Inbox"
4. Install the custom Shopify app on your store
5. Verify the webhook connection

---

### 8. Email

**Authentication:**
- SMTP configuration
- Email server credentials
- IMAP/POP3 for receiving

**Features:**
- HTML email support
- Attachment support
- Email threading
- Email templates
- Rich formatting

**Use Cases:**
- Formal communications
- Detailed information sharing
- Document delivery
- Newsletter campaigns

**Setup:**
1. Go to Settings → Channels
2. Click "Add Channel"
3. Select "Email"
4. Configure SMTP settings
5. Configure IMAP/POP3 for receiving
6. Test connection

---

### 9. LinkedIn

**Authentication:**
- OAuth authentication
- Business/organization account connection

**Features:**
- Direct messaging (inbound and outbound)
- Post publishing via the LinkedIn v202401 API

**Use Cases:**
- B2B lead conversations
- Professional networking follow-ups
- Recruiting and sales outreach

**Setup:**
1. Go to Settings → Channels
2. Click "Add Channel"
3. Select "LinkedIn"
4. Connect via LinkedIn OAuth
5. Select the organization account
6. Grant permissions

---

### 10. SMS *(outbound broadcast / sequences only — not shown in the unified inbox)*

**Authentication:**
- SMS gateway via Appgain Notify (VictoryLink provider)
- Provider API credentials

**Features:**
- Character limit management (160 standard, 1600 concatenated)
- Delivery tracking
- Cost tracking
- Link shortening (optional)
- Bulk messaging

**Use Cases:**
- SMS notifications
- Two-factor authentication
- Appointment reminders
- Marketing campaigns

**Setup:**
1. Go to Settings → Channels
2. Click "Add Channel"
3. Select "SMS"
4. Choose SMS provider
5. Enter API credentials
6. Test sending

---

### 11. Web Push Notifications

**Authentication:**
- VAPID key authentication
- Service worker integration
- Browser permission request

**Features:**
- Background notifications (works when app is closed)
- Android support (Chrome, Firefox, Samsung Internet)
- iOS support (Safari PWA, iOS 16.4+)
- Automatic subscription management
- Notification click handling
- Rich notifications

**Use Cases:**
- Real-time notifications
- Offline notifications
- Mobile app-like experience
- Urgent alerts

**Setup:**
1. Configure VAPID keys in Settings
2. Enable browser notifications
3. Users grant permission on first visit
4. Automatic subscription on login
5. Notifications work in background

---

### 12. ShrinkIt Push Notifications

**Authentication:**
- ShrinkIt integration
- API credentials
- Mobile app integration

**Features:**
- Push notification support
- Mobile app integration
- Notification delivery
- Cross-platform support

**Use Cases:**
- Mobile app notifications
- Push notifications
- App engagement

**Setup:**
1. Go to Settings → Channels
2. Click "Add Channel"
3. Select "ShrinkIt Push"
4. Enter ShrinkIt credentials
5. Configure mobile app integration

---

## Unified Inbox

### Features

**Multi-Channel View:**
- All channels in one conversation list
- Channel badges for identification
- Unified conversation threading
- Cross-channel customer view

**Real-Time Sync:**
- Instant message delivery
- Live status updates
- Real-time conversation sync
- Multi-device support

**Channel Management:**
- Multiple channels of same type
- Channel naming
- Channel status (Active/Inactive)
- Channel configuration
- Channel health monitoring

**Channel Statistics:**
- Messages sent/received per channel
- Conversation count per channel
- Response time per channel
- Channel performance metrics

---

## Channel-Specific Features

### WhatsApp Features
- Template messaging (WhatsApp Cloud)
- Media attachments
- Location sharing
- Contact cards (vCard)
- Delivery and read receipts
- Link previews

### Messenger Features
- Quick replies
- Persistent menu
- Buttons and carousels
- Typing indicators
- Read receipts
- Messenger extensions

### Instagram Features
- Stories mentions
- Media sharing
- Direct messaging
- Message requests
- Business account features

### Telegram Features
- Stickers and emojis
- Polls and quizzes
- Group chats
- Channel broadcasting
- Bot commands
- File sharing

### Email Features
- HTML formatting
- Rich text editor
- Attachment support
- Email threading
- CC/BCC support
- Reply-to configuration

### SMS Features
- Character limit handling
- Concatenated messages
- Delivery reports
- Cost tracking
- Link shortening
- Unicode support

---

## Best Practices

### Channel Selection
1. **Use WhatsApp** for international reach and rich media
2. **Use Messenger** for Facebook users and social engagement
3. **Use Instagram** for visual content and younger demographics
4. **Use Email** for formal communications and detailed information
5. **Use SMS** for urgent notifications and universal reach
6. **Use Web Push** for real-time browser notifications

### Message Formatting
- Keep messages concise and clear
- Use appropriate channel for message type
- Include media when relevant
- Use templates for consistency
- Personalize with variables

### Channel Health
- Monitor channel status regularly
- Check delivery rates
- Monitor error rates
- Keep channels active
- Use warming campaigns for WhatsApp

---

## Troubleshooting

### Channel Connection Issues

**WhatsApp Lite:**
- Ensure QR code is scanned correctly
- Check phone number format
- Verify session is active
- Reconnect if disconnected

**WhatsApp Cloud:**
- Verify business verification status
- Check template approval status
- Verify OAuth permissions
- Check Meta Business Account

**Messenger/Instagram:**
- Verify OAuth permissions
- Check page/account connection
- Verify business account status
- Re-authenticate if needed

### Message Delivery Issues

**Failed Messages:**
- Check channel connection status
- Verify recipient information
- Check message format
- Review error messages
- Retry sending

**Delivery Delays:**
- Check channel status
- Verify rate limits
- Check network connectivity
- Review channel logs

---

## Related Documentation

- [Inbox Feature](https://docs.connectgain.cloud/05-integrations/02-user-guide/inbox.md)
- [Messages Feature](https://docs.connectgain.cloud/05-integrations/02-user-guide/messages.md)
- [Channels Feature](https://docs.connectgain.cloud/05-integrations/multi-channel-messaging/channels.md)
- [Campaigns Feature](https://docs.connectgain.cloud/05-integrations/02-user-guide/campaigns.md)
- [Settings Feature](https://docs.connectgain.cloud/05-integrations/03-admin-guide/settings.md)
- [Integrations on connectgain.cloud](https://connectgain.cloud/en/integrations) — feature overview on the ConnectGain website

---

**Last Updated:** February 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/05-integrations/index.md)*

---

# WhatsApp Cloud Manual Setup with a System User – ConnectGain

Source: https://docs.connectgain.cloud/05-integrations/whatsapp-cloud-system-user/

# WhatsApp Cloud — Manual Connection with a System User

How to connect a WhatsApp Cloud (Meta) number to ConnectGain **manually**, using a
Meta **System User** token instead of the Facebook login wizard.

Use this guide when the number you want **does not appear** in the "Connect with
Facebook" selector / Embedded Signup flow.

**Contents:** [When to use this](#1-when-to-use-this-vs-the-facebook-wizard) · [The three pieces you need](#2-the-three-pieces-you-need) · [Prerequisites](#3-prerequisites-in-meta-business-manager) · [Verify access](#4-verify-access-before-you-connect-recommended) · [Connect in ConnectGain](#5-connect-in-connectgain) · [Configure the webhook](#6-configure-the-webhook-on-meta-so-inbound--delivery-status-work) · [Send a test message](#7-send-a-test-message) · [Troubleshooting](#8-troubleshooting)

---

## 1. When to use this (vs. the Facebook wizard)

ConnectGain has two ways to connect a WhatsApp Cloud number, and they use **two
different Meta identities**:

| Flow | Identity used | Sees only… |
|------|---------------|------------|
| **Connect with Facebook** (wizard / Embedded Signup) | the **person** who logs in | WABAs that *person* administers and grants on the consent screen |
| **Manual Entry** (this guide) | a **System User** token you paste | WABAs assigned to that *system user* |

A number is **missing from the wizard** whenever the human logging in is not an
admin of the WABA's owning business — most commonly a **partner/client WABA** that
was assigned to a **system user** for server-to-server use, but never assigned to
any person. The wizard can only show what the logged-in human can see; the system
user, on the other hand, has the WABA assigned, so **Manual Entry** is the path.

> Rule of thumb: if the WABA was set up for API/server use, it's a system-user
> WABA → connect it manually.

---

## 2. The three pieces you need

A WhatsApp Cloud connection is **not** one object — it's three:

| Piece | What it is | Where to get it |
|-------|------------|-----------------|
| **Access Token** | the **System User** token (the *actor* that calls Meta) | Business Settings → Users → System Users → *Generate token* |
| **Phone Number ID** | the number *under* the WABA (not the phone number itself) | App Dashboard → WhatsApp → API Setup |
| **WABA ID** | the WhatsApp Business **Account** asset | App Dashboard → WhatsApp → API Setup ("WhatsApp Business Account ID") |

You authenticate **as** the system user, but you connect **to** a WABA. The
system-user ID never goes into the form — the **WABA ID** and **Phone Number ID** do.

> A `100059…`-style ID is a **user / system-user** profile, **not** a WABA. WABA
> IDs look like `995632549547163`. Don't paste a system-user ID into the WABA field.

---

## 3. Prerequisites in Meta Business Manager

Do these once, in **business.facebook.com → Business Settings** of the business that
**owns the WABA**:

1. **Assign the WABA to the system user**
 - Users → **System Users** → select (or create) the system user.
 - **Add Assets → WhatsApp Accounts** → select the WABA → enable **Manage / Full
 control** → Save.
 - If there are **multiple system users with the same name**, match by **ID**, not name.

2. **Generate a permanent token**
 - On that system user, **Generate New Token** → select the **ConnectGain/Appgain
 app** → **Token expiration: Never**.
 - Tick scopes: **`whatsapp_business_management`** and **`whatsapp_business_messaging`**.
 - Copy the token — this is your **Access Token**. (A system-user token never
 expires, which is why it's preferred over a short-lived login token.)

---

## 4. Verify access before you connect (recommended)

Confirm the token can actually reach the number before wiring it in. Replace
`<TOKEN>`, `<PHONE_NUMBER_ID>`, `<WABA_ID>` (Graph API **v22.0**):

```bash
# (a) The token acts AS the right system user
curl "https://graph.facebook.com/v22.0/me?fields=id,name&access_token=<TOKEN>"

# (b) The number is reachable and live → expect status: CONNECTED
curl "https://graph.facebook.com/v22.0/<PHONE_NUMBER_ID>?fields=display_phone_number,verified_name,status,account_mode&access_token=<TOKEN>"

# (c) The WABA is approved & the business is verified
curl "https://graph.facebook.com/v22.0/<WABA_ID>?fields=name,account_review_status,business_verification_status&access_token=<TOKEN>"
```

If (b) returns `Object … does not exist, cannot be loaded due to missing
permissions` (**code 100 / subcode 33**), the WABA is **not assigned to this system
user** — go back to step 3.1.

---

## 5. Connect in ConnectGain

1. Go to **Settings → Channels** and click **Add Channel** (opens the **"Add New
 Channel"** page).
2. Select **WhatsApp Cloud**.
3. Choose connection mode **Manual Entry**, then provider **Meta**.
4. Fill in:

 | Field | Value |
 |-------|-------|
 | **Access Token** | the system user token from step 3.2 |
 | **Phone Number ID** | from App Dashboard → WhatsApp → API Setup |
 | **WABA ID** | from App Dashboard → WhatsApp → API Setup |
 | **Verify Token** | any string you invent (e.g. `cg_<name>_<random>`) — see step 6 |
 | **Confirm Account Password** | your ConnectGain login password (used once to provision channel credentials) |

5. Save.

**What happens on save** (identical to the Facebook wizard's Appgain calls):
- Provisions Appgain credentials → `{ apiKey }`.
- Configures the Meta vendor for the organization:
 `PUT https://notify.appgain.io/{organizationId}/config` with
 `vendor: "meta"` and `connection_info: { type, phone_number_id, waba_id, access_token }`.
- Inserts the channel (with `waba_id` persisted).
- Syncs the same token to Appgain as the `FBSessionToken` so Appgain can act on
 behalf of the number.

> The **Access Token** is also used as the Facebook session token — they are the
> same value, so there is **no separate "Facebook Session Token" field**.

---

## 6. Configure the webhook on Meta (so inbound + delivery status work)

In **App Dashboard → WhatsApp → Configuration → Webhook**:
- **Verify token**: the *exact same* string you typed in the form.
- **Callback URL**: your ConnectGain WhatsApp Cloud webhook endpoint.
- Subscribe to the **messages** field.

The Verify Token is **not** something you fetch from Meta — it's a shared secret you
choose, entered in both places so Meta's verification handshake matches.

> Without the webhook, messages can still be **sent**, but you will **not** receive
> inbound messages or delivery/read/failed status callbacks.

---

## 7. Send a test message

WhatsApp requires an **approved template** to open a conversation (outside the
customer's 24-hour service window). Supply a value for **every** template variable:

```bash
curl -X POST "https://graph.facebook.com/v22.0/<PHONE_NUMBER_ID>/messages" \
 -H "Authorization: Bearer <TOKEN>" \
 -H "Content-Type: application/json" \
 -d '{
 "messaging_product": "whatsapp",
 "to": "<RECIPIENT_E164_NO_PLUS>",
 "type": "template",
 "template": {
 "name": "<template_name>",
 "language": { "code": "<lang_code>" },
 "components": [
 { "type": "body", "parameters": [
 { "type": "text", "text": "Value1" },
 { "type": "text", "text": "Value2" }
 ] }
 ]
 }
 }'
```

A `messages[].message_status: "accepted"` response means Meta **queued** the message.
Final **delivered / read / failed** status arrives only via the webhook (step 6).

To find a template's exact language and how many variables it expects:

```bash
curl "https://graph.facebook.com/v22.0/<WABA_ID>/message_templates?name=<template_name>&fields=name,status,category,language,components&access_token=<TOKEN>"
```

---

## 8. Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| Number **not listed** in the Facebook wizard | The WABA is assigned to a **system user**, not the human logging in | Use **Manual Entry** (this guide), or assign the WABA to your person in Business Settings |
| `code 100 / subcode 33` "does not exist / missing permissions" on the WABA or number | Token's identity has **no access** to that WABA | Assign the WABA to the system user (step 3.1) |
| Token's `/me` returns the **wrong** system user | Two system users (often **same name**) — token generated from the wrong one | Generate the token from the system user that **has the WABA assigned**; match by **ID** |
| `(#100) nonexisting field (phone_numbers)` on an ID | That ID is **not a WABA** (e.g. a Page or system-user profile) | Use the real **WABA ID** from API Setup |
| `(#132000) Number of parameters does not match` | Template has body variables you didn't fill | Add a `body` component with one `parameters` entry per `{{n}}` |
| Send is `accepted` but **not delivered** | No webhook capturing status; or the number's **display name is `PENDING_REVIEW`** (`can_send_message: LIMITED`); or recipient undeliverable (`131026`) | Configure the webhook (step 6) to see the real status; wait for display-name approval to raise limits; confirm the recipient is on WhatsApp |

---

## Related Documentation

- [Channels overview](https://docs.connectgain.cloud/05-integrations/whatsapp-cloud-system-user/channels.md)
- [WhatsApp webhook troubleshooting](https://docs.connectgain.cloud/05-integrations/whatsapp-cloud-system-user/whatsapp-webhook-troubleshooting.md)
- [Multi-channel messaging](https://docs.connectgain.cloud/05-integrations/whatsapp-cloud-system-user/multi-channel-messaging.md)
- [Appgain integration](https://docs.connectgain.cloud/05-integrations/whatsapp-cloud-system-user/appgain.md)
- [WhatsApp Cloud on connectgain.cloud](https://connectgain.cloud/en/whatsapp-cloud) — feature overview on the ConnectGain website
- [WhatsApp Business on connectgain.cloud](https://connectgain.cloud/en/whatsapp) — feature overview on the ConnectGain website

---

**Last updated:** 2026-06-08.

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/05-integrations/index.md)*

---

# WhatsApp Lite API Guide – Send via Appgain – ConnectGain

Source: https://docs.connectgain.cloud/05-integrations/whatsapp-lite-api/

# WhatsApp Lite API Guide

Complete documentation for the WhatsApp Lite edge functions, with internal logic and sample curl commands for all use cases. WhatsApp Lite runs on [Appgain](https://docs.connectgain.cloud/05-integrations/whatsapp-lite-api/appgain.md) (`api.appgain.io`) with QR-code pairing.

## Table of Contents
1. [whatsapp-lite-send - Sending Messages](#whatsapp-lite-send---sending-messages)
2. [Direct AppGain API - curl for all calling cases](#direct-appgain-api---curl-for-all-calling-cases)
3. [Curl Examples (Supabase edge function)](#curl-examples-supabase-edge-function)
4. [appgain-whatsapp-webhook - Receiving Messages](#appgain-whatsapp-webhook---receiving-messages)
5. [Common Use Cases](#common-use-cases)

---

## whatsapp-lite-send - Sending Messages

### Internal Logic Flow

```text
1. Request Validation
 ├─ Validates JSON payload
 ├─ Ensures required fields: `to`, `message`
 ├─ Validates message length (max 4096 chars)
 └─ Ensures `organizationId` is provided

2. Phone Number Processing
 ├─ Cleans phone number (removes @s.whatsapp.net)
 └─ Logs both original and cleaned versions

3. Organization Lookup
 ├─ Look up org by `organizationId`

4. Get AppGain Credentials
 ├─ Extract `appgain_api_key` from org settings

5. Send via AppGain API
 ├─ POST to https://notify.appgain.io/{organizationId}/send
 ├─ Headers: appapikey, Content-Type
 └─ Body: UOWHATSAPP payload with cleaned phone number

6. Contact Management
 ├─ Find existing contact by phone number (via shared utility)
 ├─ If not found, create with `contactName` or "Unknown Contact"
 └─ Store multiple phone number variations for better matching

7. Channel Account Management
 ├─ Look up ALL active channel accounts for organization
 ├─ Use the FIRST (most recent) one found
 └─ If none exist, create new channel account

8. Conversation Management
 ├─ If `conversationId` provided → use it directly
 ├─ If not provided:
 │ ├─ Search for existing OPEN conversation for contact + channel
 │ ├─ If found → use existing conversation ID
 │ └─ If not found → create new conversation
 └─ Update `last_message_at` timestamp

9. Message Storage
 ├─ Insert message with direction: "OUTBOUND"
 ├─ Set status: "SENT"
 ├─ Store `external_id` from AppGain response
 ├─ If `from` provided → add to metadata as `sender_name`
 └─ Link to conversation and contact

10. Return Response
 ├─ success: true/false
 ├─ result: AppGain API response
 ├─ conversationId
 ├─ contactId
 └─ debug info
```

### API Endpoint
```text
POST https://YOUR_SUPABASE_URL/functions/v1/whatsapp-lite-send
```

### Required Headers
```text
Authorization: Bearer YOUR_ANON_KEY
Content-Type: application/json
```

### Request Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `to` | string | ✅ Yes | Recipient phone number (supports `201001383533@s.whatsapp.net` format) |
| `message` | string | ✅ Yes | Message content (max 4096 characters) |
| `organizationId` | string | ✅ Yes | Your ConnectGain organization UUID |
| `conversationId` | string | ❌ No | Use existing conversation ID instead of creating/finding one |
| `contactName` | string | ❌ No | Contact name when creating new contact |
| `from` | string | ❌ No | Sender name for UI display (stored in metadata) |

### Response

**Success Response (200 OK):**
```json
{
 "success": true,
 "result": {
 "status": "success",
 "message": "successfully sent"
 },
 "conversationId": "uuid-of-conversation",
 "contactId": "uuid-of-contact",
 "debug": {
 "hasChannelAccount": false,
 "hasConversationId": true,
 "hasContactId": true
 }
}
```

**Error Response (400/404/500):**
```json
{
 "error": "Error message describing what went wrong"
}
```

---

## Direct AppGain API - curl for all calling cases

These examples call the **AppGain notify API** directly (`https://notify.appgain.io/{organizationId}/send`). Use your `organizationId` and AppGain [API key](https://docs.connectgain.cloud/05-integrations/07-api/api-key-authentication.md) from channel settings.

- **Base:** `POST https://notify.appgain.io/{organizationId}/send`
- **Headers:** `appapikey: YOUR_APPGAIN_API_KEY`, `Content-Type: application/json`
- **Body:** JSON with top-level key `UOWHATSAPP`. Phone numbers must be cleaned (no `@s.whatsapp.net`).

### AppGain case 1: Text only
```bash
curl -X POST "https://notify.appgain.io/your-org-uuid-here/send" \
 -H "appapikey: YOUR_APPGAIN_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "UOWHATSAPP": {
 "random_string": 0,
 "receivers": [{ "mobileNum": "201001383533" }],
 "message": "Hello, this is a text-only message"
 }
 }'
```

### AppGain case 2: Image only (no caption)
```bash
curl -X POST "https://notify.appgain.io/your-org-uuid-here/send" \
 -H "appapikey: YOUR_APPGAIN_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "UOWHATSAPP": {
 "random_string": 0,
 "receivers": [{ "mobileNum": "201001383533" }],
 "imageUrl": "https://example.com/image.jpg"
 }
 }'
```

### AppGain case 3: Image with caption
```bash
curl -X POST "https://notify.appgain.io/your-org-uuid-here/send" \
 -H "appapikey: YOUR_APPGAIN_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "UOWHATSAPP": {
 "random_string": 0,
 "receivers": [{ "mobileNum": "201001383533" }],
 "imageUrl": "https://example.com/image.jpg",
 "message": "Check out this image"
 }
 }'
```

### AppGain case 4: Video
```bash
curl -X POST "https://notify.appgain.io/your-org-uuid-here/send" \
 -H "appapikey: YOUR_APPGAIN_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "UOWHATSAPP": {
 "random_string": 0,
 "receivers": [{ "mobileNum": "201001383533" }],
 "message": "Optional caption for video",
 "videoUrl": "https://example.com/video.mp4",
 "imageUrl": ""
 }
 }'
```

### AppGain case 5: Document
```bash
curl -X POST "https://notify.appgain.io/your-org-uuid-here/send" \
 -H "appapikey: YOUR_APPGAIN_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "UOWHATSAPP": {
 "random_string": 0,
 "receivers": [{ "mobileNum": "201001383533" }],
 "message": "Optional caption for document",
 "documentUrl": "https://example.com/document.pdf",
 "imageUrl": ""
 }
 }'
```

### AppGain case 6: Multiple receivers (broadcast)
```bash
curl -X POST "https://notify.appgain.io/your-org-uuid-here/send" \
 -H "appapikey: YOUR_APPGAIN_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "UOWHATSAPP": {
 "random_string": 0,
 "receivers": [
 { "mobileNum": "201001383533" },
 { "mobileNum": "2015551234567" }
 ],
 "message": "Broadcast message to multiple numbers"
 }
 }'
```

**Note:** The `whatsapp-lite-send` edge function only uses AppGain cases 1–3 (text, image, image+caption). Video and document (cases 4–5) are used by the campaign scheduler; multiple receivers (case 6) are used by campaigns, not by the single-message edge function.

**Multi-attachment delivery:** When one message carries multiple attachments, the edge function sends one AppGain call per attachment. Two things are needed so all of them are delivered (not just the first):

- **Unique `random_string` on calls 2..N only.** AppGain treats `random_string` as a per-send de-duplication nonce, so reusing a constant value for a burst to the same receiver makes AppGain drop calls 2..N as duplicate retries. However, AppGain also **reflects a non-zero `random_string` in the delivered message content** — sending every call with a unique nonce altered normal chat texts in production (recipients received the typed text with the nonce appended). The edge function therefore sends `random_string: 0` on the first/only call (the one carrying the typed text or caption — matching the curl examples above) and a unique value only on the caption-less attachment calls 2..N.
- **Randomized pacing.** A randomized ~0.8–2.5 s delay is inserted between consecutive sends so the WhatsApp session doesn't collapse a rapid burst.

---

## Curl Examples (Supabase edge function)

### Example 1: Basic Message Using organizationId
```bash
curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-lite-send \
 -H "Authorization: Bearer YOUR_ANON_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "to": "201001383533",
 "message": "Hello, this is a test message",
 "organizationId": "your-org-uuid-here"
 }'
```

### Example 2: Message with Phone Number Including @s.whatsapp.net
```bash
curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-lite-send \
 -H "Authorization: Bearer YOUR_ANON_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "to": "201001383533@s.whatsapp.net",
 "message": "Message with @s.whatsapp.net format",
 "organizationId": "your-org-uuid-here"
 }'
```

### Example 3: Message with Custom Sender Name (from field)
```bash
curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-lite-send \
 -H "Authorization: Bearer YOUR_ANON_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "to": "201001383533",
 "message": "Hello from AIBot!",
 "from": "AIBot"
 }'
```

### Example 4: Message with Contact Name
```bash
curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-lite-send \
 -H "Authorization: Bearer YOUR_ANON_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "to": "201001383533",
 "message": "Hello Mohamed!",
 "contactName": "Mohamed Shaheen"
 }'
```

### Example 5: Complete Example with All Optional Fields
```bash
curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-lite-send \
 -H "Authorization: Bearer YOUR_ANON_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "to": "201001383533@s.whatsapp.net",
 "message": "Hello Mohamed from AIBot!",
 "contactName": "Mohamed Shaheen",
 "from": "AIBot"
 }'
```

### Example 6: Using organizationId
```bash
curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-lite-send \
 -H "Authorization: Bearer YOUR_ANON_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "to": "201001383533",
 "message": "Message using organizationId",
 "organizationId": "your-org-uuid-here"
 }'
```

### Example 7: Send to Existing Conversation
```bash
curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-lite-send \
 -H "Authorization: Bearer YOUR_ANON_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "to": "201001383533",
 "message": "Follow-up message",
 "conversationId": "existing-conversation-uuid"
 }'
```

### Example 8: Send Media (image URL with optional caption)
```bash
curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-lite-send \
 -H "Authorization: Bearer YOUR_ANON_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "to": "201001383533",
 "message": "Check out this image",
 "media_urls": ["https://example.com/image.jpg"]
 }'
```

### Example 9: Cross-Channel Response (e.g. reply via WhatsApp Lite when original was WhatsApp Cloud)
```bash
curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-lite-send \
 -H "Authorization: Bearer YOUR_ANON_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "to": "201001383533",
 "message": "Reply from Lite channel",
 "conversationId": "existing-conversation-uuid",
 "crossChannelResponse": {
 "originalChannelId": "original-channel-account-uuid",
 "originalChannelType": "WHATSAPP_CLOUD",
 "responseChannelId": "whatsapp-lite-channel-account-uuid"
 }
 }'
```

---

## appgain-whatsapp-webhook - Receiving Messages

Inbound WhatsApp Lite messages arrive through the `appgain-whatsapp-webhook` edge function. It acknowledges the provider quickly, then (in the background) looks up or creates the contact and conversation, deduplicates the message, re-hosts media in Supabase Storage, and triggers automations. See the [webhook system overview](https://docs.connectgain.cloud/05-integrations/08-webhooks/overview.md) for how inbound webhooks are processed.

## Common Use Cases

### Use Case 1: Send Welcome Message to New Customer
```bash
curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-lite-send \
 -H "Authorization: Bearer YOUR_ANON_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "to": "201001383533",
 "message": "Welcome to our service! How can we help you today?",
 "contactName": "New Customer",
 "from": "Support Team"
 }'
```

### Use Case 2: Send Order Confirmation as AIBot
```bash
curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-lite-send \
 -H "Authorization: Bearer YOUR_ANON_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "to": "201001383533",
 "message": "Your order #12345 has been confirmed. Expected delivery: 3 days.",
 "from": "AIBot"
 }'
```

### Use Case 3: Follow-up Message in Existing Conversation
```bash
curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-lite-send \
 -H "Authorization: Bearer YOUR_ANON_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "to": "201001383533",
 "message": "I wanted to follow up on your inquiry.",
 "conversationId": "existing-conversation-uuid",
 "from": "Agent Sarah"
 }'
```

## Error Handling

Failed requests return the error response format shown in the [Response](#response) section above, with HTTP status 400 (validation), 404 (organization or credentials not found), or 500 (provider or internal error).

## Notes

1. **Phone Number Formats**: Both functions automatically handle phone numbers with or without `@s.whatsapp.net` suffix
2. **Duplicate Prevention**: Both functions use the same channel account lookup to prevent duplicate conversations
3. **Contact Matching**: Uses multiple phone number variations to find existing contacts
4. **Sender Display**: The `from` field is stored in metadata and can be displayed in the UI as the message sender
5. **Automatic Creation**: Both contacts and conversations are automatically created if they don't exist

## See also

- [Appgain integration](https://docs.connectgain.cloud/05-integrations/whatsapp-lite-api/appgain.md)
- [Channels overview](https://docs.connectgain.cloud/05-integrations/whatsapp-lite-api/channels.md)
- [Multi-channel messaging](https://docs.connectgain.cloud/05-integrations/whatsapp-lite-api/multi-channel-messaging.md)
- [Webhook system overview](https://docs.connectgain.cloud/05-integrations/08-webhooks/overview.md)
- [API reference](https://docs.connectgain.cloud/05-integrations/07-api/README.md)
- [Appgain WhatsApp Business API](https://www.appgain.io/WhatsApp) — the platform powering WhatsApp Lite
- [Appgain WhatsApp getting started](https://docs.appgain.io/Omni-channels/WhatsApp%20Business/gettingStarted/) — provider-side documentation
- [WhatsApp Lite on connectgain.cloud](https://connectgain.cloud/en/whatsapp-lite) — feature overview on the ConnectGain website

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/05-integrations/index.md)*

---

# WhatsApp Cloud Webhook Troubleshooting – ConnectGain

Source: https://docs.connectgain.cloud/05-integrations/whatsapp-webhook-troubleshooting/

# WhatsApp Cloud Webhook - Troubleshooting Guide

## Problem
Marketing clicks are being received but `message.received` webhook is NOT being triggered/fired for clicks.

## Root Cause Analysis

### What We've Verified Already
1. ✅ Meta webhook subscription includes `message_actions` field
2. ✅ Code correctly handles user_actions in payload
3. ✅ Function deploys successfully
4. ⚠️ BUT: Webhook events may not be reaching your function OR function may be early-returning

## Most Likely Causes

### 1. Meta Webhook Connection Issue (MOST LIKELY)
**After changing webhook fields in Meta Developer Portal:**
- Meta needs 1-2 minutes to propagate webhook configuration
- Existing webhook subscriptions aren't automatically refreshed
- Need to verify/re-configure webhook URL on Meta side

**Solution:**
1. Go to [Meta API Dashboard](https://developers.facebook.com/)
2. Navigate to WhatsApp → Live Chat → Webhooks
3. Click "Configure Webhook"
4. **Important:** If you see the webhook field subscription still doesn't include `message_actions`
 - Delete/re-create the webhook subscription
 - OR: Add the fields, then click "Save" and verify connection
5. Test webhook URL under "Webhook Settings" to ensure connectivity

### 2. Function Not Getting Click Events (HIGHLY LIKELY)
The webhook might be hitting your function but with a `messages` event that has empty `messages` array, causing immediate early return.

**Check your Supabase function logs:**
```bash
supabase functions logs whatsapp-cloud-webhook --tail
```

**Look for these log patterns:**
- ✅ Should see: `Processing user_action: marketing_messages_link_click`
- ✅ Should see: `Marketing click details: { click_id:... }`
- ❌ If you see: `No messages or user_actions in webhook payload`
- ❌ If you see: `No valid message to process, returning ok`

**If seeing early-returns, the issue is in Meta webhook configuration**
(not your code).

### 3. Channel Account Not Found (MODERATELY LIKELY)
If your WhatsApp Cloud channel's `phone_number_id` doesn't match Meta's, no channel is found and function throws error.

**Check your WhatsApp Cloud channel settings:**
```sql
SELECT id, name, type, is_active, settings->>'phone_number_id' as phone_number_id
FROM channel_accounts
WHERE type = 'WHATSAPP_CLOUD'
AND is_active = true;
```

**Important:** This must match Meta's `metadata.phone_number_id` in webhook payload.

### 4. Function Not Deployed (LESS LIKELY)
Make sure your edge functions are deployed, not running locally.

**Verify deployment:**
```bash
supabase functions deploy whatsapp-cloud-webhook --no-verify-jwt
```

## Debugging Steps

### Step 1: Verify Webhook is Active
1. Check Meta webhook logs (Facebook Business Suite → WhatsApp → Live Chat)
2. Should see webhook pings every few seconds when active
3. If no pings at all → Webhook not subscribed or URL is wrong

### Step 2: Test with curl
Use curl to manually test your webhook with a marketing click payload:

```bash
curl -X POST \
 https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-cloud-webhook \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer YOUR_ANON_KEY" \
 -d '{
 "object": "whatsapp_business_account",
 "entry": [{
 "id": "703839838664953",
 "changes": [{
 "field": "messages",
 "value": {
 "messaging_product": "whatsapp",
 "metadata": {
 "display_phone_number": "201271111373",
 "phone_number_id": "YOUR_META_PHONE_NUMBER_ID"
 },
 "user_actions": [{
 "action_type": "marketing_messages_link_click",
 "marketing_messages_link_click_data": {
 "tracking_token": "AI@AQJqgqfnGpRlSAubAblOEKTzbNnGt1-Quw4JacCiTnPs01G7_MlUZ0PHlXgnwmI6UhfKQDWgzvHeBlcqy_lNUpm3",
 "click_id": "IwAR5DmdASMYVg7svyUmugr9yxZ8DGERlUF_hBHxxDCWc6WedyOma6pyS95ennUw_wapm_YTA5NDVhMTUtYzE4Ny00YzljLWE5MmItZDc5YWU1YTM5MGNi_waaem_TmQODyhtIouYTj6PKrsI9A",
 "click_component": "CTA"
 }
 }]
 }
 }]
 }]
 }'
```

**Expected response:**
```json
{"status": "ok"}
```

**Check logs immediately after:**
```bash
supabase functions logs whatsapp-cloud-webhook --tail
```

You should see detailed click processing logs.

### Step 3: Check Actual Click Event Payload
What Meta ACTUALLY sends vs what you expect:

**Your expected payload (marketing click):**
```json
{
 "value": {
 "user_actions": [{
 "action_type": "marketing_messages_link_click",
 "marketing_messages_link_click_data": { "...": "..." }
 }]
 }
}
```

**What Meta might send (different format):**
```json
{
 "value": {
 "messages": [{
 "from": "919876543210",
 "type": "template",
 "template": {
 "name": "marketing_link",
 "button": {
 "type": "url",
 "url": "https://example.com"
 }
 },
 "interaction": {
 "type": "click",
 "timestamp": 1699999999999
 }
 }]
 }
}
```

**Tip:** Get the ACTUAL payload from Meta webhook by implementing a test endpoint or browsing Meta's webhook debug tool.

### Step 4: Test with Simple Echo Endpoint
Create a temporary test function to see if Meta clicks are reaching your Supabase:
```typescript
// A minimal echo endpoint to confirm Meta's calls are arriving
serve(async (req) => {
 console.log('Test echo received:', JSON.stringify(await req.json, null, 2));
 const body = await req.json;
 return new Response(JSON.stringify({
 success: true,
 received: body.entry?.[0]?.changes?.[0],
 type: body.entry?.[0]?.changes?.[0]?.field
 }), { headers: { 'Content-Type': 'application/json' } });
});
```

Deploy and test:
```bash
curl -X POST "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/test-echo" \
 -H "Content-Type: application/json" -d '{"test":"value"}'
```

Then send a marketing click and check if you see it in logs.

## What to Tell Meta Developer Support (If Needed)

If the issue persists after all debugging:

1. **Verify webhook fields subscription** - explicitly ask them to confirm `message_actions` is subscribed
2. **Check webhook delivery status** - they can see if Meta is sending events
3. **Provide actual webhook payload** - Recent payload you received with the click action
4. **Assign case number** to Meta API support for WhatsApp Cloud API

## Quick Checklist

Before you proceed further:

- [ ] Meta webhook includes `message_actions` field ✅
- [ ] Webhook URL is correct: `https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-cloud-webhook`
- [ ] Verify token matches `WHATSAPP_CLOUD_VERIFY_TOKEN` ✅
- [ ] Check Supabase function logs for clicks (look for `user_action`)
- [ ] Try sending a marketing click test via WhatsApp Business account
- [ ] Verify click URL is accessible from WhatsApp (actual user clicks on it)

## Alternative: Use WhatsApp Cloud API Events Webhook

If Meta's webhook integration continues to be problematic, consider:
- Using Meta Business API to query message events periodically
- Using third-party webhook monitoring tools
- Exporting WhatsApp Business conversations data to your system

This is a temporary workaround while investigating the webhook issue.

---

**Note:** The most common issue when checking `messages.received` webhook after fixing clicks is that **Meta is delivering the event as a `message_actions` event, not a `messages` event**. Your "Get Started" automation or message monitoring might only be listening to `messages.received`, not `message_actions.received`.

Check your ConnectGain automation/webhook listeners to ensure they're also subscribed to `message_actions` event type.

## See also

- [WhatsApp Cloud — manual connection with a system user](https://docs.connectgain.cloud/05-integrations/whatsapp-webhook-troubleshooting/whatsapp-cloud-system-user.md)
- [Channels overview](https://docs.connectgain.cloud/05-integrations/whatsapp-webhook-troubleshooting/channels.md)
- [Webhook system overview](https://docs.connectgain.cloud/05-integrations/08-webhooks/overview.md)
- [Webhooks quick start](https://docs.connectgain.cloud/05-integrations/08-webhooks/quick-start.md)

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/05-integrations/index.md)*

---

# ConnectGain REST API Documentation – Overview & Guides

Source: https://docs.connectgain.cloud/07-api/

# REST API

Build integrations against ConnectGain.

## Start here

- [API overview](https://docs.connectgain.cloud/07-api/overview.md) — the three API types (Edge Functions, REST, external) with endpoint summaries.
- [API key authentication](https://docs.connectgain.cloud/07-api/api-key-authentication.md) — how `cg_`-prefixed keys work and which header to use.
- [Complete API reference](https://docs.connectgain.cloud/07-api/complete-api.md) — full endpoint, field, and error reference.

## Examples

- [cURL samples](https://docs.connectgain.cloud/07-api/curl-samples.md) — complete cURL requests for contacts, leads, and deals endpoints.
- [REST cURL examples](https://docs.connectgain.cloud/07-api/rest-api-curl-examples.md) — CRUD examples for the REST API proxy.
- [Proxy array search](https://docs.connectgain.cloud/07-api/rest-api-proxy-array-search.md) — searching array columns (phones, emails, tags) via the proxy.
- [Inbox filters (cURL)](https://docs.connectgain.cloud/07-api/inbox-filters-curls.md) — reproduce every inbox filter with PostgREST queries.

## Resources

- [Contacts & Deals API](https://docs.connectgain.cloud/07-api/contacts-and-deals.md) — technical reference for pushing CRM data from external systems.
- [Deals API guide](https://docs.connectgain.cloud/07-api/deals-api-guide.md) — creating, searching, and updating deals, with common pitfalls.
- [Deals bulk behavior](https://docs.connectgain.cloud/07-api/deals-bulk-behavior.md) — how `create-deals-bulk` resolves and creates contacts.

## Companion APIs

- [Mobile API](https://docs.connectgain.cloud/07-api/mobile-api.md) — login, contacts, and call-recording upload for mobile apps.
- [Bot Control API](https://docs.connectgain.cloud/07-api/bot-control-api.md) — pause/resume the AI bot on conversations.

## Postman

- [Postman collection](https://docs.connectgain.cloud/07-api/postman.md) — import and test the public REST API ([direct download](https://docs.connectgain.cloud/07-api/connectgain.postman_collection.json)).

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/index.md)*

---

# API Key Authentication – ConnectGain cg_ Keys & Headers

Source: https://docs.connectgain.cloud/07-api/api-key-authentication/

# API Key Authentication Guide

## Problem

When using Supabase REST API directly with custom API keys (`cg_...`), you may encounter this error:

```json
{
 "message": "No API key found in request",
 "hint": "No `apikey` request header or url param was found."
}
```

## Root Cause

**Supabase REST API only accepts Supabase's own API keys** (`anon` or `service_role` keys), not custom API keys. Custom API keys (`cg_...`) are only supported in Edge Functions.

## Solutions

### Option 1: Use Supabase Anon Key (Recommended for Direct REST API)

For direct REST API calls, use the Supabase `anon` key with the `apikey` header (lowercase):

```bash
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/rest/v1/contacts?first_name=ilike.*John*' \
 --header 'apikey: YOUR_SUPABASE_ANON_KEY' \
 --header 'Authorization: Bearer YOUR_SUPABASE_ANON_KEY'
```

**Note:** Replace `YOUR_SUPABASE_ANON_KEY` with your actual Supabase anon key from the Supabase Dashboard → Settings → API.

### Option 2: Use REST API Proxy with Custom API Key (Recommended for External APIs)

We've created a proxy Edge Function that allows you to use custom API keys (`cg_...`) with REST API endpoints.

**Base URL:** `https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy`

**Example:**

```bash
# Instead of:
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/rest/v1/contacts?first_name=ilike.*John*' \
 --header 'X-API-Key: cg_your_api_key_here'

# Use:
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?first_name=ilike.*John*' \
 --header 'X-API-Key: cg_your_api_key_here'
```

**Supported Query Parameters:**

- `select` - Specify columns to return: `?select=id,first_name,last_name`
- `order` - Order results: `?order=created_at.desc`
- Filter operators:
 - `?first_name=eq.John` - Equals
 - `?first_name=ilike.*John*` - Case-insensitive like (use `*` for wildcards)
 - `?age=gt.18` - Greater than
 - `?age=gte.18` - Greater than or equal
 - `?age=lt.65` - Less than
 - `?age=lte.65` - Less than or equal
 - `?tags=contains.["tag1","tag2"]` - Contains array
 - `?id=in.uuid1,uuid2` - In array
- `limit` - Limit results: `?limit=50`
- `offset` - Pagination: `?offset=100`

**Example Queries:**

```bash
# Search contacts by name
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?first_name=ilike.*John*' \
 --header 'X-API-Key: cg_...'

# Get conversations with pagination
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/conversations?limit=20&offset=0&order=last_message_at.desc' \
 --header 'X-API-Key: cg_...'

# Get specific columns only
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?select=id,first_name,last_name,phones' \
 --header 'X-API-Key: cg_...'
```

### Option 3: Use Edge Functions (For Complex Operations)

For more complex operations, use Edge Functions that support custom API keys:

```bash
# Example: Insert message
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/insert-message' \
 --header 'X-API-Key: cg_your_api_key_here' \
 --header 'Content-Type: application/json' \
 --data '{
 "phone": "+1234567890",
 "content": "Hello from API",
 "direction": "outgoing"
 }'
```

## Key Differences

| Method | Header Name | Key Type | Use Case |
|--------|-------------|----------|----------|
| **Supabase REST API** | `apikey` (lowercase) | Supabase anon key | Direct database access |
| **REST API Proxy** | `X-API-Key` | Custom `cg_...` key | External API access |
| **Edge Functions** | `X-API-Key` | Custom `cg_...` key | Complex operations |

## Security Notes

1. **Custom API keys** are scoped to your organization and respect Row Level Security (RLS) policies
2. **Supabase anon key** has broader access but is still limited by RLS policies
3. Always use HTTPS in production
4. Never expose your Supabase `service_role` key in client-side code

## Troubleshooting

### Error: "No API key found in request"
- **Cause:** Using wrong header name or missing header
- **Fix:** Use `apikey` (lowercase) for Supabase REST API, or `X-API-Key` for proxy/edge functions

### Error: "Invalid or expired API key"
- **Cause:** API key is invalid, expired, or inactive
- **Fix:** Generate a new API key from Settings → API Keys

### Error: "Invalid URL format"
- **Cause:** Incorrect proxy URL format
- **Fix:** Use format: `/rest-api-proxy/<table_name>?<query_params>`

## Getting Your Supabase Anon Key

1. Go to [Supabase Dashboard](https://app.supabase.com)
2. Select your project
3. Go to Settings → API
4. Copy the `anon` `public` key

## Generating Custom API Keys

1. Log into ConnectGain
2. Go to Settings → API Keys
3. Click "Generate API Key"
4. Save the key immediately (it's only shown once)

## See also

- [API overview](https://docs.connectgain.cloud/07-api/api-key-authentication/overview.md) — the three ConnectGain API types at a glance.
- [Complete API reference](https://docs.connectgain.cloud/07-api/api-key-authentication/complete-api.md) — every endpoint, including Generate API Key.
- [REST API proxy cURL examples](https://docs.connectgain.cloud/07-api/api-key-authentication/rest-api-curl-examples.md) — CRUD requests using `X-API-Key`.
- [Proxy array search](https://docs.connectgain.cloud/07-api/api-key-authentication/rest-api-proxy-array-search.md) — searching phones/emails/tags arrays via the proxy.
- [Postman collection](https://docs.connectgain.cloud/07-api/api-key-authentication/postman.md) — test the API without writing code.

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/07-api/index.md)*

---

# Bot Control API – Pause & Resume Bots | ConnectGain

Source: https://docs.connectgain.cloud/07-api/bot-control-api/

# Bot Control API

Control bot (AI agent) status on conversations — pause/resume automation from your mobile app or external system.

## Authentication

All endpoints support two auth methods:

| Method | Header | Example |
|--------|--------|---------|
| API Key | `X-API-Key` | `X-API-Key: cg_your_api_key` |
| Bearer Token | `Authorization` | `Authorization: Bearer <supabase_jwt>` |

---

## 1. Check Bot Status (via REST API Proxy)

The `ai_agent_active` field is included in every conversation response.

### Get single conversation

```
GET /functions/v1/rest-api-proxy/conversations?id=<conversation_id>&select=id,ai_agent_active,status,contact_id,channel_account_id
```

**Response:**
```json
[
 {
 "id": "conv-uuid",
 "ai_agent_active": true,
 "status": "open",
 "contact_id": "contact-uuid",
 "channel_account_id": "channel-uuid"
 }
]
```

| Field | Type | Description |
|-------|------|-------------|
| `ai_agent_active` | `boolean` | `true` = bot is handling, `false` = human is handling |

### List all bot-active conversations for a channel

```
GET /functions/v1/rest-api-proxy/conversations?channel_account_id=<channel_id>&ai_agent_active=true&select=id,ai_agent_active,contact_id,status,last_message_at&order=last_message_at.desc&limit=100
```

### Filter by status

```
GET /functions/v1/rest-api-proxy/conversations?status=open&ai_agent_active=true&select=id,ai_agent_active,contact_id
```

---

## 2. Pause Bot (Human Takeover)

Pauses the bot on a specific conversation. Also deactivates any active [bot flow](https://docs.connectgain.cloud/07-api/02-user-guide/bot-flows.md) sessions and triggers the Human Takeover Webhook if configured on the channel.

```
POST /functions/v1/bot-control
```

**Headers:**
```
Content-Type: application/json
X-API-Key: cg_your_api_key
```

**Body:**
```json
{
 "conversation_id": "conv-uuid",
 "action": "pause"
}
```

**Response:**
```json
{
 "success": true,
 "conversation_id": "conv-uuid",
 "bot_active": false,
 "action": "pause"
}
```

### What happens on pause:
1. `ai_agent_active` is set to `false`
2. All active `bot_sessions` for this conversation are deactivated
3. The **Human Takeover Webhook** is triggered (if configured on the channel)

---

## 3. Resume Bot

Re-enables the bot on a conversation.

```
POST /functions/v1/bot-control
```

**Body:**
```json
{
 "conversation_id": "conv-uuid",
 "action": "resume"
}
```

**Response:**
```json
{
 "success": true,
 "conversation_id": "conv-uuid",
 "bot_active": true,
 "action": "resume"
}
```

---

## 4. Human Takeover Webhook Configuration

Configure per channel in **Settings → Channels → Edit → Settings tab**.

| Field | Description |
|-------|-------------|
| **URL** | The endpoint to call when bot is paused |
| **Method** | `POST`, `PUT`, or `PATCH` |
| **Custom Headers** | JSON object, e.g. `{"Authorization": "Bearer xxx"}` |
| **Custom Body** | JSON object merged with default payload |

### Default Webhook Payload

```json
{
 "event": "human_takeover",
 "conversation_id": "conv-uuid",
 "channel_account_id": "channel-uuid",
 "channel_name": "My WhatsApp Channel",
 "agent": {
 "id": "agent-uuid",
 "name": "Jane Smith",
 "email": "jane@company.com"
 },
 "contact": {
 "id": "contact-uuid",
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+1234567890"],
 "emails": ["john@example.com"]
 },
 "timestamp": "2026-03-14T00:00:00.000Z"
}
```

Custom body fields are **merged** with the default payload (custom fields override defaults if keys overlap).

---

## Error Responses

| Status | Error | Description |
|--------|-------|-------------|
| 400 | `Required: conversation_id, action` | Missing required fields |
| 400 | `action must be "pause" or "resume"` | Invalid action value |
| 401 | `Missing authentication` | No API key or Bearer token |
| 404 | `Conversation not found` | Invalid ID or wrong organization |

---

## cURL Examples

### Check bot status
```bash
curl -X GET \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/conversations?id=CONV_ID&select=id,ai_agent_active,status" \
 -H "X-API-Key: cg_your_api_key"
```

### Pause bot
```bash
curl -X POST \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/bot-control" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: cg_your_api_key" \
 -d '{"conversation_id": "CONV_ID", "action": "pause"}'
```

### Resume bot
```bash
curl -X POST \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/bot-control" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: cg_your_api_key" \
 -d '{"conversation_id": "CONV_ID", "action": "resume"}'
```

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/07-api/index.md)*

---

# ConnectGain Complete API Reference – Endpoints & Fields

Source: https://docs.connectgain.cloud/07-api/complete-api/

# ConnectGain Complete API Documentation

**Version:** 3.0.0
**Last Updated:** January 2025
**Base URL:** `https://txpaxbxhnvnhsjwwaeoy.supabase.co`

---

## Table of Contents

1. [Overview](#overview)
2. [Authentication](#authentication)
3. [Edge Functions API](#edge-functions-api)
4. [REST API Reference](#rest-api-reference)
5. [Features & Capabilities](#features--capabilities)
6. [Error Handling](#error-handling)
7. [Rate Limits & Best Practices](#rate-limits--best-practices)

---

## Overview

ConnectGain is a comprehensive customer engagement and CRM platform that provides:

- **Multi-channel messaging** ([WhatsApp Lite](https://docs.connectgain.cloud/07-api/05-integrations/whatsapp-lite-api.md), WhatsApp Cloud, Facebook Messenger, Instagram, Telegram, TikTok, Shopify Inbox, Bulk Email, LinkedIn)
- **CRM functionality** (Contacts, Deals, Companies, Pipelines)
- **Conversation management** (Inbox, Messages, Assignments)
- **Automation** (Bot Flows, Automation Rules, Templates)
- **Campaign management** (Broadcast campaigns, SMS, WhatsApp)
- **Project management** (Projects, Tasks, Milestones)
- **Analytics & Reporting** (Dashboard widgets, Performance metrics)
- **Team collaboration** (Organizations, Users, Permissions, Invitations)
- **Webhooks** (Event-driven integrations)
- **API integrations** (External system integration via API keys)

### API Types

ConnectGain provides three types of APIs:

1. **Supabase Edge Functions** - Custom serverless functions for business logic
2. **Supabase REST API** - Direct database access via PostgREST
3. **External APIs** - APIs designed for external systems (using API keys)

---

## Authentication

### Standard Authentication (Bearer Token)

Most APIs use Bearer token authentication with your Supabase anon key:

```bash
Authorization: Bearer YOUR_ANON_KEY
apikey: YOUR_ANON_KEY
```

**Getting your anon key:**
1. Go to Supabase Dashboard
2. Navigate to Settings → API
3. Copy the `anon` `public` key

### API Key Authentication (External Systems)

External APIs use `X-API-Key` header for authentication:

```bash
X-API-Key: cg_abc123def456...
```

API keys are generated per organization and can be created via the [Generate API Key](#generate-api-key) endpoint.

**Key Features:**
- Prefixed with `cg_` for easy identification
- Scoped to the organization that created it
- Can have custom permissions (send messages, read messages, etc.)
- Can have expiration dates
- Should be stored securely (only shown once on creation)

---

## Edge Functions API

Edge Functions are serverless functions that handle business logic, integrations, and complex operations.

### Message Sending Functions

#### WhatsApp Lite - Send Message

Send messages via WhatsApp Lite (AppGain integration).

**Endpoint:** `POST /functions/v1/whatsapp-lite-send`

**Headers:**
```bash
Authorization: Bearer YOUR_ANON_KEY
Content-Type: application/json
```

**Request Body:**
```json
{
 "to": "201001383533",
 "message": "Hello from ConnectGain!",
 "organizationId": "org-uuid",
 "contactName": "John Doe",
 "from": "AIBot",
 "conversationId": "conv-uuid"
}
```

**Parameters:**
- `to` (required): Phone number in international format (e.g., "201001383533")
- `message` (required): Message content (max 4096 characters)
- `organizationId` (required): Your ConnectGain organization UUID
- `contactName` (optional): Contact name for display
- `from` (optional): Sender name for UI display
- `conversationId` (optional): Existing conversation ID

**Response:**
```json
{
 "success": true,
 "result": {
 "messageId": "message_id",
 "id": "message_id"
 },
 "conversationId": "conv-uuid",
 "contactId": "contact-uuid"
}
```

**Curl Example:**
```bash
curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-lite-send \
 -H "Authorization: Bearer YOUR_ANON_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "to": "201001383533",
 "message": "Hello!",
 "from": "AIBot"
 }'
```

#### WhatsApp Cloud - Send Message

Send messages via [WhatsApp Cloud](https://docs.connectgain.cloud/07-api/05-integrations/whatsapp-cloud-system-user.md) API (Meta).

**Endpoint:** `POST /functions/v1/whatsapp-cloud-send`

**Request Body:**
```json
{
 "to": "phone_number",
 "message": "Hello via WhatsApp Cloud!",
 "conversationId": "conv-uuid",
 "accessToken": "facebook_access_token",
 "phoneNumberId": "phone_number_id"
}
```

#### Facebook Messenger - Send Message

Send messages via Facebook Messenger.

**Endpoint:** `POST /functions/v1/messenger-send`

**Request Body:**
```json
{
 "to": "user_psid",
 "message": "Hello via Messenger!",
 "conversationId": "conv-uuid",
 "accessToken": "messenger_access_token"
}
```

#### Instagram - Send Message

Send direct messages via Instagram.

**Endpoint:** `POST /functions/v1/instagram-send`

**Request Body:**
```json
{
 "to": "instagram_user_id",
 "message": "Hello via Instagram!",
 "conversationId": "conv-uuid"
}
```

#### Telegram - Send Message

Send messages via Telegram.

**Endpoint:** `POST /functions/v1/telegram-send`

**Request Body:**
```json
{
 "to": "telegram_chat_id",
 "message": "Hello via Telegram!",
 "conversationId": "conv-uuid"
}
```

#### TikTok - Send Message

Send messages via TikTok.

**Endpoint:** `POST /functions/v1/tiktok-send`

**Request Body:**
```json
{
 "to": "tiktok_user_id",
 "message": "Hello via TikTok!",
 "conversationId": "conv-uuid"
}
```

### Search & Import Functions

#### Search Contacts

Advanced contact search with filtering by name, phone, email, tags, and company.

**Endpoint:** `POST /functions/v1/search-contacts`

**Headers:**
```bash
Authorization: Bearer YOUR_ANON_KEY
Content-Type: application/json
```

**Request Body:**
```json
{
 "searchTerm": "John",
 "tags": ["customer", "vip"],
 "dealStatus": "open"
}
```

**Parameters:**
- `searchTerm` (optional): Search term for name, phone, email, or tags
- `tags` (optional): Array of tags to filter by
- `dealStatus` (optional): Filter by deal status ("open", "closed", etc.)

**Response:**
```json
{
 "contacts": [
 {
 "id": "uuid",
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+1234567890"],
 "emails": ["john@example.com"],
 "tags": ["customer"],
 "company": {
 "id": "uuid",
 "name": "Acme Inc"
 },
 "assignee": {
 "id": "uuid",
 "first_name": "Agent",
 "last_name": "Name"
 }
 }
 ],
 "count": 1
}
```

**Features:**
- Searches across first name, last name, full name, reversed name
- Phone number matching (with country code variations)
- Email matching (full email or username part)
- Tag matching
- Company name matching
- Returns up to 2000 results
- Includes related company and assignee data

#### Search Companies

Search companies by name, domain, email, phone, city, industry, or description.

**Endpoint:** `POST /functions/v1/search-companies`

**Request Body:**
```json
{
 "searchTerm": "Acme",
 "country": "US"
}
```

**Parameters:**
- `searchTerm` (optional): Search term for company fields
- `country` (optional): Filter by country (use `__no_country__` for null countries)

**Response:**
```json
{
 "companies": [
 {
 "id": "uuid",
 "name": "Acme Inc",
 "domain": "acme.com",
 "email": "contact@acme.com",
 "phone": "+1234567890",
 "city": "New York",
 "country": "US",
 "industry": "Technology"
 }
 ]
}
```

#### Import Contacts (CSV)

Bulk import contacts from CSV data.

**Endpoint:** `POST /functions/v1/import-contacts`

**Request Body:**
```json
{
 "csvData": "First Name,Last Name,Email,Phone Number\nJohn,Doe,john@example.com,+1234567890",
 "organizationId": "org-uuid"
}
```

**Supported CSV Fields:**
- First Name, Last Name
- Email, Phone Number, Mobile Phone Number
- Company name, Job Title
- Lead Status, Lifecycle Stage
- Street Address, City, State/Region, Postal Code, Country/Region

**Response:**
```json
{
 "success": true,
 "imported": 10,
 "skipped": 2,
 "errors": []
}
```

#### Import Companies (CSV)

Bulk import companies from CSV data.

**Endpoint:** `POST /functions/v1/import-companies`

**Request Body:**
```json
{
 "csvData": "Company name,Company Domain Name,Phone Number,City,Country/Region\nAcme Inc,acme.com,+1234567890,New York,US",
 "organizationId": "org-uuid"
}
```

**Supported CSV Fields:**
- Company name, Company Domain Name, Website URL
- Industry, Phone Number
- City, State/Region, Country/Region, Street Address, Postal Code
- Annual Revenue, Number of Employees
- LinkedIn Company Page, Facebook Company Page, Twitter Handle
- Logo URL, Description
- Lifecycle Stage, Lead Status, Company owner

#### Import Kommo Leads

Import leads from Kommo CRM.

**Endpoint:** `POST /functions/v1/import-kommo-leads`

**Request Body:**
```json
{
 "csvData": "Kommo lead CSV data",
 "organizationId": "org-uuid"
}
```

### External APIs

#### Insert Message (External)

Insert a message into ConnectGain from an external system. Automatically creates or finds contacts and conversations.

**Endpoint:** `POST /functions/v1/insert-message`

**Headers:**
```bash
X-API-Key: cg_abc123def456...
Content-Type: application/json
```

**Request Body:**
```json
{
 "phone": "201001383533",
 "content": "Hello from external system!",
 "direction": "outgoing",
 "status": "sent",
 "message_type": "text",
 "metadata": {},
 "channel_account_id": "channel-uuid"
}
```

**Parameters:**
- `phone` (required): Phone number in international format
- `content` (required): Message content/text
- `direction` (required): "incoming" or "outgoing"
- `status` (required): "sent", "received", "delivered", "failed", etc.
- `message_type` (optional): Message type (default: "text")
- `metadata` (optional): Additional metadata object
- `channel_account_id` (optional): Specific channel account ID

**Response:**
```json
{
 "success": true,
 "message": {
 "id": "message-uuid",
 "conversation_id": "conversation-uuid",
 "contact_id": "contact-uuid"
 }
}
```

**Behavior:**
- Finds or creates contact based on phone number
- Finds or creates conversation for the contact
- Reopens closed conversations if message is inbound
- Inserts message with specified direction and status
- Updates conversation's last_message_at timestamp

**Curl Example:**
```bash
curl -X POST \
 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/insert-message' \
 -H 'X-API-Key: cg_abc123def456...' \
 -H 'Content-Type: application/json' \
 -d '{
 "phone": "201001383533",
 "content": "Hello from external system!",
 "direction": "outgoing",
 "status": "sent"
 }'
```

#### Generate API Key

Create a new API key for external system integration.

**Endpoint:** `POST /functions/v1/generate-api-key`

**Headers:**
```bash
Authorization: Bearer YOUR_ANON_KEY
Content-Type: application/json
```

**Request Body:**
```json
{
 "name": "External System Integration",
 "expires_in_days": 365,
 "permissions": {
 "can_send_messages": true,
 "can_read_messages": false
 }
}
```

**Parameters:**
- `name` (required): Descriptive name for the API key
- `expires_in_days` (optional): Number of days until expiration (null for no expiration)
- `permissions` (optional): Permission object
 - `can_send_messages` (boolean): Allow sending messages
 - `can_read_messages` (boolean): Allow reading messages

**Response:**
```json
{
 "success": true,
 "api_key": "cg_abc123def456...",
 "key_info": {
 "id": "key-uuid",
 "name": "External System Integration",
 "key_prefix": "cg_abc123...",
 "expires_at": "2026-01-15T10:30:00Z",
 "created_at": "2025-01-15T10:30:00Z"
 },
 "warning": "Save this API key now. You will not be able to see it again!"
}
```

**Important:** The full API key is only shown once. Store it securely immediately after creation.

### Organization & Authentication Functions

#### List Organizations

Get all organizations the authenticated user has access to.

**Endpoint:** `GET /functions/v1/list-organizations`

**Headers:**
```bash
Authorization: Bearer YOUR_ANON_KEY
```

**Response:**
```json
{
 "organizations": [
 {
 "id": "uuid",
 "name": "Organization Name",
 "hasAppgainCredentials": true
 }
 ],
 "count": 1
}
```

#### Switch Organization

Switch the user's active organization.

**Endpoint:** `POST /functions/v1/switch-organization`

**Request Body:**
```json
{
 "organizationId": "org-uuid"
}
```

#### Accept Invitation

Accept a team invitation and create user account.

**Endpoint:** `POST /functions/v1/accept-invitation`

**Request Body:**
```json
{
 "token": "invitation_token",
 "email": "user@example.com",
 "password": "secure_password",
 "first_name": "John",
 "last_name": "Doe"
}
```

#### Send Invitation Email

Send an invitation email to a new team member.

**Endpoint:** `POST /functions/v1/send-invitation-email`

**Request Body:**
```json
{
 "email": "newuser@example.com",
 "role": "AGENT",
 "organizationId": "org-uuid"
}
```

#### Facebook OAuth

Handle Facebook OAuth callback for channel integration.

**Endpoint:** `GET /functions/v1/facebook-oauth?code=oauth_code`

### Payment & Subscription Functions

#### Create Stripe Checkout

Create a Stripe checkout session for subscription.

**Endpoint:** `POST /functions/v1/create-checkout`

**Request Body:**
```json
{
 "priceId": "price_xxxxx",
 "couponCode": "optional_coupon"
}
```

**Response:**
```json
{
 "url": "https://checkout.stripe.com/pay/..."
}
```

#### Get Customer Portal URL

Get Stripe customer portal URL for managing subscription.

**Endpoint:** `GET /functions/v1/customer-portal`

**Response:**
```json
{
 "url": "https://billing.stripe.com/p/portal/..."
}
```

#### Check Subscription

Check current subscription status.

**Endpoint:** `GET /functions/v1/check-subscription`

**Response:**
```json
{
 "hasActiveSubscription": true,
 "plan": "pro",
 "status": "active"
}
```

### Webhook Functions

Webhook endpoints receive events from external services (WhatsApp, Messenger, Instagram, Telegram, TikTok, Stripe).

**Available Webhooks:**
- `POST /functions/v1/whatsapp-lite-webhook` - WhatsApp Lite webhooks
- `POST /functions/v1/whatsapp-cloud-webhook` - WhatsApp Cloud webhooks
- `POST /functions/v1/messenger-webhook` - Facebook Messenger webhooks
- `POST /functions/v1/instagram-webhook` - Instagram webhooks
- `POST /functions/v1/telegram-webhook` - Telegram webhooks
- `POST /functions/v1/tiktok-webhook` - TikTok webhooks
- `POST /functions/v1/appgain-whatsapp-webhook` - AppGain WhatsApp webhooks
- `POST /functions/v1/stripe-webhook` - Stripe payment webhooks

These endpoints are typically configured in the external service's webhook settings and handle incoming events automatically.

---

## REST API Reference

The REST API provides direct access to all database tables via PostgREST. All endpoints support standard HTTP methods (GET, POST, PATCH, DELETE) and PostgREST query syntax.

### Base URL

```text
https://txpaxbxhnvnhsjwwaeoy.supabase.co/rest/v1/
```

### Common Headers

```bash
apikey: YOUR_ANON_KEY
Authorization: Bearer YOUR_ANON_KEY
Content-Type: application/json
Prefer: return=representation # Optional: return created/updated record
```

### Query Parameters

PostgREST supports powerful query parameters:

- `select` - Select specific columns or relations (e.g., `select=*,contacts(*)`)
- `filter` - Filter rows (e.g., `id=eq.uuid`, `status=eq.OPEN`)
- `order` - Order results (e.g., `order=created_at.desc`)
- `limit` - Limit results (e.g., `limit=100`)
- `offset` - Pagination offset (e.g., `offset=50`)

**Filter Operators:**
- `eq` - Equal
- `neq` - Not equal
- `gt` - Greater than
- `gte` - Greater than or equal
- `lt` - Less than
- `lte` - Less than or equal
- `like` - Pattern match (case-sensitive)
- `ilike` - Pattern match (case-insensitive)
- `is` - IS NULL / IS NOT NULL
- `in` - In array
- `contains` - JSONB contains

### Contacts API

**Base Endpoint:** `/rest/v1/contacts`

**List Contacts:**
```bash
GET /rest/v1/contacts?select=*&organization_id=eq.{org_id}&order=created_at.desc&limit=100
```

**Get Single Contact:**
```bash
GET /rest/v1/contacts?id=eq.{contact_id}&select=*
```

**Create Contact:**
```bash
POST /rest/v1/contacts
Content-Type: application/json

{
 "organization_id": "org-uuid",
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+1234567890"],
 "emails": ["john@example.com"],
 "tags": ["customer", "vip"],
 "custom_fields": {
 "company": "Acme Inc",
 "position": "Manager"
 },
 "opt_in_status": true
}
```

**Update Contact:**
```bash
PATCH /rest/v1/contacts?id=eq.{contact_id}
Content-Type: application/json

{
 "first_name": "Jane",
 "tags": ["customer", "vip", "priority"]
}
```

**Delete Contact:**
```bash
DELETE /rest/v1/contacts?id=eq.{contact_id}
```

**Search Contacts:**
```bash
GET /rest/v1/contacts?first_name=ilike.*John*&organization_id=eq.{org_id}
```

**Contact Fields:**
- `id` (UUID) - Unique identifier
- `organization_id` (UUID) - Organization reference
- `first_name` (text) - First name
- `last_name` (text) - Last name
- `phones` (text[]) - Array of phone numbers
- `emails` (text[]) - Array of email addresses
- `tags` (text[]) - Array of tags
- `custom_fields` (jsonb) - Custom field data
- `opt_in_status` (boolean) - Marketing opt-in status
- `company_id` (UUID) - Associated company
- `assignee_id` (UUID) - Assigned user
- `created_at` (timestamp) - Creation timestamp
- `updated_at` (timestamp) - Last update timestamp

### Companies API

**Base Endpoint:** `/rest/v1/companies`

**List Companies:**
```bash
GET /rest/v1/companies?select=*&organization_id=eq.{org_id}&order=name.asc
```

**Create Company:**
```bash
POST /rest/v1/companies
Content-Type: application/json

{
 "organization_id": "org-uuid",
 "name": "Acme Inc",
 "domain": "acme.com",
 "email": "contact@acme.com",
 "phone": "+1234567890",
 "city": "New York",
 "country": "US",
 "industry": "Technology",
 "description": "Company description"
}
```

**Company Fields:**
- `id` (UUID) - Unique identifier
- `organization_id` (UUID) - Organization reference
- `name` (text) - Company name
- `domain` (text) - Company domain
- `email` (text) - Contact email
- `phone` (text) - Contact phone
- `city` (text) - City
- `country` (text) - Country code
- `industry` (text) - Industry
- `description` (text) - Company description
- `employee_count` (integer) - Number of employees
- `annual_revenue` (numeric) - Annual revenue
- `created_at` (timestamp) - Creation timestamp
- `updated_at` (timestamp) - Last update timestamp

### Deals API

**Base Endpoint:** `/rest/v1/deals`

**List Deals:**
```bash
GET /rest/v1/deals?select=*,contacts(*),profiles!deals_owner_id_fkey(*)&organization_id=eq.{org_id}&order=created_at.desc
```

**Create Deal:**
```bash
POST /rest/v1/deals
Content-Type: application/json

{
 "organization_id": "org-uuid",
 "contact_id": "contact-uuid",
 "pipeline_id": "pipeline-uuid",
 "title": "New Lead - John Doe",
 "stage": "lead",
 "value": 5000,
 "probability": 10,
 "expected_close_date": "2025-02-15",
 "custom_fields": {
 "source": "website",
 "priority": "high"
 }
}
```

**Update Deal Stage:**
```bash
PATCH /rest/v1/deals?id=eq.{deal_id}
Content-Type: application/json

{
 "stage": "qualified",
 "probability": 50,
 "value": 7500
}
```

**Deal Fields:**
- `id` (UUID) - Unique identifier
- `organization_id` (UUID) - Organization reference
- `contact_id` (UUID) - Associated contact
- `pipeline_id` (UUID) - Associated pipeline
- `owner_id` (UUID) - Deal owner
- `title` (text) - Deal title
- `stage` (text) - Current stage (lead, qualified, proposal, negotiation, closed_won, closed_lost)
- `value` (numeric) - Deal value
- `probability` (integer) - Win probability (0-100)
- `expected_close_date` (date) - Expected close date
- `tags` (text[]) - Array of tags
- `custom_fields` (jsonb) - Custom field data
- `created_at` (timestamp) - Creation timestamp
- `updated_at` (timestamp) - Last update timestamp

### Pipelines API

**Base Endpoint:** `/rest/v1/pipelines`

**List Pipelines:**
```bash
GET /rest/v1/pipelines?select=*&organization_id=eq.{org_id}
```

**Create Pipeline:**
```bash
POST /rest/v1/pipelines
Content-Type: application/json

{
 "organization_id": "org-uuid",
 "name": "Sales Pipeline",
 "stages": "[{\"id\":\"lead\",\"name\":\"Lead\"},{\"id\":\"qualified\",\"name\":\"Qualified\"}]",
 "is_default": false
}
```

**Pipeline Fields:**
- `id` (UUID) - Unique identifier
- `organization_id` (UUID) - Organization reference
- `name` (text) - Pipeline name
- `stages` (jsonb) - Pipeline stages configuration
- `is_default` (boolean) - Default pipeline flag
- `created_at` (timestamp) - Creation timestamp
- `updated_at` (timestamp) - Last update timestamp

### Conversations API

**Base Endpoint:** `/rest/v1/conversations`

**List Conversations:**
```bash
GET /rest/v1/conversations?select=*,contacts(*),channel_accounts(*),profiles!conversations_assignee_id_fkey(*)&organization_id=eq.{org_id}&order=last_message_at.desc
```

**Create Conversation:**
```bash
POST /rest/v1/conversations
Content-Type: application/json

{
 "organization_id": "org-uuid",
 "contact_id": "contact-uuid",
 "channel_account_id": "channel-uuid",
 "status": "OPEN",
 "tags": ["urgent", "customer"]
}
```

**Assign Conversation:**
```bash
PATCH /rest/v1/conversations?id=eq.{conversation_id}
Content-Type: application/json

{
 "assignee_id": "user-uuid"
}
```

**Conversation Fields:**
- `id` (UUID) - Unique identifier
- `organization_id` (UUID) - Organization reference
- `contact_id` (UUID) - Associated contact
- `channel_account_id` (UUID) - Associated channel
- `assignee_id` (UUID) - Assigned user
- `status` (text) - Status (OPEN, CLOSED)
- `tags` (text[]) - Array of tags
- `last_message_at` (timestamp) - Last message timestamp
- `created_at` (timestamp) - Creation timestamp
- `updated_at` (timestamp) - Last update timestamp

### Messages API

**Base Endpoint:** `/rest/v1/messages`

**List Messages:**
```bash
GET /rest/v1/messages?conversation_id=eq.{conversation_id}&order=created_at.asc
```

**Create Message:**
```bash
POST /rest/v1/messages
Content-Type: application/json

{
 "organization_id": "org-uuid",
 "conversation_id": "conversation-uuid",
 "contact_id": "contact-uuid",
 "direction": "OUTBOUND",
 "content": "Hello! This is a test message.",
 "status": "SENT",
 "message_type": "text",
 "metadata": {
 "sender_name": "AIBot"
 }
}
```

**Message Fields:**
- `id` (UUID) - Unique identifier
- `organization_id` (UUID) - Organization reference
- `conversation_id` (UUID) - Associated conversation
- `contact_id` (UUID) - Associated contact
- `sender_id` (UUID) - Sender user (null for system messages)
- `direction` (enum) - INBOUND or OUTBOUND
- `content` (text) - Message content
- `status` (enum) - SENT, DELIVERED, READ, FAILED
- `message_type` (text) - Message type (text, image, video, etc.)
- `metadata` (jsonb) - Additional metadata
- `created_at` (timestamp) - Creation timestamp
- `updated_at` (timestamp) - Last update timestamp

### Tasks API

**Base Endpoint:** `/rest/v1/tasks`

**List Tasks:**
```bash
GET /rest/v1/tasks?select=*,contacts(*)&organization_id=eq.{org_id}&order=due_date.asc
```

**Create Task:**
```bash
POST /rest/v1/tasks
Content-Type: application/json

{
 "organization_id": "org-uuid",
 "contact_id": "contact-uuid",
 "title": "Follow up with customer",
 "description": "Call to discuss pricing",
 "due_date": "2025-01-30T12:00:00Z",
 "completed": false,
 "priority": "HIGH"
}
```

**Task Fields:**
- `id` (UUID) - Unique identifier
- `organization_id` (UUID) - Organization reference
- `contact_id` (UUID) - Associated contact
- `deal_id` (UUID) - Associated deal
- `assignee_id` (UUID) - Assigned user
- `title` (text) - Task title
- `description` (text) - Task description
- `due_date` (timestamp) - Due date
- `completed` (boolean) - Completion status
- `priority` (text) - Priority (LOW, MEDIUM, HIGH)
- `created_at` (timestamp) - Creation timestamp
- `updated_at` (timestamp) - Last update timestamp

### Templates API

**Base Endpoint:** `/rest/v1/templates`

**List Templates:**
```bash
GET /rest/v1/templates?select=*&organization_id=eq.{org_id}&order=created_at.desc
```

**Create Template:**
```bash
POST /rest/v1/templates
Content-Type: application/json

{
 "organization_id": "org-uuid",
 "name": "Welcome Message",
 "components": [{
 "type": "BODY",
 "text": "Hello {{name}}, welcome to our service!"
 }],
 "status": "APPROVED",
 "category": "UTILITY"
}
```

**Template Fields:**
- `id` (UUID) - Unique identifier
- `organization_id` (UUID) - Organization reference
- `name` (text) - Template name
- `components` (jsonb) - Template components (WhatsApp template format)
- `status` (text) - Status (DRAFT, APPROVED, REJECTED)
- `category` (text) - Category (GENERAL, QUICK_REPLY, UTILITY, MARKETING)
- `created_at` (timestamp) - Creation timestamp
- `updated_at` (timestamp) - Last update timestamp

### Bot Flows API

**Base Endpoint:** `/rest/v1/bot_flows`

**List Bot Flows:**
```bash
GET /rest/v1/bot_flows?select=*&organization_id=eq.{org_id}&order=created_at.desc
```

**Create Bot Flow:**
```bash
POST /rest/v1/bot_flows
Content-Type: application/json

{
 "organization_id": "org-uuid",
 "name": "Customer Support Flow",
 "description": "Automated customer support bot",
 "nodes": [],
 "edges": [],
 "status": "DRAFT",
 "version": 1
}
```

**Bot Flow Fields:**
- `id` (UUID) - Unique identifier
- `organization_id` (UUID) - Organization reference
- `name` (text) - Flow name
- `description` (text) - Flow description
- `nodes` (jsonb) - Flow nodes configuration
- `edges` (jsonb) - Flow edges configuration
- `status` (enum) - DRAFT, PUBLISHED, ARCHIVED
- `version` (integer) - Flow version
- `created_at` (timestamp) - Creation timestamp
- `updated_at` (timestamp) - Last update timestamp

### Automation Rules API

**Base Endpoint:** `/rest/v1/automation_rules`

**List Automation Rules:**
```bash
GET /rest/v1/automation_rules?select=*&organization_id=eq.{org_id}&order=created_at.desc
```

**Create Automation Rule:**
```bash
POST /rest/v1/automation_rules
Content-Type: application/json

{
 "organization_id": "org-uuid",
 "name": "Auto Assign New Messages",
 "trigger_type": "MESSAGE_CREATED",
 "conditions": [{
 "field": "direction",
 "operator": "equals",
 "value": "INBOUND"
 }],
 "actions": [{
 "type": "ASSIGN_CONVERSATION",
 "assignee_id": "user-uuid"
 }],
 "is_active": true
}
```

**Automation Rule Fields:**
- `id` (UUID) - Unique identifier
- `organization_id` (UUID) - Organization reference
- `name` (text) - Rule name
- `trigger_type` (enum) - Trigger type (MESSAGE_CREATED, DEAL_STAGE_CHANGED, TASK_DUE, CONTACT_CREATED, etc.)
- `conditions` (jsonb) - Condition array
- `actions` (jsonb) - Action array
- `is_active` (boolean) - Active status
- `created_at` (timestamp) - Creation timestamp
- `updated_at` (timestamp) - Last update timestamp

### Campaigns API

**Base Endpoint:** `/rest/v1/campaigns`

**List Campaigns:**
```bash
GET /rest/v1/campaigns?select=*&organization_id=eq.{org_id}&order=created_at.desc
```

**Create Campaign:**
```bash
POST /rest/v1/campaigns
Content-Type: application/json

{
 "organization_id": "org-uuid",
 "name": "New Product Launch",
 "type": "SMS",
 "content": "Check out our new product!",
 "target_type": "ALL",
 "status": "DRAFT",
 "scheduled_at": "2025-02-01T10:00:00Z"
}
```

**Campaign Fields:**
- `id` (UUID) - Unique identifier
- `organization_id` (UUID) - Organization reference
- `name` (text) - Campaign name
- `type` (enum) - SMS, WHATSAPP_LITE, WHATSAPP_BUSINESS
- `content` (text) - Campaign content
- `target_type` (enum) - ALL, TAGS, INDIVIDUAL
- `target_tags` (text[]) - Target tags (if target_type is TAGS)
- `target_contacts` (uuid[]) - Target contact IDs (if target_type is INDIVIDUAL)
- `status` (enum) - DRAFT, SCHEDULED, SENDING, COMPLETED, CANCELLED
- `scheduled_at` (timestamp) - Scheduled send time
- `timezone` (text) - Timezone for scheduling
- `image_url` (text) - Campaign image URL
- `created_at` (timestamp) - Creation timestamp
- `updated_at` (timestamp) - Last update timestamp

### Notes API

**Base Endpoint:** `/rest/v1/notes`

**List Notes:**
```bash
GET /rest/v1/notes?select=*&contact_id=eq.{contact_id}&order=created_at.desc
```

**Create Note:**
```bash
POST /rest/v1/notes
Content-Type: application/json

{
 "organization_id": "org-uuid",
 "contact_id": "contact-uuid",
 "content": "Customer called to inquire about pricing",
 "author_id": "user-uuid"
}
```

**Note Fields:**
- `id` (UUID) - Unique identifier
- `organization_id` (UUID) - Organization reference
- `contact_id` (UUID) - Associated contact
- `author_id` (UUID) - Note author
- `content` (text) - Note content
- `created_at` (timestamp) - Creation timestamp
- `updated_at` (timestamp) - Last update timestamp

### Channel Accounts API

**Base Endpoint:** `/rest/v1/channel_accounts`

**List Channel Accounts:**
```bash
GET /rest/v1/channel_accounts?select=*&organization_id=eq.{org_id}
```

**Create Channel Account:**
```bash
POST /rest/v1/channel_accounts
Content-Type: application/json

{
 "organization_id": "org-uuid",
 "name": "WhatsApp Business",
 "type": "WHATSAPP_CLOUD",
 "is_active": true,
 "settings": {
 "access_token": "token",
 "phone_number_id": "phone_id"
 }
}
```

**Channel Account Fields:**
- `id` (UUID) - Unique identifier
- `organization_id` (UUID) - Organization reference
- `name` (text) - Channel name
- `type` (enum) - WHATSAPP_LITE, WHATSAPP_CLOUD, FB_MESSENGER, INSTAGRAM, TELEGRAM, TIKTOK, SHOPIFY_INBOX, LINKEDIN, BULK_EMAIL, BULK_EMAIL_SES, EMAIL, SMS, SHRINKIT_PUSH
- `is_active` (boolean) - Active status
- `settings` (jsonb) - Channel-specific settings
- `created_at` (timestamp) - Creation timestamp
- `updated_at` (timestamp) - Last update timestamp

### Projects API

**Base Endpoint:** `/rest/v1/projects`

**List Projects:**
```bash
GET /rest/v1/projects?select=*&organization_id=eq.{org_id}&order=created_at.desc
```

**Create Project:**
```bash
POST /rest/v1/projects
Content-Type: application/json

{
 "organization_id": "org-uuid",
 "name": "New Project",
 "description": "Project description",
 "status": "PLANNING",
 "start_date": "2025-02-01",
 "end_date": "2025-03-01"
}
```

**Project Fields:**
- `id` (UUID) - Unique identifier
- `organization_id` (UUID) - Organization reference
- `name` (text) - Project name
- `description` (text) - Project description
- `status` (enum) - PLANNING, IN_PROGRESS, COMPLETED, DELAYED, CANCELLED
- `start_date` (date) - Start date
- `end_date` (date) - End date
- `created_at` (timestamp) - Creation timestamp
- `updated_at` (timestamp) - Last update timestamp

### Organizations & Users API

**Base Endpoint:** `/rest/v1/organizations` and `/rest/v1/profiles`

**List Organizations:**
```bash
GET /rest/v1/organizations?select=*
```

**List Profiles (Users):**
```bash
GET /rest/v1/profiles?select=*&organization_id=eq.{org_id}
```

**Update Profile:**
```bash
PATCH /rest/v1/profiles?id=eq.{user_id}
Content-Type: application/json

{
 "first_name": "John",
 "last_name": "Doe"
}
```

**Profile Fields:**
- `id` (UUID) - User UUID (references auth.users)
- `organization_id` (UUID) - Organization reference
- `first_name` (text) - First name
- `last_name` (text) - Last name
- `email` (text) - Email address
- `avatar_url` (text) - Avatar URL
- `is_active` (boolean) - Active status
- `created_at` (timestamp) - Creation timestamp
- `updated_at` (timestamp) - Last update timestamp

**Note:** Roles are not stored on `profiles`. User roles (OWNER, ADMIN, AGENT, PROJECT_MANAGER, TEAM_ADMIN) live in the separate `user_roles` table and cannot be changed by patching a profile.

---

## Features & Capabilities

### Dashboard & Analytics

**Dashboard Features:**
- Customizable widgets (drag-and-drop)
- Real-time metrics (messages, conversations, deals, tasks)
- Performance charts
- Date range filtering
- Widget configuration and visibility controls

**Analytics Features:**
- Average response time
- SLA compliance tracking
- Total messages count
- Resolved conversations
- Unassigned messages
- Overdue conversations
- Contact and deal metrics
- Task completion rates

### Contact Management

**Features:**
- Contact CRUD operations
- Bulk import (CSV)
- Advanced search (name, phone, email, tags, company)
- Tag management
- Custom fields support
- Company association
- Contact assignment
- Duplicate detection and merging
- Contact notes
- Deal association
- Task association

**Views:**
- Grid view (cards)
- Table view
- Contact details dialog
- Contact edit dialog

### Company Management

**Features:**
- Company CRUD operations
- Bulk import (CSV)
- Search by name, domain, email, phone, city, industry
- Country filtering
- Company details view
- Contact association
- Deal association

**Views:**
- Grid view (cards)
- Table view
- Company details dialog

### Deal Pipeline Management

**Features:**
- Deal CRUD operations
- Pipeline management (multiple pipelines)
- Stage management (drag-and-drop)
- Deal filtering (stage, value range, assignee, tags)
- Deal assignment
- Value and probability tracking
- Expected close date
- Custom fields
- Deal notes
- Contact association

**Views:**
- Kanban board view
- Deal details dialog
- Pipeline configuration

### Conversation Management

**Features:**
- Conversation CRUD operations
- Message threading
- Conversation assignment
- Status management (OPEN, CLOSED)
- Tag management
- Real-time updates
- Multi-channel support
- Contact association
- Deal creation from conversation

**Views:**
- Conversation list
- Message thread view
- Contact panel
- Mobile-responsive design

### Message Management

**Features:**
- Message CRUD operations
- Multi-channel messaging
- Message status tracking (SENT, DELIVERED, READ, FAILED)
- Message types (text, image, video, audio, document)
- Metadata support
- Real-time delivery
- Message history

### Task Management

**Features:**
- Task CRUD operations
- Task assignment
- Due date tracking
- Priority levels (LOW, MEDIUM, HIGH)
- Completion tracking
- Task filtering (status, priority, assignee)
- Contact and deal association
- Calendar view
- List view

**Views:**
- List view
- Calendar view
- Task details dialog

### Template Management

**Features:**
- Template CRUD operations
- WhatsApp template format support
- Template categories (GENERAL, QUICK_REPLY, UTILITY, MARKETING)
- Template status (DRAFT, APPROVED, REJECTED)
- Template components (BODY, HEADER, FOOTER, BUTTONS)
- Variable support ({{name}}, {{company}}, etc.)

### Bot Flows

**Features:**
- Bot flow CRUD operations
- Visual flow builder
- Node-based flow design
- Flow publishing (DRAFT, PUBLISHED, ARCHIVED)
- Version management
- Flow execution tracking
- Bot session management

**Flow Node Types:**
- Send Message
- Collect Input
- Condition
- Webhook
- Assign Conversation
- Create Task
- End Flow

### Automation Rules

**Features:**
- Automation rule CRUD operations
- Trigger-based automation
- Condition matching
- Action execution
- Active/inactive toggle

**Trigger Types:**
- `message.received` - New message received
- `message.sent` - Message sent
- `contact.created` - Contact created
- `contact.updated` - Contact updated
- `contact.assigned` - Contact assigned
- `deal.created` - Deal created
- `deal.updated` - Deal updated
- `deal.stage.changed` - Deal stage changed
- `deal.assigned` - Deal assigned
- `conversation.created` - Conversation created
- `conversation.assigned` - Conversation assigned
- `conversation.status.changed` - Conversation status changed

**Action Types:**
- `SEND_MESSAGE` - Send a message
- `ASSIGN_CONVERSATION` - Assign conversation to user
- `ASSIGN_CONTACT` - Assign contact to user
- `ASSIGN_DEAL` - Assign deal to user
- `CREATE_TASK` - Create a task
- `CREATE_DEAL` - Create a deal
- `ADD_TAG` - Add tag to contact/deal
- `REMOVE_TAG` - Remove tag from contact/deal
- `UPDATE_FIELD` - Update custom field

### Campaign Management

**Features:**
- Campaign CRUD operations
- Campaign types (SMS, WHATSAPP_LITE, WHATSAPP_BUSINESS)
- Target selection (ALL, TAGS, INDIVIDUAL)
- Campaign scheduling
- Timezone support
- Image support
- Campaign status tracking (DRAFT, SCHEDULED, SENDING, COMPLETED, CANCELLED)
- Campaign preview
- Notification logs

**Views:**
- Campaign list
- Campaign creation dialog
- Campaign preview
- Notification logs

### Project Management

**Features:**
- Project CRUD operations
- Project status tracking (PLANNING, IN_PROGRESS, COMPLETED, DELAYED, CANCELLED)
- Start and end dates
- Project timeline view
- Grid view
- Project details

**Views:**
- Grid view
- Timeline view
- Project details dialog

### Channel Management

**Supported Channels (9):**
- WhatsApp Lite (Appgain)
- WhatsApp Cloud (Meta)
- Facebook Messenger
- Instagram Direct Messages
- Telegram
- TikTok
- Shopify Inbox
- Bulk Email
- LinkedIn

SMS is available for [broadcast campaigns](https://docs.connectgain.cloud/07-api/02-user-guide/campaigns.md) and sequences only — it is not an inbox channel.

**Features:**
- Channel account CRUD operations
- Channel connection/disconnection
- Channel status tracking
- Channel-specific settings
- Webhook configuration
- OAuth integration (Facebook, Instagram)

### Webhooks

**Features:**
- Webhook configuration management
- Event subscription
- HMAC signature verification
- Webhook delivery logging
- Retry mechanism
- Webhook testing

**Available Events:**
- Contact events: `contact.created`, `contact.updated`, `contact.assigned`
- Deal events: `deal.created`, `deal.updated`, `deal.stage.changed`, `deal.assigned`
- Conversation events: `conversation.created`, `conversation.assigned`, `conversation.status.changed`
- Message events: `message.received`, `message.sent`

**Webhook Request Format:**
```json
{
 "event": "contact.created",
 "timestamp": "2025-01-15T10:30:00Z",
 "data": {
 "id": "contact-uuid",
 "first_name": "John",
 "last_name": "Doe"
 }
}
```

**Headers:**
- `X-Webhook-Event` - Event type
- `X-Webhook-Timestamp` - ISO timestamp
- `X-Webhook-Signature` - HMAC-SHA256 signature (if secret configured)

### Team & Organization Management

**Features:**
- Organization CRUD operations
- User management (profiles)
- Role-based access control (OWNER, ADMIN, AGENT, PROJECT_MANAGER, TEAM_ADMIN)
- Team invitations
- Permission management
- Organization switching
- User profile management

**Permissions:**
- `can_access_crm` - Access CRM features
- `can_access_pm` - Access project management
- `can_manage_team` - Manage team members
- `can_manage_settings` - Manage organization settings
- `can_send_messages` - Send messages
- `can_read_messages` - Read messages

### API Key Management

**Features:**
- API key generation
- API key permissions
- API key expiration
- API key prefix identification
- API key security (hashed storage)

---

## Error Handling

### Standard Error Response

All APIs return errors in a consistent format:

```json
{
 "error": "Error message",
 "details": "Detailed error information",
 "code": "ERROR_CODE"
}
```

### HTTP Status Codes

- `200 OK` - Successful request
- `201 Created` - Resource created successfully
- `400 Bad Request` - Invalid request parameters
- `401 Unauthorized` - Authentication required or invalid
- `403 Forbidden` - Insufficient permissions
- `404 Not Found` - Resource not found
- `409 Conflict` - Resource conflict (e.g., duplicate)
- `422 Unprocessable Entity` - Validation error
- `500 Internal Server Error` - Server error
- `503 Service Unavailable` - Service temporarily unavailable

### Common Error Codes

- `AUTHENTICATION_FAILED` - Authentication failed
- `INVALID_API_KEY` - Invalid API key
- `INSUFFICIENT_PERMISSIONS` - Insufficient permissions
- `RESOURCE_NOT_FOUND` - Resource not found
- `VALIDATION_ERROR` - Request validation failed
- `RATE_LIMIT_EXCEEDED` - Rate limit exceeded
- `SERVICE_UNAVAILABLE` - Service unavailable

### Error Examples

**401 Unauthorized:**
```json
{
 "error": "JWT expired",
 "code": "AUTHENTICATION_FAILED"
}
```

**403 Forbidden:**
```json
{
 "error": "Invalid API key",
 "code": "INVALID_API_KEY"
}
```

**404 Not Found:**
```json
{
 "error": "Could not find resource",
 "code": "RESOURCE_NOT_FOUND"
}
```

**422 Unprocessable Entity:**
```json
{
 "error": "Validation error",
 "details": {
 "field": "email",
 "message": "Invalid email format"
 },
 "code": "VALIDATION_ERROR"
}
```

---

## Rate Limits & Best Practices

### Rate Limits

- **Edge Functions:** 100 requests per minute per organization
- **REST API:** 1000 requests per minute per organization
- **External APIs:** 500 requests per minute per API key

Rate limit headers are included in responses:
- `X-RateLimit-Limit` - Request limit
- `X-RateLimit-Remaining` - Remaining requests
- `X-RateLimit-Reset` - Reset timestamp

### Best Practices

1. **Authentication:**
 - Store API keys securely
 - Use environment variables for keys
 - Rotate API keys regularly
 - Use Bearer tokens for internal requests

2. **Error Handling:**
 - Always check response status codes
 - Handle rate limit errors gracefully
 - Implement retry logic with exponential backoff
 - Log errors for debugging

3. **Performance:**
 - Use pagination for large datasets
 - Use `select` parameter to fetch only needed fields
 - Use filters to reduce data transfer
 - Cache frequently accessed data

4. **Data Management:**
 - Use bulk operations when possible (import functions)
 - Batch related operations
 - Use transactions for multi-step operations
 - Validate data before sending

5. **Webhooks:**
 - Verify HMAC signatures
 - Handle webhook failures gracefully
 - Implement idempotency for webhook handlers
 - Respond quickly (within 5 seconds)

6. **Security:**
 - Never expose API keys in client-side code
 - Use HTTPS for all requests
 - Validate and sanitize all inputs
 - Implement proper access controls

---

## Postman Collection

A complete Postman collection is available on the [Postman collection page](https://docs.connectgain.cloud/07-api/complete-api/postman.md) ([direct download](https://docs.connectgain.cloud/07-api/complete-api/connectgain.postman_collection.json)).

### Setting Up Postman

1. Import the collection into Postman
2. Set collection variables:
 - `url`: `https://txpaxbxhnvnhsjwwaeoy.supabase.co`
 - `anon_key`: Your Supabase anon key
 - `api_key`: Your ConnectGain API key (for external APIs)
 - `organization_id`: Your organization UUID
 - Other resource IDs as needed

3. Start testing APIs!

### Collection Structure

The collection is organized into folders:
- Edge Functions - Message Sending
- Edge Functions - Search & Import
- Edge Functions - External APIs
- Edge Functions - Organization & Auth
- Edge Functions - Payment & Subscription
- Edge Functions - Webhooks
- REST API - Contacts
- REST API - Companies
- REST API - Deals
- REST API - Pipelines
- REST API - Conversations
- REST API - Messages
- REST API - Tasks
- REST API - Templates
- REST API - Bot Flows
- REST API - Automation Rules
- REST API - Campaigns
- REST API - Notes
- REST API - Channel Accounts
- REST API - Projects
- REST API - Organizations & Users

---

## Support & Resources

- **Documentation:** https://docs.connectgain.cloud
- **App:** https://dashboard.connectgain.cloud
- **API Base URL:** `https://txpaxbxhnvnhsjwwaeoy.supabase.co`
- **Postman Collection:** [Postman collection page](https://docs.connectgain.cloud/07-api/complete-api/postman.md)

---

**Documentation Version:** 3.0.0
**Last Updated:** January 2025
**Status:** Production Ready

## See also

- [API overview](https://docs.connectgain.cloud/07-api/complete-api/overview.md) — a shorter tour of the three API types.
- [API key authentication](https://docs.connectgain.cloud/07-api/complete-api/api-key-authentication.md) — anon keys vs `cg_` API keys and which header to use.
- [Contacts & Deals API](https://docs.connectgain.cloud/07-api/complete-api/contacts-and-deals.md) — the external integration surface in depth.
- [Inbox filters (cURL)](https://docs.connectgain.cloud/07-api/complete-api/inbox-filters-curls.md) — PostgREST queries behind every inbox filter.
- [Webhooks overview](https://docs.connectgain.cloud/07-api/08-webhooks/overview.md) — receiving ConnectGain events in your systems.

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/07-api/index.md)*

---

# Contacts & Deals API – ConnectGain CRM Integration

Source: https://docs.connectgain.cloud/07-api/contacts-and-deals/

# Contacts & Deals API — Technical Documentation

**Base URL:** `https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1`
**Authentication:** `X-API-Key: cg_your_api_key_here`
**Content-Type:** `application/json`

API keys are scoped to a single organization. All requests are tenant-isolated; you cannot read or write data outside the organization that owns the key.

---

## Table of Contents

1. [Overview](#1-overview)
2. [Contacts API](#2-contacts-api)
 - [2.1 Endpoints](#21-endpoints)
 - [2.2 Request Fields](#22-request-fields)
 - [2.3 Bulk Payload Structure](#23-bulk-payload-structure)
3. [Deals API](#3-deals-api)
 - [3.1 Endpoints](#31-endpoints)
 - [3.2 Request Fields](#32-request-fields)
 - [3.3 Bulk Payload Structure](#33-bulk-payload-structure)
4. [Custom Fields](#4-custom-fields)
5. [Validation Rules](#5-validation-rules)
6. [Best Practices](#6-best-practices)
7. [Full Example Flows](#7-full-example-flows)
8. [Error Reference](#8-error-reference)

---

## 1. Overview

### Purpose

The Contacts and Deals APIs let external systems (e‑commerce platforms, lead-gen forms, ERPs, scripts) push customer data and sales opportunities into the CRM. They are the primary integration surface for:

- Importing customers from a website, Shopify, or in-house systems.
- Streaming new orders / opportunities into the [sales pipeline](https://docs.connectgain.cloud/07-api/02-user-guide/deals.md).
- Keeping CRM data in sync with an external source of truth (upsert pattern).
- Searching contacts before creating new ones to prevent duplicates.

### Single vs Bulk endpoints

| Use case | Endpoint type | Typical batch |
|---|---|---|
| Real-time event (new signup, single order) | **Single** (`/create-lead`, `rest-api-proxy/deals` POST) | 1 record |
| Nightly sync, CSV upload, migration | **Bulk** (`/import-contacts-bulk`, `/create-deals-bulk`) | up to 100 (deals) / 500 (contacts) per call |

Bulk endpoints return per-row results so partial success is observable. Single endpoints return either the created record or an error.

### Typical use cases

- **E-commerce checkout** → create a contact + a deal per order.
- **Lead-gen form** → upsert contact and assign to a sales rep.
- **CRM enrichment** → search by phone/email, then PATCH the contact.
- **Pipeline reporting** → bulk-load historical orders as deals into a "closed-won" stage.

---

## 2. Contacts API

### 2.1 Endpoints

| Action | Method | Path |
|---|---|---|
| Create single contact | `POST` | `/rest-api-proxy/contacts` |
| Create + auto-deal (lead) | `POST` | `/create-lead` |
| Bulk create / upsert contacts | `POST` | `/import-contacts-bulk` |
| Get contact by ID | `GET` | `/rest-api-proxy/contacts?id=eq.<uuid>` |
| Search contacts (phone) | `GET` | `/rest-api-proxy/contacts?phones=cs.{"+201017177777"}` |
| Search contacts (email) | `GET` | `/rest-api-proxy/contacts?emails=cs.{"user@example.com"}` |
| Search contacts (free text) | `POST` | `/search-contacts` |
| Update contact | `PATCH` | `/rest-api-proxy/contacts?id=eq.<uuid>` |
| Delete contact | `DELETE` | `/rest-api-proxy/contacts?id=eq.<uuid>` |

All endpoints require:

```text
X-API-Key: cg_your_api_key_here
Content-Type: application/json
```

---

#### 2.1.1 Create single contact

```bash
curl -X POST 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts' \
 -H 'X-API-Key: cg_xxx' \
 -H 'Content-Type: application/json' \
 -H 'Prefer: return=representation' \
 -d '{
 "first_name": "Mahmoud",
 "last_name": "Ali",
 "phones": ["+201017177777"],
 "emails": ["mahmoud@example.com"],
 "source": "website",
 "tags": ["vip", "newsletter"],
 "custom_fields": {
 "customer_type": "VIP",
 "last_order_value": 1200
 }
 }'
```

**Response `201 Created`:**
```json
[{
 "id": "f2b4f7ab-7033-47ce-be06-b30a47de020a",
 "first_name": "Mahmoud",
 "last_name": "Ali",
 "phones": ["+201017177777"],
 "emails": ["mahmoud@example.com"],
 "tags": ["vip", "newsletter"],
 "source": "website",
 "custom_fields": { "customer_type": "VIP", "last_order_value": 1200 },
 "created_at": "2026-04-23T10:12:34.567Z"
}]
```

**Status codes:** `201` created · `400` invalid payload · `401` bad key · `409` duplicate phone (if dedupe enabled) · `500` internal error.

---

#### 2.1.2 Search contact by phone or email

> The `cs` (contains) operator is required for the `phones[]` and `emails[]` array columns. Always URL-encode `+` as `%2B` (or use `--data-urlencode`).

```bash
curl -G 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts' \
 -H 'X-API-Key: cg_xxx' \
 --data-urlencode 'phones=cs.{"+201017177777"}' \
 --data-urlencode 'select=id,first_name,last_name,phones,emails,custom_fields' \
 --data-urlencode 'limit=1'
```

By email:
```bash
curl -G 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts' \
 -H 'X-API-Key: cg_xxx' \
 --data-urlencode 'emails=cs.{"mahmoud@example.com"}' \
 --data-urlencode 'limit=1'
```

By custom field (JSONB equality):
```bash
curl -G 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts' \
 -H 'X-API-Key: cg_xxx' \
 --data-urlencode 'custom_fields->>customer_type=eq.VIP' \
 --data-urlencode 'limit=50'
```

**Response `200 OK`:** array of contact objects (empty `[]` if no match).

---

#### 2.1.3 Update contact

```bash
curl -X PATCH 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?id=eq.f2b4f7ab-7033-47ce-be06-b30a47de020a' \
 -H 'X-API-Key: cg_xxx' \
 -H 'Content-Type: application/json' \
 -H 'Prefer: return=representation' \
 -d '{
 "first_name": "Mahmoud Updated",
 "tags": ["vip", "premium"],
 "custom_fields": { "customer_type": "Platinum", "last_order_value": 2400 }
 }'
```

You can also update by phone:

```bash
curl -X PATCH -G 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts' \
 -H 'X-API-Key: cg_xxx' \
 -H 'Content-Type: application/json' \
 --data-urlencode 'phones=cs.{"+201017177777"}' \
 --data '{"first_name":"Mahmoud Updated"}'
```

> ⚠️ `custom_fields` is **replaced**, not merged. To preserve existing keys, GET → merge client-side → PATCH.

---

#### 2.1.4 Bulk create / upsert contacts

```bash
curl -X POST 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/import-contacts-bulk' \
 -H 'X-API-Key: cg_xxx' \
 -H 'Content-Type: application/json' \
 -d '{
 "contacts": [
 {
 "first_name": "Ahmed",
 "phones": ["+201111111111"],
 "emails": ["ahmed@example.com"],
 "tags": ["import-2026-04"],
 "custom_fields": { "city": "Cairo" }
 },
 {
 "first_name": "Sara",
 "phones": ["+201222222222"],
 "source": "csv-import"
 }
 ],
 "skip_duplicates": false,
 "default_tags": ["batch-2026-04"],
 "default_source": "csv-import"
 }'
```

**Response `200 OK`:**
```json
{
 "success": true,
 "summary": { "total": 2, "successful": 2, "failed": 0, "new_contacts": 1, "updated_contacts": 1 },
 "results": [
 { "index": 0, "success": true, "contact_id": "...", "is_new": false },
 { "index": 1, "success": true, "contact_id": "...", "is_new": true }
 ]
}
```

---

### 2.2 Request Fields

| Field | Type | Required | Description | Example | Validation |
|---|---|---|---|---|---|
| `first_name` | string | optional | Given name | `"Mahmoud"` | ≤ 100 chars |
| `last_name` | string | optional | Family name | `"Ali"` | ≤ 100 chars |
| `phones` | string[] | optional* | E.164 phone numbers | `["+201017177777"]` | Must start with `+`, 8–15 digits |
| `emails` | string[] | optional* | RFC 5322 emails | `["a@b.com"]` | Standard email regex |
| `source` | string | optional | Origin label (free text) | `"website"`, `"shopify"`, `"api"` | ≤ 50 chars |
| `tags` | string[] | optional | Free-form labels | `["vip","newsletter"]` | each ≤ 50 chars |
| `assignee_id` | uuid | optional | User who owns this contact | `"f2b4..."` | Must exist in org |
| `company_id` | uuid | optional | Linked company record | `"a1b2..."` | Must exist in org |
| `description` | string | optional | Notes / bio | `"VIP customer since 2023"` | ≤ 5000 chars |
| `opt_in_status` | bool | optional | Marketing consent (default `true`) | `true` | — |
| `custom_fields` | object | optional | Arbitrary JSON metadata | `{"city":"Cairo"}` | Valid JSON, ≤ 32 KB |

\* At least one of `phones` or `emails` is recommended for deduplication and outbound messaging.

---

### 2.3 Bulk Payload Structure

```json
{
 "contacts": [ /* contact objects, max 500 */ ],
 "skip_duplicates": false,
 "default_source": "csv-import",
 "default_tags": ["batch-2026-04"]
}
```

| Behavior | Detail |
|---|---|
| **Max batch size** | 500 contacts per request |
| **Atomicity** | Per-row; failure of one row does not roll back others |
| **Duplicate handling** | Contacts are matched on email first, then on any phone (normalized to E.164). When a match is found, `skip_duplicates: true` skips the row and `skip_duplicates: false` (default) merges the incoming data into the existing contact |
| **Idempotency** | Re-sending the same payload → no duplicates created (matched rows are merged or skipped) |
| **Partial success** | `summary.failed > 0` while `summary.new_contacts`/`summary.updated_contacts > 0`; inspect `results[]` for per-row errors |

---

## 3. Deals API

### 3.1 Endpoints

| Action | Method | Path |
|---|---|---|
| Create single deal | `POST` | `/rest-api-proxy/deals` |
| Create lead (contact + deal) | `POST` | `/create-lead` |
| Bulk create deals | `POST` | `/create-deals-bulk` |
| Bulk create leads (contact + deal) | `POST` | `/create-leads-bulk` |
| Get deal by ID | `GET` | `/rest-api-proxy/deals?id=eq.<uuid>` |
| Search deals by title | `GET` | `/rest-api-proxy/deals?title=ilike.*Order*` |
| Search deals by contact | `GET` | `/rest-api-proxy/deals?contact_id=eq.<uuid>` |
| Update deal | `PATCH` | `/rest-api-proxy/deals?id=eq.<uuid>` |
| Delete deal | `DELETE` | `/rest-api-proxy/deals?id=eq.<uuid>` |

---

#### 3.1.1 Create single deal

```bash
curl -X POST 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals' \
 -H 'X-API-Key: cg_xxx' \
 -H 'Content-Type: application/json' \
 -H 'Prefer: return=representation' \
 -d '{
 "title": "Order #68297792",
 "value": 11523,
 "currency": "SAR",
 "stage": "qualified",
 "contact_id": "f2b4f7ab-7033-47ce-be06-b30a47de020a",
 "source": "shopify",
 "expected_close_date": "2026-05-15",
 "probability": 60,
 "tags": ["online-order"],
 "custom_fields": {
 "shopify_order_id": "68297792",
 "payment_method": "mada"
 }
 }'
```

> ⚠️ **`stage` must be lowercase** and must match a stage ID configured on the pipeline (e.g. `"new"`, `"qualified"`, `"won"`, `"lost"`). Uppercase values like `"QUALIFIED"` are accepted but will not render in the dashboard.

---

#### 3.1.2 Bulk create deals

```bash
curl -X POST 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-deals-bulk' \
 -H 'X-API-Key: cg_xxx' \
 -H 'Content-Type: application/json' \
 -d '{
 "default_currency": "SAR",
 "default_stage": "qualified",
 "skip_if_exists": true,
 "deals": [
 {
 "title": "Order #68297792",
 "value": 11523,
 "contact_phone": "+201017177777",
 "contact_first_name": "Mahmoud",
 "create_contact_if_missing": true,
 "custom_fields": { "order_id": "68297792" }
 },
 {
 "title": "Order #68297793",
 "value": 540,
 "contact_email": "noha@example.com",
 "contact_first_name": "Noha",
 "create_contact_if_missing": true
 }
 ]
 }'
```

**Response `200 OK`:**
```json
{
 "success": true,
 "summary": {
 "total": 2,
 "successful": 2,
 "failed": 0,
 "new_deals": 2,
 "skipped_existing": 0,
 "new_contacts_created": 1
 },
 "results": [
 { "index": 0, "success": true, "deal_id": "...", "contact_id": "f2b4f7ab-...", "is_new_contact": false },
 { "index": 1, "success": true, "deal_id": "...", "contact_id": "...", "is_new_contact": true }
 ]
}
```

---

#### 3.1.3 Search deals by title (substring match)

```bash
curl -G 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals' \
 -H 'X-API-Key: cg_xxx' \
 --data-urlencode 'title=ilike.*68297792*' \
 --data-urlencode 'select=id,title,value,stage,contact_id' \
 --data-urlencode 'limit=10'
```

| Operator | Meaning |
|---|---|
| `ilike.*foo*` | Case-insensitive substring (PostgreSQL `ILIKE %foo%`) |
| `like.*Foo*` | Case-sensitive substring |
| `eq.foo` | Exact match |

#### 3.1.4 Update deal (e.g. mark as won)

```bash
curl -X PATCH 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals?id=eq.<deal-id>' \
 -H 'X-API-Key: cg_xxx' \
 -H 'Content-Type: application/json' \
 -d '{ "stage": "won", "probability": 100 }'
```

Bulk-fix wrong stage casing:
```bash
curl -X PATCH -G 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals' \
 -H 'X-API-Key: cg_xxx' \
 -H 'Content-Type: application/json' \
 --data-urlencode 'stage=eq.QUALIFIED' \
 --data '{ "stage": "qualified" }'
```

---

### 3.2 Request Fields

| Field | Type | Required | Description | Example | Validation |
|---|---|---|---|---|---|
| `title` | string | **required** | Human-readable deal name | `"Order #12345"` | 1–200 chars |
| `value` | number | optional | Monetary value (numeric, no symbols) | `11523` | ≥ 0 |
| `currency` | string | optional | ISO 4217 code (default `USD`) | `"SAR"`, `"EUR"` | 3-letter code |
| `stage` | string | optional | Pipeline stage ID (lowercase) | `"qualified"` | Must exist in pipeline.stages |
| `pipeline_id` | uuid | optional | Specific pipeline; falls back to default | `"a1b2..."` | Must exist in org |
| `contact_id` | uuid | required* | Existing contact UUID | `"f2b4..."` | Must exist in org |
| `contact_email` | string | required* | Lookup contact by email | `"a@b.com"` | Bulk only |
| `contact_phone` | string | required* | Lookup contact by phone | `"+201017177777"` | Bulk only, E.164 |
| `contact_first_name` | string | optional | Used when creating new contact | `"Mahmoud"` | Bulk only |
| `contact_last_name` | string | optional | Used when creating new contact | `"Ali"` | Bulk only |
| `create_contact_if_missing` | bool | optional | Auto-provision contact (default `false`) | `true` | Bulk only |
| `description` | string | optional | Notes | — | ≤ 5000 chars |
| `expected_close_date` | date | optional | ISO date | `"2026-05-15"` | YYYY-MM-DD |
| `probability` | number | optional | Win probability 0–100 | `60` | 0–100 |
| `source` | string | optional | Origin label | `"shopify"`, `"api"` | ≤ 50 chars |
| `tags` | string[] | optional | Free-form labels | `["online-order"]` | each ≤ 50 chars |
| `owner_id` | uuid | optional | Sales rep UUID | `"u1..."` | Must exist in org |
| `company_id` | uuid | optional | Linked company | `"c1..."` | Must exist in org |
| `custom_fields` | object | optional | Arbitrary JSON metadata | `{"order_id":"123"}` | Valid JSON, ≤ 32 KB |
| `products` | object[] | optional | Line items | `[{"name":"Sku1","quantity":2,"unit_price":50}]` | Optional schema |

\* For `/create-deals-bulk`: provide **at least one** of `contact_id`, `contact_email`, or `contact_phone`.

---

### 3.3 Bulk Payload Structure

```json
{
 "deals": [ /* deal objects, max 100 */ ],
 "default_pipeline_id": "uuid (optional)",
 "default_stage": "qualified",
 "default_currency": "SAR",
 "skip_if_exists": true
}
```

| Behavior | Detail |
|---|---|
| **Max batch size** | 100 deals per request (HTTP 400 above this) |
| **Contact resolution order** | `contact_id` → `contact_email` → `contact_phone` |
| **Linking vs creating** | Match found → deal linked, contact NOT updated. No match + `create_contact_if_missing: true` → new contact created |
| **`skip_if_exists`** | Skips when a deal with the same `title` already exists for the resolved contact (returns existing `deal_id`, counted in `skipped_existing`) |
| **Atomicity** | Per-row; failures isolated, no rollback |
| **Idempotency** | Re-running with `skip_if_exists: true` is safe |
| **Partial success** | Always inspect `summary.failed` and per-row `results[].error` |

---

## 4. Custom Fields

`custom_fields` is a free-form JSONB object on both contacts and deals. It is the recommended way to attach business-specific data without modifying the core schema.

### Where to send them

- Single create: `body.custom_fields`
- Bulk create: `body.deals[i].custom_fields` or `body.contacts[i].custom_fields`
- Update: PATCH the whole `custom_fields` object (replaces existing — merge client-side first)

### Naming rules

- Keys: `snake_case`, ASCII alphanumerics + underscore, ≤ 64 chars.
- Avoid keys starting with `_` (reserved).
- Total payload ≤ 32 KB.

### Supported value types

| Type | Example |
|---|---|
| string | `{"customer_type":"VIP"}` |
| number | `{"last_order_value":1200}` |
| boolean | `{"is_returning":true}` |
| date (ISO string) | `{"signup_date":"2026-04-22"}` |
| array | `{"interests":["sports","music"]}` |
| nested object | `{"address":{"city":"Cairo","zip":"11511"}}` |

### Pre-creation in dashboard

Custom fields **do not need to be pre-defined** to be stored. However, to make them visible as columns/filters in the CRM dashboard, an admin should register them in **Settings → Custom Fields**.

### Example

```json
{
 "title": "Order #68297792",
 "value": 11523,
 "contact_id": "f2b4f7ab-...",
 "custom_fields": {
 "shopify_order_id": "68297792",
 "payment_method": "mada",
 "is_gift": true,
 "delivered_at": "2026-04-25",
 "shipping_address": { "city": "Riyadh", "zip": "12345" }
 }
}
```

### Querying by custom field

```bash
# String equality
?custom_fields->>customer_type=eq.VIP

# Numeric comparison (cast required)
?custom_fields->>last_order_value=gt.1000

# Existence
?custom_fields=cs.{"is_gift":true}
```

---

## 5. Validation Rules

### Required fields

| Entity | Required |
|---|---|
| Contact | none strictly required, but at least one of `phones[]` / `emails[]` recommended |
| Deal (single) | `title`, `contact_id` |
| Deal (bulk) | `title` + one of `contact_id` / `contact_email` / `contact_phone` |

### Phone format (E.164)

- Normalized server-side via the platform.
- Must contain only digits and an optional leading `+`.
- After normalization: 8–15 digits.
- Whitespace, dashes, parentheses, dots are stripped.
- Numbers without `+` and ≥ 8 digits get `+` prepended.
- Stored example: `"+201017177777"`.

| Input | Stored as |
|---|---|
| `"+20 101 717 7777"` | `"+201017177777"` |
| `"201017177777"` | `"+201017177777"` |
| `"abc"` | rejected |

> ⚠️ **Provide numbers in proper E.164 with a leading `+` and country code.** A `00` international prefix is **not** auto-converted to `+`: an input like `"00201017177777"` simply gets a `+` prepended (yielding `"+00201017177777"`), which is not a valid E.164 number. Send `"+201017177777"` instead.

### Email validation

- Regex: `^[^\s@]+@[^\s@]+\.[^\s@]{2,}$`
- Lowercased before storage.

### Duplicate detection

| Endpoint | Logic |
|---|---|
| `/import-contacts-bulk` | Matches on email first, then on any phone (normalized to E.164). `skip_duplicates: true` skips matched rows; otherwise matched rows are merged |
| `/create-deals-bulk` | When `skip_if_exists: true`, matches on `(contact_id, title)` |
| `rest-api-proxy/contacts` POST | No automatic dedupe; caller responsible (search → create) |

### Linking rules

- A deal **must** link to exactly one `contact_id`. Deals without a contact are not visible in the dashboard pipeline.
- Multiple contacts on a deal: use the `deal_contacts` relation table (separate endpoint).
- `pipeline_id` defaults to the org's `is_default = true` pipeline; specifying an invalid pipeline returns `400`.

---

## 6. Best Practices

### Upsert pattern (recommended)

```text
1. SEARCH contact by phone or email
 GET /rest-api-proxy/contacts?phones=cs.{"+201017177777"}&limit=1
2. If found → reuse contact_id
 If not found → POST /rest-api-proxy/contacts
3. POST /rest-api-proxy/deals with the contact_id
```

For high-volume sources, use `/create-deals-bulk` with `create_contact_if_missing: true` and `skip_if_exists: true` — it does the upsert atomically per row.

### Bulk processing

- Cap each request to the documented max (500 contacts / 100 deals).
- Send batches sequentially or with controlled concurrency (≤ 5 in flight) to avoid rate limits.
- Always inspect `results[]` — never trust a `200` response alone.

### Retry strategy

- Retry on `5xx` and network errors with **exponential backoff** (1s, 2s, 4s, 8s, max 30s).
- Do **not** retry on `4xx` (bad payload) — fix and resend.
- Use idempotency keys at the row level: `custom_fields.external_id` + `skip_if_exists: true`.

### Rate limits

- Soft guideline: **120 requests/minute** per API key. Heavier loads may be throttled with HTTP `429`.
- Bulk endpoints count as **one** request regardless of batch size — prefer them for migrations.

### Logging

- Log the full `results` array from bulk responses so you can replay failed rows.
- Persist your own external ID → CRM ID mapping after each successful create.

### Webhook integrations

- For real-time syncing, register a webhook on the source system (Shopify, Stripe, your form) → forward payload to a small adapter → call the CRM API.
- Include the original event ID in `custom_fields.external_id` for traceability.

---

## 7. Full Example Flows

### 7.1 Create a contact

```bash
curl -X POST 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts' \
 -H 'X-API-Key: cg_xxx' -H 'Content-Type: application/json' \
 -H 'Prefer: return=representation' \
 -d '{
 "first_name": "Mahmoud", "last_name": "Ali",
 "phones": ["+201017177777"],
 "emails": ["mahmoud@example.com"],
 "source": "website",
 "custom_fields": { "signup_campaign": "spring2026" }
 }'
```

### 7.2 Update a contact (merge custom_fields safely)

```bash
# 1. Read current
curl -G '.../rest-api-proxy/contacts?id=eq.f2b4f7ab-...' \
 -H 'X-API-Key: cg_xxx' --data-urlencode 'select=custom_fields'

# 2. Merge in your code, then PATCH
curl -X PATCH '.../rest-api-proxy/contacts?id=eq.f2b4f7ab-...' \
 -H 'X-API-Key: cg_xxx' -H 'Content-Type: application/json' \
 -d '{ "custom_fields": { "signup_campaign":"spring2026", "last_login":"2026-04-23" } }'
```

### 7.3 Create a deal linked by contact_id

```bash
curl -X POST '.../rest-api-proxy/deals' \
 -H 'X-API-Key: cg_xxx' -H 'Content-Type: application/json' \
 -H 'Prefer: return=representation' \
 -d '{
 "title": "Order #68297792",
 "value": 11523, "currency": "SAR",
 "stage": "qualified",
 "contact_id": "f2b4f7ab-7033-47ce-be06-b30a47de020a",
 "source": "shopify",
 "custom_fields": { "shopify_order_id": "68297792" }
 }'
```

### 7.4 Bulk create deals (with auto-contact creation)

```bash
curl -X POST '.../create-deals-bulk' \
 -H 'X-API-Key: cg_xxx' -H 'Content-Type: application/json' \
 -d '{
 "default_currency": "SAR",
 "default_stage": "qualified",
 "skip_if_exists": true,
 "deals": [
 {
 "title": "Order #68297792", "value": 11523,
 "contact_phone": "+201017177777",
 "contact_first_name": "Mahmoud",
 "create_contact_if_missing": true,
 "custom_fields": { "external_id": "68297792" }
 },
 {
 "title": "Order #68297793", "value": 540,
 "contact_email": "noha@example.com",
 "contact_first_name": "Noha",
 "create_contact_if_missing": true,
 "custom_fields": { "external_id": "68297793" }
 }
 ]
 }'
```

### 7.5 Find a deal by external ID and mark it won

```bash
# 1. Find
curl -G '.../rest-api-proxy/deals' \
 -H 'X-API-Key: cg_xxx' \
 --data-urlencode 'custom_fields->>external_id=eq.68297792' \
 --data-urlencode 'select=id,title,stage' --data-urlencode 'limit=1'

# 2. Update
curl -X PATCH '.../rest-api-proxy/deals?id=eq.<deal-id>' \
 -H 'X-API-Key: cg_xxx' -H 'Content-Type: application/json' \
 -d '{ "stage": "won", "probability": 100 }'
```

---

## 8. Error Reference

| HTTP | Body example | Cause | Fix |
|---|---|---|---|
| `400` | `{"error":"title is required"}` | Missing required field | Validate payload before send |
| `400` | `{"error":"Maximum batch size is 100 deals"}` | Bulk size exceeded | Chunk batches |
| `400` | `{"error":"No pipeline found..."}` | Org has no pipelines | Create one in dashboard or pass `pipeline_id` |
| `401` | `{"error":"Unauthorized"}` | Missing/invalid `X-API-Key` | Re-issue key from Settings → API Keys |
| `404` | `[]` empty array on GET | No matching record | Verify filters (especially `cs.{}` syntax for arrays) |
| `409` | `{"error":"duplicate key..."}` | Unique constraint hit | Use upsert / `skip_if_exists` |
| `429` | `{"error":"rate limit"}` | Too many requests | Backoff and reduce concurrency |
| `500` | `{"error":"Internal server error","details":"..."}` | Server-side issue | Retry with backoff; report `details` |

### Common gotchas

| Symptom | Likely cause |
|---|---|
| Deal created but invisible in dashboard | `stage` was uppercase (`"QUALIFIED"`) — must be lowercase |
| `malformed array literal: "{ +201..."` | `+` not URL-encoded — use `--data-urlencode` or `%2B` |
| `is_new_contact: true` for known phone | The phone in storage uses a different format — normalize to E.164 with `+` |
| `custom_fields` got wiped after PATCH | PATCH replaces the object — read-merge-write |
| Bulk response `200` but rows missing | Check `summary.failed` and `results[].error` |

## See also

- [Deals API guide](https://docs.connectgain.cloud/07-api/contacts-and-deals/deals-api-guide.md) — practical walkthrough with common pitfalls.
- [Deals bulk behavior](https://docs.connectgain.cloud/07-api/contacts-and-deals/deals-bulk-behavior.md) — exactly how `create-deals-bulk` resolves contacts.
- [Proxy array search](https://docs.connectgain.cloud/07-api/contacts-and-deals/rest-api-proxy-array-search.md) — searching `phones[]`/`emails[]` correctly.
- [cURL samples](https://docs.connectgain.cloud/07-api/contacts-and-deals/curl-samples.md) — full request/response examples for every endpoint.
- [API key authentication](https://docs.connectgain.cloud/07-api/contacts-and-deals/api-key-authentication.md) — issuing and using `cg_` keys.

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/07-api/index.md)*

---

# ConnectGain API cURL Samples – Complete Examples

Source: https://docs.connectgain.cloud/07-api/curl-samples/

# ConnectGain API - Complete cURL Samples

**Base URL:** `https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1`

**Authentication:** All endpoints require `X-API-Key` header with your [API key](https://docs.connectgain.cloud/07-api/curl-samples/api-key-authentication.md) (prefix `cg_`).

---

## Table of Contents

1. [Create Single Contact](#1-create-single-contact)
2. [Create Bulk Contacts](#2-create-bulk-contacts)
3. [Create Single Lead with Deal](#3-create-single-lead-with-deal)
4. [Create Bulk Leads](#4-create-bulk-leads)
5. [Create Single Deal](#5-create-single-deal)
6. [Create Bulk Deals](#6-create-bulk-deals)

---

## 1. Create Single Contact

**Endpoint:** `POST /create-lead`

Creates a single contact/lead with optional deal creation.

### Minimal Request

```bash
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-lead' \
 --header 'X-API-Key: cg_YOUR_API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
 "first_name": "John",
 "last_name": "Doe",
 "email": "john.doe@example.com"
 }'
```

### Full Request (All Fields)

```bash
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-lead' \
 --header 'X-API-Key: cg_YOUR_API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
 "first_name": "John",
 "last_name": "Doe",
 "email": "john.doe@example.com",
 "emails": ["john.work@company.com", "john.personal@gmail.com"],
 "phone": "+1234567890",
 "phones": ["+1987654321", "+1555666777"],
 "source": "website_form",
 "tags": ["hot-lead", "enterprise", "demo-requested"],
 "description": "Interested in enterprise plan. Budget: $50k. Timeline: Q2 2025",
 "company_name": "Acme Corporation",
 "custom_fields": {
 "industry": "Technology",
 "company_size": "100-500",
 "job_title": "VP of Sales",
 "linkedin_url": "https://linkedin.com/in/johndoe",
 "referral_source": "Google Ads",
 "campaign_id": "spring_2025_campaign",
 "lead_score": 85
 },
 "deal": {
 "title": "Acme Corp - Enterprise License",
 "value": 50000,
 "currency": "USD",
 "stage": "qualified",
 "pipeline_id": "your-pipeline-uuid"
 }
 }'
```

### Response

```json
{
 "success": true,
 "message": "Lead created successfully",
 "data": {
 "contact": {
 "id": "uuid-of-contact",
 "first_name": "John",
 "last_name": "Doe",
 "emails": ["john.doe@example.com", "john.work@company.com"],
 "phones": ["+1234567890", "+1987654321"],
 "source": "website_form",
 "tags": ["hot-lead", "enterprise", "demo-requested"],
 "created_at": "2025-02-05T12:00:00Z"
 },
 "deal": {
 "id": "uuid-of-deal",
 "title": "Acme Corp - Enterprise License",
 "value": 50000,
 "currency": "USD",
 "stage": "qualified"
 },
 "is_new": true
 }
}
```

---

## 2. Create Bulk Contacts

**Endpoint:** `POST /import-contacts-bulk`

Import up to 500 contacts in a single request with duplicate detection and merge capabilities.

### Minimal Request

```bash
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/import-contacts-bulk' \
 --header 'X-API-Key: cg_YOUR_API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
 "contacts": [
 {
 "first_name": "Alice",
 "email": "alice@example.com"
 },
 {
 "first_name": "Bob",
 "phone": "+1234567890"
 }
 ]
 }'
```

### Full Request (All Fields)

```bash
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/import-contacts-bulk' \
 --header 'X-API-Key: cg_YOUR_API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
 "contacts": [
 {
 "first_name": "Alice",
 "last_name": "Smith",
 "email": "alice@example.com",
 "emails": ["alice.work@company.com"],
 "phone": "+1234567890",
 "phones": ["+1555123456"],
 "source": "trade_show",
 "tags": ["vip", "decision-maker"],
 "description": "Met at Tech Summit 2025. Very interested in AI features.",
 "company_id": "uuid-of-existing-company",
 "assignee_id": "uuid-of-sales-rep",
 "opt_in_status": true,
 "custom_fields": {
 "job_title": "CTO",
 "department": "Engineering",
 "budget_range": "$100k-$500k",
 "preferred_contact_time": "mornings",
 "timezone": "America/New_York"
 }
 },
 {
 "first_name": "Bob",
 "last_name": "Johnson",
 "email": "bob@company.com",
 "emails": ["bob.personal@gmail.com"],
 "phone": "+1987654321",
 "source": "referral",
 "tags": ["warm-lead", "sme"],
 "description": "Referred by Alice Smith",
 "opt_in_status": true,
 "custom_fields": {
 "job_title": "Director of Operations",
 "company_size": "50-100",
 "use_case": "Customer support automation"
 }
 },
 {
 "first_name": "Carol",
 "last_name": "Williams",
 "email": "carol@enterprise.com",
 "phone": "+1555888999",
 "source": "inbound",
 "tags": ["enterprise", "high-priority"],
 "company_name": "Enterprise Corp",
 "custom_fields": {
 "job_title": "VP of Customer Success",
 "current_solution": "Zendesk",
 "pain_points": ["slow response times", "lack of automation"],
 "contract_end_date": "2025-06-30"
 }
 }
 ],
 "skip_duplicates": false,
 "default_tags": ["import-feb-2025", "api-import"],
 "default_source": "api_bulk_import"
 }'
```

### Response

```json
{
 "success": true,
 "summary": {
 "total": 3,
 "successful": 3,
 "failed": 0,
 "new_contacts": 2,
 "updated_contacts": 1,
 "skipped_duplicates": 0
 },
 "results": [
 {
 "index": 0,
 "success": true,
 "contact_id": "uuid-1",
 "is_new": true
 },
 {
 "index": 1,
 "success": true,
 "contact_id": "uuid-2",
 "is_new": false
 },
 {
 "index": 2,
 "success": true,
 "contact_id": "uuid-3",
 "is_new": true
 }
 ]
}
```

---

## 3. Create Single Lead with Deal

Same as Create Single Contact but with deal creation.

```bash
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-lead' \
 --header 'X-API-Key: cg_YOUR_API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
 "first_name": "Enterprise",
 "last_name": "Client",
 "email": "procurement@enterprise.com",
 "phone": "+1800555000",
 "source": "enterprise_inquiry",
 "tags": ["enterprise", "priority", "q1-target"],
 "description": "Large enterprise account. Multiple stakeholders involved.",
 "custom_fields": {
 "company": "Fortune 500 Corp",
 "employees": 10000,
 "annual_revenue": "$1B+",
 "decision_timeline": "60 days"
 },
 "deal": {
 "title": "Fortune 500 Corp - Enterprise Suite",
 "value": 250000,
 "currency": "USD",
 "stage": "discovery",
 "pipeline_id": "enterprise-pipeline-uuid"
 }
 }'
```

---

## 4. Create Bulk Leads

**Endpoint:** `POST /create-leads-bulk`

Create up to 100 leads with duplicate handling.

### Full Request

```bash
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-leads-bulk' \
 --header 'X-API-Key: cg_YOUR_API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
 "leads": [
 {
 "first_name": "Lead",
 "last_name": "One",
 "email": "lead1@example.com",
 "phone": "+1111111111",
 "source": "facebook_ads",
 "tags": ["facebook", "cold-lead"],
 "description": "Downloaded whitepaper on AI automation",
 "custom_fields": {
 "campaign": "facebook_feb_2025",
 "ad_set": "lookalike_audience",
 "landing_page": "/whitepaper-ai"
 }
 },
 {
 "first_name": "Lead",
 "last_name": "Two",
 "email": "lead2@example.com",
 "phone": "+2222222222",
 "source": "google_ads",
 "tags": ["google", "warm-lead"],
 "description": "Requested pricing information",
 "custom_fields": {
 "campaign": "google_search_feb_2025",
 "keyword": "crm software pricing",
 "match_type": "exact"
 }
 },
 {
 "first_name": "Lead",
 "last_name": "Three",
 "email": "lead3@example.com",
 "phones": ["+3333333333", "+3333333334"],
 "source": "linkedin",
 "tags": ["linkedin", "decision-maker"],
 "description": "Connected via LinkedIn Sales Navigator",
 "custom_fields": {
 "linkedin_profile": "https://linkedin.com/in/leadthree",
 "mutual_connections": 5,
 "engagement_score": "high"
 }
 }
 ],
 "skip_duplicates": true
 }'
```

### Response

```json
{
 "success": true,
 "summary": {
 "total": 3,
 "successful": 3,
 "failed": 0,
 "new_contacts": 2,
 "updated_contacts": 0,
 "skipped_duplicates": 1
 },
 "results": [
 {"index": 0, "success": true, "contact_id": "uuid-1", "is_new": true},
 {"index": 1, "success": true, "contact_id": "uuid-2", "is_new": true},
 {"index": 2, "success": true, "contact_id": "uuid-3", "is_new": false}
 ]
}
```

---

## 5. Create Single Deal

Use the `/create-lead` endpoint with the `deal` parameter.

```bash
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-lead' \
 --header 'X-API-Key: cg_YOUR_API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
 "first_name": "Sarah",
 "last_name": "Connor",
 "email": "sarah@skynet.com",
 "deal": {
 "title": "Skynet - AI Platform License",
 "value": 75000,
 "currency": "USD",
 "stage": "negotiation",
 "pipeline_id": "your-pipeline-uuid"
 }
 }'
```

---

## 6. Create Bulk Deals

**Endpoint:** `POST /create-deals-bulk`

Create up to 100 deals with automatic contact resolution or creation.

### Minimal Request

```bash
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-deals-bulk' \
 --header 'X-API-Key: cg_YOUR_API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
 "deals": [
 {
 "title": "Deal One",
 "contact_email": "customer1@example.com",
 "value": 5000
 },
 {
 "title": "Deal Two",
 "contact_phone": "+1234567890",
 "value": 10000
 }
 ]
 }'
```

### Full Request (All Fields)

```bash
curl --location 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-deals-bulk' \
 --header 'X-API-Key: cg_YOUR_API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
 "deals": [
 {
 "contact_id": "uuid-of-existing-contact",
 "title": "Enterprise Agreement - Q1 2025",
 "value": 150000,
 "currency": "USD",
 "stage": "proposal",
 "pipeline_id": "enterprise-pipeline-uuid",
 "description": "Multi-year enterprise agreement with volume discounts",
 "expected_close_date": "2025-03-31",
 "probability": 75,
 "source": "enterprise_sales",
 "tags": ["enterprise", "multi-year", "priority"],
 "owner_id": "uuid-of-sales-rep",
 "company_id": "uuid-of-company",
 "custom_fields": {
 "contract_term": "3 years",
 "payment_terms": "net-30",
 "discount_percentage": 15,
 "stakeholders": ["CEO", "CTO", "CFO"],
 "competitor": "Salesforce",
 "implementation_timeline": "90 days"
 },
 "products": [
 {
 "name": "Enterprise License",
 "quantity": 500,
 "unit_price": 200
 },
 {
 "name": "Premium Support",
 "quantity": 1,
 "unit_price": 25000
 },
 {
 "name": "Implementation Services",
 "quantity": 1,
 "unit_price": 15000
 }
 ]
 },
 {
 "contact_email": "new.customer@startup.com",
 "create_contact_if_missing": true,
 "contact_first_name": "New",
 "contact_last_name": "Customer",
 "title": "Startup Growth Plan",
 "value": 12000,
 "currency": "USD",
 "stage": "qualified",
 "description": "Growing startup, interested in growth tier",
 "expected_close_date": "2025-02-28",
 "probability": 60,
 "source": "inbound",
 "tags": ["startup", "growth-tier", "saas"],
 "custom_fields": {
 "company_stage": "Series A",
 "team_size": 25,
 "current_mrr": "$50k",
 "use_case": "Sales automation"
 },
 "products": [
 {
 "name": "Growth Plan - Annual",
 "quantity": 1,
 "unit_price": 12000
 }
 ]
 },
 {
 "contact_phone": "+1555999888",
 "create_contact_if_missing": true,
 "contact_first_name": "Phone",
 "contact_last_name": "Lead",
 "title": "SMB Standard Package",
 "value": 3600,
 "currency": "USD",
 "stage": "discovery",
 "description": "Small business, monthly billing preferred",
 "expected_close_date": "2025-03-15",
 "probability": 40,
 "source": "phone_inquiry",
 "tags": ["smb", "monthly-billing"],
 "custom_fields": {
 "billing_preference": "monthly",
 "seats_needed": 10,
 "industry": "Retail"
 }
 }
 ],
 "default_pipeline_id": "main-pipeline-uuid",
 "default_stage": "new",
 "default_currency": "USD",
 "skip_if_exists": false
 }'
```

### Response

```json
{
 "success": true,
 "summary": {
 "total": 3,
 "successful": 3,
 "failed": 0,
 "new_deals": 3,
 "skipped_existing": 0,
 "new_contacts_created": 2
 },
 "results": [
 {
 "index": 0,
 "success": true,
 "deal_id": "deal-uuid-1",
 "contact_id": "contact-uuid-1",
 "is_new_contact": false
 },
 {
 "index": 1,
 "success": true,
 "deal_id": "deal-uuid-2",
 "contact_id": "contact-uuid-2",
 "is_new_contact": true
 },
 {
 "index": 2,
 "success": true,
 "deal_id": "deal-uuid-3",
 "contact_id": "contact-uuid-3",
 "is_new_contact": true
 }
 ]
}
```

---

## Field Reference

### Contact Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `first_name` | string | No* | Contact's first name |
| `last_name` | string | No* | Contact's last name |
| `email` | string | No* | Primary email address |
| `emails` | string[] | No | Additional email addresses |
| `phone` | string | No* | Primary phone number |
| `phones` | string[] | No | Additional phone numbers |
| `source` | string | No | Lead source (e.g., "website", "referral") |
| `tags` | string[] | No | Tags for categorization |
| `description` | string | No | Notes about the contact |
| `company_id` | uuid | No | Link to existing company |
| `company_name` | string | No | Company name (for reference) |
| `assignee_id` | uuid | No | Assigned team member |
| `opt_in_status` | boolean | No | Marketing consent status |
| `custom_fields` | object | No | Any custom key-value pairs |

*At least one of `first_name`, `last_name`, `email`, or `phone` is required.

### Deal Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | string | **Yes** | Deal title |
| `contact_id` | uuid | No* | Existing contact UUID |
| `contact_email` | string | No* | Find contact by email |
| `contact_phone` | string | No* | Find contact by phone |
| `value` | number | No | Deal value (default: 0) |
| `currency` | string | No | Currency code (default: "USD") |
| `stage` | string | No | Pipeline stage (default: "new") |
| `pipeline_id` | uuid | No | Pipeline UUID |
| `description` | string | No | Deal notes |
| `expected_close_date` | string | No | ISO date string |
| `probability` | number | No | Win probability (0-100) |
| `source` | string | No | Deal source |
| `tags` | string[] | No | Deal tags |
| `owner_id` | uuid | No | Deal owner (sales rep) |
| `company_id` | uuid | No | Associated company |
| `custom_fields` | object | No | Custom key-value pairs |
| `products` | array | No | Products/line items |
| `create_contact_if_missing` | boolean | No | Create contact if not found |
| `contact_first_name` | string | No | First name for new contact |
| `contact_last_name` | string | No | Last name for new contact |

*At least one of `contact_id`, `contact_email`, or `contact_phone` is required.

### Bulk Options

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `skip_duplicates` | boolean | false | Skip instead of merge duplicates |
| `default_tags` | string[] | [] | Apply to all contacts |
| `default_source` | string | "api" | Default source value |
| `default_pipeline_id` | uuid | null | Default pipeline for deals |
| `default_stage` | string | "new" | Default stage for deals |
| `default_currency` | string | "USD" | Default currency for deals |
| `skip_if_exists` | boolean | false | Skip if deal already exists |

---

## Error Handling

All endpoints return consistent error responses:

```json
{
 "error": "Error message description",
 "details": "Additional technical details (optional)"
}
```

### Common HTTP Status Codes

| Code | Description |
|------|-------------|
| 200 | Success (bulk operations) |
| 201 | Created (single contact/deal) |
| 400 | Bad Request - Invalid input |
| 401 | Unauthorized - Invalid API key |
| 405 | Method Not Allowed - Use POST |
| 500 | Internal Server Error |

---

## Rate Limits

- **Bulk Contacts:** Max 500 per request
- **Bulk Leads:** Max 100 per request
- **Bulk Deals:** Max 100 per request

For larger imports, split into multiple requests.

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/07-api/index.md)*

---

# Deals API Guide – Create, Search & Update ConnectGain Deals

Source: https://docs.connectgain.cloud/07-api/deals-api-guide/

# Deals & Contacts API Guide

Complete reference for creating deals, managing contacts, searching, updating, and storing external data.

## Table of Contents

1. [How Deals Work](#1-how-deals-work)
2. [Create a Single Deal](#2-create-a-single-deal-existing-contact-by-phone)
3. [Create a Deal with `create_contact_if_missing`](#3-create-a-deal-with-create_contact_if_missing)
4. [Search Deals by Title, then Update](#4-search-deals-by-title-contains--then-update)
5. [Search Contacts by Phone or Email](#5-search-contacts-by-phone-or-email)
6. [Storing External Data (`custom_fields`)](#6-storing-external-data-custom_fields)
7. [Common Pitfalls](#7-common-pitfalls)
8. [Useful Operators](#8-useful-operators-rest-proxy)

**Base URLs:**
- Bulk Deals: `https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-deals-bulk`
- REST Proxy: `https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy`

**Auth:** Header `X-API-Key: cg_your_api_key_here`

---

## 1. How Deals Work

Each deal in ConnectGain has:

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `title` | string | ✅ | Free-text deal name (e.g., "Order 12345") |
| `value` | number | ❌ | Numeric amount (NOT a string) |
| `currency` | string | ❌ | ISO 4217 (e.g., `SAR`, `USD`, `EUR`) |
| `stage` | string | ❌ | **Must be lowercase pipeline stage ID** |
| `contact_id` / `contact_phone` / `contact_email` | — | ✅ (one of) | How the deal links to a customer |
| `create_contact_if_missing` | bool | ❌ | Auto-create contact if not found |
| `expected_close_date` | ISO date | ❌ | e.g., `"2025-12-31"` |
| `probability` | 0–100 | ❌ | Win probability % |
| `source` | string | ❌ | e.g., `shopify`, `referral`, `website` |
| `tags` | string[] | ❌ | Free-form labels |
| `custom_fields` | object | ❌ | Any external structured data (JSON) |

### Valid stage values (default pipeline)
| Stage ID | Display |
|----------|---------|
| `new` | New |
| `lead` | Lead |
| `qualified` | Qualified |
| `proposal` | Proposal |
| `won` | Won |
| `lost` | Lost |

> ⚠️ Stages are **case-sensitive lowercase**. `"QUALIFIED"` will be saved but won't appear in the dashboard pipeline.

### How contact linking works
1. If `contact_id` is supplied → deal links directly.
2. Else if `contact_phone` or `contact_email` matches an existing contact → links to that one.
3. Else if `create_contact_if_missing: true` → creates a new contact and links it.
4. Else → request fails with `Contact not found`.

---

## 2. Create a Single Deal (existing contact by phone)

```bash
curl -X POST 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-deals-bulk' \
 -H 'X-API-Key: cg_your_api_key_here' \
 -H 'Content-Type: application/json' \
 -d '{
 "deals": [{
 "title": "Order 68297795",
 "value": 5000,
 "currency": "SAR",
 "stage": "new",
 "contact_phone": "+201017177777"
 }]
 }'
```

If the contact with phone `+201017177777` exists → deal is linked.
If not → request fails (no `create_contact_if_missing`).

---

## 3. Create a Deal with `create_contact_if_missing`

> ⚠️ **Common mistake fixed below**: `"stage": "QUALIFIED"` (uppercase) saves the deal but it won't appear in the dashboard pipeline. Always use lowercase: `"qualified"`.

### ❌ Wrong (deal created but invisible on dashboard)
```json
{
 "default_stage": "QUALIFIED",
 "deals": [{
 "title": "Order 68297792",
 "value": "11523.00",
 "contact": { "phone": "+201017177777" }
 }]
}
```
Problems: uppercase stage, value as string, nested `contact` object, no `create_contact_if_missing`.

### ✅ Correct bulk create with mixed contact lookup
```bash
curl -X POST 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-deals-bulk' \
 -H 'X-API-Key: cg_your_api_key_here' \
 -H 'Content-Type: application/json' \
 -d '{
 "default_currency": "SAR",
 "default_stage": "qualified",
 "skip_if_exists": true,
 "deals": [
 {
 "title": "Order 68297792",
 "value": 11523,
 "contact_phone": "+201017177777",
 "create_contact_if_missing": true,
 "contact_first_name": "Customer"
 },
 {
 "title": "Order 68297793",
 "value": 4500,
 "contact_phone": "+201020000000",
 "create_contact_if_missing": true,
 "contact_first_name": "Sara"
 },
 {
 "title": "Order 68297794",
 "value": 8900,
 "contact_email": "vip@example.com",
 "create_contact_if_missing": true,
 "contact_first_name": "VIP"
 }
 ]
 }'
```

### Fix existing deals saved with wrong stage casing
```bash
curl -X PATCH \
 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals?stage=eq.QUALIFIED' \
 -H 'X-API-Key: cg_your_api_key_here' \
 -H 'Content-Type: application/json' \
 -d '{ "stage": "qualified" }'
```

### Single deal with new contact
When the contact may or may not exist — let the API handle both cases:

```bash
curl -X POST 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-deals-bulk' \
 -H 'X-API-Key: cg_your_api_key_here' \
 -H 'Content-Type: application/json' \
 -d '{
 "deals": [{
 "title": "Order 68297796",
 "value": 8900,
 "currency": "SAR",
 "stage": "qualified",
 "contact_phone": "+201020000000",
 "contact_email": "sara@example.com",
 "contact_first_name": "Sara",
 "contact_last_name": "Ahmed",
 "create_contact_if_missing": true
 }]
 }'
```

Response includes `is_new_contact: true` if a new one was created.

### Bulk version with shared defaults
```bash
curl -X POST 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-deals-bulk' \
 -H 'X-API-Key: cg_your_api_key_here' \
 -H 'Content-Type: application/json' \
 -d '{
 "default_currency": "SAR",
 "default_stage": "qualified",
 "skip_if_exists": true,
 "deals": [
 {
 "title": "Order 1001",
 "value": 11523,
 "contact_phone": "+201017177777",
 "create_contact_if_missing": true,
 "contact_first_name": "Ahmed"
 },
 {
 "title": "Order 1002",
 "value": 4500,
 "contact_email": "sara@example.com",
 "create_contact_if_missing": true,
 "contact_first_name": "Sara"
 }
 ]
 }'
```

`skip_if_exists: true` prevents duplicate deals (same title + same contact).

---

## 4. Search Deals by Title (contains) → then Update

The REST proxy supports PostgREST `ilike` for case-insensitive partial match.

### Search deals where title contains "Order 6829"
```bash
curl -X GET \
 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals?title=ilike.*Order%206829*&order=created_at.desc' \
 -H 'X-API-Key: cg_your_api_key_here'
```

> URL-encode spaces as `%20`. The `*` acts as wildcard (`%` in SQL).

### Update all matching deals (e.g., move to `won`)
```bash
curl -X PATCH \
 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals?title=ilike.*Order%206829*' \
 -H 'X-API-Key: cg_your_api_key_here' \
 -H 'Content-Type: application/json' \
 -d '{
 "stage": "won",
 "probability": 100
 }'
```

### Update one deal by ID (recommended for safety)
```bash
curl -X PATCH \
 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals?id=eq.9ba51a0e-fa67-4fc2-8af7-6f4b9fedafc2' \
 -H 'X-API-Key: cg_your_api_key_here' \
 -H 'Content-Type: application/json' \
 -d '{
 "stage": "proposal",
 "value": 12000,
 "expected_close_date": "2025-12-31"
 }'
```

---

## 5. Search Contacts by Phone or Email

Phones and emails are stored as **arrays** → use the `cs` (contains) operator.

### Search by phone
```bash
curl -X GET \
 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?phones=cs.{%22%2B201017177777%22}' \
 -H 'X-API-Key: cg_your_api_key_here'
```
> `%22` = `"` and `%2B` = `+`. Decoded: `phones=cs.{"+201017177777"}`

### Search by email
```bash
curl -X GET \
 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?emails=cs.{%22sara@example.com%22}' \
 -H 'X-API-Key: cg_your_api_key_here'
```

### Search by name (partial, case-insensitive)
```bash
curl -X GET \
 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?first_name=ilike.*sara*' \
 -H 'X-API-Key: cg_your_api_key_here'
```

### Update a contact found by phone
```bash
curl -X PATCH \
 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?phones=cs.{%22%2B201017177777%22}' \
 -H 'X-API-Key: cg_your_api_key_here' \
 -H 'Content-Type: application/json' \
 -d '{
 "first_name": "Ahmed",
 "last_name": "Ali",
 "tags": ["vip", "shopify"]
 }'
```

---

## 6. Storing External Data (`custom_fields`)

Both **deals** and **contacts** have a `custom_fields` JSONB column for any external data (Shopify order ID, ERP ref, invoice number, anything).

### Deal with external Shopify metadata
```bash
curl -X POST 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-deals-bulk' \
 -H 'X-API-Key: cg_your_api_key_here' \
 -H 'Content-Type: application/json' \
 -d '{
 "deals": [{
 "title": "Shopify Order #68297797",
 "value": 7500,
 "currency": "SAR",
 "stage": "new",
 "source": "shopify",
 "contact_phone": "+201017177777",
 "create_contact_if_missing": true,
 "tags": ["shopify", "online"],
 "expected_close_date": "2025-12-15",
 "custom_fields": {
 "shopify_order_id": "68297797",
 "shopify_order_url": "https://mystore.myshopify.com/admin/orders/68297797",
 "payment_method": "mada",
 "shipping_city": "Riyadh",
 "items_count": 3,
 "external_invoice_ref": "INV-2025-0042"
 }
 }]
 }'
```

> ❌ Do **not** send `"custom_fields": "None"` (string). Either omit it or send a real object `{}`.

### Contact with external CRM/ERP IDs
```bash
curl -X POST 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts' \
 -H 'X-API-Key: cg_your_api_key_here' \
 -H 'Content-Type: application/json' \
 -d '{
 "first_name": "Sara",
 "last_name": "Ahmed",
 "emails": ["sara@example.com"],
 "phones": ["+201020000000"],
 "source": "external_erp",
 "tags": ["vip"],
 "custom_fields": {
 "erp_customer_id": "ERP-99821",
 "loyalty_tier": "gold",
 "lifetime_value": 45200,
 "preferred_language": "ar",
 "external_sync_at": "2025-04-22T10:00:00Z"
 }
 }'
```

### Update only `custom_fields` on an existing deal
```bash
curl -X PATCH \
 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals?id=eq.DEAL_UUID' \
 -H 'X-API-Key: cg_your_api_key_here' \
 -H 'Content-Type: application/json' \
 -d '{
 "custom_fields": {
 "tracking_number": "DHL-9988776655",
 "fulfillment_status": "shipped"
 }
 }'
```

> ⚠️ `custom_fields` is **replaced**, not merged. Always send the full object you want to keep.

---

## 7. Common Pitfalls

| Mistake | Fix |
|---------|-----|
| `"value": "11523.00"` (string) | Use number: `"value": 11523` |
| `"stage": "QUALIFIED"` | Lowercase: `"stage": "qualified"` |
| `"contact": { "phone": "..." }` (nested) | Flat: `"contact_phone": "..."` |
| `"custom_fields": "None"` | Omit, or use `{}` / a real object |
| Missing `create_contact_if_missing` → "Contact not found" | Add `"create_contact_if_missing": true` |
| Duplicate deals on retries | Add `"skip_if_exists": true` |

---

## 8. Useful Operators (REST proxy)

| Operator | Example | Meaning |
|----------|---------|---------|
| `eq` | `?stage=eq.won` | Equals |
| `neq` | `?stage=neq.lost` | Not equals |
| `gt`/`gte`/`lt`/`lte` | `?value=gte.1000` | Numeric comparisons |
| `ilike` | `?title=ilike.*order*` | Case-insensitive contains |
| `in` | `?stage=in.(new,qualified)` | In list |
| `cs` | `?phones=cs.{"+20101..."}` | Array contains |
| `is` | `?company_id=is.null` | Is null |
| `order` | `?order=created_at.desc` | Sort |
| `limit` | `?limit=50` | Page size |

## See also

- [Deals bulk behavior](https://docs.connectgain.cloud/07-api/deals-api-guide/deals-bulk-behavior.md) — contact resolution order in `create-deals-bulk`.
- [Contacts & Deals API](https://docs.connectgain.cloud/07-api/deals-api-guide/contacts-and-deals.md) — full field, validation, and error reference.
- [Proxy array search](https://docs.connectgain.cloud/07-api/deals-api-guide/rest-api-proxy-array-search.md) — encoding rules for phone/email searches.
- [cURL samples](https://docs.connectgain.cloud/07-api/deals-api-guide/curl-samples.md) — copy-paste requests for leads, contacts, and deals.
- [API key authentication](https://docs.connectgain.cloud/07-api/deals-api-guide/api-key-authentication.md) — where to generate your `cg_` key.

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/07-api/index.md)*

---

# create-deals-bulk Behavior – ConnectGain Bulk Deals API

Source: https://docs.connectgain.cloud/07-api/deals-bulk-behavior/

# `/create-deals-bulk` — Behavior Reference

Endpoint: `POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-deals-bulk`
Auth: `X-API-Key: cg_...`

## Table of Contents

1. [Contact resolution order](#1-contact-resolution-order-per-deal)
2. [Curl — existing contact](#2-curl--existing-contact-links-does-not-duplicate)
3. [Curl — `create_contact_if_missing: true`](#3-curl--create_contact_if_missing-true-new-contact)
4. [Search a contact by phone](#4-search-a-contact-by-phone-current-state-of-201017177777)
5. [Behavior cheat sheet](#5-behavior-cheat-sheet)

---

## 1. Contact resolution order (per deal)

For each deal in the `deals[]` array, the function resolves the contact in this exact order:

1. **`contact_id`** — if provided, used directly. No lookup, no creation.
2. **`contact_email`** — searches `contacts.emails` (array, case-sensitive `contains`) within the org.
3. **`contact_phone`** — searches `contacts.phones` (array, exact match) within the org.
4. **`create_contact_if_missing: true`** — only runs if steps 1–3 found nothing.

**Key point:** if a contact with that phone/email already exists in your org, the deal is **linked to the existing contact**. A new contact is **never** created when one is found. `is_new_contact: false` in the response confirms this.

---

## 2. Curl — existing contact (links, does NOT duplicate)

Phone `+201017177777` already exists as contact `f2b4f7ab-7033-47ce-be06-b30a47de020a` (mahmoud).

```bash
curl -X POST 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-deals-bulk' \
 -H 'X-API-Key: cg_your_api_key_here' \
 -H 'Content-Type: application/json' \
 -d '{
 "default_currency": "SAR",
 "default_stage": "qualified",
 "skip_if_exists": true,
 "deals": [
 {
 "title": "Order 68297792",
 "value": 11523,
 "contact_phone": "+201017177777",
 "create_contact_if_missing": true,
 "contact_first_name": "Customer"
 }
 ]
 }'
```

**Expected response:**
```json
{
 "results": [{
 "index": 0,
 "success": true,
 "deal_id": "...",
 "contact_id": "f2b4f7ab-7033-47ce-be06-b30a47de020a",
 "is_new_contact": false
 }],
 "summary": { "new_contacts_created": 0 }
}
```

The `contact_first_name: "Customer"` is **ignored** because the contact already exists — the existing record (mahmoud) is reused as-is. The bulk endpoint does **not** update existing contact fields.

---

## 3. Curl — `create_contact_if_missing: true` (new contact)

When no contact matches the phone/email, the function inserts a new row into `contacts` using **only these fields**:

| Source field | Goes into column |
|---|---|
| `contact_first_name` | `first_name` |
| `contact_last_name` | `last_name` |
| `contact_email` | `emails` (as `[email]`) |
| `contact_phone` | `phones` (as `[phone]`) |
| _hardcoded_ | `source = 'api'` |
| _hardcoded_ | `tags = ['deal-import']` |
| _hardcoded_ | `organization_id` (from API key) |

No other contact fields (company, custom_fields, description, assignee...) are accepted by this endpoint.

```bash
curl -X POST 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-deals-bulk' \
 -H 'X-API-Key: cg_your_api_key_here' \
 -H 'Content-Type: application/json' \
 -d '{
 "default_currency": "SAR",
 "default_stage": "qualified",
 "deals": [
 {
 "title": "Order 99999001",
 "value": 4500,
 "contact_phone": "+201020000099",
 "contact_email": "newlead@example.com",
 "contact_first_name": "Sara",
 "contact_last_name": "Hassan",
 "create_contact_if_missing": true
 }
 ]
 }'
```

**Result:** a new contact is created with `first_name=Sara`, `last_name=Hassan`, `emails=["newlead@example.com"]`, `phones=["+201020000099"]`, `source=api`, `tags=["deal-import"]`. The deal is linked to it. `is_new_contact: true`.

**You do NOT need a separate contact creation step** — the deal-level fields are sufficient for a properly populated contact.

### If you need richer contact data (company, custom_fields, description, etc.)

Create the contact first via the REST API proxy, then pass its `contact_id` to the bulk endpoint:

```bash
# Step 1 — create contact with full details
curl -X POST 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts' \
 -H 'X-API-Key: cg_...' -H 'Content-Type: application/json' \
 -d '{
 "first_name": "Sara",
 "last_name": "Hassan",
 "phones": ["+201020000099"],
 "emails": ["newlead@example.com"],
 "description": "VIP from Shopify",
 "tags": ["vip","shopify"],
 "custom_fields": { "shopify_customer_id": "12345" }
 }'
# → returns [{ "id": "uuid-..." }]

# Step 2 — create the deal with contact_id
curl -X POST 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/create-deals-bulk' \
 -H 'X-API-Key: cg_...' -H 'Content-Type: application/json' \
 -d '{ "deals": [{ "title": "Order...", "value": 4500, "contact_id": "uuid-..." }] }'
```

---

## 4. Search a contact by phone (current state of `+201017177777`)

```bash
curl -G 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts' \
 -H 'X-API-Key: cg_your_api_key_here' \
 --data-urlencode 'phones=cs.{"+201017177777"}' \
 --data-urlencode 'select=id,first_name,last_name,emails,phones,source,tags,created_at'
```

**Actual record currently in the DB for that phone:**
```json
[{
 "id": "f2b4f7ab-7033-47ce-be06-b30a47de020a",
 "first_name": "mahmoud",
 "last_name": null,
 "emails": ["issmail@gmail.com"],
 "phones": ["+201017177777"],
 "source": null,
 "tags": [],
 "created_at": "2026-04-22T16:00:58.354Z"
}]
```

Search by email instead:
```bash
curl -G '.../rest-api-proxy/contacts' \
 -H 'X-API-Key: cg_...' \
 --data-urlencode 'emails=cs.{"issmail@gmail.com"}'
```

---

## 5. Behavior cheat sheet

| Scenario | Result | `is_new_contact` |
|---|---|---|
| `contact_phone` matches existing | Deal linked to existing contact, name fields ignored | `false` |
| `contact_email` matches existing | Deal linked to existing contact | `false` |
| No match, `create_contact_if_missing: false` (or omitted) | Deal **fails** with "Contact not found" error | — |
| No match, `create_contact_if_missing: true` | New contact created from `contact_*` fields | `true` |
| `contact_id` provided | Used directly, no lookup | `false` |
| `skip_if_exists: true` + same `(contact_id, title)` exists | Returns existing `deal_id`, no new deal | `false` |

> ⚠️ The bulk endpoint **never updates** an existing contact. To enrich `mahmoud` with a proper `last_name`, company, etc., use a `PATCH` against `/rest-api-proxy/contacts?id=eq.f2b4f7ab-...`.

## See also

- [Deals API guide](https://docs.connectgain.cloud/07-api/deals-bulk-behavior/deals-api-guide.md) — creating, searching, and updating deals step by step.
- [Contacts & Deals API](https://docs.connectgain.cloud/07-api/deals-bulk-behavior/contacts-and-deals.md) — full field and validation reference.
- [cURL samples](https://docs.connectgain.cloud/07-api/deals-bulk-behavior/curl-samples.md) — complete request/response examples.
- [Proxy array search](https://docs.connectgain.cloud/07-api/deals-bulk-behavior/rest-api-proxy-array-search.md) — the `cs` operator and encoding rules.
- [API key authentication](https://docs.connectgain.cloud/07-api/deals-bulk-behavior/api-key-authentication.md) — issuing and using `cg_` keys.

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/07-api/index.md)*

---

# Inbox Filters cURL Reference – ConnectGain Conversations API

Source: https://docs.connectgain.cloud/07-api/inbox-filters-curls/

# Inbox Filters — cURL Reference

Base URL: `https://txpaxbxhnvnhsjwwaeoy.supabase.co`

Auth headers (use either):
- `Authorization: Bearer <SUPABASE_JWT>` (user session token)
- `apikey: <SUPABASE_ANON_KEY>` (required by PostgREST)

```bash
SUPABASE_URL="https://txpaxbxhnvnhsjwwaeoy.supabase.co"
ANON_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InR4cGF4YnhobnZuaHNqd3dhZW95Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NTc1NDQyMzAsImV4cCI6MjA3MzEyMDIzMH0.T2Rj5tc6ThGKQdDUymL3vNT7miiVsjCf4QfQeS_jVNg"
JWT="<your_user_jwt_here>"
```

> All filters are powered by the `conversations` table + 2 RPCs (remote procedure calls).
> RLS (Row Level Security) automatically scopes results to the caller's `organization_id`.

## Table of Contents

1. [All messages](#1-all-messages-no-filter)
2. [Unread conversations](#2-unread-conversations)
3. [Read conversations](#3-read-conversations)
4. [Assigned to me](#4-assigned-to-me)
5. [Unassigned](#5-unassigned)
6. [By status](#6-by-status-open--closed--pending)
7. [By channel type](#7-by-channel-type-instagram-whatsapp-messenger-etc)
8. [Instagram comments only](#8-instagram-comments-only)
9. [Facebook comments only](#9-facebook-comments-only)
10. [Important / starred](#10-important--starred)
11. [By tag](#11-by-tag)
12. [Search](#12-search-by-contact-name--phone)
13. [Unanswered count](#13-unanswered-count-sidebar-badge)

---

## 1. ALL MESSAGES (no filter)

Returns all conversations for the org, newest first.

```bash
curl -G "$SUPABASE_URL/rest/v1/conversations" \
 -H "apikey: $ANON_KEY" \
 -H "Authorization: Bearer $JWT" \
 --data-urlencode "select=*,contact:contacts!conversations_contact_id_fkey(id,first_name,last_name,phones,emails,tags),channel_account:channel_accounts(id,type,name),assignee:profiles!conversations_assignee_id_fkey(id,first_name,last_name)" \
 --data-urlencode "order=last_message_at.desc.nullslast" \
 --data-urlencode "limit=50"
```

---

## 2. UNREAD CONVERSATIONS

Two-step process: get the list of conversation IDs that have unread messages, then fetch their rows.

### Step 2a — Get unread counts (RPC)

```bash
curl -X POST "$SUPABASE_URL/rest/v1/rpc/get_conversation_unread_counts" \
 -H "apikey: $ANON_KEY" \
 -H "Authorization: Bearer $JWT" \
 -H "Content-Type: application/json" \
 -d '{}'
```

**Response:**
```json
[
 { "conversation_id": "uuid-1", "unread_count": 3 },
 { "conversation_id": "uuid-2", "unread_count": 1 }
]
```

### Step 2b — Fetch only those conversations

```bash
curl -G "$SUPABASE_URL/rest/v1/conversations" \
 -H "apikey: $ANON_KEY" \
 -H "Authorization: Bearer $JWT" \
 --data-urlencode "select=*,contact:contacts!conversations_contact_id_fkey(*),channel_account:channel_accounts(*)" \
 --data-urlencode "id=in.(uuid-1,uuid-2)" \
 --data-urlencode "order=last_message_at.desc"
```

---

## 3. READ CONVERSATIONS

Read = conversations whose IDs are NOT in the unread list. After fetching unread IDs from step 2a, exclude them:

```bash
curl -G "$SUPABASE_URL/rest/v1/conversations" \
 -H "apikey: $ANON_KEY" \
 -H "Authorization: Bearer $JWT" \
 --data-urlencode "select=*,contact:contacts!conversations_contact_id_fkey(*),channel_account:channel_accounts(*)" \
 --data-urlencode "id=not.in.(uuid-1,uuid-2)" \
 --data-urlencode "order=last_message_at.desc" \
 --data-urlencode "limit=50"
```

> Alternative (simpler heuristic): `last_read_at >= last_message_at`
>
> ```text
> --data-urlencode "or=(last_read_at.gte.last_message_at)"
> ```

---

## 4. ASSIGNED TO ME

```bash
curl -G "$SUPABASE_URL/rest/v1/conversations" \
 -H "apikey: $ANON_KEY" \
 -H "Authorization: Bearer $JWT" \
 --data-urlencode "select=*,contact:contacts!conversations_contact_id_fkey(*),channel_account:channel_accounts(*)" \
 --data-urlencode "assignee_id=eq.<your_user_id>" \
 --data-urlencode "order=last_message_at.desc"
```

---

## 5. UNASSIGNED

```bash
curl -G "$SUPABASE_URL/rest/v1/conversations" \
 -H "apikey: $ANON_KEY" \
 -H "Authorization: Bearer $JWT" \
 --data-urlencode "select=*,contact:contacts!conversations_contact_id_fkey(*),channel_account:channel_accounts(*)" \
 --data-urlencode "assignee_id=is.null" \
 --data-urlencode "order=last_message_at.desc"
```

---

## 6. BY STATUS (open / closed / pending)

```bash
curl -G "$SUPABASE_URL/rest/v1/conversations" \
 -H "apikey: $ANON_KEY" \
 -H "Authorization: Bearer $JWT" \
 --data-urlencode "status=eq.open" \
 --data-urlencode "order=last_message_at.desc"
```

Allowed values: `open`, `pending`, `resolved`, `closed`.

---

## 7. BY CHANNEL TYPE (Instagram, WhatsApp, Messenger, etc.)

Channels live in the `channel_accounts` table. Filter via embedded resource:

```bash
# Get all Instagram channel account IDs first
curl -G "$SUPABASE_URL/rest/v1/channel_accounts" \
 -H "apikey: $ANON_KEY" \
 -H "Authorization: Bearer $JWT" \
 --data-urlencode "select=id" \
 --data-urlencode "type=eq.INSTAGRAM"

# Then filter conversations
curl -G "$SUPABASE_URL/rest/v1/conversations" \
 -H "apikey: $ANON_KEY" \
 -H "Authorization: Bearer $JWT" \
 --data-urlencode "select=*,channel_account:channel_accounts!inner(id,type,name)" \
 --data-urlencode "channel_account.type=eq.INSTAGRAM" \
 --data-urlencode "order=last_message_at.desc"
```

Channel `type` values: `WHATSAPP_LITE`, `WHATSAPP_CLOUD`, `FB_MESSENGER`, `INSTAGRAM`, `TELEGRAM`, `TIKTOK`, `SHOPIFY_INBOX`, `BULK_EMAIL`, `LINKEDIN`.

---

## 8. INSTAGRAM COMMENTS ONLY

Comments are stored in the same `conversations` table but flagged with `metadata.is_comment_thread = true`.

```bash
curl -G "$SUPABASE_URL/rest/v1/conversations" \
 -H "apikey: $ANON_KEY" \
 -H "Authorization: Bearer $JWT" \
 --data-urlencode "select=*,channel_account:channel_accounts!inner(id,type,name)" \
 --data-urlencode "channel_account.type=eq.INSTAGRAM" \
 --data-urlencode "metadata->>is_comment_thread=eq.true" \
 --data-urlencode "order=last_message_at.desc"
```

### Instagram DMs only (exclude comments)

```bash
curl -G "$SUPABASE_URL/rest/v1/conversations" \
 -H "apikey: $ANON_KEY" \
 -H "Authorization: Bearer $JWT" \
 --data-urlencode "select=*,channel_account:channel_accounts!inner(id,type,name)" \
 --data-urlencode "channel_account.type=eq.INSTAGRAM" \
 --data-urlencode "or=(metadata->>is_comment_thread.is.null,metadata->>is_comment_thread.eq.false)" \
 --data-urlencode "order=last_message_at.desc"
```

---

## 9. FACEBOOK COMMENTS ONLY

```bash
curl -G "$SUPABASE_URL/rest/v1/conversations" \
 -H "apikey: $ANON_KEY" \
 -H "Authorization: Bearer $JWT" \
 --data-urlencode "select=*,channel_account:channel_accounts!inner(id,type,name)" \
 --data-urlencode "channel_account.type=eq.MESSENGER" \
 --data-urlencode "metadata->>is_comment_thread=eq.true" \
 --data-urlencode "order=last_message_at.desc"
```

---

## 10. IMPORTANT / STARRED

```bash
curl -G "$SUPABASE_URL/rest/v1/conversations" \
 -H "apikey: $ANON_KEY" \
 -H "Authorization: Bearer $JWT" \
 --data-urlencode "is_important=eq.true" \
 --data-urlencode "order=last_message_at.desc"
```

---

## 11. BY TAG

```bash
curl -G "$SUPABASE_URL/rest/v1/conversations" \
 -H "apikey: $ANON_KEY" \
 -H "Authorization: Bearer $JWT" \
 --data-urlencode 'tags=cs.{"vip"}' \
 --data-urlencode "order=last_message_at.desc"
```

---

## 12. SEARCH (by contact name / phone)

```bash
# Search contacts then filter conversations by contact_id
curl -G "$SUPABASE_URL/rest/v1/conversations" \
 -H "apikey: $ANON_KEY" \
 -H "Authorization: Bearer $JWT" \
 --data-urlencode "select=*,contact:contacts!inner(id,first_name,last_name,phones)" \
 --data-urlencode "contact.full_name_search=ilike.*john*" \
 --data-urlencode "order=last_message_at.desc"
```

---

## 13. UNANSWERED COUNT (sidebar badge)

```bash
curl -X POST "$SUPABASE_URL/rest/v1/rpc/get_unanswered_conversations_count" \
 -H "apikey: $ANON_KEY" \
 -H "Authorization: Bearer $JWT" \
 -H "Content-Type: application/json" \
 -d '{}'
```

**Response:** `42`

---

## Filter Combination Reference

| UI Filter | Endpoint / Filter |
|----------------------|-------------------|
| All messages | `GET /rest/v1/conversations` |
| Unread | RPC `get_conversation_unread_counts` → `id=in.(...)` |
| Read | `id=not.in.(unread_ids)` |
| Mine | `assignee_id=eq.<user_id>` |
| Unassigned | `assignee_id=is.null` |
| Open / Closed | `status=eq.open` |
| Instagram (all) | `channel_account.type=eq.INSTAGRAM` |
| Instagram comments | `+ metadata->>is_comment_thread=eq.true` |
| Instagram DMs | `+ metadata->>is_comment_thread.is.null` |
| Facebook comments | `channel_account.type=eq.MESSENGER + is_comment_thread=true` |
| WhatsApp | `channel_account.type=in.(WHATSAPP_LITE,WHATSAPP_CLOUD)` |
| Important | `is_important=eq.true` |
| Tag | `tags=cs.{"tag_name"}` |

---

**Notes:**
- All requests are RLS-scoped to the caller's organization automatically.
- Use `!inner` joins to filter by embedded resource columns (e.g. `channel_account.type`).
- JSONB fields use `->>` for text comparisons (e.g. `metadata->>is_comment_thread`).
- For pagination, append `&offset=N&limit=50`.

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/07-api/index.md)*

---

# ConnectGain Mobile API Reference

Source: https://docs.connectgain.cloud/07-api/mobile-api/

# Mobile API Documentation

**Base URL:** `https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/mobile-api`

---

## 1. Login

**`POST /login`** — No auth required

### Request
```json
{
 "email": "agent@company.com",
 "password": "secret123"
}
```

### Response (200)
```json
{
 "access_token": "eyJ...",
 "refresh_token": "abc...",
 "expires_in": 2592000,
 "user": {
 "id": "uuid",
 "first_name": "Ahmed",
 "last_name": "Ali",
 "email": "agent@company.com",
 "organization_id": "uuid",
 "avatar_url": null
 }
}
```

### Errors
| Status | Description |
|--------|-------------|
| 401 | Invalid credentials |
| 403 | Account deactivated/suspended |

---

## 2. List Contacts

**`GET /contacts`** — Bearer token required

### Headers
```
Authorization: Bearer <access_token>
```

### Query Parameters
| Param | Default | Description |
|---------|---------|---------------------------------|
| page | 1 | Page number |
| limit | 50 | Items per page (max 200) |
| search | | Search by name or phone number |

### Response (200)
```json
{
 "contacts": [
 {
 "id": "uuid",
 "first_name": "Sara",
 "last_name": "Hassan",
 "phones": ["+201001234567"],
 "emails": ["sara@example.com"],
 "tags": ["VIP"],
 "company_id": "uuid",
 "created_at": "2026-03-10T...",
 "updated_at": "2026-03-15T..."
 }
 ],
 "total": 150,
 "page": 1,
 "limit": 50,
 "total_pages": 3
}
```

---

## 3. View Single Contact

**`GET /contacts/:id`** — Bearer token required

### Headers
```
Authorization: Bearer <access_token>
```

### Response (200)
```json
{
 "id": "uuid",
 "first_name": "Sara",
 "last_name": "Hassan",
 "phones": ["+201001234567"],
 "emails": ["sara@example.com"],
 "tags": ["VIP"],
 "description": "Key account",
 "company_id": "uuid",
 "assignee_id": "uuid",
 "source": "whatsapp",
 "opt_in_status": true,
 "custom_fields": {},
 "created_at": "2026-03-10T...",
 "updated_at": "2026-03-15T...",
 "company": { "id": "uuid", "name": "Acme Corp" }
}
```

---

## 4. Upload Call Recording

**`POST /call-recording`** — Bearer token required, `multipart/form-data`

### Headers
```
Authorization: Bearer <access_token>
Content-Type: multipart/form-data
```

### Form Fields
| Field | Required | Description |
|-------------------|----------|--------------------------------------------------|
| file | ✅ | Audio file (MP3, M4A, WAV, OGG, WebM, AAC, 3GP, AMR). Max 50 MB |
| contact_id | | UUID of the contact (if known) |
| customer_phone | | Phone number — used to auto-match contact if `contact_id` is empty |
| duration_seconds | | Call duration in seconds |
| call_timestamp | | ISO 8601 timestamp (defaults to now) |
| direction | | `inbound` (default) or `outbound` |
| notes | | Free-text notes about the call |

### Response (200)
```json
{
 "success": true,
 "call_record_id": "uuid",
 "status": "received",
 "contact_matched": true,
 "recording_stored": true
}
```

### Processing Pipeline
After upload, the recording is automatically processed:
1. **Transcription** — Speech-to-text (Arabic/English optimized)
2. **AI Analysis** — Sentiment, keywords, action items, summary
3. **Timeline** — Results appear on the contact's activity timeline

### Errors
| Status | Description |
|--------|-------------|
| 400 | Missing file or unsupported format |
| 401 | Invalid/expired token |
| 403 | Account deactivated/suspended |
| 500 | Upload or processing failure |

---

## cURL Examples

### Login
```bash
curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/mobile-api/login \
 -H "Content-Type: application/json" \
 -d '{"email":"agent@company.com","password":"secret123"}'
```

### List Contacts
```bash
curl https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/mobile-api/contacts?page=1&limit=20 \
 -H "Authorization: Bearer <access_token>"
```

### Upload Recording
```bash
curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/mobile-api/call-recording \
 -H "Authorization: Bearer <access_token>" \
 -F "file=@recording.mp3" \
 -F "customer_phone=+201001234567" \
 -F "duration_seconds=180" \
 -F "direction=outbound" \
 -F "notes=Follow up on pricing"
```

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/07-api/index.md)*

---

# ConnectGain API Overview – Edge Functions, REST & External APIs

Source: https://docs.connectgain.cloud/07-api/overview/

# ConnectGain API Overview

## Overview

ConnectGain provides three types of APIs:

1. **Supabase Edge Functions** - Custom serverless functions
2. **Supabase REST API** - Direct database access
3. **External APIs** - APIs for external systems (using API keys)

---

## Table of Contents

1. [Authentication](#authentication)
2. [Edge Functions API](#edge-functions-api)
3. [External APIs](#external-apis)
4. [REST API - Contacts](#rest-api---contacts)
5. [REST API - Deals/Leads](#rest-api---dealsleads)
6. [REST API - Conversations](#rest-api---conversations)
7. [REST API - Messages](#rest-api---messages)
8. [REST API - Tasks](#rest-api---tasks)
9. [Error Responses](#error-responses)

---

## Base Configuration

**Base URL:** `https://txpaxbxhnvnhsjwwaeoy.supabase.co`
**REST API URL:** `/rest/v1/`
**Functions URL:** `/functions/v1/`

---

## Authentication

### Standard Authentication (Bearer Token)

Most APIs use Bearer token authentication:

```bash
Authorization: Bearer YOUR_ANON_KEY
apikey: YOUR_ANON_KEY
```

Get your anon key from: Supabase Dashboard → Settings → API

### API Key Authentication (External Systems)

External APIs use `X-API-Key` header:

```bash
X-API-Key: cg_abc123def456...
```

API keys are generated per organization and can be created via the [Create API Key](#generate-api-key) endpoint.

---

## Edge Functions API

### Send Messages

#### WhatsApp Lite - Send Message

**Endpoint:** `POST /functions/v1/whatsapp-lite-send`

**Headers:**
```bash
Authorization: Bearer YOUR_ANON_KEY
Content-Type: application/json
```

**Body:**
```json
{
 "to": "201001383533",
 "message": "Hello!",
 "organizationId": "org-uuid",
 "contactName": "John Doe",
 "from": "AIBot",
 "conversationId": "conv-uuid"
}
```

**Curl:**
```bash
curl -X POST https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/whatsapp-lite-send \
 -H "Authorization: Bearer YOUR_ANON_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "to": "201001383533",
 "message": "Hello!",
 "from": "AIBot"
 }'
```

**Response:**
```json
{
 "success": true,
 "result": {
 "messageId": "message_id",
 "id": "message_id"
 },
 "conversationId": "conv-uuid",
 "contactId": "contact-uuid"
}
```

See the [WhatsApp Lite API guide](https://docs.connectgain.cloud/07-api/05-integrations/whatsapp-lite-api.md) for complete WhatsApp documentation.

#### WhatsApp Cloud - Send Message

**Endpoint:** `POST /functions/v1/whatsapp-cloud-send`

**Body:**
```json
{
 "to": "phone_number",
 "message": "Hello via Cloud API!",
 "conversationId": "conv-uuid",
 "accessToken": "facebook_access_token",
 "phoneNumberId": "phone_number_id"
}
```

#### Messenger - Send Message

**Endpoint:** `POST /functions/v1/messenger-send`

**Body:**
```json
{
 "to": "user_psid",
 "message": "Hello via Messenger!",
 "conversationId": "conv-uuid",
 "accessToken": "messenger_access_token"
}
```

#### Instagram - Send Message

**Endpoint:** `POST /functions/v1/instagram-send`

**Body:**
```json
{
 "to": "instagram_user_id",
 "message": "Hello via Instagram!",
 "conversationId": "conv-uuid"
}
```

#### Telegram - Send Message

**Endpoint:** `POST /functions/v1/telegram-send`

**Body:**
```json
{
 "to": "telegram_chat_id",
 "message": "Hello via Telegram!",
 "conversationId": "conv-uuid"
}
```

#### TikTok - Send Message

**Endpoint:** `POST /functions/v1/tiktok-send`

**Body:**
```json
{
 "to": "tiktok_user_id",
 "message": "Hello via TikTok!",
 "conversationId": "conv-uuid"
}
```

### Search & Utilities

#### Search Contacts

**Endpoint:** `POST /functions/v1/search-contacts`

**Headers:**
```bash
Authorization: Bearer YOUR_ANON_KEY
Content-Type: application/json
```

**Body:**
```json
{
 "searchTerm": "John",
 "tags": ["customer", "vip"],
 "dealStatus": "open"
}
```

**Response:**
```json
{
 "contacts": [
 {
 "id": "uuid",
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+1234567890"],
 "emails": ["john@example.com"],
 "tags": ["customer"]
 }
 ],
 "count": 1
}
```

#### Search Companies

**Endpoint:** `POST /functions/v1/search-companies`

**Body:**
```json
{
 "searchTerm": "Acme",
 "country": "US"
}
```

#### List Organizations

**Endpoint:** `GET /functions/v1/list-organizations`

**Response:**
```json
{
 "organizations": [
 {
 "id": "uuid",
 "name": "Organization Name",
 "hasAppgainCredentials": true
 }
 ],
 "count": 1
}
```

### Payments

#### Create Stripe Checkout

**Endpoint:** `POST /functions/v1/create-checkout`

**Body:**
```json
{
 "priceId": "price_xxxxx",
 "couponCode": "optional_coupon"
}
```

#### Get Customer Portal URL

**Endpoint:** `GET /functions/v1/customer-portal`

**Response:**
```json
{
 "url": "https://billing.stripe.com/p/portal/..."
}
```

---

## External APIs

These APIs use `X-API-Key` header for authentication and are designed for external systems to integrate with ConnectGain.

### Insert Message

**Endpoint:** `POST /functions/v1/insert-message`

**Headers:**
```bash
X-API-Key: cg_abc123def456...
Content-Type: application/json
```

**Body:**
```json
{
 "phone": "201001383533",
 "content": "Hello from external system!",
 "direction": "outgoing",
 "status": "sent"
}
```

**Curl:**
```bash
curl -X POST \
 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/insert-message' \
 -H 'X-API-Key: cg_abc123def456...' \
 -H 'Content-Type: application/json' \
 -d '{
 "phone": "201001383533",
 "content": "Hello from external system!",
 "direction": "outgoing",
 "status": "sent"
 }'
```

**Response:**
```json
{
 "success": true,
 "messageId": "message-uuid",
 "conversationId": "conversation-uuid",
 "contactId": "contact-uuid"
}
```

**Description:**
Inserts a message into the ConnectGain system. The system will:
- Find or create a contact based on the phone number
- Find or create a conversation for the contact
- Insert the message with the specified direction and status

**Parameters:**
- `phone` (required): Phone number in international format (e.g., "201001383533")
- `content` (required): Message content/text
- `direction` (required): Message direction - "incoming" or "outgoing"
- `status` (required): Message status - "sent", "received", "delivered", "failed", etc.

### Generate API Key

**Endpoint:** `POST /functions/v1/generate-api-key`

**Headers:**
```bash
Authorization: Bearer YOUR_ANON_KEY
Content-Type: application/json
```

**Body:**
```json
{
 "name": "External System Integration",
 "organizationId": "org-uuid"
}
```

**Curl:**
```bash
curl -X POST \
 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/generate-api-key' \
 -H 'Authorization: Bearer YOUR_ANON_KEY' \
 -H 'Content-Type: application/json' \
 -d '{
 "name": "External System Integration",
 "organizationId": "org-uuid"
 }'
```

**Response:**
```json
{
 "success": true,
 "api_key": "cg_abc123def456...",
 "key_info": {
 "id": "key-uuid",
 "name": "External System Integration",
 "key_prefix": "cg_abc123",
 "expires_at": null,
 "created_at": "2025-01-15T10:30:00Z"
 },
 "warning": "Store this key now — it will not be shown again."
}
```

**Description:**
Creates a new API key for your organization. API keys are prefixed with `cg_` and can be used with external APIs that require `X-API-Key` header authentication.

**Important:** Store the API key securely immediately after creation, as it will not be shown again.

**Parameters:**
- `name` (required): Descriptive name for the API key (e.g., "Production API", "Development Integration")
- `organizationId` (required): Your organization UUID

---

## REST API - Contacts

### List All Contacts

**Endpoint:** `GET /rest/v1/contacts`

**Query Parameters:**
- `select=*` - Select all fields
- `limit=100` - Limit results
- `offset=0` - Pagination
- `organization_id=eq.{org_id}` - Filter by organization

**Curl:**
```bash
curl -X GET "https://txpaxbxhnvnhsjwwaeoy.supabase.co/rest/v1/contacts?select=*" \
 -H "apikey: YOUR_ANON_KEY" \
 -H "Authorization: Bearer YOUR_ANON_KEY"
```

**Response:**
```json
[
 {
 "id": "uuid",
 "organization_id": "uuid",
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+1234567890"],
 "emails": ["john@example.com"],
 "tags": ["customer"],
 "custom_fields": {},
 "opt_in_status": true,
 "created_at": "2025-01-01T00:00:00Z",
 "updated_at": "2025-01-01T00:00:00Z"
 }
]
```

### Get Single Contact

**Endpoint:** `GET /rest/v1/contacts?id=eq.{contact_id}`

### Create Contact

**Endpoint:** `POST /rest/v1/contacts`

**Body:**
```json
{
 "organization_id": "org-uuid",
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+1234567890"],
 "emails": ["john@example.com"],
 "tags": ["customer", "vip"],
 "custom_fields": {
 "company": "Acme Inc",
 "position": "Manager"
 },
 "opt_in_status": true
}
```

### Update Contact

**Endpoint:** `PATCH /rest/v1/contacts?id=eq.{contact_id}`

**Body:**
```json
{
 "first_name": "Jane",
 "last_name": "Smith",
 "tags": ["customer", "vip", "priority"]
}
```

### Delete Contact

**Endpoint:** `DELETE /rest/v1/contacts?id=eq.{contact_id}`

### Search Contacts

**Endpoint:** `GET /rest/v1/contacts?first_name=ilike.*John*`

---

## REST API - Deals/Leads

### List All Deals

**Endpoint:** `GET /rest/v1/deals`

**With Relations:**
```text
GET /rest/v1/deals?select=*,contacts(*),profiles!deals_owner_id_fkey(*)
```

### Get Single Deal

**Endpoint:** `GET /rest/v1/deals?id=eq.{deal_id}`

### Create Deal (Lead)

**Endpoint:** `POST /rest/v1/deals`

**Body:**
```json
{
 "organization_id": "org-uuid",
 "contact_id": "contact-uuid",
 "pipeline_id": "pipeline-uuid",
 "title": "New Lead - John Doe",
 "stage": "lead",
 "value": 5000,
 "probability": 10,
 "expected_close_date": "2025-02-15",
 "custom_fields": {
 "source": "website",
 "priority": "high"
 }
}
```

### Update Deal Stage

**Endpoint:** `PATCH /rest/v1/deals?id=eq.{deal_id}`

**Body:**
```json
{
 "stage": "qualified",
 "probability": 50,
 "value": 7500
}
```

### Delete Deal

**Endpoint:** `DELETE /rest/v1/deals?id=eq.{deal_id}`

### Filter Deals by Stage

**Endpoint:** `GET /rest/v1/deals?stage=eq.lead`

---

## REST API - Conversations

### List All Conversations

**Endpoint:** `GET /rest/v1/conversations`

**With Relations:**
```text
GET /rest/v1/conversations?select=*,contacts(*),channel_accounts(*),profiles!conversations_assignee_id_fkey(*)
```

### Get Single Conversation

**Endpoint:** `GET /rest/v1/conversations?id=eq.{conversation_id}`

### Create Conversation

**Endpoint:** `POST /rest/v1/conversations`

**Body:**
```json
{
 "organization_id": "org-uuid",
 "contact_id": "contact-uuid",
 "channel_account_id": "channel-uuid",
 "status": "OPEN",
 "tags": ["urgent", "customer"]
}
```

### Update Conversation

**Endpoint:** `PATCH /rest/v1/conversations?id=eq.{conversation_id}`

**Body:**
```json
{
 "status": "CLOSED",
 "assignee_id": "user-uuid"
}
```

### Assign Conversation

**Endpoint:** `PATCH /rest/v1/conversations?id=eq.{conversation_id}`

**Body:**
```json
{
 "assignee_id": "user-uuid"
}
```

### Delete Conversation

**Endpoint:** `DELETE /rest/v1/conversations?id=eq.{conversation_id}`

### Filter Open Conversations

**Endpoint:** `GET /rest/v1/conversations?status=eq.OPEN`

---

## REST API - Messages

### List Messages for Conversation

**Endpoint:** `GET /rest/v1/messages?conversation_id=eq.{conversation_id}`

**Ordered:**
```text
GET /rest/v1/messages?conversation_id=eq.{conversation_id}&order=created_at.asc
```

### Create Message

**Endpoint:** `POST /rest/v1/messages`

**Body:**
```json
{
 "organization_id": "org-uuid",
 "conversation_id": "conversation-uuid",
 "contact_id": "contact-uuid",
 "direction": "OUTBOUND",
 "content": "Hello! This is a test message.",
 "status": "SENT",
 "metadata": {
 "sender_name": "AIBot"
 }
}
```

### Update Message Status

**Endpoint:** `PATCH /rest/v1/messages?id=eq.{message_id}`

**Body:**
```json
{
 "status": "DELIVERED"
}
```

### Delete Message

**Endpoint:** `DELETE /rest/v1/messages?id=eq.{message_id}`

---

## REST API - Tasks

### List All Tasks

**Endpoint:** `GET /rest/v1/tasks`

**With Relations:**
```text
GET /rest/v1/tasks?select=*,contacts(*)
```

**Filter Incomplete:**
```text
GET /rest/v1/tasks?completed=eq.false
```

### Create Task

**Endpoint:** `POST /rest/v1/tasks`

**Body:**
```json
{
 "organization_id": "org-uuid",
 "contact_id": "contact-uuid",
 "title": "Follow up with customer",
 "description": "Call to discuss pricing",
 "due_date": "2025-01-30T12:00:00Z",
 "completed": false
}
```

### Mark Task Complete

**Endpoint:** `PATCH /rest/v1/tasks?id=eq.{task_id}`

**Body:**
```json
{
 "completed": true
}
```

### Delete Task

**Endpoint:** `DELETE /rest/v1/tasks?id=eq.{task_id}`

---

## Error Responses

**400 Bad Request:**
```json
{
 "message": "Error message",
 "details": "Detailed error information"
}
```

**401 Unauthorized:**
```json
{
 "message": "JWT expired"
}
```

**403 Forbidden:**
```json
{
 "message": "Invalid API key"
}
```

**404 Not Found:**
```json
{
 "message": "Could not find resource"
}
```

**500 Internal Server Error:**
```json
{
 "message": "Internal server error",
 "error": "Error details"
}
```

---

## Postman Collection

Download the official collection from the [Postman collection page](https://docs.connectgain.cloud/07-api/overview/postman.md) ([direct download](https://docs.connectgain.cloud/07-api/overview/connectgain.postman_collection.json)).

### Setting Up Variables

1. Import collection into Postman
2. Set collection variables:
 - `url`: `https://txpaxbxhnvnhsjwwaeoy.supabase.co`
 - `anon_key`: Your Supabase anon key
 - `api_key`: Your ConnectGain API key (for external APIs)
 - `organization_id`: Your organization UUID
 - `contact_id`: Test contact ID
 - `deal_id`: Test deal ID
 - `conversation_id`: Test conversation ID
 - `message_id`: Test message ID

3. Start testing APIs!

---

## Complete CRUD Examples

### Complete Contact Workflow

```bash
# 1. List contacts
curl -X GET "{{url}}/rest/v1/contacts" \
 -H "apikey: {{anon_key}}" \
 -H "Authorization: Bearer {{anon_key}}"

# 2. Create contact
curl -X POST "{{url}}/rest/v1/contacts" \
 -H "apikey: {{anon_key}}" \
 -H "Authorization: Bearer {{anon_key}}" \
 -H "Content-Type: application/json" \
 -d '{"organization_id": "{{organization_id}}", "first_name": "John", "last_name": "Doe"}'

# 3. Update contact (use contact_id from step 2)
curl -X PATCH "{{url}}/rest/v1/contacts?id=eq.CONTACT_UUID" \
 -H "apikey: {{anon_key}}" \
 -H "Authorization: Bearer {{anon_key}}" \
 -H "Content-Type: application/json" \
 -d '{"first_name": "Jane"}'

# 4. Delete contact
curl -X DELETE "{{url}}/rest/v1/contacts?id=eq.CONTACT_UUID" \
 -H "apikey: {{anon_key}}" \
 -H "Authorization: Bearer {{anon_key}}"
```

### Complete Deal Workflow

```bash
# 1. Create deal
curl -X POST "{{url}}/rest/v1/deals" \
 -H "apikey: {{anon_key}}" \
 -H "Authorization: Bearer {{anon_key}}" \
 -H "Content-Type: application/json" \
 -d '{
 "organization_id": "{{organization_id}}",
 "contact_id": "{{contact_id}}",
 "pipeline_id": "{{pipeline_id}}",
 "title": "New Deal",
 "stage": "lead",
 "value": 5000
 }'

# 2. Move deal to qualified
curl -X PATCH "{{url}}/rest/v1/deals?id=eq.DEAL_UUID" \
 -H "apikey: {{anon_key}}" \
 -H "Authorization: Bearer {{anon_key}}" \
 -H "Content-Type: application/json" \
 -d '{"stage": "qualified", "probability": 50}'

# 3. Close as won
curl -X PATCH "{{url}}/rest/v1/deals?id=eq.DEAL_UUID" \
 -H "apikey: {{anon_key}}" \
 -H "Authorization: Bearer {{anon_key}}" \
 -H "Content-Type: application/json" \
 -d '{"stage": "closed_won", "probability": 100}'
```

### External System Integration Example

```bash
# 1. Create API key
curl -X POST "{{url}}/functions/v1/generate-api-key" \
 -H "Authorization: Bearer {{anon_key}}" \
 -H "Content-Type: application/json" \
 -d '{
 "name": "External System Integration",
 "organizationId": "{{organization_id}}"
 }'

# 2. Use API key to insert message
curl -X POST "{{url}}/functions/v1/insert-message" \
 -H "X-API-Key: cg_abc123def456..." \
 -H "Content-Type: application/json" \
 -d '{
 "phone": "201001383533",
 "content": "Hello from external system!",
 "direction": "outgoing",
 "status": "sent"
 }'
```

---

## Notes

- All timestamps are in ISO 8601 format
- JSONB fields support nested objects
- Arrays (tags, phones, emails) work with standard JSON arrays
- Relations can be fetched using `select` parameter
- Filtering uses PostgREST syntax: `column=eq.value`
- Supports `order`, `limit`, `offset` for pagination
- API keys are prefixed with `cg_` and should be kept secure
- External APIs (using X-API-Key) are scoped to the organization that created the key

---

**Complete Documentation:** See the [WhatsApp Lite API guide](https://docs.connectgain.cloud/07-api/05-integrations/whatsapp-lite-api.md) for detailed WhatsApp Lite edge functions documentation.

## See also

- [Complete API reference](https://docs.connectgain.cloud/07-api/overview/complete-api.md) — the full endpoint, field, and error reference.
- [API key authentication](https://docs.connectgain.cloud/07-api/overview/api-key-authentication.md) — which key and header to use for each API type.
- [Contacts & Deals API](https://docs.connectgain.cloud/07-api/overview/contacts-and-deals.md) — pushing CRM data from external systems.
- [cURL samples](https://docs.connectgain.cloud/07-api/overview/curl-samples.md) — ready-to-run requests for leads, contacts, and deals.
- [Webhooks overview](https://docs.connectgain.cloud/07-api/08-webhooks/overview.md) — receiving events from ConnectGain.

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/07-api/index.md)*

---

# Postman Collection

Source: https://docs.connectgain.cloud/07-api/postman/

# Postman Collection

Use the official ConnectGain Postman collection to explore and test the public REST API without writing any code.

[:material-download: Download the ConnectGain collection](https://docs.connectgain.cloud/07-api/postman/connectgain.postman_collection.json){.md-button.md-button--primary download="ConnectGain.postman_collection.json" }

## What's inside

Every request in this collection authenticates the same way — with a `cg_` **API key** in the `X-API-Key` header — so it maps to the public integration API surface:

- **Search** — search contacts and companies
- **Messages** — insert an inbound message from an external system
- **Leads & Deals** — single and bulk lead creation, bulk deal ingestion, bulk contact import
- **Call Intelligence** — call-recording webhook ingestion
- **Organizations** — list your organizations by API key

!!! note "API-key endpoints only"
 This collection is intentionally scoped to endpoints that authenticate with an **API key**. Platform-admin endpoints are internal and excluded. The JWT-authenticated Supabase REST endpoints (contacts, deals, conversations, …) are documented on the [Complete API Reference](https://docs.connectgain.cloud/07-api/postman/complete-api.md) and [REST API cURL Examples](https://docs.connectgain.cloud/07-api/postman/rest-api-curl-examples.md) pages — use a signed-in user session for those.

See the [Complete API Reference](https://docs.connectgain.cloud/07-api/postman/complete-api.md) for the full endpoint list and the [Authentication guide](https://docs.connectgain.cloud/07-api/postman/api-key-authentication.md) for how keys work.

## Import & configure

1. In Postman, choose **Import** and select the downloaded `ConnectGain.postman_collection.json` file.
2. Set the `url` collection variable — for production use the Edge Functions base from the [API Overview](https://docs.connectgain.cloud/07-api/postman/overview.md).
3. Set the `api_key` collection variable to your key. Every request sends it as:

 ```http
 X-API-Key: cg_your_api_key_here
 ```

 Generate a key in the app under **Settings → Storage & Developer → API Keys**. Keys are prefixed `cg_`. Keep them secret — treat a key like a password.

## Authentication recap

This collection's endpoints authenticate with **`cg_`-prefixed API keys** sent in the `X-API-Key` header. Full details, scopes and rotation are in [API Authentication](https://docs.connectgain.cloud/07-api/postman/api-key-authentication.md).

!!! tip "cURL instead?"
 Prefer the command line? See [cURL Samples](https://docs.connectgain.cloud/07-api/postman/curl-samples.md) and [REST API cURL Examples](https://docs.connectgain.cloud/07-api/postman/rest-api-curl-examples.md).

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/07-api/index.md)*

---

# REST API Proxy cURL Examples – ConnectGain

Source: https://docs.connectgain.cloud/07-api/rest-api-curl-examples/

# REST API Proxy - cURL Examples

Base URL: `https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy`

## Authentication

Use either:
- `X-API-Key: cg_your_api_key` ([API key](https://docs.connectgain.cloud/07-api/rest-api-curl-examples/api-key-authentication.md) from Settings → API Keys)
- `Authorization: Bearer <supabase_jwt_token>` (from user session)

---

## 1. CREATE DEAL

```bash
curl -X POST \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: cg_your_api_key_here" \
 -d '{
 "title": "Enterprise Software Deal",
 "stage": "LEAD",
 "value": 50000,
 "currency": "USD",
 "contact_id": "uuid-of-contact",
 "company_id": "uuid-of-company",
 "expected_close_date": "2025-12-31",
 "probability": 30,
 "priority": "high",
 "source": "referral"
 }'
```

**Response:** Returns created deal with auto-generated `id`, `organization_id`, timestamps.

---

## 2. UPDATE DEAL

```bash
# Update deal by ID
curl -X PATCH \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals?id=eq.deal-uuid-here" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: cg_your_api_key_here" \
 -d '{
 "stage": "NEGOTIATION",
 "value": 75000,
 "probability": 60,
 "notes": "Advanced to negotiation phase"
 }'

# Update multiple deals by stage
curl -X PATCH \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals?stage=eq.LEAD" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: cg_your_api_key_here" \
 -d '{"priority": "low"}'
```

---

## 3. CREATE CONTACT (Customer)

```bash
curl -X POST \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: cg_your_api_key_here" \
 -d '{
 "first_name": "John",
 "last_name": "Doe",
 "emails": ["john.doe@example.com", "john@company.com"],
 "phones": ["+1234567890"],
 "company_id": "uuid-of-company",
 "tags": ["lead", "warm"],
 "source": "website",
 "description": "Interested in enterprise package",
 "custom_fields": {
 "job_title": "CTO",
 "linkedin": "linkedin.com/in/johndoe"
 }
 }'
```

**Response:** Returns created contact with auto-generated `id`, `organization_id`, timestamps.

---

## 4. UPDATE CONTACT

```bash
# Update contact by ID
curl -X PATCH \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?id=eq.contact-uuid-here" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: cg_your_api_key_here" \
 -d '{
 "first_name": "Jonathan",
 "tags": ["lead", "warm", "qualified"],
 "emails": ["john.doe@newcompany.com"]
 }'

# Update contacts by tag
curl -X PATCH \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?tags=cs.{\"cold\"}" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: cg_your_api_key_here" \
 -d '{"source": "cold_call_campaign"}'
```

**Note:** `organization_id` is automatically set on create and filtered on update. Cannot be changed.

---

## 5. QUERY / READ

```bash
# Get all deals (organization-scoped)
curl -X GET \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals?limit=100" \
 -H "X-API-Key: cg_your_api_key_here"

# Get deal by ID
curl -X GET \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals?id=eq.deal-uuid" \
 -H "X-API-Key: cg_your_api_key_here"

# Search contacts by name (case-insensitive)
curl -X GET \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?first_name=ilike.*John*" \
 -H "X-API-Key: cg_your_api_key_here"

# Get deals with stage filter
curl -X GET \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals?stage=eq.CLOSED_WON&order=created_at.desc" \
 -H "X-API-Key: cg_your_api_key_here"
```

---

## 6. DELETE

```bash
# Delete deal by ID
curl -X DELETE \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/deals?id=eq.deal-uuid" \
 -H "X-API-Key: cg_your_api_key_here"

# Delete contacts by tag (batch)
curl -X DELETE \
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts?tags=cs.{\"test\"}" \
 -H "X-API-Key: cg_your_api_key_here"
```

---

## Supported Operators

| Operator | Description | Example |
|----------|-------------|---------|
| `eq` | Equals | `?stage=eq.LEAD` |
| `neq` | Not equals | `?stage=neq.CLOSED_LOST` |
| `gt` | Greater than | `?value=gt.1000` |
| `gte` | Greater or equal | `?created_at=gte.2025-01-01` |
| `lt` | Less than | `?value=lt.5000` |
| `lte` | Less or equal | `?probability=lte.50` |
| `like` | Pattern match | `?title=like.*Corp*` |
| `ilike` | Case-insensitive match | `?first_name=ilike.*john*` |
| `is` | Is null | `?company_id=is.null` |
| `in` | In list | `?stage=in.(LEAD,PROSPECT)` |
| `cs` | Contains (arrays) | `?tags=cs.{\"warm\"}` |

---

## Response Format

**Success (200):**
```json
[
 {
 "id": "uuid",
 "organization_id": "org-uuid",
 "title": "Enterprise Software Deal",...
 }
]
```

**Error (4xx/5xx):**
```json
{
 "error": "Error message",
 "hint": "Helpful hint"
}
```

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/07-api/index.md)*

---

# Array Column Search – ConnectGain REST API Proxy

Source: https://docs.connectgain.cloud/07-api/rest-api-proxy-array-search/

# Searching Array Columns via the REST API Proxy

The `rest-api-proxy` edge function now fully supports PostgREST array operators on `text[]` columns like `contacts.phones`, `contacts.emails`, and `contacts.tags`.

> Fixed `2026-04-22`: previously the proxy did not recognize the `cs` (contains) operator and tried to compare the array column to a literal string, causing:
> `malformed array literal: "cs.{...}"`. This is now resolved.

## Supported operators

| Operator | Meaning | Example |
|---|---|---|
| `cs` / `contains` | Array contains all of the given values | `phones=cs.{"+201017177777"}` |
| `cd` / `containedBy` | Array is contained by | `tags=cd.{"vip","lead"}` |
| `ov` / `overlaps` | Arrays share at least one value | `phones=ov.{"+201017177777","+201111111111"}` |
| `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`, `is`, `in`, `not`, `fts`, `plfts`, `phfts`, `wfts` | Standard PostgREST operators | — |

## Search a contact by phone number

```bash
curl -G 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts' \
 -H 'X-API-Key: cg_xxx' \
 --data-urlencode 'phones=cs.{"+201017177777"}' \
 --data-urlencode 'select=id,first_name,last_name,phones,emails' \
 --data-urlencode 'limit=1'
```

**Response:**
```json
[{
 "id": "f2b4f7ab-7033-47ce-be06-b30a47de020a",
 "first_name": "mahmoud",
 "last_name": null,
 "phones": ["+201017177777"],
 "emails": ["issmail@gmail.com"]
}]
```

## Search a contact by email

```bash
curl -G 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts' \
 -H 'X-API-Key: cg_xxx' \
 --data-urlencode 'emails=cs.{"issmail@gmail.com"}' \
 --data-urlencode 'limit=1'
```

## Search by multiple phone numbers (overlap)

Returns contacts where **any** of the listed phones exists in the array:

```bash
curl -G 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts' \
 -H 'X-API-Key: cg_xxx' \
 --data-urlencode 'phones=ov.{"+201017177777","+201111111111"}' \
 --data-urlencode 'select=id,phones'
```

## Update a contact found by phone

```bash
curl -X PATCH -G 'https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts' \
 -H 'X-API-Key: cg_xxx' \
 -H 'Content-Type: application/json' \
 --data-urlencode 'phones=cs.{"+201017177777"}' \
 --data '{"first_name":"Mahmoud Updated"}'
```

## Encoding rules (important)

The PostgREST array literal uses curly braces: `{"value1","value2"}`. The `+` sign **must** be URL-encoded to `%2B` when sent in the raw query string. The safest approach in `curl` is `--data-urlencode`, which handles this automatically.

| Source value | What goes on the wire |
|---|---|
| `phones=cs.{"+201017177777"}` (curl `--data-urlencode`) | `phones=cs.%7B%22%2B201017177777%22%7D` |
| Manual encoding | `phones=cs.%7B%22%2B201017177777%22%7D` |

In Python:

```python
import requests

requests.get(
 "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts",
 headers={"X-API-Key": "cg_xxx"},
 params={
 "phones": 'cs.{"+201017177777"}',
 "select": "id,first_name,phones,emails",
 "limit": 1,
 },
)
```

`requests` URL-encodes the `+` and braces automatically.

In Node.js (`fetch`):

```js
const url = new URL("https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/contacts");
url.searchParams.set("phones", 'cs.{"+201017177777"}');
url.searchParams.set("select", "id,first_name,phones,emails");
url.searchParams.set("limit", "1");

await fetch(url, { headers: { "X-API-Key": "cg_xxx" } });
```

## Common errors

| Error | Cause | Fix |
|---|---|---|
| `malformed array literal: "cs.{...}"` | Old proxy version that didn't recognize `cs` | Already fixed — redeploy if you see this again |
| `malformed array literal: "{ +201..."` (note leading space) | The `+` was decoded as a space | Encode `+` as `%2B`, or use `--data-urlencode` |
| Empty `[]` response | Number stored without `+` while you searched with `+` (or vice versa) | Phones are normalized to E.164 (`+<country><number>`); always include the `+` |

## See also

- [REST API proxy cURL examples](https://docs.connectgain.cloud/07-api/rest-api-proxy-array-search/rest-api-curl-examples.md) — CRUD requests via the proxy.
- [Contacts & Deals API](https://docs.connectgain.cloud/07-api/rest-api-proxy-array-search/contacts-and-deals.md) — full contact/deal field reference.
- [Deals API guide](https://docs.connectgain.cloud/07-api/rest-api-proxy-array-search/deals-api-guide.md) — search-then-update workflows for deals.
- [API key authentication](https://docs.connectgain.cloud/07-api/rest-api-proxy-array-search/api-key-authentication.md) — why the proxy needs `X-API-Key`.

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/07-api/index.md)*

---

# Webhooks – Real-Time Event Notifications | ConnectGain

Source: https://docs.connectgain.cloud/08-webhooks/

# Webhooks

Receive real-time events from ConnectGain.

- [Quick start](https://docs.connectgain.cloud/08-webhooks/quick-start.md) — create and test your first webhook in about 5 minutes.
- [Webhook system overview](https://docs.connectgain.cloud/08-webhooks/overview.md) — full reference: events, payloads, signatures, and example code.
- [Enhanced payload](https://docs.connectgain.cloud/08-webhooks/enhanced-payload.md) — the enriched payload structure with full contact, organization, and conversation objects.
- [Webhooks feature page (user-facing)](https://docs.connectgain.cloud/08-webhooks/webhooks-feature.md) — feature guide with use cases, test cases, and API integration.

## See also

- [WhatsApp webhook troubleshooting](https://docs.connectgain.cloud/05-integrations/whatsapp-webhook-troubleshooting.md)
- [API overview](https://docs.connectgain.cloud/07-api/overview.md)
- [Automations](https://docs.connectgain.cloud/02-user-guide/automations.md)

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/index.md)*

---

# Enhanced Webhook Payloads – Full Object Data | ConnectGain

Source: https://docs.connectgain.cloud/08-webhooks/enhanced-payload/

# Enhanced Webhook Payload Documentation

## Overview

ConnectGain webhooks now send detailed, enriched payloads that include complete contact, organization, and conversation objects instead of just IDs. This makes it easier for external systems to process webhook events without needing to make additional API calls.

## Payload Structure

### Base Payload Format

```json
{
 "event": "message.received",
 "timestamp": "2025-01-15T12:34:56.789Z",
 "data": {
 // Event-specific data with enhanced objects
 }
}
```

### Enhanced Data Fields

The `data` object now includes the following enhanced fields when applicable:

#### Contact Object
When a `contact_id` is present in the event data, the full contact object is included:

```json
{
 "contact": {
 "id": "uuid",
 "organization_id": "uuid",
 "first_name": "John",
 "last_name": "Doe",
 "phones": ["+1234567890"],
 "emails": ["john.doe@example.com"],
 "tags": ["customer", "vip"],
 "custom_fields": {},
 "opt_in_status": true,
 "created_at": "2025-01-01T00:00:00Z",
 "updated_at": "2025-01-15T00:00:00Z",
 "company": {
 // Company details if associated
 "id": "uuid",
 "name": "Acme Corp",
 "domain": "acme.com",
 "website": "https://acme.com",
 "industry": "Technology",
 //... other company fields
 }
 }
}
```

#### Organization Object
When an `organization_id` is present, the full organization object is included:

```json
{
 "organization": {
 "id": "uuid",
 "name": "My Organization",
 "slug": "my-org",
 "settings": {
 // Organization settings
 },
 "created_at": "2025-01-01T00:00:00Z",
 "updated_at": "2025-01-15T00:00:00Z"
 }
}
```

#### Conversation Object
When a `conversation_id` is present, the full conversation object with related data is included:

```json
{
 "conversation": {
 "id": "uuid",
 "organization_id": "uuid",
 "contact_id": "uuid",
 "channel_account_id": "uuid",
 "assignee_id": "uuid",
 "status": "OPEN",
 "sla_deadline": null,
 "last_message_at": "2025-01-15T12:00:00Z",
 "tags": [],
 "created_at": "2025-01-01T00:00:00Z",
 "updated_at": "2025-01-15T00:00:00Z",
 "channel_account": {
 "id": "uuid",
 "type": "WHATSAPP_LITE",
 "name": "WhatsApp Business",
 "settings": {},
 "is_active": true
 },
 "assignee": {
 "id": "uuid",
 "first_name": "Agent",
 "last_name": "Smith",
 "email": "agent@example.com"
 }
 }
}
```

## Event Examples

### message.received Event

```json
{
 "event": "message.received",
 "timestamp": "2025-01-15T12:34:56.789Z",
 "data": {
 "id": "message-uuid",
 "conversation_id": "conversation-uuid",
 "contact_id": "contact-uuid",
 "organization_id": "org-uuid",
 "content": "Hello, I need help with my order",
 "direction": "INBOUND",
 "status": "DELIVERED",
 "created_at": "2025-01-15T12:34:56.789Z",
 "channel_type": "WHATSAPP_LITE",
 "channel_name": "WhatsApp Business",
 "contact": {
 // Full contact object as shown above
 },
 "organization": {
 // Full organization object as shown above
 },
 "conversation": {
 // Full conversation object as shown above
 }
 }
}
```

### message.sent Event

```json
{
 "event": "message.sent",
 "timestamp": "2025-01-15T12:35:00.000Z",
 "data": {
 "id": "message-uuid",
 "conversation_id": "conversation-uuid",
 "contact_id": "contact-uuid",
 "organization_id": "org-uuid",
 "content": "Thank you for reaching out. How can I help you today?",
 "direction": "OUTBOUND",
 "status": "SENT",
 "created_at": "2025-01-15T12:35:00.000Z",
 "contact": {
 // Full contact object
 },
 "organization": {
 // Full organization object
 },
 "conversation": {
 // Full conversation object
 }
 }
}
```

### conversation.created Event

```json
{
 "event": "conversation.created",
 "timestamp": "2025-01-15T12:30:00.000Z",
 "data": {
 "id": "conversation-uuid",
 "contact_id": "contact-uuid",
 "organization_id": "org-uuid",
 "channel_account_id": "channel-uuid",
 "status": "OPEN",
 "created_at": "2025-01-15T12:30:00.000Z",
 "contact": {
 // Full contact object
 },
 "organization": {
 // Full organization object
 },
 "conversation": {
 // Full conversation object with channel_account details
 }
 }
}
```

## Benefits

1. **No Additional API Calls**: External systems receive all necessary data in a single webhook payload
2. **Complete Context**: Full contact and organization details provide complete context for each event
3. **Related Data**: Includes related entities like companies (for contacts) and channel accounts (for conversations)
4. **Consistent Structure**: All webhook events follow the same enhanced payload structure

## Migration Notes

- The original fields (contact_id, organization_id, conversation_id) are still present for backward compatibility
- The enhanced objects are added as additional fields (contact, organization, conversation)
- If fetching enhanced data fails, the webhook still sends with the original IDs only
- Enhanced data fetching is done asynchronously and doesn't block webhook delivery

## Headers

Webhook requests include the following headers:

- `Content-Type: application/json`
- `X-Webhook-Event: <event-type>`
- `X-Webhook-Timestamp: <ISO-8601-timestamp>`
- `X-Webhook-Signature: <HMAC-signature>` (HMAC SHA-256 of the request body, sent if a webhook secret is configured)
- Any custom headers configured in the webhook settings

## See also

- [Webhook system overview](https://docs.connectgain.cloud/08-webhooks/enhanced-payload/overview.md)
- [Webhooks feature guide](https://docs.connectgain.cloud/08-webhooks/enhanced-payload/webhooks-feature.md)
- [API overview](https://docs.connectgain.cloud/08-webhooks/07-api/overview.md)

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/08-webhooks/index.md)*

---

# Webhook System Overview – Events, Payloads & HMAC | ConnectGain

Source: https://docs.connectgain.cloud/08-webhooks/overview/

# Webhook System - Documentation

## Overview

The webhook system allows you to configure HTTP endpoints that will be called automatically when specific events occur in your ConnectGain system. This enables you to integrate with external systems, trigger [automations](https://docs.connectgain.cloud/08-webhooks/02-user-guide/automations.md), or build custom workflows.

**On this page:**

- [Available Events (17 Total)](#available-events-17-total)
- [HTTP Method: POST](#http-method-post)
- [Event Payload Format](#event-payload-format)
- [Webhook Signature](#webhook-signature)
- [Configuration](#configuration)
- [Example Implementations](#example-implementations)
- [Webhook Logs](#webhook-logs)
- [Testing Webhooks](#testing-webhooks)
- [Best Practices](#best-practices)
- [Troubleshooting](#troubleshooting)

## Available Events (17 Total)

### Contact Events (3)
- **contact.created** - Fired when a new contact is created
- **contact.updated** - Fired when a contact is updated
- **contact.assigned** - Fired when a contact is assigned to someone

### Deal/Lead Events (4)
- **deal.created** - Fired when a new deal/lead is created
- **deal.updated** - Fired when a deal is updated
- **deal.stage.changed** - Fired when a deal moves to a different pipeline stage
- **deal.assigned** - Fired when a deal is assigned to someone

### Conversation Events (3)
- **conversation.created** - Fired when a new conversation is created
- **conversation.assigned** - Fired when a conversation is assigned
- **conversation.status.changed** - Fired when conversation status changes (OPEN/CLOSED)

### Message Events (5)
- **message.received** - Fired when a new message is received
- **message.sent** - Fired when a message is sent
- **message.delivered** - Fired when a sent message is delivered to the recipient
- **message.read** - Fired when a sent message is read by the recipient
- **message.failed** - Fired when a message fails to send

### Broadcast Events (1)
- **broadcast.response** - Fired when a contact replies to a broadcast/campaign message

### Meeting Events (1)
- **zoom.recording.completed** - Fired when a Zoom cloud recording finishes processing

## HTTP Method: POST

All webhooks are sent as **HTTP POST** requests with JSON payload.

⚠️ **Your endpoint must accept POST requests** (not GET).

The webhook dispatcher sends:
- **Method:** POST
- **Content-Type:** application/json
- **Body:** JSON payload with event data

## Event Payload Format

All webhook calls follow this format:

```json
{
 "event": "contact.created",
 "timestamp": "2024-01-15T10:30:00Z",
 "data": {
 "id": "uuid-here",
 "first_name": "John",
 "last_name": "Doe",
 "organization_id": "org-uuid",
 //... other fields specific to the event
 }
}
```

## Webhook Signature

If you provide a secret when configuring your webhook, requests will include an HMAC SHA-256 signature:

**Headers:**
- `X-Webhook-Event`: The event type
- `X-Webhook-Timestamp`: ISO timestamp
- `X-Webhook-Signature`: HMAC signature (if secret is set)

**Verification:**
1. Get the `X-Webhook-Signature` header
2. Compute HMAC SHA-256 of the request body using your secret
3. Compare the signatures (use constant-time comparison)

## Configuration

Webhooks are configured via the Settings page or through the API.

### Using the API

```typescript
import { createWebhookConfig } from '@/lib/webhook';

await createWebhookConfig({
 name: 'My Integration',
 url: 'https://example.com/webhooks',
 events: ['contact.created', 'deal.stage.changed'],
 secret: 'your-hmac-secret', // Optional
 is_active: true
});
```

### Configuration Fields
- **name**: Human-readable name for the webhook
- **url**: Endpoint URL to receive webhook calls
- **events**: Array of event types to subscribe to
- **secret**: HMAC secret for signature verification (optional)
- **is_active**: Whether the webhook is active

## Example Implementations

### Node.js Example

```javascript
const express = require('express');
const crypto = require('crypto');

const app = express;
app.use(express.json); // Parse JSON body

app.post('/webhooks', (req, res) => {
 console.log('Received webhook:', req.method, req.headers);
 const signature = req.headers['x-webhook-signature'];
 const secret = 'your-secret-here';

 // Verify signature
 const hmac = crypto.createHmac('sha256', secret);
 hmac.update(JSON.stringify(req.body));
 const computedSignature = hmac.digest('hex');

 if (signature !== computedSignature) {
 return res.status(401).send('Invalid signature');
 }

 const { event, data } = req.body;

 // Handle the event
 switch (event) {
 case 'contact.created':
 console.log('New contact:', data);
 break;
 case 'deal.stage.changed':
 console.log('Deal stage changed:', data);
 break;
 }

 res.status(200).send('OK');
});
```

### Python Example

```python
import hmac
import hashlib
from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks', methods=['POST'])
def webhook:
 signature = request.headers.get('X-Webhook-Signature')
 secret = b'your-secret-here'

 # Verify signature
 computed = hmac.new(secret, request.data, hashlib.sha256).hexdigest

 if not hmac.compare_digest(computed, signature):
 return 'Invalid signature', 401

 event = request.json['event']
 data = request.json['data']

 # Handle event
 if event == 'contact.created':
 print(f'New contact: {data}')
 elif event == 'deal.stage.changed':
 print(f'Deal stage changed: {data}')

 return 'OK', 200
```

## Webhook Logs

All webhook delivery attempts are logged in the `webhook_logs` table, including:
- Event type and payload
- Response status code
- Response body
- Error messages (if any)

View logs in Settings > Webhooks > Logs

## Testing Webhooks

You can test your webhook configuration by sending a test event:

```typescript
import { testWebhook } from '@/lib/webhook';

await testWebhook('webhook-id');
```

This sends a test event to your configured endpoint.

## Best Practices

1. **Always verify signatures** - Use the HMAC signature to verify webhook authenticity
2. **Use HTTPS** - Never send webhooks over unencrypted connections
3. **Respond quickly** - Your endpoint should respond within 5 seconds
4. **Idempotent handlers** - Webhooks may be retried, handle duplicate events gracefully
5. **Log deliveries** - Keep your own logs of webhook deliveries
6. **Handle failures** - Failed deliveries are logged and routed to a dead-letter queue, then retried automatically; use the delivery logs to monitor status

## Rate Limits

Webhooks are dispatched in near real time as events occur. If you have high event volumes, consider:

- Batch processing events
- Using a queueing system
- Filtering events you actually need

## Troubleshooting

**Webhooks not being called:**
1. Check that webhook is `is_active: true`
2. Verify the endpoint URL is correct and accessible
3. Check webhook logs for errors

**Invalid signature:**
1. Ensure you're using the same secret
2. Verify you're computing HMAC-SHA256 correctly
3. Check that request body matches what you're hashing

**Events not firing:**
1. Verify the event types are subscribed in your webhook config
2. Check that the action triggers the event (e.g., creates/updates records)

## Next Steps

After deploying this system, you can:
1. Configure webhooks in Settings page
2. Monitor webhook delivery in logs
3. Test with sample events
4. Integrate with external systems

## API Reference

See the [Webhooks Feature guide](https://docs.connectgain.cloud/08-webhooks/overview/webhooks-feature.md) and [Enhanced Payload](https://docs.connectgain.cloud/08-webhooks/overview/enhanced-payload.md) reference for the complete event catalogue and payload schemas.

## See also

- [Quick start](https://docs.connectgain.cloud/08-webhooks/overview/quick-start.md)
- [Enhanced payload reference](https://docs.connectgain.cloud/08-webhooks/overview/enhanced-payload.md)
- [Webhooks feature guide](https://docs.connectgain.cloud/08-webhooks/overview/webhooks-feature.md)
- [API overview](https://docs.connectgain.cloud/08-webhooks/07-api/overview.md)
- [Automations](https://docs.connectgain.cloud/08-webhooks/02-user-guide/automations.md)

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/08-webhooks/index.md)*

---

# Webhooks Quick Start – First Webhook in 5 Minutes | ConnectGain

Source: https://docs.connectgain.cloud/08-webhooks/quick-start/

# 🚀 Quick Start - Webhooks Ready!

## ✅ What's Included

1. Webhook configuration storage in the database
2. Webhook dispatcher edge function
3. UI in Settings
4. Events integrated across the platform
5. Help documentation added

## 🎯 Next Steps (5 minutes)

### 1. Open Your App

Go to: **Settings** → **Webhooks**

### 2. Get a Test URL

Visit: https://webhook.site
Copy your unique URL

### 3. Create & Test

1. Click **"Create Webhook"**
2. Paste your webhook.site URL
3. Select "Contact Created" event
4. Click **"Test"** → Watch webhook.site!

### 4. Test Real Events

- Create a contact → See `contact.created` event
- Update a deal stage → See `deal.stage.changed` event
- Check logs → See delivery status

## 📊 What's Behind It

- Database: `webhook_configurations`, `webhook_logs` tables
- Backend: `webhook-dispatcher` edge function
- Frontend: Settings → Webhooks tab
- Integration: Contact/Deal events trigger webhooks
- Help: On-screen guidance throughout the UI

## 📚 Documentation

- [Webhook system overview](https://docs.connectgain.cloud/08-webhooks/quick-start/overview.md) — full documentation
- [Webhooks feature guide](https://docs.connectgain.cloud/08-webhooks/quick-start/webhooks-feature.md) — use cases and test walkthroughs

## 🎉 You're Ready!

Go to Settings → Webhooks and start creating! 🚀

## See also

- [Webhook system overview](https://docs.connectgain.cloud/08-webhooks/quick-start/overview.md)
- [Enhanced payload reference](https://docs.connectgain.cloud/08-webhooks/quick-start/enhanced-payload.md)
- [API overview](https://docs.connectgain.cloud/08-webhooks/07-api/overview.md)

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/08-webhooks/index.md)*

---

# Webhooks Feature Guide – Setup, Use Cases & Testing | ConnectGain

Source: https://docs.connectgain.cloud/08-webhooks/webhooks-feature/

# Webhooks Feature

## Overview

Webhooks enable businesses to receive real-time event notifications from ConnectGain to external systems. Webhooks support HMAC signature verification, event filtering, delivery logging, and comprehensive testing capabilities.

**On this page:**

- [Features](#features)
- [Use Cases](#use-cases)
- [Test Cases](#test-cases)
- [API Integration](#api-integration)
- [Best Practices](#best-practices)
- [Troubleshooting](#troubleshooting)

---

## Features

### 1. Webhook Configuration

**Configuration Options:**
- Webhook name
- Webhook URL (HTTPS required)
- Event subscriptions
- Secret key (for HMAC signatures)
- Active/inactive status

### 2. Available Events

**Contact Events:**
- **contact.created** - New contact created
- **contact.updated** - Contact information updated
- **contact.assigned** - Contact assigned to user

**Deal Events:**
- **deal.created** - New deal created
- **deal.updated** - Deal information updated
- **deal.stage.changed** - Deal moved to different stage
- **deal.assigned** - Deal assigned to user

**Conversation Events:**
- **conversation.created** - New conversation started
- **conversation.assigned** - Conversation assigned to user
- **conversation.status.changed** - Conversation status changed

**Message Events:**
- **message.received** - New message received
- **message.sent** - Message sent successfully
- **message.delivered** - Sent message delivered to recipient
- **message.read** - Sent message read by recipient
- **message.failed** - Message failed to send

**Broadcast Events:**
- **broadcast.response** - Contact replied to a broadcast/campaign message

**Meeting Events:**
- **zoom.recording.completed** - Zoom cloud recording finished processing

### 3. Event Filtering

**Filtering Features:**
- Subscribe to specific events
- Multiple event selection
- Event-based routing
- Selective notifications

### 4. HMAC Signature Verification

**Security Features:**
- Optional secret key configuration
- HMAC-SHA256 signatures
- Signature verification
- Secure webhook delivery

### 5. Delivery Logging

**Logging Features:**
- All delivery attempts logged
- Response codes tracked
- Error messages recorded
- Delivery timestamps
- Success/failure tracking

### 6. Webhook Testing

**Testing Features:**
- Test webhook button
- Test payload generation
- Delivery verification
- Response validation

### 7. Webhook Management

**Management Features:**
- Create webhooks
- Edit webhook configuration
- Delete webhooks
- Enable/disable webhooks
- View webhook logs
- Retry failed deliveries

### 8. Request Format

**HTTP Method:** POST

**Headers:**
- `Content-Type: application/json`
- `X-Webhook-Event: event.type`
- `X-Webhook-Timestamp: ISO timestamp`
- `X-Webhook-Signature: HMAC-SHA256` (if secret configured)

**Body:**
```json
{
 "event": "contact.created",
 "timestamp": "2025-01-15T10:30:00Z",
 "data": {
 "id": "uuid",
 "first_name": "John",
 "last_name": "Doe",...
 }
}
```

---

## Use Cases

### Use Case 1: Sync Contacts to External CRM

**Scenario:**
Business wants to sync new contacts to external CRM system.

**Steps:**
1. Go to Settings → Webhooks
2. Click "Create Webhook"
3. Enter name: "CRM Sync"
4. Enter URL: https://crm.example.com/webhook
5. Select events: contact.created, contact.updated
6. Set secret key (optional)
7. Activate webhook
8. Test webhook
9. Verify delivery in logs
10. Create test contact
11. Verify webhook received

**Expected Outcome:**
New contacts automatically synced to external CRM.

### Use Case 2: Notify on Deal Stage Changes

**Scenario:**
Business wants to notify external system when deal moves to "Won" stage.

**Steps:**
1. Create webhook
2. Set URL: https://api.example.com/deals
3. Select event: deal.stage.changed
4. Configure secret key
5. Activate webhook
6. Test webhook
7. Change deal stage to "Won"
8. Verify webhook received
9. Check delivery logs

**Expected Outcome:**
External system notified when deal won.

### Use Case 3: Real-Time Message Notifications

**Scenario:**
Business wants real-time notifications for new messages.

**Steps:**
1. Create webhook
2. Set URL: https://notifications.example.com/webhook
3. Select events: message.received
4. Configure secret key
5. Activate webhook
6. Receive test message
7. Verify webhook triggered
8. Check delivery logs
9. Verify notification sent

**Expected Outcome:**
Real-time notifications for new messages.

---

## Test Cases

### Test Case 1: Create Webhook

**Test:** Verify webhook creation

**Steps:**
1. Go to Settings → Webhooks
2. Click "Create Webhook"
3. Enter name and URL
4. Select events
5. Set secret key (optional)
6. Activate webhook
7. Save webhook
8. Verify webhook appears in list
9. Verify configuration saved

**Expected Result:**
Webhook created successfully

### Test Case 2: Test Webhook

**Test:** Verify webhook testing

**Steps:**
1. Create webhook
2. Click "Test" button
3. Verify test payload sent
4. Check webhook.site or endpoint
5. Verify payload received
6. Check delivery logs
7. Verify response code

**Expected Result:**
Webhook test successful

### Test Case 3: Event Triggering

**Test:** Verify event triggering

**Steps:**
1. Create webhook with contact.created event
2. Activate webhook
3. Create new contact
4. Verify webhook triggered
5. Check delivery logs
6. Verify payload correct
7. Verify event type matches

**Expected Result:**
Webhook triggered on event

### Test Case 4: HMAC Signature

**Test:** Verify HMAC signature

**Steps:**
1. Create webhook with secret key
2. Trigger webhook
3. Extract signature from headers
4. Verify signature using secret
5. Check signature matches
6. Test with invalid secret
7. Verify signature fails

**Expected Result:**
HMAC signature verification works

### Test Case 5: Delivery Logging

**Test:** Verify delivery logging

**Steps:**
1. Create webhook
2. Trigger multiple events
3. View webhook logs
4. Verify all attempts logged
5. Check response codes
6. Verify timestamps
7. Check error messages

**Expected Result:**
All deliveries logged correctly

---

## API Integration

### Create Webhook

**Endpoint:** `POST /rest/v1/webhook_configurations`

**Request:**
```json
{
 "organization_id": "org-uuid",
 "name": "CRM Sync",
 "url": "https://crm.example.com/webhook",
 "events": ["contact.created", "contact.updated"],
 "secret": "your-secret-key",
 "is_active": true
}
```

### Get Webhooks

**Endpoint:** `GET /rest/v1/webhook_configurations`

**Query Parameters:**
- `organization_id` - Filter by organization
- `is_active` - Filter by status

### Get Webhook Logs

**Endpoint:** `GET /rest/v1/webhook_logs`

**Query Parameters:**
- `webhook_id` - Filter by webhook
- `status` - Filter by delivery status
- `created_at` - Filter by date

---

## Best Practices

1. **Webhook Design**
 - Use HTTPS URLs only
 - Implement idempotency
 - Handle retries gracefully
 - Respond quickly (< 5 seconds)

2. **Security**
 - Use HMAC signatures
 - Verify signatures server-side
 - Use secure secret keys
 - Rotate secrets regularly

3. **Error Handling**
 - Log all webhook deliveries
 - Monitor failure rates
 - Implement retry logic
 - Alert on persistent failures

4. **Performance**
 - Respond quickly
 - Process asynchronously
 - Handle timeouts
 - Monitor webhook performance

---

## Troubleshooting

### Webhook Not Triggering

**Issue:** Webhook not receiving events

**Solutions:**
- Check webhook status (must be active)
- Verify event subscriptions
- Check webhook logs
- Verify event occurred

### Delivery Failures

**Issue:** Webhook deliveries failing

**Solutions:**
- Check endpoint URL
- Verify endpoint accessible
- Check response codes
- Review error messages
- Test endpoint manually

### Signature Verification Fails

**Issue:** HMAC signature not matching

**Solutions:**
- Verify secret key correct
- Check signature calculation
- Verify header name
- Review signature format

---

## Related Documentation

- [Webhook system overview](https://docs.connectgain.cloud/08-webhooks/webhooks-feature/overview.md)
- [Enhanced payload reference](https://docs.connectgain.cloud/08-webhooks/webhooks-feature/enhanced-payload.md)
- [Automations Feature](https://docs.connectgain.cloud/08-webhooks/02-user-guide/automations.md)
- [Channels Feature](https://docs.connectgain.cloud/08-webhooks/05-integrations/channels.md)
- [API Documentation](https://docs.connectgain.cloud/08-webhooks/07-api/complete-api.md)

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/08-webhooks/index.md)*

---

# Reference – FAQ, Glossary & Troubleshooting | ConnectGain

Source: https://docs.connectgain.cloud/09-reference/

# Reference

Quick lookups when you're stuck.

- [FAQ](https://docs.connectgain.cloud/09-reference/faq.md) — answers to common questions about setup, features, security, and billing.
- [Glossary](https://docs.connectgain.cloud/09-reference/glossary.md) — definitions of ConnectGain terms, from API keys to webhooks.
- [Troubleshooting](https://docs.connectgain.cloud/09-reference/troubleshooting.md) — symptoms and solutions for login, channel, data, and integration issues.
- [Best practices](https://docs.connectgain.cloud/09-reference/best-practices.md) — recommendations for data quality, messaging, automation, campaigns, and security.

## See also

- [Getting started](https://docs.connectgain.cloud/01-getting-started/README.md)
- [User guide](https://docs.connectgain.cloud/02-user-guide/README.md)
- [Integrations](https://docs.connectgain.cloud/05-integrations/README.md)

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/index.md)*

---

# ConnectGain Best Practices – CRM, Messaging & Automation

Source: https://docs.connectgain.cloud/09-reference/best-practices/

# Best Practices Guide

## Overview

This guide provides best practices for using ConnectGain effectively, ensuring optimal performance, security, and user experience.

**On this page:**

- [Data Management](#data-management)
- [Communication Best Practices](#communication-best-practices)
- [Automation Best Practices](#automation-best-practices)
- [Campaign Best Practices](#campaign-best-practices)
- [Security Best Practices](#security-best-practices)
- [Performance Best Practices](#performance-best-practices)
- [Team Collaboration](#team-collaboration)
- [Monitoring & Analytics](#monitoring--analytics)

---

## Data Management

### Contact Data Quality

**Best Practices:**
1. **Standardize Formats**
 - Use consistent phone number format (E.164: +1234567890)
 - Standardize name formats (First Last)
 - Use consistent email formats
 - Keep addresses standardized

2. **Data Validation**
 - Validate phone numbers before import
 - Verify email addresses
 - Check for duplicates before import
 - Validate custom field data

3. **Regular Maintenance**
 - Clean duplicates monthly
 - Update outdated information
 - Archive inactive contacts
 - Remove invalid data

4. **Data Organization**
 - Use tags consistently
 - Create tag hierarchy
 - Use custom fields appropriately
 - Keep data structured

### Import Best Practices

1. **Prepare Data**
 - Clean data before import
 - Standardize formats
 - Remove duplicates
 - Validate required fields

2. **Import Process**
 - Test with small batch first
 - Map fields carefully
 - Review preview before importing
 - Handle duplicates appropriately

3. **Post-Import**
 - Verify import results
 - Check for errors
 - Fix data issues
 - Tag imported contacts

---

## Communication Best Practices

### Response Time

1. **Set SLAs**
 - Define response time goals
 - Monitor response times
 - Alert on SLA breaches
 - Optimize workflows

2. **Quick Responses**
 - Use quick replies for common questions
 - Set up automation for after-hours
 - Prioritize urgent conversations
 - Batch similar responses

### Message Quality

1. **Content**
 - Be clear and concise
 - Use professional tone
 - Personalize messages
 - Include call-to-action

2. **Formatting**
 - Use proper grammar
 - Check spelling
 - Format consistently
 - Use emojis appropriately

3. **Media**
 - Optimize image sizes
 - Use appropriate formats
 - Compress large files
 - Test media rendering

### Channel Selection

1. **Choose Right Channel**
 - WhatsApp for international
 - SMS for universal reach (available for broadcast campaigns and sequences)
 - Messenger for Facebook users
 - Email for formal communication

2. **Channel Best Practices**
 - Respect channel guidelines
 - Follow rate limits
 - Use approved templates
 - Test before sending

---

## Automation Best Practices

For feature walkthroughs, see the [bot flows](https://docs.connectgain.cloud/09-reference/02-user-guide/bot-flows.md) and [automations](https://docs.connectgain.cloud/09-reference/02-user-guide/automations.md) guides.

### Bot Flow Design

1. **User Experience**
 - Keep flows simple
 - Provide clear options
 - Allow human escalation
 - Test thoroughly

2. **Flow Structure**
 - Start with greeting
 - Provide clear paths
 - Handle errors gracefully
 - End with next steps

3. **Testing**
 - Test all paths
 - Test error scenarios
 - Test variable substitution
 - Monitor performance

### Automation Rules

1. **Rule Design**
 - Keep rules simple
 - Test triggers
 - Verify actions
 - Monitor execution

2. **Performance**
 - Avoid complex conditions
 - Limit rule complexity
 - Monitor execution time
 - Optimize queries

3. **Maintenance**
 - Review rules regularly
 - Update as needed
 - Disable unused rules
 - Document rules

---

## Campaign Best Practices

For feature walkthroughs, see the [campaigns](https://docs.connectgain.cloud/09-reference/02-user-guide/campaigns.md) and [sequences](https://docs.connectgain.cloud/09-reference/02-user-guide/sequences.md) guides.

### Targeting

1. **Segmentation**
 - Use tags for segmentation
 - Segment by behavior
 - Consider preferences
 - Test segments

2. **Timing**
 - Send during business hours
 - Consider timezones
 - Test optimal times
 - Avoid spam hours

3. **Frequency**
 - Don't over-message
 - Respect preferences
 - Space out campaigns
 - Monitor engagement

### Content

1. **Message Design**
 - Clear value proposition
 - Strong call-to-action
 - Personalize content
 - Test variations

2. **Compliance**
 - Obtain consent
 - Include opt-out
 - Follow regulations
 - Respect preferences

3. **Testing**
 - Test with small group
 - A/B test content
 - Monitor performance
 - Optimize based on data

---

## Security Best Practices

### Authentication

1. **Password Security**
 - Use strong passwords
 - Enable 2FA (if available)
 - Rotate passwords regularly
 - Don't share credentials

2. **API Keys**
 - Store keys securely
 - Rotate keys regularly
 - Use minimal permissions
 - Monitor key usage

3. **Access Control**
 - Use role-based access
 - Grant minimum permissions
 - Review access regularly
 - Revoke unused access

### Data Security

1. **Data Protection**
 - Encrypt sensitive data
 - Limit data access
 - Audit data access
 - Backup regularly

2. **Compliance**
 - Follow GDPR guidelines
 - Respect privacy laws
 - Obtain consent
 - Provide opt-out

---

## Performance Best Practices

### Dashboard Optimization

1. **Widget Management**
 - Limit widget count (12-15)
 - Use date range filtering
 - Optimize custom queries
 - Hide unused widgets

2. **Data Loading**
 - Use pagination
 - Limit data fetched
 - Cache frequently used data
 - Optimize queries

### API Usage

1. **Request Optimization**
 - Batch requests when possible
 - Use filters to limit data
 - Cache responses
 - Respect rate limits

2. **Error Handling**
 - Implement retry logic
 - Handle errors gracefully
 - Log errors appropriately
 - Monitor API usage

---

## Team Collaboration

### Workflow Management

1. **Assignment**
 - Assign promptly
 - Balance workload
 - Use auto-assignment
 - Review assignments

2. **Communication**
 - Use notes for context
 - Tag team members
 - Document decisions
 - Share knowledge

3. **Training**
 - Provide comprehensive training
 - Create documentation
 - Share best practices
 - Regular updates

---

## Monitoring & Analytics

### Key Metrics

1. **Response Metrics**
 - Average response time
 - First response time
 - Response rate
 - SLA compliance

2. **Engagement Metrics**
 - Message open rate
 - Click-through rate
 - Conversation completion
 - Customer satisfaction

3. **Business Metrics**
 - Conversion rate
 - Deal closure rate
 - Revenue impact
 - Cost per acquisition

### Reporting

1. **Regular Reports**
 - Daily performance
 - Weekly summaries
 - Monthly analytics
 - Quarterly reviews

2. **Data Analysis**
 - Identify trends
 - Find opportunities
 - Optimize processes
 - Make data-driven decisions

---

## Troubleshooting Best Practices

### Issue Resolution

1. **Documentation**
 - Document issues
 - Record solutions
 - Share knowledge
 - Update documentation

2. **Prevention**
 - Monitor proactively
 - Set up alerts
 - Regular maintenance
 - Test changes

3. **Escalation**
 - Know when to escalate
 - Provide context
 - Include error details
 - Follow up

---

## Related Documentation

- [FAQ](https://docs.connectgain.cloud/09-reference/best-practices/faq.md)
- [Troubleshooting Guide](https://docs.connectgain.cloud/09-reference/best-practices/troubleshooting.md)
- [User Guide](https://docs.connectgain.cloud/09-reference/02-user-guide/README.md)
- [API Documentation](https://docs.connectgain.cloud/09-reference/07-api/complete-api.md)
- [Webhooks Documentation](https://docs.connectgain.cloud/09-reference/08-webhooks/README.md)
- [Security on connectgain.cloud](https://connectgain.cloud/en/security) — feature overview on the ConnectGain website

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/09-reference/index.md)*

---

# ConnectGain FAQ – Setup, Features, Security & Billing

Source: https://docs.connectgain.cloud/09-reference/faq/

# Frequently Asked Questions (FAQ)

**On this page:**

- [General Questions](#general-questions)
- [Setup & Configuration](#setup--configuration)
- [Features](#features)
- [Technical Questions](#technical-questions)
- [Troubleshooting](#troubleshooting)
- [Security & Privacy](#security--privacy)
- [Billing & Subscriptions](#billing--subscriptions)
- [Support](#support)
- [Best Practices](#best-practices)

## General Questions

### What is ConnectGain?

ConnectGain is a comprehensive customer engagement and CRM platform that unifies multi-channel messaging (WhatsApp Lite, [WhatsApp Cloud](https://docs.connectgain.cloud/09-reference/05-integrations/whatsapp-cloud-system-user.md), Facebook Messenger, Instagram, Telegram, TikTok, Shopify Inbox, Email, and LinkedIn) with customer relationship management, automation, and analytics. SMS is also available for broadcast campaigns and sequences.

### Who is ConnectGain for?

ConnectGain is designed for businesses of all sizes that need to:
- Communicate with customers across multiple channels
- Manage customer relationships
- Track sales pipelines
- Automate customer interactions
- Run marketing campaigns
- Analyze customer engagement

### How much does ConnectGain cost?

ConnectGain offers subscription plans with different feature sets and usage limits. Sign up or contact sales to discuss the right plan for your team.

### Is there a free trial?

Yes, ConnectGain offers a free trial period. Sign up to get started.

---

## Setup & Configuration

### How do I connect WhatsApp?

**WhatsApp Lite (AppGain):**
1. Get an AppGain account
2. Go to Settings → Channels
3. Add WhatsApp Lite channel
4. Connect
5. Connect

**WhatsApp Cloud (Meta):**
1. Set up Meta Business Account
2. Get WhatsApp Business API access
3. Go to Settings → Channels
4. Add WhatsApp Cloud channel
5. Enter access token and phone number ID
6. Configure webhook URL

See the [channels guide](https://docs.connectgain.cloud/09-reference/05-integrations/channels.md) and [WhatsApp Lite API guide](https://docs.connectgain.cloud/09-reference/05-integrations/whatsapp-lite-api.md) for details.

### How do I import my existing contacts?

1. Go to Contacts → Import
2. Download CSV template (optional)
3. Prepare your CSV file with contact data
4. Upload CSV file
5. Map columns to ConnectGain fields
6. Review preview
7. Import

Supported formats: CSV, Kommo CRM export

See the [contacts guide](https://docs.connectgain.cloud/09-reference/02-user-guide/contacts.md) for field mapping and import tips.

### How do I set up team members?

1. Go to Settings → Team
2. Click "Invite Team Member"
3. Enter email address
4. Select role (OWNER, ADMIN, AGENT, PROJECT_MANAGER, or TEAM_ADMIN)
5. Send invitation
6. Team member accepts invitation

---

## Features

### How does the unified inbox work?

The [unified inbox](https://docs.connectgain.cloud/09-reference/02-user-guide/inbox.md) displays all conversations from all connected channels (WhatsApp, Messenger, Instagram, etc.) in one place. You can:

- See all conversations together
- Filter by channel
- Assign conversations to team members
- Respond from one interface

### Can I automate responses?

Yes! ConnectGain offers several automation options:

1. **[Bot Flows](https://docs.connectgain.cloud/09-reference/02-user-guide/bot-flows.md)** - Visual chatbot builder for interactive conversations
2. **[Automation Rules](https://docs.connectgain.cloud/09-reference/02-user-guide/automations.md)** - Trigger-based automation (e.g., auto-assign conversations)
3. **[Sequences](https://docs.connectgain.cloud/09-reference/02-user-guide/sequences.md)** - Multi-step drip campaigns across email, WhatsApp, and SMS

### How do campaigns work?

1. Create a [campaign](https://docs.connectgain.cloud/09-reference/02-user-guide/campaigns.md)
2. Select target audience (all contacts, tags, or individual)
3. Write message content
4. Schedule or send immediately
5. Track delivery and engagement

### Can I track sales deals?

Yes! ConnectGain includes a complete CRM with:

- [Deal pipeline management](https://docs.connectgain.cloud/09-reference/02-user-guide/deals.md)
- Kanban board view
- Value and probability tracking
- Deal stages
- Sales forecasting

---

## Technical Questions

### What APIs are available?

ConnectGain provides:
- **REST API** - Direct database access via PostgREST
- **Edge Functions** - Custom serverless functions
- **External APIs** - API key authenticated endpoints

See [Complete API Documentation](https://docs.connectgain.cloud/09-reference/07-api/complete-api.md) for details.

### How do I get an API key?

1. Go to Settings → API Keys
2. Click "Generate API Key"
3. Enter name and permissions
4. Copy the key (shown only once)
5. Store securely

See [API key authentication](https://docs.connectgain.cloud/09-reference/07-api/api-key-authentication.md) for usage details.

### Can I integrate with my existing systems?

Yes! ConnectGain supports:
- Webhooks for event notifications
- REST API for data access
- CSV import/export
- Kommo CRM integration

### What webhooks are available?

Webhooks are available for:

- Contact events (created, updated, assigned)
- Deal events (created, updated, stage changed, assigned)
- Conversation events (created, assigned, status changed)
- Message events (received, sent, delivered, read, failed)
- Broadcast responses and Zoom recording completion

See the [Webhooks Documentation](https://docs.connectgain.cloud/09-reference/08-webhooks/README.md) and the [webhook system overview](https://docs.connectgain.cloud/09-reference/08-webhooks/overview.md) for details.

---

## Troubleshooting

### Messages not appearing in inbox

**Possible causes:**
- Channel not connected
- Webhook not configured
- Message filters active
- Real-time connection lost

**Solutions:**
1. Check channel connection status
2. Verify webhook configuration
3. Check message filters
4. Refresh inbox
5. Check real-time connection

### Messages not sending

**Possible causes:**
- Channel disconnected
- Invalid message format
- Rate limit exceeded
- Channel-specific restrictions

**Solutions:**
1. Check channel connection
2. Verify message format
3. Check rate limits
4. Review error messages
5. Test channel separately

### Import errors

**Possible causes:**
- Invalid CSV format
- Missing required fields
- Data validation errors
- Duplicate detection

**Solutions:**
1. Check CSV format
2. Verify required fields
3. Review validation errors
4. Handle duplicates appropriately
5. Check import logs

### Dashboard not loading

**Possible causes:**
- Database connection issues
- Widget query errors
- Date range issues
- Performance problems

**Solutions:**
1. Refresh page
2. Check database connection
3. Verify widget queries
4. Check date range
5. Reduce widget count

---

## Security & Privacy

### How is my data secured?

- Encrypted database connections
- Encrypted file storage
- Row Level Security (RLS)
- Secure API authentication
- Webhook signature verification

### Who can access my data?

Only users in your organization can access your data. Data is isolated by organization using Row Level Security.

### Can I export my data?

Yes! You can export:
- Contacts (CSV)
- Deals (CSV)
- Conversations (via API)
- Campaign reports

### Is my data backed up?

Yes, Supabase provides automatic database backups. Contact support for backup restoration.

---

## Billing & Subscriptions

### How does billing work?

ConnectGain uses Stripe and Paddle for payment processing. You can:

- Subscribe to plans
- Manage billing in customer portal
- Update payment methods
- View invoices

### Can I change my plan?

Yes! Go to Settings → Subscription → Change Plan

### What happens if I cancel?

Your subscription remains active until the end of the billing period. After cancellation, you'll lose access at the end of the period.

### Do you offer refunds?

Refund policies vary by plan. Contact support for refund requests.

---

## Support

### How do I get help?

- **Documentation:** Browse this documentation site
- **FAQ:** Check this FAQ
- **Support:** Contact support team
- **Community:** Join community forum (if available)

### Where can I report bugs?

Report bugs through:
- Support email
- In-app feedback
- GitHub issues (if public)

### Can I request features?

Yes! Submit feature requests through:
- Support email
- In-app feedback
- Feature request form

---

## Best Practices

### How should I organize my contacts?

- Use tags consistently
- Assign contacts to team members
- Link contacts to companies
- Keep custom fields organized
- Regular duplicate cleanup

### How should I manage my pipeline?

- Keep stages clear and distinct
- Limit to 5-7 stages
- Update deals regularly
- Set realistic probabilities
- Close lost deals

### How should I use automation?

- Start with simple automation
- Test thoroughly
- Monitor performance
- Adjust based on results
- Document automation rules

---

## Related Documentation

- [Getting Started Guide](https://docs.connectgain.cloud/09-reference/01-getting-started/README.md)
- [User Guide](https://docs.connectgain.cloud/09-reference/02-user-guide/README.md)
- [API Documentation](https://docs.connectgain.cloud/09-reference/07-api/complete-api.md)
- [Troubleshooting Guide](https://docs.connectgain.cloud/09-reference/faq/troubleshooting.md)
- [Glossary](https://docs.connectgain.cloud/09-reference/faq/glossary.md)
- [Product FAQ on connectgain.cloud](https://connectgain.cloud/en/faq) — feature overview on the ConnectGain website

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/09-reference/index.md)*

---

# ConnectGain Glossary – CRM & Messaging Terms Explained

Source: https://docs.connectgain.cloud/09-reference/glossary/

# Glossary

## Terms and Definitions

### A

**API Key**
A unique identifier used to authenticate external systems with ConnectGain APIs. [API keys](https://docs.connectgain.cloud/09-reference/07-api/api-key-authentication.md) are prefixed with `cg_` and are scoped to organizations.

**Automation Rule**
A configuration that automatically performs actions when specific triggers occur (e.g., assign conversation when message received).

**Assignee**
The team member assigned to handle a contact, deal, conversation, or task.

---

### B

**Bot Flow**
A visual workflow builder for creating automated chatbots that can interact with customers through conversations. See the [bot flows guide](https://docs.connectgain.cloud/09-reference/02-user-guide/bot-flows.md).

**Broadcast Campaign**
A marketing campaign that sends messages to multiple contacts simultaneously via SMS, WhatsApp, or other channels.

---

### C

**Channel**
A messaging platform integrated with ConnectGain. Nine channels are supported: WhatsApp Lite, WhatsApp Cloud, Facebook Messenger, Instagram, Telegram, TikTok, Shopify Inbox, Bulk Email, and LinkedIn. SMS is available for broadcast campaigns and sequences only. See the [channels guide](https://docs.connectgain.cloud/09-reference/05-integrations/channels.md).

**Channel Account**
A connected instance of a messaging channel (e.g., a specific WhatsApp Business account).

**Contact**
A customer or lead record in the CRM system, containing information like name, phone, email, and custom fields.

**Conversation**
A message thread between a contact and your team, containing multiple messages across a channel.

**Custom Field**
User-defined fields added to contacts, deals, or other entities to store additional information.

---

### D

**Deal**
A sales opportunity tracked through stages in a pipeline, with value, probability, and expected close date.

**Dashboard Widget**
A customizable component on the dashboard that displays specific metrics or data visualizations.

---

### E

**Edge Function**
A serverless function hosted on Supabase that handles business logic, integrations, and API endpoints.

---

### F

**Filter**
A condition applied to lists (contacts, deals, conversations) to show only matching items.

---

### G

**Grid View**
A card-based display mode for viewing contacts, companies, or other entities.

---

### H

**HMAC Signature**
A cryptographic signature used to verify webhook authenticity and prevent unauthorized requests.

---

### I

**Import**
The process of bulk loading data (contacts, companies) from CSV files or external systems.

**Inbox**
The unified messaging center where all conversations from all channels are displayed together.

---

### K

**Kanban Board**
A visual board view for deals, showing stages as columns and deals as cards that can be dragged between stages.

**Kommo**
A CRM system that can be integrated with ConnectGain for importing leads and contacts.

---

### M

**Message**
An individual communication sent or received through a channel, part of a conversation.

**Message Template**
A pre-defined message format that can be reused, often with variable placeholders.

---

### N

**Note**
A text annotation added to a contact, deal, or conversation to document interactions or information.

**Notification Log**
A record of campaign message delivery attempts and status for tracking campaign performance.

---

### O

**Organization**
A company or business entity using ConnectGain. Users belong to organizations and data is scoped to organizations.

---

### P

**Pipeline**
A sales process with defined stages (e.g., Lead, Qualified, Proposal, Closed Won) through which deals progress.

**Probability**
The likelihood (0-100%) that a deal will close successfully, used for revenue forecasting.

**Profile**
A user account record containing name, email, permissions, and organization membership. Roles (OWNER, ADMIN, AGENT, PROJECT_MANAGER, TEAM_ADMIN) are managed separately from the profile.

---

### Q

**Quick Reply**
A pre-defined message template that can be quickly inserted into conversations for common responses.

---

### R

**Real-time**
Live updates that appear automatically without page refresh, powered by WebSocket connections.

**RLS (Row Level Security)**
Database-level security that restricts data access based on user permissions and organization membership.

---

### S

**Sequence**
A multi-step drip campaign that sends messages to enrolled contacts over time across channels such as email, WhatsApp, and SMS. See the [sequences guide](https://docs.connectgain.cloud/09-reference/02-user-guide/sequences.md).

**Stage**
A step in a [sales pipeline](https://docs.connectgain.cloud/09-reference/02-user-guide/deals.md) (e.g., "Lead", "Qualified") representing where a deal is in the sales process.

**Subscription**
A paid plan that determines feature access, usage limits, and billing for an organization.

---

### T

**Tag**
A label applied to contacts, deals, or conversations for categorization and filtering.

**Task**
A to-do item assigned to a team member, often related to a contact or deal, with due dates and priorities.

**Template**
A reusable message format, especially for WhatsApp Business API approved [message templates](https://docs.connectgain.cloud/09-reference/02-user-guide/templates.md).

---

### U

**Unified Inbox**
The central inbox that displays all conversations from all connected channels in one place.

**Use Case**
A specific business scenario demonstrating how ConnectGain features solve real-world problems.

---

### W

**Webhook**
An HTTP callback that sends event notifications to external systems when specific events occur in ConnectGain.

**Widget**
A customizable dashboard component that displays specific metrics or data.

---

### Z

**Zone (Timezone)**
Time zone settings used for scheduling campaigns, setting business hours, and displaying timestamps.

---

## Acronyms

- **API** - Application Programming Interface
- **B2B** - Business to Business
- **CRM** - Customer Relationship Management
- **CSV** - Comma-Separated Values
- **JWT** - JSON Web Token
- **OAuth** - Open Authorization
- **RBAC** - Role-Based Access Control
- **RLS** - Row Level Security
- **SLA** - Service Level Agreement
- **SMS** - Short Message Service
- **UI** - User Interface
- **UUID** - Universally Unique Identifier

---

## See also

- [FAQ](https://docs.connectgain.cloud/09-reference/glossary/faq.md)
- [Troubleshooting](https://docs.connectgain.cloud/09-reference/glossary/troubleshooting.md)
- [User guide](https://docs.connectgain.cloud/09-reference/02-user-guide/README.md)
- [Channels guide](https://docs.connectgain.cloud/09-reference/05-integrations/channels.md)
- [Webhooks documentation](https://docs.connectgain.cloud/09-reference/08-webhooks/README.md)

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/09-reference/index.md)*

---

# ConnectGain Troubleshooting – Fix Common Issues Fast

Source: https://docs.connectgain.cloud/09-reference/troubleshooting/

# Troubleshooting Guide

## Common Issues and Solutions

**On this page:**

- [Authentication Issues](#authentication-issues)
- [Channel Connection Issues](#channel-connection-issues)
- [Data Issues](#data-issues)
- [Performance Issues](#performance-issues)
- [Feature-Specific Issues](#feature-specific-issues)
- [Integration Issues](#integration-issues)
- [Browser & Device Issues](#browser--device-issues)
- [Data Loss Prevention](#data-loss-prevention)
- [Getting Help](#getting-help)

---

## Authentication Issues

### Issue: Cannot log in

**Symptoms:**
- Login fails with error message
- "Invalid credentials" error
- Account locked

**Solutions:**
1. Verify email and password are correct
2. Check if email is verified
3. Try password reset
4. Check for account lockout
5. Clear browser cache and cookies
6. Try incognito/private mode
7. Contact support if issue persists

### Issue: Session expired

**Symptoms:**
- "Session expired" error
- Unexpected logout
- Token refresh fails

**Solutions:**
1. Log in again
2. Check token expiration settings
3. Verify system time is correct
4. Clear browser storage
5. Check network connectivity

---

## Channel Connection Issues

### Issue: WhatsApp not connecting

**Symptoms:**
- Connection status shows "Disconnected"
- Cannot send/receive messages
- Webhook errors

**Solutions:**

**For [WhatsApp Lite](https://docs.connectgain.cloud/09-reference/05-integrations/whatsapp-lite-api.md):**
1. Verify Appgain credentials are provisioned for your organization
2. Check AppGain account status
3. Verify your Appgain account is active
4. Test the channel in Settings → Channels
5. Reconnect channel

**For [WhatsApp Cloud](https://docs.connectgain.cloud/09-reference/05-integrations/whatsapp-cloud-system-user.md):**
1. Verify access token is valid
2. Check phone number ID
3. Verify webhook URL configured
4. Check webhook verification
5. Review Meta Developer Console logs
6. Reconnect channel

For a deeper dive, see the [WhatsApp webhook troubleshooting guide](https://docs.connectgain.cloud/09-reference/05-integrations/whatsapp-webhook-troubleshooting.md).

### Issue: Messages not receiving

**Symptoms:**
- Messages sent but not appearing in inbox
- Webhook not triggering
- Delivery status unknown

**Solutions:**
1. Check channel connection status
2. Verify webhook URL is correct
3. Check webhook logs
4. Verify webhook signature (if configured)
5. Test webhook endpoint manually
6. Check Supabase Edge Function logs
7. Verify message filters not hiding messages

### Issue: Messages not sending

**Symptoms:**
- Message stuck in "Sending" status
- "Failed to send" error
- Rate limit errors

**Solutions:**
1. Check channel connection
2. Verify message format is valid
3. Check rate limits
4. Review error messages
5. Test channel separately
6. Check message length limits
7. Verify recipient number format
8. Check channel-specific restrictions

---

## Data Issues

### Issue: Contacts not importing

**Symptoms:**
- Import fails
- Partial import
- Data validation errors

**Solutions:**
1. Check CSV format
2. Verify required fields present
3. Check data validation errors
4. Review import logs
5. Fix data issues in CSV
6. Try smaller batch import
7. Verify organization ID correct

### Issue: Search not finding contacts

**Symptoms:**
- Known contacts not appearing
- Search returns no results
- Partial matches not working

**Solutions:**
1. Check search term spelling
2. Verify phone number format
3. Check organization filter
4. Try different search terms
5. Check contact data accuracy
6. Verify search index updated
7. Clear search cache

### Issue: Duplicate contacts

**Symptoms:**
- Multiple entries for same contact
- Import creates duplicates
- Manual duplicates

**Solutions:**
1. Use duplicate detection tool
2. Merge duplicates manually
3. Review import process
4. Use unique identifiers
5. Standardize data format
6. Set up duplicate prevention rules

---

## Performance Issues

### Issue: Dashboard loads slowly

**Symptoms:**
- Long load times
- Widgets loading slowly
- Timeout errors

**Solutions:**
1. Reduce number of widgets
2. Use date range filtering
3. Optimize custom widget queries
4. Check database performance
5. Clear browser cache
6. Check network connectivity
7. Review database indexes

### Issue: Real-time updates not working

**Symptoms:**
- Updates not appearing automatically
- Need to refresh page
- Connection errors

**Solutions:**
1. Check browser WebSocket support
2. Verify real-time connection status
3. Check network connectivity
4. Review firewall settings
5. Refresh page
6. Check Supabase real-time status
7. Review browser console for errors

### Issue: API requests timing out

**Symptoms:**
- API calls fail
- Timeout errors
- Slow responses

**Solutions:**
1. Check network connectivity
2. Verify API endpoint is accessible
3. Check rate limits
4. Review request size
5. Optimize queries
6. Check Supabase status
7. Retry with exponential backoff

---

## Feature-Specific Issues

### Issue: Deals not moving in kanban

**Symptoms:**
- Cannot drag deals
- Deals stuck in stage
- Stage changes not saving

**Solutions:**
1. Check browser compatibility
2. Verify pipeline configuration
3. Refresh page
4. Check permissions
5. Verify deal data integrity
6. Try different browser
7. Clear browser cache

### Issue: Automation not triggering

**Symptoms:**
- Rules not executing
- Actions not performed
- No automation logs

**Solutions:**
1. Verify automation is active
2. Check trigger conditions
3. Review automation logs
4. Test trigger manually
5. Verify permissions
6. Check data matches conditions
7. Review automation configuration

### Issue: Campaign not sending

**Symptoms:**
- Campaign stuck in "DRAFT"
- Messages not delivered
- Delivery errors

**Solutions:**
1. Check campaign status
2. Verify target contacts exist
3. Check channel connections
4. Review delivery logs
5. Verify message content
6. Check rate limits
7. Review error messages

### Issue: Bot flow not executing

**Symptoms:**
- Bot not responding
- Flow not triggered
- Session errors

**Solutions:**
1. Verify flow is published
2. Check flow configuration
3. Review bot session logs
4. Test flow manually
5. Verify trigger conditions
6. Check conversation status
7. Review flow nodes

---

## Integration Issues

### Issue: Webhook not receiving events

**Symptoms:**
- No webhook calls
- Events not triggering
- 404 errors

**Solutions:**
1. Verify webhook URL is correct
2. Check webhook is active
3. Test webhook endpoint manually
4. Verify webhook signature
5. Check firewall settings
6. Review webhook logs
7. Verify event subscriptions

See the [webhook system overview](https://docs.connectgain.cloud/09-reference/08-webhooks/overview.md) for the full event catalogue and signature verification examples.

### Issue: API key not working

**Symptoms:**
- 401 Unauthorized errors
- API calls rejected
- Invalid key errors

**Solutions:**
1. Verify [API key](https://docs.connectgain.cloud/09-reference/07-api/api-key-authentication.md) is correct
2. Check API key is active
3. Verify key hasn't expired
4. Check key permissions
5. Verify organization matches
6. Review API key logs
7. Regenerate key if needed

### Issue: External system integration failing

**Symptoms:**
- Integration errors
- Data not syncing
- Connection timeouts

**Solutions:**
1. Verify API credentials
2. Check API endpoint URLs
3. Review integration logs
4. Test API endpoints separately
5. Verify data format
6. Check rate limits
7. Review error messages

---

## Browser & Device Issues

### Issue: Features not working in browser

**Symptoms:**
- Buttons not clicking
- Forms not submitting
- JavaScript errors

**Solutions:**
1. Check browser compatibility
2. Update browser
3. Clear browser cache
4. Disable browser extensions
5. Try different browser
6. Check JavaScript console
7. Verify browser settings

### Issue: Mobile app issues

**Symptoms:**
- Features not working
- Layout issues
- Performance problems

**Solutions:**
1. Check mobile browser compatibility
2. Clear mobile browser cache
3. Update mobile browser
4. Check network connectivity
5. Verify responsive design
6. Test on different devices
7. Review mobile-specific issues

---

## Data Loss Prevention

### Issue: Accidentally deleted data

**Symptoms:**
- Contact deleted
- Deal removed
- Conversation lost

**Solutions:**
1. Check if cascade deletion occurred
2. Review deletion logs
3. Check database backups
4. Contact support for restoration
5. Verify backup availability
6. Implement deletion confirmations
7. Set up data retention policies

### Issue: Data not saving

**Symptoms:**
- Changes not persisting
- Data reverts
- Save errors

**Solutions:**
1. Check network connectivity
2. Verify save button clicked
3. Review validation errors
4. Check permissions
5. Verify data format
6. Review error messages
7. Try saving again

---

## Getting Help

### When to Contact Support

Contact support when:
- Issue persists after troubleshooting
- Data loss occurred
- Security concerns
- Billing issues
- Feature requests
- Bug reports

### Information to Provide

When contacting support, provide:
1. Description of issue
2. Steps to reproduce
3. Expected vs actual behavior
4. Error messages
5. Screenshots/videos
6. Browser/device information
7. Account information (if safe)

### Self-Service Resources

Before contacting support:
1. Check this troubleshooting guide
2. Review FAQ
3. Search documentation
4. Check status page
5. Review error logs
6. Test in different browser
7. Clear cache and retry

---

## Prevention Best Practices

### Regular Maintenance

1. **Monitor Channels**
 - Check connection status daily
 - Review webhook logs weekly
 - Test message sending regularly

2. **Data Quality**
 - Regular duplicate cleanup
 - Data validation
 - Backup important data

3. **Performance**
 - Monitor dashboard load times
 - Review API response times
 - Optimize queries regularly

4. **Security**
 - Review API keys regularly
 - Update passwords periodically
 - Monitor access logs

5. **Updates**
 - Keep browser updated
 - Review release notes
 - Test new features

---

## Related Documentation

- [FAQ](https://docs.connectgain.cloud/09-reference/troubleshooting/faq.md)
- [User Guide](https://docs.connectgain.cloud/09-reference/02-user-guide/README.md)
- [API Documentation](https://docs.connectgain.cloud/09-reference/07-api/complete-api.md)
- [Getting Started Guide](https://docs.connectgain.cloud/09-reference/01-getting-started/README.md)
- [WhatsApp Webhook Troubleshooting](https://docs.connectgain.cloud/09-reference/05-integrations/whatsapp-webhook-troubleshooting.md)

---

**Last Updated:** January 2025

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/09-reference/index.md)*

---

# AI Re-Engagement One-Pager – Recover Meta DM Leads

Source: https://docs.connectgain.cloud/marketing/ai-reengagement-onepager/

# AI Re-Engagement — Sales One-Pager

## The problem
Up to **40% of Messenger and Instagram DM leads go cold** because Meta's 24-hour response window closes before a human agent gets back. Once it closes, you can't message that contact again until *they* message *you*.

## The solution
**ConnectGain AI Re-Engagement** watches every Messenger and Instagram conversation, and — a few hours before the 24h timer expires — drafts a personalised, on-brand follow-up and sends it (or queues it for agent approval).

## How it works
1. Customer messages, agent replies (or doesn't).
2. Scanner detects the conversation is approaching 24h.
3. AI reads the last 5 messages, picks tone + language, drafts a ≤240-char nudge ending in a question.
4. Nudge is sent inside the window, logged in the inbox timeline.
5. Customer reply → counter resets. 3 strikes → auto-pause.

## Compliance
We send strictly **inside** Meta's standard 24-hour customer-service window. No policy bypass, no template gymnastics.

## Why customers love it
- Recovers leads that would otherwise die silently.
- On-brand, multilingual, never generic.
- Optional human-in-the-loop approval.
- Per-conversation kill switch.
- Full audit trail.

## Call to action

**Settings → AI & Automation → AI Re-Engagement → Start free trial.**

## See also

- [AI Re-Engagement — use cases](https://docs.connectgain.cloud/marketing/04-use-cases/ai-reengagement-use-cases.md)
- [AI Re-Engagement user guide](https://docs.connectgain.cloud/marketing/02-user-guide/ai-reengagement.md)
- [BYOK — Bring Your Own Gemini Key](https://docs.connectgain.cloud/marketing/05-integrations/ai-byok-gemini.md)
- [AI Re-Engagement on connectgain.cloud](https://connectgain.cloud/en/ai-reengagement) — feature overview on the ConnectGain website

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/marketing/index.md)*

---

# WhatsApp Lite vs WhatsApp Cloud API – ConnectGain Comparison

Source: https://docs.connectgain.cloud/marketing/whatsapp-lite-vs-cloud/

# WhatsApp on ConnectGain — Lite & Cloud

A complete guide to the two WhatsApp channels available in ConnectGain. Use this as source content for landing pages, sales decks, and onboarding material.

---

## At a Glance

| | **WhatsApp Lite** | **WhatsApp Cloud (Official)** |
|---|---|---|
| **Powered by** | Appgain WhatsApp gateway | Meta WhatsApp Business Platform (Cloud API) |
| **Setup** | Scan a QR code with your phone (2 minutes) | Embedded Signup via Facebook + Business verification |
| **Best for** | SMBs, agencies, fast go-live, sales outreach, warming numbers | Mid-market & enterprise, branded support, high-volume verified messaging |
| **Phone number** | Any personal or business mobile number | Dedicated business number registered with Meta |
| **Templates needed?** | No — free-form messages anytime | Yes for messages outside the 24h window |
| **24h customer-care window** | Not enforced | Enforced by Meta |
| **Green tick / verified badge** | Not available | Available after Meta business verification |
| **Sending limits** | Soft limits, ramp via warming | Tiered: 1K → 10K → 100K → unlimited / 24h |
| **Cost model** | Flat subscription, no per-message fees | Meta conversation-based pricing + platform fee |
| **Compliance risk** | Higher — unofficial channel, ban risk if abused | Low — fully sanctioned by Meta |

---

## WhatsApp Lite

The fastest way to put a real WhatsApp number into a shared team inbox. No Facebook Business Manager, no template approvals, no waiting.

### Key features

- **QR-code pairing** — connect any WhatsApp number in under 2 minutes from Settings → Channels.
- **Shared team inbox** — multiple agents reply from the same number with assignment, internal notes, and read receipts.
- **Free-form messaging** — send and receive messages anytime, no template approval required.
- **Rich media** — images, videos, documents, audio notes, location, contacts, and stickers.
- **Bulk campaigns & broadcasts** — schedule one-to-many sends through the broadcast composer.
- **Number warming** — built-in warming campaigns gradually ramp activity to protect new numbers.
- **Link shortening** — automatic per-recipient short links with click tracking.
- **Sequences (drip campaigns)** — multi-step outreach with dynamic variables and unsubscribe handling.
- **Bot flows** — visual builder deployed to n8n; numbered-menu fallbacks for universal compatibility.
- **AI auto-reply** — Gemini-powered RAG agent answers from your knowledge base with zero hallucination.
- **Delivery & read receipts** — full status sync (SENT / DELIVERED / READ / FAILED).
- **Media persistence** — every inbound/outbound media file re-hosted to secure storage so links never expire.
- **Multi-number support** — connect unlimited WhatsApp Lite numbers per workspace (sales, support, branches).
- **Webhooks & API** — push inbound events to n8n, Zapier, Make, or your own backend.
- **Sentiment & auto-tagging** — AI classifies intent and tags contacts automatically.
- **Translation** — one-click translate inbound and outbound messages across 12 languages.

### When to choose Lite
- You need to launch **today** without Facebook verification.
- You run **outbound sales / cold outreach** where templates would slow you down.
- You operate **multiple numbers per team** and want flat pricing.
- You want to **test** WhatsApp as a channel before committing to Meta onboarding.

---

## WhatsApp Cloud (Official Meta API)

The fully sanctioned WhatsApp Business Platform, hosted by Meta. Built for brands that need verification, scale, and compliance.

### Key features

- **Embedded Signup** — one-click Meta onboarding inside ConnectGain; we provision the WABA and phone number for you.
- **Manual System User connection** — for partner WABAs that don't appear in the wizard.
- **Green-tick verification** — eligible accounts can apply for the Official Business badge.
- **Approved [message templates](https://docs.connectgain.cloud/marketing/02-user-guide/templates.md)** — submit, edit, translate, and reuse templates across markets.
- **Dynamic template variables** — fully personalised body, header (image / video / document / location), and CTA buttons.
- **Interactive messages** — reply buttons, list pickers, single/multi-product messages, flows.
- **24h customer-care window** — automatic detection; the UI nudges you to use a template when the window closes.
- **Tier-based scaling** — automatic Meta limit upgrades from 1K → 10K → 100K → unlimited unique recipients / 24h.
- **WABA health monitoring** — live status of business verification, account review, template namespace, and per-entity send eligibility.
- **Auto token refresh & re-connect** — background token-health checks; channels auto-deactivate and notify admins before failure.
- **Conversation-based billing visibility** — see Meta categories (Marketing / Utility / Authentication / Service) per conversation.
- **Catalog & commerce** — product messages, single & multi-product, with Shopify and custom catalogs.
- **Click-to-WhatsApp ads** — receive ad-referral context on the first inbound message for attribution.
- **Comment-to-DM** — automatically (or manually) move a Facebook/Instagram comment into a WhatsApp Cloud DM where supported.
- **Historical sync** — back-fill recent conversations on connect via the unified `channel-sync-history` job.
- **End-to-end encrypted** in transit, with media re-hosted to your private storage bucket.

### When to choose Cloud
- You need the **green tick** and verified business identity.
- You run **high-volume utility or marketing** notifications (orders, OTPs, reminders).
- You require **enterprise compliance** (Meta-sanctioned, full audit trail).
- You're scaling beyond what Lite's soft limits comfortably allow.

---

## Shared capabilities (both channels)

Every feature below works identically across WhatsApp Lite and WhatsApp Cloud.

### Unified inbox
- One inbox for WhatsApp, Messenger, Instagram, Telegram, TikTok, LinkedIn, Shopify Inbox, Email.
- Conversation assignment with **slots → online → round-robin** workload balancing.
- Human takeover pauses automation at the conversation level.
- Reply-to (quoted messages), reactions, typing indicators, voice notes.
- Internal notes, mentions, and team-only threads.
- Snooze, close, reopen, and bulk actions.
- Per-user channel access controls.

### CRM & automation
- Auto-create / match contacts by E.164 phone number with strict normalization.
- Auto-tag, auto-assign, and trigger deals from inbound messages.
- Task automation engine with 24h-window-aware actions.
- Sequences with timezone-aware scheduling, opt-out enforcement, and secure random unsubscribe tokens.
- Bot flows with AI intent classification (Gemini 2.5 Flash) and voice agent nodes (ElevenLabs).

### AI
- **RAG-powered auto-reply** trained on your docs, products, and FAQs.
- **Conversation analysis** — sentiment, summary, next-best action.
- **[AI re-engagement](https://docs.connectgain.cloud/marketing/02-user-guide/ai-reengagement.md)** for stale conversations with anti-spam pacing (30s–10min jitter).
- **Translation** across 12 languages.
- **Speech-to-text** for voice notes (Gemini 2.5 Flash).

### Analytics & monitoring
- Per-channel volume, response time, FRT, resolution time.
- Per-agent performance (excludes Owners/Admins/PMs from agent reports).
- Inbox health dashboard with provider-vs-insertion latency.
- Webhook DLQ with automatic retry cron.
- Sentry-backed error monitoring with PII scrubbing.

### Security & reliability
- HMAC-verified webhooks with constant-time comparison.
- Multi-tenant Row-Level Security on every table.
- 30-day JWT sessions for mobile reliability.
- Media persisted to private storage; provider URL expiry handled automatically.
- 24h-window guard prevents non-template sends from failing silently.

---

## Decision helper

> **Pick WhatsApp Lite if** you want to launch today, send freely, run outbound sales, or operate many numbers on flat pricing.
>
> **Pick WhatsApp Cloud if** you need the green tick, verified branding, high-volume utility/marketing, or full Meta compliance.
>
> **Use both** — Lite for sales & outbound, Cloud for branded support & transactional notifications. ConnectGain unifies them in the same inbox, CRM, and automations.

---

## CTAs for landing page

- **Primary:** *Connect your WhatsApp in 2 minutes* → onboarding → Channels → WhatsApp Lite.
- **Secondary:** *Get the official Meta API* → onboarding → Channels → WhatsApp Cloud (Embedded Signup).
- **Tertiary:** *Talk to sales* for enterprise WABA migration.

---

## See also

- [Channel connection guide](https://docs.connectgain.cloud/marketing/05-integrations/channels.md)
- [WhatsApp Lite API](https://docs.connectgain.cloud/marketing/05-integrations/whatsapp-lite-api.md)
- [WhatsApp Cloud System User setup](https://docs.connectgain.cloud/marketing/05-integrations/whatsapp-cloud-system-user.md)
- [Sequences (drip campaigns)](https://docs.connectgain.cloud/marketing/02-user-guide/sequences.md)
- [Campaigns & broadcast](https://docs.connectgain.cloud/marketing/02-user-guide/campaigns.md)
- [Appgain WhatsApp Business API](https://www.appgain.io/WhatsApp) — WhatsApp Lite's underlying service
- [WhatsApp Lite page on connectgain.cloud](https://connectgain.cloud/en/whatsapp-lite) — feature overview on the ConnectGain website
- [WhatsApp Cloud page on connectgain.cloud](https://connectgain.cloud/en/whatsapp-cloud) — feature overview on the ConnectGain website

---

**Last updated:** 2026-06-12.

---

*[ConnectGain](https://connectgain.cloud) — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. [Open the app](https://dashboard.connectgain.cloud) · [Docs home](https://docs.connectgain.cloud/marketing/index.md)*