Message Management Feature¶

Overview¶

Message Management is the core messaging functionality that enables sending and receiving messages across multiple channels (WhatsApp Lite, WhatsApp Cloud, Facebook Messenger, Instagram Direct Messages, Telegram, TikTok, Email, SMS, and Web Push) with support for rich media, message status tracking, and real-time delivery. Messages are managed within conversations in the unified inbox.

Features¶

1. Multi-Channel Messaging¶

Supported Channels: - WhatsApp Lite (AppGain) - QR code authentication, media support, delivery receipts, template messaging, link shortening - WhatsApp Cloud (Meta) - Business API integration, OAuth authentication, approved templates, rich media, interactive buttons - Facebook Messenger - OAuth integration, page connection, quick replies, buttons and carousels, typing indicators - Instagram Direct Messages - Business account connection, OAuth authentication, stories, media support, message requests - Telegram - Bot API integration, bot token authentication, stickers, polls, group messaging, channel broadcasting - TikTok - Business API integration, token authentication, video messaging, media support - Email - SMTP integration, HTML email support, attachment support, email threading - SMS (outbound broadcast/sequences only — not in the inbox) - via Appgain Notify (VictoryLink provider), character limit management (160/1600), delivery tracking, link shortening - Web Push Notifications - Background notifications (Android/iOS PWA), automatic subscription, VAPID authentication

Channel Features: - Channel-specific capabilities - Channel-specific formatting - Channel status tracking (Active/Inactive) - Channel-specific media support - Channel health monitoring - Delivery and read receipts (where supported)

2. Message Types¶

Text Messages: - Plain text - Rich text formatting - Emoji support - Character limits per channel

Media Messages: - Images - JPG, PNG, GIF, WebP - Videos - MP4, MOV, AVI - Audio - MP3, WAV, OGG - Documents - PDF, DOCX, XLSX, etc. - Location - GPS coordinates - Contacts - vCard format

Interactive Messages: - Buttons - Quick replies - Lists - Templates

3. Message Status Tracking¶

Status Types: - Sent ✓ - Message sent successfully - Delivered ✓✓ - Message delivered to recipient - Read ✓✓ (blue) - Message read by recipient (WhatsApp) - Failed ✗ - Message failed to send - Pending ⏳ - Message queued for sending

Status Features: - Real-time status updates - Status indicators in UI (visual icons) - Status history tracking - Delivery receipts (channel-dependent) - Read receipts (WhatsApp, Messenger) - Failed message retry logic - Error message details

4. Message Sending¶

Sending Features: - Send to single contact - Send to multiple contacts - Schedule messages - Template-based sending - Variable substitution - Media attachments

Sending Options: - Send immediately - Schedule for later - Recurring messages - Bulk sending

5. Message Receiving¶

Receiving Features: - Real-time message delivery - Webhook integration - Message parsing - Contact auto-creation - Conversation auto-creation - Media download

6. Message Threading¶

Threading Features: - Conversation-based threading - Message history - Thread continuity - Multi-participant threads - Thread assignment

7. Message History¶

History Features: - Complete message history - Search messages - Filter by date - Filter by channel - Filter by contact - Export messages

8. Message Actions¶

Available Actions: - Reply to message - Forward message - Delete message - Mark as read/unread - Copy message text - Download attachments - Create task from message - Create deal from message

Use Cases¶

Use Case 1: Send Text Message¶

Scenario: Agent wants to send a text message to a customer.

Steps: 1. Open conversation in Inbox 2. Type message in composer 3. Click send 4. Verify message sent 5. Check message status 6. Wait for delivery confirmation 7. Wait for read receipt (if available)

Expected Outcome: Message sent successfully with status tracking.

Use Case 2: Send Media Message¶

Scenario: Agent wants to send product image to customer.

Steps: 1. Open conversation 2. Click attach media button 3. Select image file 4. Add caption (optional) 5. Send message 6. Verify image sent 7. Check delivery status

Expected Outcome: Image message sent and delivered successfully.

Use Case 3: Send Template Message¶

Scenario: Business wants to send approved template message.

Steps: 1. Open conversation 2. Click template button 3. Select template from library 4. Fill template variables 5. Preview message 6. Send message 7. Verify template used correctly

Expected Outcome: Template message sent with variables substituted.

Use Case 4: Schedule Message¶

Scenario: Agent wants to send message at specific time.

Steps: 1. Compose message 2. Click schedule button 3. Select date and time 4. Confirm schedule 5. Verify message scheduled 6. Wait for scheduled time 7. Verify message sent automatically

Expected Outcome: Message scheduled and sent at specified time.

Use Case 5: Receive and Respond¶

Scenario: Customer sends message, agent needs to respond.

Steps: 1. Receive notification of new message 2. Open conversation 3. View incoming message 4. Read message content 5. Compose response 6. Send reply 7. Verify conversation updated

