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:
- A ClickSend account
- Account balance (prepaid credits for sending SMS)
- ClickSend API credentials
Setup
Step 1: Create a ClickSend Account
- Visit ClickSend
- Sign up for a new account
- Verify your email and phone number
- 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:
- Log in to your ClickSend dashboard
- Navigate to Billing or Add Credit
- Choose an amount to top up
- Complete the payment
Pricing varies by country. Check ClickSend's pricing page for your region.
Step 3: Get API Credentials
- Log in to ClickSend
- Navigate to API Credentials or Developers
- Find or generate your API Key
- 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:
[email protected]
with your ClickSend usernameXXXXXXXX-...
with your actual API key
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
- Log in to LIVCK
- Navigate to
/user/profile
- Find the Phone Number field
- Enter your phone number in international format (e.g.,
+491701234567
) - 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:
- Click the Test all configured Notification-Channels button in your profile
- 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:
- Use SMS only for critical alerts
- Limit the number of users with SMS enabled
- Use other channels (email, Slack, Telegram) for routine notifications
- Monitor your ClickSend balance regularly
- Set up balance alerts in ClickSend dashboard
Set Balance Alerts:
- Log in to ClickSend
- Go to Settings or Notifications
- Set up low balance alerts
- You'll receive an email when balance drops below threshold
Monitoring Usage
Check your SMS usage:
- Log in to ClickSend dashboard
- View SMS History or Reports
- Monitor messages sent and remaining balance
- Review which alerts triggered SMS
Troubleshooting
SMS Not Sending
Check ClickSend Configuration:
- Verify
CLICKSEND_USERNAME
andCLICKSEND_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
not0170 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:
- Log in to ClickSend dashboard
- Top up your account balance
- 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
- Notification Throttling - Configure SMS rate limits and cost control
- ClickSend Documentation
- ClickSend Pricing
- Users & Roles - Member profile management
- Email Notifications - Configure email alerts
- Advanced Configuration - Environment configuration