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 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 first.
- You connect a WhatsApp group (for example, your "Field Tech Daily" group) to your agent by providing the group ID
- Incoming group messages are buffered in the database (text messages only)
- On a configurable schedule, buffered messages are formatted into a conversation transcript
- The transcript is processed through the RAG pipeline, chunked, embedded, and stored as a knowledge source
- 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.
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.
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.
| 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 |
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.
List Configured Groups#
GET /api/applications/:appId/whatsapp-groupsReturns all group configs with message statistics (total messages, pending messages, last message timestamp).
Update a Group Config#
PUT /api/applications/:appId/whatsapp-groups/:id{
"miningMode": "both",
"ingestionIntervalMinutes": 360
}Pause a Group#
Set isActive to false to stop buffering new messages without deleting the config:
{
"isActive": false
}Trigger Manual Ingestion#
Instead of waiting for the next scheduled ingestion, trigger it immediately:
POST /api/applications/:appId/whatsapp-groups/:id/ingestReturns the number of messages processed and chunks created.
Remove a Group#
DELETE /api/applications/:appId/whatsapp-groups/:idThis 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 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 |
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.
No messages being buffered?
- Verify the group ID matches exactly (including the
@g.ussuffix) - Check that the group config
isActiveistrue - 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
knowledgeorboth
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 to build an agent that proactively shares insights from the field-tech group with the dispatch team.
*AVCodex · Your AV expertise. Amplified by AI.*