# WhatsApp Groups

Mine the field-tech group chats your team already runs. Every "anyone seen this Crestron error?", every "fixed it, here's how", every "manufacturer just confirmed it's a firmware bug" gets folded into your AVCodex agent's knowledge automatically.

---

WhatsApp Groups integration lets your AVCodex agent learn from real conversations happening in your WhatsApp groups. Instead of manually creating knowledge sources, the agent'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 agent. 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 (for example, your "Field Tech Daily" group) to your agent 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 agent 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 agent 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.**
    **Ensure WhatsApp Is Connected**

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

  **2.**
    **Get the Group ID**

    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.**
    **Add the Group**

    Use the API to register the group for mining:

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

    ```json
    {
      "groupId": "120363012345678901@g.us",
      "groupName": "Field Tech Daily",
      "miningMode": "knowledge",
      "ingestionIntervalMinutes": 1440
    }
    ```

  **4.**
    **Wait for Messages**

    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 during a major commissioning week |
| 1,440 min (24 hours) | Most groups, daily knowledge updates |
| 10,080 min (7 days) | Low-traffic groups (a quiet dealer-program chat) 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. (A photo of a fault LED is not ingested. The text reply that says "that's the Tesira AVB grandmaster mismatch" is.)

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

```
WhatsApp Group: Field Tech Daily
Messages: 47

[2026-03-23 10:15:00 UTC] Sarah (+1 212 555 1234): Boardroom 4's DM-NVX-360 is dropping audio every 12 min, anyone else?
[2026-03-23 10:17:00 UTC] Mike (+1 310 555 5678): @Sarah we saw that on a 1.6111 firmware build. Roll back to 1.6010.
[2026-03-23 10:18:00 UTC] Sarah (+1 212 555 1234): Confirmed, that fixed it. Thanks.
```

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 "Field Tech Daily" group so the agent learns every fix the team discovers in real time |
| **Dealer program FAQ** | Learn from a dealer-support group to answer common dealer questions automatically |
| **Manufacturer firmware tracking** | Track manufacturer-rep groups (Crestron, QSC, Biamp) to keep the agent current on firmware quirks |
| **Bid intelligence** | Mine the bid-team group for RFP context the BD agent can reference |
| **Commissioning escalation** | Capture commissioning lead discussions so the field-facing agent learns from real resolutions |

## Message Deduplication

Messages are deduplicated by WhatsApp message ID per group config. If the same message arrives twice (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 agent
- 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 agent that proactively shares insights from the field-tech group with the dispatch team.

*AVCodex · Your AV expertise. Amplified by AI.*