# WhatsApp Groups

Mine conversations from WhatsApp groups to automatically build and update your AI's knowledge base.

---

WhatsApp Groups integration lets your AI learn from real conversations happening in your WhatsApp groups. Instead of manually creating knowledge sources, your AI's knowledge base stays current by automatically ingesting group chat transcripts through the RAG pipeline.

This is separate from [1:1 WhatsApp messaging](/docs/integrations/whatsapp) where users chat directly with your AI. Group integration is about **listening and learning**, not responding.

> **Note:** WhatsApp Groups requires an active WhatsApp Business connection. Set up [WhatsApp integration](/docs/integrations/whatsapp) first.

## How It Works

1. You connect a WhatsApp group to your app by providing the group ID
2. Incoming group messages are buffered in the database (text messages only)
3. On a configurable schedule, buffered messages are formatted into a conversation transcript
4. The transcript is processed through the RAG pipeline -- chunked, embedded, and stored as a knowledge source
5. Your AI can now reference the group's conversations when answering questions

Each connected group becomes its own knowledge source, labeled "WhatsApp Group: [name]" in your knowledge sources list. The knowledge source is updated incrementally as new messages arrive and get ingested.

## Mining Modes

Each group can be configured with a mining mode that controls how messages are used:

| Mode | Behavior |
|------|----------|
| **Knowledge** | Messages are buffered and periodically ingested into the RAG knowledge base. The AI learns from conversations but does not participate. |
| **Reactive** | Messages are available for real-time context but not permanently stored in the knowledge base. |
| **Both** | Combines knowledge ingestion with reactive access. |

The default mode is **Knowledge**, which is the most common use case.

## Connecting a Group


  **1.** 
    <strong>Ensure WhatsApp Is Connected</strong>

    Your app must have an active WhatsApp Business connection. Go to **Share** and verify the WhatsApp deployment is configured and active.
  


  **2.** 
    <strong>Get the Group ID</strong>

    The group ID is provided by the WhatsApp Business API when your number is added to a group. You can find it in the webhook payloads or through the Meta Business Platform.
  


  **3.** 
    <strong>Add the Group</strong>

    Use the API to register the group for mining:

    ```
    POST /api/applications/:appId/whatsapp-groups
    ```

    ```json
    {
      "groupId": "120363012345678901@g.us",
      "groupName": "Product Team Chat",
      "miningMode": "knowledge",
      "ingestionIntervalMinutes": 1440
    }
    ```
  


  **4.** 
    <strong>Wait for Messages</strong>

    As group members send messages, they are automatically buffered. At each ingestion interval, the buffered messages are processed into your knowledge base.
  


## Configuration Options

| Field | Range | Default | Description |
|-------|-------|---------|-------------|
| `groupName` | -- | -- | Friendly name for the group (used in the knowledge source label) |
| `miningMode` | `knowledge`, `reactive`, `both` | `knowledge` | How messages are processed |
| `ingestionIntervalMinutes` | 60--10,080 | 1,440 (24h) | How often buffered messages are ingested into RAG |
| `isActive` | `true`/`false` | `true` | Pause or resume message buffering |

### Ingestion Interval

The interval controls how frequently the cron job processes buffered messages into the knowledge base. Shorter intervals mean more current knowledge but more processing. Longer intervals batch more messages into each ingestion cycle.

| Interval | Good For |
|----------|----------|
| 60 min (1 hour) | Fast-moving groups where recency matters |
| 1,440 min (24 hours) | Most groups -- daily knowledge updates |
| 10,080 min (7 days) | Low-traffic groups or cost-sensitive setups |

## What Gets Ingested

Only **text messages** are buffered and ingested. Images, videos, documents, stickers, and other media types are silently skipped.

Messages are formatted as a timestamped conversation transcript before being processed through the RAG pipeline:

```
WhatsApp Group: Product Team Chat
Messages: 47

[2026-03-23 10:15:00 UTC] Sarah (+1 212 555 1234): Just found an amazing deal on bulk materials
[2026-03-23 10:17:00 UTC] Mike (+1 310 555 5678): @Sarah what dates are you looking at?
[2026-03-23 10:18:00 UTC] Sarah (+1 212 555 1234): Next month, around the 15th
```

Each ingestion cycle creates or updates the group's knowledge source with the new transcript, which is then chunked and embedded for retrieval.

## Managing Groups

### List Configured Groups

```
GET /api/applications/:appId/whatsapp-groups
```

Returns all group configs with message statistics (total messages, pending messages, last message timestamp).

### Update a Group Config

```
PUT /api/applications/:appId/whatsapp-groups/:id
```

```json
{
  "miningMode": "both",
  "ingestionIntervalMinutes": 360
}
```

### Pause a Group

Set `isActive` to `false` to stop buffering new messages without deleting the config:

```json
{
  "isActive": false
}
```

### Trigger Manual Ingestion

Instead of waiting for the next scheduled ingestion, trigger it immediately:

```
POST /api/applications/:appId/whatsapp-groups/:id/ingest
```

Returns the number of messages processed and chunks created.

### Remove a Group

```
DELETE /api/applications/:appId/whatsapp-groups/:id
```

This removes the group config and its buffered messages. The knowledge source created from previous ingestions remains in your knowledge base until you delete it separately.

## Use Cases

| Use Case | Example |
|----------|---------|
| **Internal knowledge capture** | Mine your team's Slack-like WhatsApp group so the AI knows about recent decisions and discussions |
| **Community FAQ** | Learn from a customer community group to answer common questions automatically |
| **Industry monitoring** | Track industry groups to keep your AI current on trends and news |
| **Sales intelligence** | Mine prospect-facing groups for context the sales AI can reference |
| **Support escalation** | Capture support team discussions so the consumer-facing AI learns from real resolutions |

## Message Deduplication

Messages are deduplicated by WhatsApp message ID per group config. If the same message arrives twice (e.g., webhook retries), only one copy is stored. This prevents duplicate content in your knowledge base.

## Troubleshooting

**No messages being buffered?**
- Verify the group ID matches exactly (including the `@g.us` suffix)
- Check that the group config `isActive` is `true`
- Confirm your WhatsApp Business number is a member of the group
- Only text messages are buffered -- media messages are skipped

**Knowledge source not updating?**
- Check the ingestion interval -- the cron job only runs when the interval has elapsed
- Use the manual ingest endpoint to trigger immediately
- Verify the mining mode is set to `knowledge` or `both`

**Duplicate group error (409)?**
- Each group ID can only be configured once per app
- Delete the existing config first if you want to reconfigure

> **Tip:** Combine WhatsApp group mining with [scheduled Heartbeat messages](/docs/guides/heartbeat) to build an AI that proactively shares insights from group conversations with individual users.