Skip to main content
Learn more about SMS alerts in the SMS alert documentation.
Use SMS Alert Channels to send SMS notifications to phone numbers when checks fail or recover. SMS alerts are ideal for critical alerts that require immediate attention. 
import { SmsAlertChannel } from 'checkly/constructs'

const smsChannel = new SmsAlertChannel("sms-channel-1", {
  phoneNumber: "+1234567890",
})

​
Configuration

  • SMS Alert Channel
  • General Alert Channel
Configure SMS-specific settings:
ParameterTypeRequiredDefaultDescription
phoneNumberstring✅-Phone number in international format (e.g., +1234567890)
namestring❌-Friendly name for the SMS alert channel (e.g. “Tim’s phone”)

​
SMS Alert Channel Options

​
phoneNumber
string
required
Phone number to send SMS notifications to. Each SmsAlertChannel supports only one phone number.Usage:
new SmsAlertChannel("team-sms", {
  phoneNumber: "+1234567890",
})
Use cases: Team notifications, individual alerts, role-based alerting.
​
name
string
Friendly name for the SMS alert channel (e.g. “Tim’s phone”).Usage:
new SmsAlertChannel("team-sms", {
  name: "Tim's phone",
  phoneNumber: "+1234567890",
})
Use cases: Personalization, user-friendly identification, role-based alerting.

​
General Alert Channel Options

​
sendRecovery
boolean
Whether to send notifications when checks recover from failure or degraded state.Usage:
new SmsAlertChannel("recovery-sms", {
  phoneNumber: "+1234567890",
  sendRecovery: true, // Send recovery notifications
})
Examples:
const opsSms = new SmsAlertChannel("ops-sms", {
  phoneNumber: "+1234567890",
  sendRecovery: true, // Get notified when issues are resolved
  sendFailure: true,
})
Use cases: Recovery confirmation, operational awareness, noise reduction.
​
sendFailure
boolean
Whether to send notifications when checks fail.Usage:
new SmsAlertChannel("failure-sms", {
  phoneNumber: "+1234567890",
  sendFailure: true, // Send failure notifications
})
Examples:
const criticalSms = new SmsAlertChannel("critical-sms", {
  phoneNumber: "+1234567890",
  sendFailure: true,
  sendRecovery: false,
  sendDegraded: false,
})
Use cases: Incident response, failure monitoring, operational alerting.
​
sendDegraded
boolean
Whether to send notifications when API checks degrade (performance thresholds exceeded but not failed).Usage:
new SmsAlertChannel("performance-sms", {
  phoneNumber: "+1234567890",
  sendDegraded: true, // Send degraded performance notifications
})
Use cases: Performance monitoring, early warning systems, SLA tracking.
​
sslExpiry
boolean
Whether to send notifications for SSL certificate expiry warnings.Usage:
new SmsAlertChannel("security-sms", {
  phoneNumber: "+1234567890",
  sslExpiry: true,
  sslExpiryThreshold: 30, // Alert 30 days before expiry
})
Use cases: Certificate management, security compliance, proactive maintenance.
​
sslExpiryThreshold
number
Number of days before SSL certificate expiry to send notifications. Only relevant when sslExpiry is enabled.Usage:
new SmsAlertChannel("ssl-monitoring", {
  phoneNumber: "+1234567890",
  sslExpiry: true,
  sslExpiryThreshold: 30, // Alert 30 days before expiry
})
Use cases: Certificate renewal planning, compliance management, operational scheduling.

​
SMS Alert Channel Examples

  • On-Call Team
  • Multiple Team Members
  • Regional On-Call
  • Severity-Based Alerting
import { ApiCheck, SmsAlertChannel } from "checkly/constructs"

const oncallSms = new SmsAlertChannel("oncall-sms", {
  phoneNumber: "+1555123456",
})

new ApiCheck("critical-api-check", {
  name: "Critical API Endpoint",
  alertChannels: [oncallSms],
  tags: ["critical", "production"],
  request: {
    method: "GET",
    url: "https://api.example.com/critical",
  },
})

​
Phone Number Format

The phone numbers used for SMS alerting need to be in E.164 format format. Stick to the following rules and you’ll be fine:
  • Prepend international access codes with a + sign
  • Do not use any white spaces
  • Use up to 15 characters
  • Correct Format
  • Incorrect Format
// US numbers
const usPhone = new SmsAlertChannel('us-sms', {
  phoneNumber: '+15551234567' // +1 (country code) + area code + number
})

// UK numbers
const ukPhone = new SmsAlertChannel('uk-sms', {
  phoneNumber: '+447911123456' // +44 (country code) + mobile number
})

// German numbers
const dePhone = new SmsAlertChannel('de-sms', {
  phoneNumber: '+491701234567' // +49 (country code) + mobile number
})

​
Combining with Other Alert Channels

SMS works well in combination with other notification methods: 
import {
  ApiCheck,
  EmailAlertChannel,
  SlackAlertChannel,
  SmsAlertChannel,
} from "checkly/constructs"

const criticalSms = new SmsAlertChannel("critical-sms", {
  phoneNumber: "+1555CRITICAL",
})

const teamEmail = new EmailAlertChannel("team-email", {
  address: "dev-team@example.com",
})

const slackChannel = new SlackAlertChannel("team-slack", {
  url: new URL("https://hooks.slack.com/services/YOUR/WEBHOOK/URL"),
  channel: "#alerts",
})

new ApiCheck("multi-channel-alerts", {
  name: "Multi-Channel Alert Check",
  alertChannels: [
    criticalSms, // Immediate SMS for critical issues
    teamEmail, // Email for documentation
    slackChannel, // Slack for team visibility
  ],
  request: {
    method: "GET",
    url: "https://api.example.com/critical-service",
  },
})

​
Best Practices

SMS Limits: Be mindful of SMS costs and potential rate limits. Use SMS for truly critical alerts and combine with other notification methods for comprehensive coverage.
  • Critical Alerts Only
  • Escalation Pattern
import { ApiCheck, SmsAlertChannel } from "checkly/constructs"

// Use SMS sparingly for the most critical alerts
const emergencySms = new SmsAlertChannel("emergency-sms", {
  phoneNumber: "+1555EMERGENCY",
  sendFailure: true,
  sendRecovery: false, // Reduce SMS volume
  sendDegraded: false, // Only failures
})

new ApiCheck("life-critical-system", {
  name: "Life Critical System",
  alertChannels: [emergencySms],
  tags: ["life-critical", "emergency"],
  request: {
    method: "GET",
    url: "https://life-critical.example.com/health",
  },
})
⌘I