WhatsApp Groups

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 where users chat directly with your AI. Group integration is about listening and learning, not responding.

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:

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

Connecting a Group

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

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

Configuration Options

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.

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

{
  "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/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

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