Conversation Management (Inbox) Feature¶

Overview¶

The Inbox (/inbox) is the unified messaging center where all customer conversations across channels (WhatsApp Lite, WhatsApp Cloud, Facebook Messenger, Instagram Direct Messages, Telegram, TikTok, Shopify Inbox, LinkedIn, and Email) are managed in one place. It provides real-time messaging, conversation assignment, quick replies, and integration with CRM features. (SMS is broadcast-only and does not appear in the inbox.)

A WhatsApp conversation open in the unified inbox.

On this page: Features · Use Cases · Test Cases · API Integration · Best Practices · Troubleshooting

Features¶

1. Unified Conversation List¶

Multi-Channel View: - All conversations in one list - WhatsApp (Lite & Cloud) - Facebook Messenger - Instagram Direct Messages - Telegram - TikTok - Shopify Inbox - LinkedIn - Email

Real-Time Updates: - Live conversation sync - Unread indicators - Last message preview - Contact information (name, avatar, channel badge) - Status indicators (Open/Closed) - Channel badges for visual identification

Filtering Options: - Quick filters by channel type - Quick filters by status (Open/Closed) - Needs human — conversations the bot handed to your team and that nobody has picked up yet (the bot stays silent on them until an agent resumes it). Owners and admins also get a notification in the bell and a browser push when a chat lands here. - Quick filters by message type - Saved filters (persisted per user)

Multi-Select Bulk Actions:

Turn on multi-select from the list header, tick the conversations you want, then use the toolbar buttons or these shortcuts. They are bound to the physical key, so they work the same on an Arabic, French or US layout, and are ignored while you are typing in a field or a dialog is open.

Key	Action
`A`	Assign selected conversations (admins)
`U`	Unassign selected conversations (admins)
`C`	Close selected conversations
`O`	Reopen selected conversations
`M`	Merge selected conversations (needs 2 or more, all one contact)
`Esc`	Leave multi-select mode

Merging conversations: merge collapses several threads that belong to the same contact — the same person who reached you twice, or on two channels — into one. It is unavailable when the selection spans different contacts, or includes a conversation with no contact linked; hover the greyed-out Merge button to see which. To combine two different people, merge the contacts on the Contacts page first, then merge their conversations here.

Additional Features: - Search functionality - Bulk actions (clear all conversations) - Refresh control - Split view toggle - Full-screen mode (Esc to exit) - Online agents count and list - "Analyze Interest" conversation analysis - Runs automatically on a conversation's 3rd, 6th, 9th… incoming message, and on demand from the button. Owners and admins can switch the automatic runs off in Settings → AI Summaries → AI Conversation Analysis; the button keeps working either way. Each run is a metered AI call, so busy accounts that do not use the analysis should turn it off. - Online/offline connection status indicator

2. Message Thread View¶

Complete Message History: - Full conversation timeline - Real-time message delivery - Message status tracking: - Sent ✓ - Delivered ✓✓ - Read ✓✓ (blue) - Failed ✗ - Pending ⏳

Message Types Support: - Text messages - Images (JPG, PNG, GIF, WebP) - Videos (MP4, MOV, AVI) - Audio files (MP3, WAV, OGG) - Documents (PDF, DOCX, XLSX, etc.) - Location sharing - Contact cards (vCard)

Message Information: - Precise timestamps - Sender information (contact details and channel) - Sent from phone — a WhatsApp Lite message someone typed directly on the linked phone, rather than in ConnectGain, is labelled Sent from phone with a phone icon. It is never shown as sent by you or by whichever teammate is looking at the conversation. - Message actions: - Reply - Forward - Delete - Copy message text - Download attachments - View full details

3. Message Composer¶

Rich Text Input: - Full message composition - Media attachments (upload images, videos, documents) - Quick reply templates - Emoji support (full emoji picker) - Typing indicators - Message scheduling

Channel-Specific Features: - WhatsApp: Templates, media, location - Messenger: Quick replies, buttons - Instagram: Stories, media - Telegram: Stickers, polls

WhatsApp template messages in the thread: a template shows in the conversation exactly as the customer received it — the header, the body with their details filled in, and the footer, plus the header image, video or document if the template has one. This holds whoever sent it: you from the composer, a bot flow, an automation or a sequence. If WhatsApp could not be reached at the moment of sending, the thread shows the template's name instead, and the message itself still goes out.

4. Contact Panel¶

Contact Details: - Full contact information (name, email, phone) - Company association - Tags - Custom fields

Contact History: - All past interactions - Related deals - Related tasks - Related notes

Other Conversations: - Lists this customer's other chats, each on the number or channel it arrived on - Shows the channel and when the chat was last active - Click one to open it and read the full earlier history

A customer who writes to a second number of yours starts a separate chat, so the screen you are reading only shows what was said on that number. Use this list to jump to what the customer said on your other numbers.

