PhoneCallAlertChannel Construct

Learn how to configure phone call alert channels with the Checkly CLI.

Learn more about Phone Call alerts in the Phone Call Alerts documentation.

Use Phone Call Alerts to make voice calls when checks fail or recover. Phone call alerts are the most immediate form of notification, ideal for critical systems requiring instant attention.

Basic Example

import { PhoneCallAlertChannel } from "checkly/constructs"

const callChannel = new PhoneCallAlertChannel("call-channel-1", {
  phoneNumber: "[phone]",
  name: "Tim's phone",
})

import { PhoneCallAlertChannel } from "checkly/constructs"

const emergencyCall = new PhoneCallAlertChannel("emergency-call-channel", {
  phoneNumber: "[phone]",
  name: "Tim's phone",
  sendRecovery: false, // Only call for failures, not recoveries
  sendFailure: true,
  sendDegraded: false, // Only for complete failures
  sslExpiry: true,
  sslExpiryThreshold: 3, // Call 3 days before SSL expires
})

Configuration

Phone Call Alert Channel

Configure phone call-specific settings:

Parameter	Type	Required	Default	Description
phoneNumber	string	✅	-	Phone number in international format (e.g., [phone])
name	string	❌	-	Friendly name for the phone call 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

Phone Call Alert Channel Examples

Emergency Response

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

const emergencyCall = new PhoneCallAlertChannel("emergency-response", {
  phoneNumber: "+1555EMERGENCY",
  sendFailure: true,
  sendRecovery: false, // Don't call for recoveries
  sendDegraded: false, // Only complete failures
})

new ApiCheck("life-safety-system", {
  name: "Life Safety System",
  alertChannels: [emergencyCall],
  tags: ["life-safety", "critical"],
  request: {
    method: "GET",
    url: "https://life-safety.example.com/health",
  },
})

Executive Notifications

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

const executiveCall = new PhoneCallAlertChannel("executive-call", {
  phoneNumber: "+1555EXEC", // Executive phone number
  sendFailure: true,
  sendRecovery: true, // Notify of both failures and recoveries
  sendDegraded: false,
})

new ApiCheck("revenue-critical-api", {
  name: "Revenue Critical API",
  alertChannels: [executiveCall],
  tags: ["revenue-critical", "executive-level"],
  request: {
    method: "GET",
    url: "https://payments.example.com/health",
  },
})

Security Incident Response

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

const securityCall = new PhoneCallAlertChannel("security-incident", {
  phoneNumber: "+1555SECURITY",
  sendFailure: true,
  sendRecovery: false,
  sslExpiry: true,
  sslExpiryThreshold: 1, // Call immediately for SSL expiry
})

new ApiCheck("security-endpoint", {
  name: "Security Endpoint Monitor",
  alertChannels: [securityCall],
  tags: ["security", "authentication"],
  request: {
    method: "GET",
    url: "https://auth.example.com/security-health",
  },
})

Phone Number Format

The phone numbers used for SMS alerting need to be in E.164 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 usCall = new PhoneCallAlertChannel('us-call', {
  phoneNumber: '[phone]' // +1 (country code) + area code + number
})

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

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

// Australian numbers
const auCall = new PhoneCallAlertChannel('au-call', {
  phoneNumber: '[phone]' // +61 (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

Phone calls should be used as part of a comprehensive alerting strategy:

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

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

const oncallEmail = new EmailAlertChannel("oncall-email", {
  address: "[e-mail]",
})

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

const emergencyCall = new PhoneCallAlertChannel("emergency-call", {
  phoneNumber: "+1555EMERGENCY",
  sendFailure: true,
  sendRecovery: false, // Only call for failures
})

new ApiCheck("comprehensive-alerting", {
  name: "Critical System with Comprehensive Alerting",
  alertChannels: [
    teamSlack, // Immediate team visibility
    oncallEmail, // Documentation and detail
    oncallSms, // Mobile notification
    emergencyCall, // Immediate voice alert
  ],
  tags: ["critical", "comprehensive"],
  request: {
    method: "GET",
    url: "https://critical.example.com/health",
  },
})

Best Practices

Use Sparingly: Phone calls are the most intrusive form of notification. Reserve them for truly critical systems where immediate human intervention is required.

Recovery Notifications: Consider whether recovery calls are necessary. For some critical systems, knowing when the system recovers is as important as knowing when it fails.