SmsAlertChannel Construct

Learn how to configure SMS alert channels with the Checkly CLI.

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.

Basic Example

import { SmsAlertChannel } from 'checkly/constructs'

const smsChannel = new SmsAlertChannel("sms-channel-1", {
  phoneNumber: "[phone]",
})

Configuration

SMS Alert Channel

Configure SMS-specific settings:

Parameter	Type	Required	Default	Description
phoneNumber	string	✅	-	Phone number in international format (e.g., [phone])
name	string	❌	-	Friendly name for the SMS alert channel (e.g. “Tim’s phone”)

General Alert Channel

Configure common alert channel properties:

Property	Type	Required	Default	Description
sendRecovery	boolean	❌	true	Send notifications when checks recover
sendFailure	boolean	❌	true	Send notifications when checks fail
sendDegrade	boolean	❌	false	Send notifications when checks degrade (API checks only)
sslExpiry	boolean	❌	false	Send notifications for SSL certificate expiry
sslExpiryThreshold	number	❌	30	Days before SSL expiry to send notification

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: "[phone]",
})

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: "[phone]",
})

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: "[phone]",
  sendRecovery: true, // Send recovery notifications
})

Examples:

Recovery Notifications

const opsSms = new SmsAlertChannel("ops-sms", {
  phoneNumber: "[phone]",
  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: "[phone]",
  sendFailure: true, // Send failure notifications
})

Examples:

Failures Only

const criticalSms = new SmsAlertChannel("critical-sms", {
  phoneNumber: "[phone]",
  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: "[phone]",
  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: "[phone]",
  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: "[phone]",
  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

import { ApiCheck, SmsAlertChannel } from "checkly/constructs"

const oncallSms = new SmsAlertChannel("oncall-sms", {
  phoneNumber: "[phone]",
})

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

Multiple Team Members

import { ApiCheck, SmsAlertChannel } from "checkly/constructs"

const primaryOncall = new SmsAlertChannel("primary-oncall", {
  phoneNumber: "[phone]",
})

const secondaryOncall = new SmsAlertChannel("secondary-oncall", {
  phoneNumber: "[phone]",
})

const teamLead = new SmsAlertChannel("team-lead", {
  phoneNumber: "[phone]",
  sendFailure: true,
  sendRecovery: false, // Only failures
})

new ApiCheck("payment-api-check", {
  name: "Payment API Check",
  alertChannels: [primaryOncall, secondaryOncall, teamLead],
  request: {
    method: "GET",
    url: "https://api.example.com/payments/health",
  },
})

Regional On-Call

import { ApiCheck, SmsAlertChannel } from "checkly/constructs"

// US on-call
const usOncall = new SmsAlertChannel("us-oncall", {
  phoneNumber: "[phone]",
})

// Europe on-call
const euOncall = new SmsAlertChannel("eu-oncall", {
  phoneNumber: "[phone]",
})

// Asia-Pacific on-call
const apacOncall = new SmsAlertChannel("apac-oncall", {
  phoneNumber: "[phone]",
})

// Regional API checks
new ApiCheck("us-api-check", {
  name: "US API Check",
  locations: ["us-east-1", "us-west-2"],
  alertChannels: [usOncall],
  request: {
    method: "GET",
    url: "https://us-api.example.com/health",
  },
})

new ApiCheck("eu-api-check", {
  name: "EU API Check",
  locations: ["eu-west-1"],
  alertChannels: [euOncall],
  request: {
    method: "GET",
    url: "https://eu-api.example.com/health",
  },
})

Severity-Based Alerting

import { ApiCheck, SmsAlertChannel } from "checkly/constructs"

const criticalSms = new SmsAlertChannel("critical-sms", {
  phoneNumber: "+1555CRITICAL",
  sendFailure: true,
  sendRecovery: true,
  sendDegraded: false, // Only for failures
})

const warningSms = new SmsAlertChannel("warning-sms", {
  phoneNumber: "+1555WARNING",
  sendFailure: true,
  sendRecovery: false,
  sendDegraded: true, // Include degraded performance
})

// Critical service
new ApiCheck("critical-service", {
  name: "Critical Payment Service",
  alertChannels: [criticalSms],
  tags: ["critical", "payment"],
  request: {
    method: "GET",
    url: "https://payment.example.com/health",
  },
})

// Warning-level service
new ApiCheck("analytics-service", {
  name: "Analytics Service",
  alertChannels: [warningSms],
  maxResponseTime: 5000,
  degradedResponseTime: 2000,
  tags: ["analytics", "non-critical"],
  request: {
    method: "GET",
    url: "https://analytics.example.com/health",
  },
})

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

// US numbers
const usPhone = new SmsAlertChannel('us-sms', {
  phoneNumber: '[phone]' // +1 (country code) + area code + number
})

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

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

Incorrect Format

// ❌ Don't use these formats:

// Missing country code
phoneNumber: '5551234567'

// With spaces or dashes
phoneNumber: '[phone]'

// With parentheses
phoneNumber: '[phone]'

// Domestic format
phoneNumber: '[phone]'

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: "[e-mail]",
})

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

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",
  },
})

Escalation Pattern

import {
  ApiCheck,
  EmailAlertChannel,
  SmsAlertChannel,
} from "checkly/constructs"

// Start with less intrusive methods, escalate to SMS
const teamEmail = new EmailAlertChannel("team-email", {
  address: "[e-mail]",
})

const urgentSms = new SmsAlertChannel("urgent-sms", {
  phoneNumber: "+1555URGENT",
})

// Regular monitoring with email
new ApiCheck("regular-service", {
  name: "Regular Service",
  alertChannels: [teamEmail],
  request: {
    method: "GET",
    url: "https://api.example.com/regular",
  },
})

// Critical service with SMS escalation
new ApiCheck("critical-service", {
  name: "Critical Service",
  alertChannels: [teamEmail, urgentSms], // Both email and SMS
  request: {
    method: "GET",
    url: "https://api.example.com/critical",
  },
})