Quick Actions: - Send message - Create deal - Create task - Add note - Edit contact - View full profile

5. Conversation Management¶

Conversation Actions: - Assign conversations to team members - Status management (Open/Close conversations) - Add tags to organize conversations - Add notes (internal notes) - Create deal (convert conversation to deal) - Create task (create follow-up task) - Delete conversation - Conversation search

Tags on a chat in the list:

A chat in the list shows its first three tags on a single line. When it has more, a +N button appears; click it to see every tag without opening the chat. Long tag names are shortened, and hovering over one shows the full name.

Handing a chat to a colleague:

Open the chat, choose Assign and pick the person. They are notified, and the chat moves into their inbox.

If your account is set up to show only the chats assigned to you, the chat leaves your list the moment you hand it over, and the thread you had open closes. That is expected — your colleague has it now. Ask an administrator if you need to keep seeing chats after passing them on.

When a customer gives a different phone number:

Customers often order for someone else, or give a second number for delivery. The chat stays with the person you are actually talking to — it does not move to the other number, and the conversation keeps its history in one place. The order itself is still saved against the delivery number they gave you.

Pausing and resuming the bot:

When a bot is handling a chat, a Bot button sits in the chat header and shows whether it is currently answering or paused. Pause it to take the conversation over yourself, and switch it back on when you want the bot to carry on.

If the bot stops on its own — for example because someone on your team replied — the button stays in the header so you can switch it back on whenever you are done. You will see it on any chat where the bot is paused, including chats run by a bot flow.

Mobile Optimization: - Responsive layout (optimized for mobile devices) - Touch-friendly interactions - Sheet panels (slide-out panels for mobile) - Swipe actions (gesture-based controls)

6. Quick Replies¶

Features: - Pre-defined message templates - Variable substitution - Category organization - Quick access (type /) - Recent replies - Favorite replies

If you have no quick replies yet, the quick reply picker shows a Create a template link that opens Settings → Templates with the new-template window already open.

7. Real-time Updates¶

Real-time Features: - New message notifications - Typing indicators - Message status updates - Conversation status changes - Assignment notifications - Online/offline status

8. Mobile Responsive¶

Mobile Features: - Touch-optimized interface - Swipe actions - Mobile notifications - Offline support - Quick actions menu

What the conversation counts include¶

Closing a conversation takes it out of the work queues immediately. Every number that tells you what still needs attention counts open conversations only:

The unread badge on each conversation in the list
The Unread, Unassigned and Awaiting reply filter counts above the list
The unread count beside each channel in the channel sidebar
The Inbox badge in the main navigation, on every screen
The Unread Conversations and Awaiting Our Reply widgets on the Dashboard

So if you close a conversation that still has an unread message in it, it leaves those counts the moment you close it. Nothing is deleted — the conversation, its messages and its history stay exactly where they were, and you can still find it through the Closed filter or search.

Reports where you choose the scope behave differently. In Settings → Conversation Routing, the workload and distribution cards have an Open only / Total switch:

Open only counts what is still open — the same rule as the queues above
Total counts everything handled in the period, including conversations that have since been closed

Both are correct; they answer different questions. Use Total when you want to know how much work someone actually got through, since an agent who closes everything they touch would otherwise look idle.

Your plan usage counts every conversation, open or closed. Closing conversations tidies your queues; it does not reduce the number counted against your plan.

A closed conversation reopens by itself if the customer writes again. It returns to the open list and starts counting towards the queue numbers once more, so a returning customer is never lost behind a closed status.

Use Cases¶

Use Case 1: Customer Support Agent Responding to Inquiries¶

Scenario: Support agent receives customer inquiry via WhatsApp.

Steps: 1. Agent opens Inbox 2. Sees new unread conversation 3. Clicks on conversation 4. Reads customer message 5. Reviews contact panel for customer history 6. Types response 7. Uses quick reply template if applicable 8. Sends message 9. Marks conversation as assigned to self 10. Updates conversation status if resolved

Expected Outcome: Customer receives timely response, conversation tracked in system.

Use Case 2: Sales Team Managing Lead Conversations¶

Scenario: Sales team receives lead inquiry, needs to qualify and convert.

Steps: 1. Lead message received in Inbox 2. Sales agent assigns conversation to self 3. Reviews contact information 4. Qualifies lead through conversation 5. Adds tags: "Qualified Lead", "Interested" 6. Creates deal from conversation 7. Links deal to contact 8. Updates deal stage based on conversation 9. Schedules follow-up task 10. Closes conversation when deal won

Expected Outcome: Lead qualified, deal created, follow-up scheduled.

Use Case 3: Multi-Channel Customer Engagement¶

Scenario: Customer contacts via multiple channels, needs unified view.

