SmsAlertChannel Construct

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:

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

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

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

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

const secondaryOncall = new SmsAlertChannel("secondary-oncall", {
  phoneNumber: "+1555654321",
})

const teamLead = new SmsAlertChannel("team-lead", {
  phoneNumber: "+1555999888",
  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",
  },
})

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

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

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

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

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

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

// ❌ Don't use these formats:

// Missing country code
phoneNumber: '5551234567'

// With spaces or dashes
phoneNumber: '+1 555-123-4567'

// With parentheses
phoneNumber: '+1 (555) 123-4567'

// Domestic format
phoneNumber: '(555) 123-4567'

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

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

// Start with less intrusive methods, escalate to SMS
const teamEmail = new EmailAlertChannel("team-email", {
  address: "team@example.com",
})

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

Getting Started

DETECT

COMMUNICATE

Project & Configuration

Platform

SmsAlertChannel Construct

Configuration

SMS Alert Channel Options

General Alert Channel Options

SMS Alert Channel Examples

Phone Number Format

Combining with Other Alert Channels

Best Practices

Getting Started

DETECT

COMMUNICATE

Project & Configuration

Platform

​Configuration

​SMS Alert Channel Options

​General Alert Channel Options

​SMS Alert Channel Examples

​Phone Number Format

​Combining with Other Alert Channels

​Best Practices

Configuration

SMS Alert Channel Options

General Alert Channel Options

SMS Alert Channel Examples

Phone Number Format

Combining with Other Alert Channels

Best Practices