SMS Notifications

Send critical LIVCK alerts, incidents, and maintenance notifications directly to mobile phones via SMS using ClickSend.

Overview

SMS notifications ensure that team members receive critical alerts even when they don't have internet access or aren't actively monitoring other channels. LIVCK uses ClickSend as the SMS provider, offering reliable global SMS delivery.

Important: SMS notifications are rate-limited (throttled) to control costs and prevent excessive messaging. See Notification Throttling for detailed configuration.

Prerequisites

Before configuring SMS notifications, you need:

  1. A ClickSend account
  2. Account balance (prepaid credits for sending SMS)
  3. ClickSend API credentials

Setup

Step 1: Create a ClickSend Account

  1. Visit ClickSend
  2. Sign up for a new account
  3. Verify your email and phone number
  4. Complete account setup

Step 2: Top Up Your Account Balance

SMS messages are charged per message. You need to add funds to your ClickSend account:

  1. Log in to your ClickSend dashboard
  2. Navigate to Billing or Add Credit
  3. Choose an amount to top up
  4. Complete the payment

Pricing varies by country. Check ClickSend's pricing page for your region.

Step 3: Get API Credentials

  1. Log in to ClickSend
  2. Navigate to API Credentials or Developers
  3. Find or generate your API Key
  4. Note your Username (usually your email address)

Step 4: Configure Environment Variables

Add your ClickSend credentials to your .env file:

[email protected]
CLICKSEND_API_KEY=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Replace:

Step 5: Restart Application

Restart LIVCK to apply the configuration:

docker compose restart app

User Configuration

Once ClickSend is configured at the system level, each team member needs to add their phone number to receive SMS notifications.

Adding Phone Number to Profile

  1. Log in to LIVCK
  2. Navigate to /user/profile
  3. Find the Phone Number field
  4. Enter your phone number in international format (e.g., +491701234567)
  5. Click Save

Phone Number Format:

  • Include country code with + prefix
  • No spaces, dashes, or parentheses
  • Example: +491701234567 (Germany)
  • Example: +12025551234 (USA)
  • Example: +447700123456 (UK)

Testing SMS Notifications

After configuring your phone number:

  1. Click the Test all configured Notification-Channels button in your profile
  2. Check your phone for the test SMS

If you receive the test message, SMS notifications are working correctly.

Rate Limiting (Throttling)

Important: SMS notifications are rate-limited to control costs.

LIVCK implements throttling to prevent excessive SMS usage and unexpected charges:

  • SMS are sent only for critical notifications
  • There may be a delay between notifications to prevent spam
  • Repeated updates to the same alert may be batched

This is an intentional cost control measure to prevent accidentally sending hundreds of SMS messages.

For detailed throttling configuration, see Notification Throttling.

How Throttling Works

  • Critical Alerts: Incidents and major outages are prioritized
  • Updates: Multiple updates may be combined into fewer messages
  • Maintenance: Non-urgent maintenance notifications may be delayed
  • Announcements: May not trigger SMS (depending on configuration)

The throttling system is configurable with options for:

  • Global or per-user limits
  • Customizable time windows (SMS Decay)
  • Adjustable SMS limits within the time window
  • Enable/disable throttling entirely

See Notification Throttling for complete configuration options and examples.

Notification Triggers

Members may receive SMS notifications for:

  • Critical Incidents - High-priority service outages
  • Status Changes - When incident status changes to critical states
  • Alert Resolution - When critical incidents are resolved (optional)

Note: Not all alerts trigger SMS notifications due to cost control. SMS is reserved for critical updates.

Cost Management

Understanding Costs

SMS notifications cost money per message. Typical costs:

  • Domestic SMS: €0.05 - €0.10 per message
  • International SMS: €0.10 - €0.50+ per message
  • Costs vary by destination country

Example: 10 team members × 5 critical alerts/month = 50 SMS × €0.08 = €4.00/month

Controlling Costs

Best Practices:

  1. Use SMS only for critical alerts
  2. Limit the number of users with SMS enabled
  3. Use other channels (email, Slack, Telegram) for routine notifications
  4. Monitor your ClickSend balance regularly
  5. Set up balance alerts in ClickSend dashboard

