TGM Expert supports multi-channel messaging including SMS, WhatsApp, Telegram, Slack, Discord, and more. Unlike email, messaging providers are not enabled by default and must be explicitly configured.

Table of Contents¶

• Overview
• Supported Channels
• Supported Providers
• Configuration
• Sending Messages
• Admin API
• Provider Setup Guides
• Best Practices

Overview¶

Key Features¶

• 8 Message Channels - SMS, WhatsApp, Telegram, Slack, Discord, Viber, Signal, Facebook Messenger
• 12 Providers - Twilio, Vonage, AWS SNS, Telegram Bot, Slack API, and more
• Per-Company Configuration - Each company can have its own providers
• Channel-Specific Providers - Different providers for different channels
• Media Support - Send images, documents, and rich content
• Template Messages - WhatsApp Business API template support

Key Differences from Email¶

Supported Channels¶

Supported Providers¶

Provider Overview¶

Provider Details¶

Twilio¶

• Best for: SMS and WhatsApp
• Features: Global coverage, phone number provisioning, delivery reports
• Pricing: Pay-per-message
• Website: twilio.com

Vonage (Nexmo)¶

• Best for: Multi-channel messaging
• Features: SMS, WhatsApp, Viber, Facebook Messenger
• Pricing: Pay-per-message
• Website: vonage.com

AWS SNS¶

• Best for: High-volume SMS at scale
• Features: Cost-effective, integrates with AWS ecosystem
• Pricing: Very low per-message cost
• Website: aws.amazon.com/sns

Telegram Bot¶

• Best for: Telegram notifications
• Features: Free, rich media support, bot commands
• Pricing: Free
• Website: core.telegram.org/bots

Slack API¶

• Best for: Team notifications
• Features: Channels, threads, rich formatting
• Pricing: Free (part of Slack subscription)
• Website: api.slack.com

Discord Bot¶

• Best for: Community notifications
• Features: Server channels, embeds, rich content
• Pricing: Free
• Website: discord.com/developers

Configuration¶

Creating a Provider Configuration¶

curl -X POST https://api.tgm-expert.com/api/admin/messaging-providers \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Company Twilio SMS",
    "providerType": "TWILIO",
    "primaryChannel": "SMS",
    "companyId": 1,
    "accountSid": "ACxxxxxxxxxxxxxxxxx",
    "authToken": "your_auth_token",
    "senderId": "+15551234567",
    "activate": true
  }'

Provider Configuration Fields¶

Common Fields¶

Twilio¶

{
  "providerType": "TWILIO",
  "accountSid": "ACxxxxxxxxxxxxxxxxx",
  "authToken": "your_auth_token",
  "senderId": "+15551234567"
}

Vonage¶

{
  "providerType": "VONAGE",
  "apiKey": "your_api_key",
  "apiSecret": "your_api_secret",
  "senderId": "YourBrand"
}

AWS SNS¶

{
  "providerType": "AWS_SNS",
  "awsAccessKeyId": "AKIAIOSFODNN7EXAMPLE",
  "awsSecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "awsRegion": "us-east-1"
}

Telegram Bot¶

{
  "providerType": "TELEGRAM_BOT",
  "telegramBotToken": "123456789:ABCdefGHIjklMNOpqrSTUvwxYZ",
  "telegramDefaultChatId": "123456789"
}

Slack API¶

{
  "providerType": "SLACK_API",
  "slackBotToken": "xoxb-your-bot-token",
  "slackDefaultChannel": "#alerts"
}

Discord Bot¶

{
  "providerType": "DISCORD_BOT",
  "discordBotToken": "your-bot-token",
  "discordDefaultChannelId": "123456789012345678"
}

Meta WhatsApp Business¶

{
  "providerType": "META_WHATSAPP",
  "authToken": "your_access_token",
  "whatsappBusinessAccountId": "123456789",
  "whatsappPhoneNumberId": "987654321"
}

Sending Messages¶

Using MessagingService (Programmatic)¶

@Service
@RequiredArgsConstructor
public class AlertNotificationService {

    private final MessagingService messagingService;

    public void sendAlertNotification(User user, Alert alert) {
        // Set company context
        MessagingService.setCurrentCompanyId(user.getCompany().getId());

        try {
            // Send SMS
            if (user.getPhoneNumber() != null) {
                messagingService.sendSms(
                    user.getPhoneNumber(),
                    "Alert: " + alert.getMessage()
                );
            }

            // Send Telegram (if configured)
            if (user.getTelegramChatId() != null) {
                messagingService.sendTelegram(
                    user.getTelegramChatId(),
                    "🚨 *Alert*: " + alert.getMessage()
                );
            }

            // Send Slack
            messagingService.sendSlack(
                "#alerts",
                "Alert triggered: " + alert.getMessage()
            );

        } finally {
            MessagingService.clearCurrentCompanyId();
        }
    }
}

MessagingService Methods¶

// SMS
messagingService.sendSms(phoneNumber, message);
messagingService.sendSms(phoneNumber, message, senderId);

// WhatsApp
messagingService.sendWhatsApp(phoneNumber, message);
messagingService.sendWhatsAppWithMedia(phoneNumber, caption, mediaUrl, mediaType);

// Telegram
messagingService.sendTelegram(chatId, message);
messagingService.sendTelegramWithMedia(chatId, caption, mediaUrl, mediaType);

// Slack
messagingService.sendSlack(channel, message);

// Discord
messagingService.sendDiscord(channelId, message);

// Check availability
boolean available = messagingService.isChannelAvailable(MessageChannel.SMS);
String providerType = messagingService.getProviderType(MessageChannel.SMS);

Company-Specific Sending¶

// Send for specific company (bypasses ThreadLocal context)
messagingService.sendSmsForCompany(companyId, phoneNumber, message, senderId);

