Skip to content

Channel Management Feature

Overview

Channel Management enables businesses to connect and configure multiple messaging channels (WhatsApp, Messenger, Instagram, Telegram, TikTok, Email, LinkedIn, Shopify Inbox) in one place. SMS is supported for outbound broadcasts and sequences only. Channels can be added, configured, activated/deactivated, and monitored for performance.

Contents: Features · Use Cases · Test Cases · API Integration · Best Practices · Troubleshooting

Features

1. Supported Channels

1. WhatsApp Lite (AppGain): - QR code authentication - Phone number messaging - Media support (images, videos, documents) - Delivery and read receipts - Template messaging - Link shortening - Warming campaigns

2. WhatsApp Cloud (Meta): - Meta WhatsApp Business API integration - OAuth authentication via Facebook or manual entry with a System User token - Approved template messaging - Rich media support - Interactive buttons - Delivery and read receipts - Business verification

Connecting a number that doesn't show in the Facebook wizard? It is almost always a system-user / partner WABA. See WhatsApp Cloud — manual connection with a system user.

3. Facebook Messenger: - Facebook Messenger API integration - OAuth authentication - Page connection - Quick replies - Buttons and carousels - Media support - Typing indicators

4. Instagram Direct Messages: - Instagram Graph API integration - OAuth authentication - Business account connection - Media support - Story mentions - Direct messaging - Message requests

5. Telegram: - Telegram Bot API integration - Bot token authentication - Sticker support - Poll support - Media support - Group messaging - Channel broadcasting (beta) — schedule posts to a Telegram channel from the Social Planner. Requires the bot to be an administrator of that channel with permission to post, and the channel's @username or numeric chat id set under Channel publishing in the channel's settings. - Invite links (t.me/yourbot?start=...) to convert channel readers into contacts you may message directly

A Telegram bot can never send the first message to a user, and a channel's member list is not readable unless you administer that channel. See Telegram Channels for what this means in practice.

6. TikTok: - TikTok Business API integration - OAuth 2.0 authentication - Video messaging - Media support - Business account features - Automatic token management

7. Email: - SMTP integration - Email sending - Email receiving - HTML email support - Attachment support - Email threading