Steps: 1. Customer sends WhatsApp message 2. Customer sends Instagram DM 3. Customer sends email 4. Agent sees all conversations in Inbox 5. Agent identifies same customer across channels 6. Agent merges conversations (if needed) 7. Agent responds via preferred channel 8. Agent maintains context across channels

Expected Outcome: Unified customer view, consistent experience across channels.

Use Case 4: Team Collaboration on Complex Issue¶

Scenario: Complex customer issue requires team collaboration.

Steps: 1. Agent receives complex inquiry 2. Agent assigns conversation to specialist 3. Specialist reviews conversation history 4. Specialist adds internal notes 5. Specialist escalates to manager (via assignment) 6. Manager reviews and responds 7. Manager adds notes with resolution 8. Agent follows up with customer 9. Conversation closed with resolution documented

Expected Outcome: Issue resolved through team collaboration, full history maintained.

Use Case 5: Automated Response with Bot Flow¶

Scenario: Customer inquiry triggers automated bot flow.

Steps: 1. Customer sends message 2. Bot flow automatically triggered 3. Bot sends initial greeting 4. Bot collects customer information 5. Bot provides automated responses 6. Bot escalates to human agent if needed 7. Agent sees conversation with bot history 8. Agent takes over conversation 9. Agent completes customer request

Expected Outcome: Initial interaction automated, seamless handoff to human agent.

Test Cases¶

Test Case 1: Receive Message¶

Test: Verify message reception

Steps: 1. Send test message via WhatsApp to connected number 2. Open Inbox 3. Verify message appears in conversation list 4. Verify unread indicator 5. Click conversation 6. Verify message displayed in thread 7. Verify contact information displayed 8. Verify timestamp correct 9. Verify channel badge displayed

Expected Result: Message received and displayed correctly

Test Case 2: Send Message¶

Test: Verify message sending

Steps: 1. Open conversation 2. Type message: "Hello, this is a test" 3. Click "Send" 4. Verify message appears in thread 5. Verify message status: "Sending" 6. Wait for delivery 7. Verify message status: "Sent" 8. Wait for read receipt (if enabled) 9. Verify message status: "Read"

Expected Result: Message sent successfully with status updates

Test Case 3: Assign Conversation¶

Test: Verify conversation assignment

Steps: 1. Open unassigned conversation 2. Click "Assign" 3. Select team member 4. Confirm assignment 5. Verify conversation assigned 6. Verify assignee sees conversation in "Assigned to me" filter 7. Verify assignment notification (if enabled) 8. Reassign to different team member 9. Verify reassignment works

Expected Result: Conversation assigned and reassigned correctly

Test Case 4: Change Conversation Status¶

Test: Verify status changes

Steps: 1. Open conversation (status: Open) 2. Click "Close Conversation" 3. Verify status changed to "Closed" 4. Verify conversation moved to closed filter 5. Send new message to closed conversation 6. Verify conversation reopened automatically 7. Verify status changed to "Open"

Expected Result: Status changes work correctly, auto-reopen on new message

Test Case 5: Quick Replies¶

Test: Verify quick reply functionality

Steps: 1. Go to Settings → Quick Replies 2. Create quick reply: "Thank you for contacting us!" 3. Open conversation 4. Type "/" 5. Verify quick replies menu appears 6. Select quick reply 7. Verify message inserted 8. Customize if needed 9. Send message 10. Verify message sent correctly

Expected Result: Quick replies work correctly

Test Case 6: Create Deal from Conversation¶

Test: Verify deal creation from conversation

Steps: 1. Open conversation 2. Click "Create Deal" 3. Fill in deal details: - Title: "Deal from Conversation" - Value: 5000 - Stage: "Lead" 4. Save deal 5. Verify deal created 6. Verify deal linked to contact 7. Verify deal linked to conversation 8. Go to Deals page 9. Verify deal appears

Expected Result: Deal created and linked correctly

Test Case 7: Add Note to Conversation¶

Test: Verify note addition

Steps: 1. Open conversation 2. Click "Add Note" 3. Enter note: "Customer requested callback" 4. Save note 5. Verify note appears in contact panel 6. Verify note timestamp 7. Verify note author 8. Edit note 9. Delete note

Expected Result: Notes can be added, edited, and deleted

Test Case 8: Real-time Updates¶

Test: Verify real-time functionality

Steps: 1. Open Inbox in Browser A 2. Open Inbox in Browser B (different user) 3. Send message from Browser A 4. Verify message appears in Browser B without refresh 5. Assign conversation in Browser A 6. Verify assignment updates in Browser B 7. Close conversation in Browser A 8. Verify status updates in Browser B

Expected Result: Real-time updates work across multiple clients

Test Case 9: Multi-Channel Conversation¶

Test: Verify multi-channel support