Set Balance Alerts:

  1. Log in to ClickSend
  2. Go to Settings or Notifications
  3. Set up low balance alerts
  4. You'll receive an email when balance drops below threshold

Monitoring Usage

Check your SMS usage:

  1. Log in to ClickSend dashboard
  2. View SMS History or Reports
  3. Monitor messages sent and remaining balance
  4. Review which alerts triggered SMS

Troubleshooting

SMS Not Sending

Check ClickSend Configuration:

  • Verify CLICKSEND_USERNAME and CLICKSEND_API_KEY in .env
  • Ensure credentials are correct (no extra spaces)
  • Restart LIVCK after changing configuration: docker-compose restart app

Check Account Balance:

  • Log in to ClickSend dashboard
  • Verify you have sufficient balance
  • Top up if balance is low or zero

Check Phone Number:

  • Ensure phone number is in international format with + and country code
  • No spaces, dashes, or parentheses
  • Example: +491701234567 not 0170 123 4567

Check Logs:

docker compose logs app | grep -i clicksend
docker compose logs app | grep -i sms

Invalid Phone Number Error

Common Issues:

  • Missing country code
  • Missing + prefix
  • Contains spaces or special characters
  • Incorrect country code

Solution:

  • Use international format: +[country code][number]
  • Remove all spaces and special characters
  • Example: +491701234567 for Germany
  • Example: +12025551234 for USA

Authentication Failed

Cause: Invalid ClickSend credentials.

Solution:

  • Verify CLICKSEND_USERNAME matches your ClickSend account email
  • Regenerate API key in ClickSend dashboard
  • Update .env with new credentials
  • Restart LIVCK:
    docker compose restart app

Insufficient Balance

Cause: ClickSend account balance too low to send SMS.

Solution:

  1. Log in to ClickSend dashboard
  2. Top up your account balance
  3. Retry sending test SMS

Rate Limiting Messages

If you see messages about rate limiting or throttling:

  • This is intentional cost control
  • SMS sending is delayed to prevent excessive costs
  • Critical alerts are still sent, but may be batched
  • Consider using other notification channels for non-critical updates

Best Practices

Phone Number Management

Verification

  • Test phone numbers after adding them
  • Verify numbers are correct before critical incidents
  • Update numbers when team members change phones

Privacy

  • Phone numbers are stored securely in LIVCK
  • Only users with appropriate permissions can view member profiles
  • Use business phones when possible

Cost Optimization

Selective Use

  • Enable SMS only for on-call team members
  • Use SMS for critical incidents only
  • Use email/Slack/Telegram for routine updates
  • Disable SMS for announcements and maintenance

On-Call Rotation

  • Update phone numbers when on-call rotation changes
  • Temporarily add SMS for on-call period
  • Remove when off-call to save costs

Reliability

Backup Channels

  • Don't rely solely on SMS
  • Configure multiple notification channels (email + SMS + Slack)
  • Test all channels regularly

Monitor Balance

  • Set up low balance alerts in ClickSend
  • Review usage monthly
  • Top up before balance runs out

Security Considerations

API Key Protection

  • Never share your ClickSend API key
  • Don't commit credentials to version control
  • Regenerate API key if exposed
  • Restrict API key permissions in ClickSend if possible

Phone Number Privacy

  • Store phone numbers securely
  • Limit access to member profiles
  • Use permission system to control who can view phone numbers
  • See Permissions for access control

International SMS

ClickSend supports international SMS delivery, but costs vary significantly by country.

Check Pricing:

  • Visit ClickSend Pricing
  • Review rates for your destination countries
  • Factor costs into your notification strategy

Country-Specific Issues:

  • Some countries have restrictions on SMS delivery
  • Delivery times may vary internationally
  • Certain countries may require sender ID registration

Alternative SMS Providers

LIVCK currently supports only ClickSend for SMS notifications. If you need a different provider:

  • Contact the LIVCK team to request support for additional SMS providers
  • Use email-to-SMS gateways as a workaround
  • Join the Discord Community to discuss feature requests

Additional Resources