Admin API¶

Provider Types and Channels¶

# List all provider types
curl -X GET "https://api.tgm-expert.com/api/admin/messaging-providers/types" \
  -H "Authorization: Bearer $JWT_TOKEN"

# List all channels
curl -X GET "https://api.tgm-expert.com/api/admin/messaging-providers/channels" \
  -H "Authorization: Bearer $JWT_TOKEN"

Provider Management¶

Testing Configuration¶

# Test provider connection
curl -X POST "https://api.tgm-expert.com/api/admin/messaging-providers/1/test" \
  -H "Authorization: Bearer $JWT_TOKEN"

# Send test message
curl -X POST "https://api.tgm-expert.com/api/admin/messaging-providers/1/test-message?to=+15551234567" \
  -H "Authorization: Bearer $JWT_TOKEN"

System Status¶

curl -X GET "https://api.tgm-expert.com/api/admin/messaging-providers/status" \
  -H "Authorization: Bearer $JWT_TOKEN"

Response:

{
  "data": {
    "messagingEnabled": true,
    "availableProviders": ["Twilio", "Vonage", "AWS SNS", "Telegram Bot", ...],
    "availableChannels": ["SMS", "WhatsApp", "Telegram", "Slack", ...]
  }
}

Provider Setup Guides¶

Twilio Setup¶

1. Create Twilio Account
2. Go to twilio.com

3. Sign up for an account

4. Get Credentials

5. Navigate to Console Dashboard

6. Copy Account SID and Auth Token

7. Get Phone Number

8. Go to Phone Numbers → Manage → Buy a Number

9. Purchase a number with SMS capability

10. For WhatsApp

11. Go to Messaging → Try it Out → WhatsApp

12. Follow sandbox setup or apply for WhatsApp Business API

13. Configure in TGM Expert

    {
      "providerType": "TWILIO",
      "accountSid": "ACxxxxxxxxxxxxxxxxx",
      "authToken": "your_auth_token",
      "senderId": "+15551234567"
    }

Telegram Bot Setup¶

1. Create Bot
2. Open Telegram and search for @BotFather
3. Send /newbot command
4. Follow prompts to name your bot

5. Save the bot token provided

6. Get Chat ID

7. Add your bot to a group or start a chat
8. Send a message to the bot
9. Visit https://api.telegram.org/bot<TOKEN>/getUpdates

10. Find the chat_id in the response

11. Configure in TGM Expert

    {
      "providerType": "TELEGRAM_BOT",
      "telegramBotToken": "123456789:ABCdefGHIjklMNOpqrSTUvwxYZ",
      "telegramDefaultChatId": "123456789"
    }

Slack Setup¶

1. Create Slack App
2. Go to api.slack.com/apps
3. Click "Create New App"

4. Choose "From scratch"

5. Configure Bot

6. Go to "OAuth & Permissions"
7. Add Bot Token Scopes: chat:write, chat:write.public
8. Install to Workspace

9. Copy Bot User OAuth Token

10. Configure in TGM Expert

    {
      "providerType": "SLACK_API",
      "slackBotToken": "xoxb-your-bot-token",
      "slackDefaultChannel": "#alerts"
    }

Discord Setup¶

1. Create Discord Application
2. Go to Discord Developer Portal

3. Click "New Application"

4. Create Bot

5. Go to "Bot" section
6. Click "Add Bot"

7. Copy the bot token

8. Invite Bot to Server

9. Go to OAuth2 → URL Generator
10. Select "bot" scope
11. Select "Send Messages" permission

12. Use generated URL to invite bot

13. Get Channel ID

14. Enable Developer Mode in Discord settings

15. Right-click channel → Copy ID

16. Configure in TGM Expert

    {
      "providerType": "DISCORD_BOT",
      "discordBotToken": "your-bot-token",
      "discordDefaultChannelId": "123456789012345678"
    }

Best Practices¶

1. Use Appropriate Channels¶

• SMS: Critical alerts, authentication codes
• WhatsApp: Customer communication, detailed notifications
• Telegram: Team notifications, automated reports
• Slack: Internal team communication
• Discord: Community updates

2. Handle Failures Gracefully¶

try {
    messagingService.sendSms(phone, message);
} catch (Exception e) {
    // Log error, don't fail the main operation
    log.error("Failed to send SMS: {}", e.getMessage());
}

3. Respect Rate Limits¶

4. Use Company Context¶

Always set and clear the company context when sending messages:

MessagingService.setCurrentCompanyId(companyId);
try {
    // Send messages
} finally {
    MessagingService.clearCurrentCompanyId();
}

5. Test Before Production¶

Always test messaging configurations before enabling in production:

curl -X POST ".../messaging-providers/1/test-message?to=+15551234567"

6. Monitor Provider Health¶

Regularly check test results and failure counts in the admin UI.

Troubleshooting¶

Messages Not Sending¶

1. Check if messaging is enabled

   messagingService.isMessagingEnabled(); // true/false

2. Check channel availability

   messagingService.isChannelAvailable(MessageChannel.SMS);

3. Verify provider configuration

4. Test connection via admin API

5. Check credentials are valid

6. Check company context

7. Ensure setCurrentCompanyId() is called
8. Verify company has active provider for channel

Invalid Credentials¶

1. Verify API keys/tokens are correct
2. Check for whitespace or encoding issues
3. Ensure credentials have correct permissions
4. Check if credentials have expired

Rate Limiting¶

1. Implement queuing for bulk sends
2. Add delays between messages
3. Consider upgrading provider tier
4. Distribute load across multiple numbers

Delivery Failures¶

1. Verify recipient number format (E.164 for SMS)
2. Check if number can receive messages
3. Verify sender ID is valid for destination country
4. Review provider's delivery reports