Steps: 1. Create conversation via WhatsApp 2. Send message via WhatsApp 3. Create conversation via Messenger (same contact) 4. Verify both conversations appear 5. Merge conversations (if feature available) 6. Send message via Messenger 7. Verify message appears in merged conversation 8. Verify channel badges displayed

Expected Result: Multi-channel conversations handled correctly

Test Case 10: Message Search¶

Test: Verify message search functionality

Steps: 1. Create conversation with multiple messages 2. Use search in conversation 3. Search for specific text 4. Verify matching messages highlighted 5. Navigate between matches 6. Search across all conversations 7. Verify search results displayed

Expected Result: Message search works correctly

Test Case 11: Attachment Handling¶

Test: Verify attachment support

Steps: 1. Open conversation 2. Click "Attach File" 3. Select image file 4. Upload attachment 5. Verify attachment uploaded 6. Send message with attachment 7. Verify attachment displayed in thread 8. Download attachment 9. Verify download works 10. Test with different file types (PDF, video, audio)

Expected Result: Attachments handled correctly for all supported types

Test Case 12: Conversation Filtering¶

Test: Verify filtering functionality

Steps: 1. Create multiple conversations: - Open, assigned - Open, unassigned - Closed - Different channels 2. Filter by status: "Open" 3. Verify only open conversations shown 4. Filter by assignee 5. Verify only assigned conversations shown 6. Filter by channel 7. Verify only selected channel shown 8. Combine filters 9. Verify combined filter works

Expected Result: All filters work correctly individually and combined

API Integration¶

List Conversations¶

Endpoint: GET /functions/v1/rest-api-proxy/conversations

curl "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/conversations?status=eq.OPEN&select=*,contacts(*)&order=last_message_at.desc" \
 -H "X-API-Key: cg_your_api_key"

Query Parameters: - status - Filter by status (?status=eq.OPEN) - select - Embed the contact: ?select=*,contacts(*) - order, limit, offset - Ordering and pagination

Response: an array of conversations, each with its status, last-message time and, when embedded, the contact's name and phone numbers.

Send Message¶

See the WhatsApp Lite External API for sending by phone number, and Send Messages for the other channels.

Assign Conversation¶

Endpoint: PATCH /functions/v1/rest-api-proxy/conversations?id=eq.{conversation_id}

Request:

{
 "assignee_id": "user-uuid"
}

Best Practices¶

Response Time
Respond within SLA (e.g., 24 hours)
Use quick replies for common responses
Set up automation for after-hours
Organization
Assign conversations promptly
Use tags for categorization
Close resolved conversations
Add notes for context
Communication
Use appropriate channel for customer
Maintain professional tone
Be concise and clear
Follow up when promised
Efficiency
Use quick replies for common questions
Create templates for frequent scenarios
Use automation for routine tasks
Batch similar responses
Quality
Review before sending
Check spelling and grammar
Verify customer information
Document important details

Troubleshooting¶

Messages Not Appearing¶

Issue: Messages not showing in inbox

Solutions: - Check channel connection status - Verify webhook configuration - Check message filters - Refresh inbox - Check real-time connection

A Customer's Older Chat Is Missing¶

Issue: You have talked to this customer for weeks, but the chat you opened only shows the last few messages.

Nothing has been deleted. Each of your connected numbers keeps its own chat with a customer, so when someone messages a different number of yours, that starts a new chat beginning from their first message to it. The earlier conversation is still saved under the number it came in on.

Solutions: - Open the Other Conversations list in the contact panel on the right and click the earlier chat — it names the number the customer used - Or search the customer's name or phone number in the inbox search bar; every chat you have with them is listed, whichever number it came in on - Check your status filter — if the older chat was closed, set the filter to All so closed chats are included

Messages Not Sending¶

Issue: Messages fail to send

Solutions: - Check channel connection - Verify message format - Check rate limits - Review error messages - Test channel separately

WhatsApp Lite send errors — what each one means: - "WhatsApp provider did not respond in time. The message may still have been delivered" — the provider took too long to answer, so ConnectGain can't tell whether the message went out. Check the customer's chat (or your linked phone) before resending, or they may get it twice. - "Could not reach the WhatsApp provider. The message was not sent" — nothing was sent; it is safe to send again. - "Sent 1 of 3 attachments, then stopped: …" — the attachments that went out appear in the chat as a normal sent message. Resend only the ones that are missing.

Real-time Updates Not Working¶

Issue: Updates not appearing in real-time

Solutions: - Check browser connection - Verify WebSocket connection - Refresh page - Check Supabase real-time status - Review browser console

More screens¶

The same inbox, a Telegram conversation.

An Instagram conversation.

A TikTok conversation.

Inbox health: response times and unanswered threads at a glance.

ConnectGain — omnichannel inbox, CRM & automation for WhatsApp, Messenger, Instagram, Telegram and more. Open the app · Docs home