> ## Documentation Index
> Fetch the complete documentation index at: https://www.docs.wazap.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Storage System Overview
> Persist and query WhatsApp messages with automatic storage integration
## What is Storage?
The WhatsApp Client SDK includes a powerful storage system that automatically persists incoming and outgoing messages to a database. This enables you to:
* ๐ **Query conversation history** - Retrieve past messages and conversations
* ๐ **Search messages** - Full-text search across all messages
* ๐ **Analytics** - Track conversation metrics and patterns
* ๐พ **Data retention** - Automatic cleanup of old messages
* ๐งต **Thread tracking** - Follow message reply chains
## Key Features
Messages are automatically saved to your database without additional code
Search through all messages with powerful query capabilities
Track message counts, response rates, and engagement metrics
Export conversations in JSON or CSV format for analysis
Automatically track message replies and conversation threads
Configure automatic deletion of old messages based on your needs
## How It Works
### 1. Enable Storage
Configure storage when initializing the WhatsApp client:
```typescript theme={null}
import { WhatsAppClient } from 'whatsapp-client-sdk';
const client = new WhatsAppClient({
accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
// Enable storage
storage: {
enabled: true,
provider: 'supabase',
options: {
url: process.env.SUPABASE_URL!,
apiKey: process.env.SUPABASE_KEY!
},
features: {
persistIncoming: true,
persistOutgoing: true,
persistStatus: true,
autoConversations: true
}
}
});
// Initialize storage
await client.initializeStorage();
```
### 2. Messages Are Saved Automatically
Once storage is enabled, all messages are automatically persisted:
```typescript theme={null}
// Incoming messages are saved automatically via webhooks
const webhookProcessor = client.createWebhookProcessor({
onTextMessage: async (message) => {
// Message is already saved to database
await client.sendText(message.from, 'Got your message!');
// Response is also saved automatically
}
});
// Outgoing messages are saved when sent
await client.sendText('+1234567890', 'Hello!');
// Saved to database automatically
```
### 3. Query Your Data
Use the built-in query methods:
```typescript theme={null}
// Get conversation history
const conversation = await client.getConversation('+1234567890', {
limit: 50
});
// Search messages
const results = await client.searchMessages({
text: 'order',
phoneNumber: '+1234567890'
});
// Get analytics
const analytics = await client.getConversationAnalytics('+1234567890');
```
## Storage Providers
### Supabase (Recommended)
Supabase is the primary storage provider with full support for all features:
* โ
PostgreSQL-backed
* โ
Real-time subscriptions
* โ
Built-in authentication
* โ
Auto-generated APIs
* โ
Free tier available
Complete setup guide for Supabase storage
### Custom Adapters
You can implement your own storage adapter for other databases:
Learn how to create custom storage adapters
## Storage Configuration
### Feature Flags
Control what data is persisted:
```typescript theme={null}
storage: {
enabled: true,
provider: 'supabase',
options: { /* ... */ },
features: {
persistIncoming: true, // Save incoming messages
persistOutgoing: true, // Save outgoing messages
persistStatus: true, // Update message status (sent, delivered, read)
autoConversations: true, // Auto-create conversations
createThreads: true, // Track message threads/replies
enableSearch: true, // Enable full-text search
retentionDays: 90 // Auto-delete messages after 90 days
}
}
```
### Data Retention
Automatically clean up old messages:
```typescript theme={null}
// Configure automatic cleanup
features: {
retentionDays: 90 // Delete messages older than 90 days
}
// Or manually trigger cleanup
const deletedCount = await client.cleanupOldMessages();
console.log(`Deleted ${deletedCount} old messages`);
```
## Use Cases
### Customer Support
Track support conversations and response times:
```typescript theme={null}
// Get customer conversation history
const history = await client.getConversation(customerPhone);
// Analyze response patterns
const analytics = await client.getConversationAnalytics(customerPhone, {
from: new Date('2024-01-01'),
to: new Date()
});
console.log(`Average response time: ${analytics.averageResponseTime}ms`);
console.log(`Total conversations: ${analytics.totalMessages}`);
```
### E-commerce
Search order-related messages:
```typescript theme={null}
// Find all messages about a specific order
const orderMessages = await client.searchMessages({
text: 'ORDER-12345',
dateFrom: new Date('2024-01-01')
});
// Export for analysis
const exportData = await client.exportConversation(customerPhone, {
format: 'json'
});
```
### Compliance & Auditing
Maintain message records for compliance:
```typescript theme={null}
// Export conversation for audit trail
const auditLog = await client.exportConversation('+1234567890', {
format: 'csv',
dateFrom: new Date('2024-01-01'),
dateTo: new Date('2024-12-31')
});
// Save to compliance system
await saveToComplianceSystem(auditLog);
```
## Performance Considerations
### Indexing
Storage providers automatically create indexes on:
* Phone numbers
* Message timestamps
* Message types
* Status fields
### Pagination
Always use pagination for large datasets:
```typescript theme={null}
// Good: Paginated queries
const page1 = await client.getConversation(phone, { limit: 50, offset: 0 });
const page2 = await client.getConversation(phone, { limit: 50, offset: 50 });
// Avoid: Loading all messages at once
const allMessages = await client.getConversation(phone, { limit: 10000 });
```
### Caching
Implement caching for frequently accessed data:
```typescript theme={null}
const cache = new Map();
async function getCachedConversation(phone: string) {
if (cache.has(phone)) {
return cache.get(phone);
}
const conversation = await client.getConversation(phone);
cache.set(phone, conversation);
// Cache for 5 minutes
setTimeout(() => cache.delete(phone), 5 * 60 * 1000);
return conversation;
}
```
## Security
### Access Control
* Use service role keys only in backend code
* Never expose database credentials in frontend
* Implement Row Level Security (RLS) in Supabase
### Data Privacy
* Hash or encrypt sensitive message content
* Implement data retention policies
* Provide user data export/deletion capabilities
Learn security and performance best practices
## Next Steps
Complete guide to set up Supabase storage
Learn how to query and search stored messages
Build custom storage adapters for other databases
Security, performance, and production tips