8. LinkedIn: - OAuth authentication (personal profile + company pages the user administers) - Post publishing via the LinkedIn v202401 API - Inbox messaging (beta) — inbound and outbound direct messages for personal profiles and company pages, handled by linkedin-webhook / linkedin-send. Opted into per account at connect time ("Inbox Messaging" toggle). Requires a LinkedIn app with messaging (partner) API access: set the extra OAuth scopes in the LINKEDIN_MESSAGING_SCOPES edge secret, and register each channel's settings.webhook_url (/functions/v1/linkedin-webhook?ca=<channel_account_id>) as the event notification endpoint in the LinkedIn developer app. The webhook answers LinkedIn's challengeCode validation and verifies X-LI-Signature (LinkedIn's request signature). Without messaging API approval, connected accounts still publish posts but LinkedIn rejects message sends. - OAuth tokens are stored encrypted and are never readable from the app; contacts are auto-created from the LinkedIn member id, and each LinkedIn conversation maps to one inbox conversation - Token lifetime — LinkedIn access tokens last about 60 days. A daily job (linkedin-token-refresh) renews any token expiring within 14 days using the stored refresh token, so a connected account keeps working without anyone touching it. If LinkedIn rejects the refresh — the refresh token expired, or access was revoked from the LinkedIn side — the channel is deactivated and the organization's owners and admins are notified; reconnecting the account is the only fix. token-health-check independently probes each LinkedIn token daily and deactivates any that LinkedIn answers with 401. - Publishing requirements — scheduling a post to LinkedIn from the Social Planner needs a connected account with a valid token plus an author (linkedin_organization_id for a company page, or linkedin_person_id for a personal profile). If either is missing the post is held, not failed: it stays scheduled with the reason shown on the post, and goes out on the next check once the channel is complete.

What LinkedIn does not allow. There is no API for listing your connections, browsing member profiles, sending connection requests, or liking and commenting on other people's posts, so ConnectGain does none of those. Messaging is reply-only by design — you can answer someone who messaged you, but there is no way to start a conversation with a member who has not. Tools that offer these features drive a logged-in browser session against LinkedIn's private endpoints, which breaches the LinkedIn User Agreement and routinely gets the member's real account restricted.

9. Shopify Inbox: - Custom Shopify app integration - Store chat handled in the unified inbox - Inbound messages via the Shopify Inbox webhook - Outbound replies from ConnectGain

10. SMS: (outbound broadcast / sequences only — not in the unified inbox) - SMS gateway via Appgain Notify (VictoryLink provider) - Character limit management (160 / 1600 concatenated) - Delivery tracking - Link shortening

11. Web Push Notifications: - Web Push API support - Background notifications (works when app is closed) - Android support (Chrome, Firefox, Samsung Internet) - iOS support (Safari PWA, iOS 16.4+) - Automatic subscription management - VAPID key authentication - Service worker integration - Notification click handling

12. ShrinkIt Push Notifications: - Push notification support - Mobile app integration - Notification delivery

2. Channel Configuration

Configuration Options: - Channel name - Channel-specific settings - API credentials - Webhook URLs - OAuth integration (Facebook, Instagram) - QR code authentication (WhatsApp Lite)

3. Channel Status

Status Management: - Active - Channel enabled and receiving messages - Inactive - Channel disabled - Connected - Channel authenticated - Disconnected - Channel not authenticated

4. Channel Statistics

Statistics Display: - Messages sent/received - Conversation count - Response time - Channel performance - Status indicators

5. OAuth Integration

OAuth Channels: - Facebook Messenger - Instagram - WhatsApp Cloud (via Facebook)

OAuth Flow: - Initiate OAuth connection - Redirect to provider - Handle callback - Store credentials - Verify connection

6. WhatsApp Lite Setup

Setup Features: - QR code authentication - Phone number configuration - Sender ID configuration - Warming campaigns - Connection status - Connected as — the channel card shows the number of the phone that actually scanned the QR code, so you can see at a glance which phone the channel is reading - Wrong-phone protection — if a different phone than the one you set up scans the QR code, the channel pauses and saves nothing from that phone (see Troubleshooting) - No owner password if you signed up with Google — adding a WhatsApp Lite or WhatsApp Cloud number normally asks for the workspace owner's email and password. If you are the owner and signed up with Google (so you never chose a password), you are not asked: sign in as the owner and the owner fields are simply not shown. Workspaces created before this change, and team members adding a channel for someone else, still enter the owner's email and password as before

7. Channel Management

Management Features: - Add new channels - Edit channel settings - Delete channels - Toggle channel status - View channel details - Monitor channel health

8. Multiple Channel Support

Multi-Channel Features: - Multiple channels of same type - Channel-specific naming - Independent configuration - Separate statistics - Individual status control

Use Cases

Use Case 1: Connect WhatsApp Lite

Scenario: Business wants to connect WhatsApp Lite channel.

Steps: 1. Go to Settings → Channels 2. Click "Add Channel" 3. Select "WhatsApp Lite" 4. Enter channel name 5. Configure sender ID and phone number 6. Scan QR code or enter credentials — with the business phone whose number you entered in step 5 7. Verify connection: the channel card shows Connected as with that same number 8. Activate channel 9. Test by sending message

Expected Outcome: WhatsApp Lite channel connected and active.

Use Case 2: Connect Facebook Messenger

Scenario: Business wants to connect Facebook Messenger via OAuth.

Steps: 1. Go to Settings → Channels 2. Click "Add Channel" 3. Select "Facebook Messenger" 4. Click "Connect via Facebook" 5. Authorize ConnectGain 6. Select Facebook Page 7. Verify connection 8. Activate channel 9. Test by receiving message

Expected Outcome: Facebook Messenger connected via OAuth.

Use Case 3: Configure Multiple WhatsApp Channels

Scenario: Business wants multiple WhatsApp Lite channels for different departments.

Steps: 1. Add first WhatsApp Lite channel: "Sales WhatsApp" 2. Configure and activate 3. Add second WhatsApp Lite channel: "Support WhatsApp" 4. Configure and activate 5. Verify both channels active 6. Check channel statistics separately 7. Test messages on both channels

Expected Outcome: Multiple WhatsApp channels configured independently.

Use Case 4: Monitor Channel Performance

Scenario: Business wants to monitor channel statistics.

Steps: 1. Go to Settings → Channels 2. View channel statistics 3. Check messages sent/received 4. Review response times 5. Monitor channel status 6. Identify performance issues 7. Take corrective action

Expected Outcome: Channel performance monitored and optimized.

Test Cases

Test Case 1: Add Channel

Test: Verify channel addition

Steps: 1. Go to Settings → Channels 2. Click "Add Channel" 3. Select channel type 4. Enter channel name 5. Configure settings 6. Save channel 7. Verify channel appears in list 8. Verify channel status

Expected Result: Channel added successfully

Test Case 2: Activate/Deactivate Channel

Test: Verify channel toggle

Steps: 1. Add channel 2. Verify default status 3. Toggle channel active 4. Verify status changed 5. Toggle channel inactive 6. Verify status changed 7. Check channel behavior

Expected Result: Channel activation toggle works correctly

Test Case 3: OAuth Connection

Test: Verify OAuth flow

Steps: 1. Add Facebook Messenger channel 2. Initiate OAuth 3. Complete authorization 4. Select page 5. Verify connection 6. Check credentials stored 7. Test message receiving

Expected Result: OAuth connection successful

Test Case 4: Channel Statistics

Test: Verify statistics display

Steps: 1. Add channel 2. Send test messages 3. Receive test messages 4. View channel statistics 5. Verify counts correct 6. Check response times 7. Monitor updates

Expected Result: Statistics display correctly

Test Case 5: Delete Channel

Test: Verify channel deletion

Steps: 1. Add channel 2. Verify channel exists 3. Delete channel 4. Confirm deletion 5. Verify channel removed 6. Check related data

Expected Result: Channel deleted successfully

API Integration

Channels are connected and configured in Settings → Channels — each channel has its own connection wizard. The API can list them:

List Channels

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

curl "https://txpaxbxhnvnhsjwwaeoy.supabase.co/functions/v1/rest-api-proxy/channel_accounts?is_active=eq.true&select=id,name,type,is_active" \
 -H "X-API-Key: cg_your_api_key"

Query Parameters: - type - Filter by channel type (?type=eq.WHATSAPP_LITE) - is_active - Filter by status (?is_active=eq.true)

Returns each channel's id, name, type, status and timestamps. The credentials a channel connects with are never returned by the API — manage them in Settings → Channels.

Results are scoped to the organization that owns the API key. WhatsApp Lite channels can also be created and paired by API — see the WhatsApp Lite External API.

Best Practices

  1. Channel Setup
  2. Use descriptive channel names
  3. Configure settings completely
  4. Test connections before activating

  5. Verify webhook configuration

  6. Channel Management

  7. Monitor channel status
  8. Review statistics regularly
  9. Update credentials when needed

  10. Deactivate unused channels

  11. Security

  12. Store credentials securely
  13. Use OAuth when available
  14. Rotate credentials regularly

  15. Monitor for unauthorized access

  16. Performance

  17. Monitor channel performance
  18. Optimize message delivery
  19. Handle errors gracefully
  20. Maintain channel health

Troubleshooting

Channel Not Connecting

Issue: Channel fails to connect

Solutions: - Verify credentials correct - Check API permissions - Review connection logs - Test credentials manually

WhatsApp Lite channel paused: wrong phone linked

Issue: A WhatsApp Lite channel card says Paused: wrong phone linked or Paused: linked to a support team phone, and you see a matching alert above your channels.

Cause: The QR code was scanned with a different phone than the number the channel was set up for. Every chat on the phone that scans the code would otherwise appear in your inbox, so the channel pauses instead, and nothing from that phone is saved.

Solutions: - It was the wrong phone: on that phone, open WhatsApp → Linked devices and log the device out. Then click Link the correct phone on the channel card and scan the QR code with your business phone. The channel resumes on its own once the right phone is linked. - It is the right phone and the number you typed was wrong: click Use linked number. The channel adopts that phone's number and resumes. - It says "support team phone": the code was scanned with a phone that belongs to our support team. This can't be accepted — link your own business phone as above.

Channels you connected before this protection existed keep working: if their phone doesn't match the number on file, the card shows a warning with Use linked number instead of pausing. Linking a different phone later still pauses them.

WhatsApp Business number greyed out: "Already connected in Shrinkit"

Issue: A WhatsApp Cloud number appears in the connect wizard but its checkbox is disabled, or manual entry rejects the WABA ID.

Cause: ConnectGain and Shrinkit share one Meta app and one Supabase project, so both products' WhatsApp Cloud numbers deliver to ConnectGain's whatsapp-cloud-webhook. It routes by phone_number_id / waba_id and lets ConnectGain win, which means connecting a WhatsApp Business Account that Shrinkit already owns would not fail — it would silently divert that number's inbound messages away from Shrinkit, leaving the Shrinkit merchant with a "connected" number that has gone quiet.

Solutions: - Disconnect the WhatsApp Business Account in Shrinkit first, then reconnect it here. - Or keep it in Shrinkit and connect a different number.

The check runs in three places, so the guarantee holds however the connection is made: the wizard lists a WhatsApp Business Account that is already in Shrinkit as disabled, manual entry re-checks right before saving, and the platform refuses the save as the final line of defence.

Shrinkit runs the mirror image of this guard against ConnectGain, so whichever product connects a WABA first keeps it.

Messages Not Receiving

Issue: Messages not appearing in inbox

Solutions: - Verify webhook configured - Check channel status (must be active) - Review webhook logs - Test webhook endpoint

OAuth Errors

Issue: OAuth connection fails

Solutions: - Verify app permissions - Check redirect URLs - Review OAuth logs - Re-authorize if needed

Last Updated: January 2025

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