Expected Outcome: Message received and responded to successfully.

Test Cases¶

Test Case 1: Send Text Message¶

Test: Verify text message sending

Steps: 1. Open conversation 2. Type message: "Hello, how can I help?" 3. Send message 4. Verify message appears in thread 5. Check status: SENT 6. Wait for delivery 7. Verify status: DELIVERED 8. Wait for read receipt 9. Verify status: READ (if supported)

Expected Result: Message sent and status tracked correctly

Test Case 2: Send Image Message¶

Test: Verify image message sending

Steps: 1. Open conversation 2. Click attach image 3. Select image file 4. Add caption: "Product image" 5. Send message 6. Verify image uploaded 7. Verify message sent 8. Check image displays correctly 9. Verify delivery status

Expected Result: Image message sent and displayed correctly

Test Case 3: Receive Message¶

Test: Verify message receiving

Steps: 1. Send test message from external channel 2. Verify webhook received 3. Verify message created in system 4. Verify conversation created/updated 5. Verify contact created/updated 6. Check message appears in inbox 7. Verify real-time update

Expected Result: Message received and processed correctly

Test Case 4: Message Status Tracking¶

Test: Verify status tracking

Steps: 1. Send message 2. Verify initial status: SENT 3. Wait for delivery confirmation 4. Verify status: DELIVERED 5. Wait for read receipt 6. Verify status: READ 7. Check status history

Expected Result: Message status tracked through all stages

Test Case 5: Multi-Channel Messaging¶

Test: Verify multi-channel support

Steps: 1. Send WhatsApp message 2. Verify WhatsApp formatting 3. Send Messenger message 4. Verify Messenger formatting 5. Send Instagram message 6. Verify Instagram formatting 7. Check channel-specific features

Expected Result: All channels supported with correct formatting

Test Case 6: Message Threading¶

Test: Verify message threading

Steps: 1. Send initial message 2. Receive reply 3. Send follow-up message 4. Verify all messages in same thread 5. Check conversation continuity 6. Verify thread assignment

Expected Result: Messages threaded correctly in conversation

Test Case 7: Message Search¶

Test: Verify message search

Steps: 1. Send multiple messages 2. Search for specific text 3. Verify matching messages found 4. Filter by date range 5. Filter by channel 6. Filter by contact 7. Verify filters work correctly

Expected Result: Message search and filtering work correctly

Test Case 8: Message Actions¶

Test: Verify message actions

Steps: 1. Send message 2. Reply to message 3. Forward message 4. Copy message text 5. Delete message 6. Mark as read/unread 7. Verify all actions work

Expected Result: All message actions work correctly

API Integration¶

Send Message¶

Endpoint: POST /functions/v1/{channel}-send

Request (WhatsApp Lite):

{
 "phone_number": "+1234567890",
 "message": "Hello, this is a test message",
 "organization_id": "org-uuid",
 "contact_id": "contact-uuid"
}

Request (with media):

{
 "phone_number": "+1234567890",
 "message": "Check out this image",
 "media_url": "https://example.com/image.jpg",
 "media_type": "image",
 "organization_id": "org-uuid"
}

Get Messages¶

Endpoint: GET /rest/v1/messages

Query Parameters: - conversation_id - Filter by conversation - contact_id - Filter by contact - channel - Filter by channel - direction - Filter by direction (INBOUND/OUTBOUND) - status - Filter by status

Webhook Receiver¶

Endpoint: POST /functions/v1/{channel}-webhook

Webhook Payload:

{
 "message_id": "msg-123",
 "from": "+1234567890",
 "to": "+0987654321",
 "message": "Hello",
 "timestamp": "2025-01-15T10:00:00Z",
 "channel": "whatsapp_lite"
}

Best Practices¶

Message Composition
Keep messages concise
Use appropriate tone
Include clear call-to-action
Personalize when possible
Media Usage
Optimize image sizes
Use appropriate formats
Add captions to media
Test media delivery
Status Monitoring
Monitor delivery status
Follow up on failed messages
Track read receipts
Analyze delivery rates
Channel Selection
Use appropriate channel
Respect channel limits
Follow channel guidelines
Test channel features
Message Timing
Send during business hours
Respect time zones
Use scheduling for off-hours
Avoid spam patterns

Troubleshooting¶

Message Not Sending¶

Issue: Message fails to send

Solutions: - Check channel configuration - Verify contact phone number - Check message format - Review error logs - Verify channel status

Message Not Delivered¶

Issue: Message sent but not delivered

Solutions: - Check recipient phone number - Verify channel connectivity - Check delivery status - Review channel logs - Contact channel support

Media Not Sending¶

Issue: Media attachments not sending

Solutions: - Check file size limits - Verify file format supported - Check media URL accessibility - Verify channel media support - Test with different file

Last Updated: January 2025