> {
const response = await this.http.get('/api/conversations', {
params: { page: pagination.page, pageSize: pagination.pageSize }
}).toPromise();
return response;
}
// Implement other required methods...
}
```
### Built-in API Implementations
#### IndexedDB API (Development/Demo)
```typescript
import {
provideConversation,
AXIndexedDBUserApi,
AXIndexedDBConversationApi,
AXIndexedDBMessageApi,
AXIndexedDBRealtimeApi,
} from '@acorex/components/conversation';
// Provides in-memory storage with sample data
// Perfect for development and demos
provideConversation({
userApi: AXIndexedDBUserApi,
conversationApi: AXIndexedDBConversationApi,
messageApi: AXIndexedDBMessageApi,
realtimeApi: AXIndexedDBRealtimeApi,
});
```
Register a service that subscribes to `AXUploaderService.onUpload`, `onResolveUrl`, and `onDeleteMedia` (see showcase `AXShowcaseConversationIndexedDbUploaderService`).
#### IndexedDB with AI API (AI-Powered Demo)
```typescript
import {
provideConversation,
AXIndexedDBUserApi,
AXIndexedDBConversationApi,
AXIndexedDBMessageAIApi,
AXIndexedDBRealtimeApi,
} from '@acorex/components/conversation';
// Includes AI-powered auto-responses via message API
provideConversation({
userApi: AXIndexedDBUserApi,
conversationApi: AXIndexedDBConversationApi,
messageApi: AXIndexedDBMessageAIApi,
realtimeApi: AXIndexedDBRealtimeApi,
});
```
## โ๏ธ Configuration
### Conversation Config
```typescript
interface AXConversationConfig {
// Pagination
messagePageSize?: number; // Default: 50
conversationPageSize?: number; // Default: 30
infiniteScrollThreshold?: number; // Default: 200px
scrollThreshold?: number; // Default: 100px
// UI Behavior
messageHighlightDuration?: number; // Default: 2000ms
typingIndicatorTimeout?: number; // Default: 3000ms
}
```
### Registry Configuration
```typescript
interface AXConversationRegistryConfiguration {
messageRenderers?: AXConversationMessageRenderer[];
messageActions?: AXConversationMessageAction[];
composerActions?: AXConversationComposerAction[];
composerTabs?: AXConversationComposerTab[];
conversationTabs?: AXConversationTab[];
infoBarActions?: AXConversationInfoBarAction[];
conversationItemActions?: AXConversationItemAction[];
}
```
## ๐จ Customization
### Custom Message Renderer
```typescript
import { Component, input } from '@angular/core';
import { AXConversationMessageRenderer } from '@acorex/components/conversation';
@Component({
selector: 'my-custom-renderer',
template: `{{ message().payload.customData }}
`
})
export class MyCustomRendererComponent {
message = input.required();
}
const myRenderer: AXConversationMessageRenderer = {
type: 'custom',
component: MyCustomRendererComponent,
priority: 100
};
// Register in config
provideConversation({
api: MyApi,
registry: {
messageRenderers: [myRenderer]
}
});
```
### Custom Message Action
```typescript
const forwardAction: AXConversationMessageAction = {
id: 'forward',
label: 'Forward',
icon: 'forward',
shortcut: 'Ctrl+F',
enabled: (message, user) => message.senderId === user.id,
execute: async (message, service) => {
// Forward logic
}
};
provideConversation({
api: MyApi,
registry: {
messageActions: [forwardAction]
}
});
```
## ๐ฑ Components
### Main Components
- `` - Full conversation UI with sidebar, messages, and composer
- `` - Conversation list sidebar
- `` - Message list with virtual scrolling
- `` - Message input area
- `` - Conversation header with actions
### Usage Examples
```html
```
## ๐ญ Services
### AXConversationService
Main service for conversation operations:
```typescript
import { inject } from '@angular/core';
import { AXConversationService } from '@acorex/components/conversation';
export class MyComponent {
private conversationService = inject(AXConversationService);
async sendMessage() {
await this.conversationService.sendMessage({
conversationId: 'conv-123',
type: 'text',
payload: { text: 'Hello!' }
});
}
async createConversation() {
const conv = await this.conversationService.createConversation(
['user-1', 'user-2'],
'private'
);
}
}
```
## ๐งช Testing
```typescript
import { TestBed } from '@angular/core/testing';
import { provideConversation, AXConversationService } from '@acorex/components/conversation';
import { MockUserApi, MockConversationApi, MockMessageApi } from './mocks/mock-apis';
describe('MyComponent', () => {
beforeEach(() => {
TestBed.configureTestingModule({
providers: [
provideConversation({
userApi: MockUserApi,
conversationApi: MockConversationApi,
messageApi: MockMessageApi,
}),
],
});
});
it('should send message', async () => {
const service = TestBed.inject(AXConversationService);
const message = await service.sendMessage({
conversationId: 'test',
type: 'text',
payload: { text: 'Test' },
});
expect(message).toBeDefined();
});
});
```
## ๐ฏ Message Types
Supported message types out of the box:
- **text** - Plain text messages
- **image** - Image messages with thumbnails
- **video** - Video messages with playback
- **audio** - Audio file messages
- **voice** - Voice recordings
- **file** - Generic file attachments
- **location** - Location sharing
- **sticker** - Sticker messages
- **contact** - Contact card sharing
- **system** - System notifications
## ๐ Security Considerations
- **API Keys**: Never hardcode API keys in source code. Use environment variables or injection tokens.
- **File Upload**: Validate file types and sizes on both client and server.
- **XSS Protection**: All user content is sanitized by default.
- **Authentication**: Implement proper authentication in your API layer.
## ๐ Performance Tips
1. **Virtual Scrolling**: Enabled by default for large message lists
2. **Lazy Loading**: Images and media are loaded on demand
3. **Pagination**: Messages are loaded in pages to reduce initial load
4. **Debouncing**: Typing indicators are debounced to reduce network traffic
5. **Memoization**: Use computed signals for expensive calculations
## ๐ Troubleshooting
### Common Issues
**Issue**: Messages not appearing
- Check if API is connected: `conversationService.connectionStatus$()`
- Verify API implementation returns correct data structure
**Issue**: File upload fails
- Check composer file-type catalogs and per-action `uploadConstraints` (`allowedMimeTypes`, `minSize`, `maxSize`)
- Register a handler service subscribed to `AXUploaderService.onUpload` (and resolve/delete events) with progress and `AbortSignal` support
**Issue**: Styling issues
- Ensure all Acorex component styles are imported
- Check for CSS conflicts with global styles
## ๐ Additional Resources
- [Quick Start Guide](./docs/QUICK-START.md) - Get started in 5 minutes
- [Architecture Overview](./docs/ARCHITECTURE-OVERVIEW.md) - Understand the module structure
- [API Documentation](./docs/ARCHITECTURE-APIS.md) - Implement custom backends
- [Component Guide](./docs/ARCHITECTURE-COMPONENTS.md) - Learn about components
- [Plugin System](./docs/ARCHITECTURE-PLUGINS.md) - Extend functionality
- [Usage Guide](./docs/USAGE-GUIDE.md) - Advanced usage patterns
## ๐ค Contributing
Contributions are welcome! Please read our [Contributing Guide](./CONTRIBUTING.md) for details.
## ๐ License
MIT License - see LICENSE file for details
## ๐ Changelog
See [CHANGELOG.md](./CHANGELOG.md) for version history and updates.
## ๐ฌ Support
- GitHub Issues: [Report a bug](https://github.com/acorexui/acorex-ui/issues)
- Discussions: [Ask questions](https://github.com/acorexui/acorex-ui/discussions)