> ## Documentation Index
> Fetch the complete documentation index at: https://checkly-422f444a-immanuel-fix-api-spec.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# SmsAlertChannel Construct

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

<Tip>
  Learn more about SMS alerts in [the SMS alert documentation](/integrations/alerts/sms).
</Tip>

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.

<CodeGroup>
  ```ts Basic Example theme={null}
  import { SmsAlertChannel } from 'checkly/constructs'

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

  ```ts Advanced Example theme={null}
  import { SmsAlertChannel } from 'checkly/constructs'

  const oncallSms = new SmsAlertChannel("oncall-sms-channel", {
    phoneNumber: "+1234567890",
    sendRecovery: true,
    sendFailure: true,
    sendDegraded: false, // Only critical failures
    sslExpiry: true,
    sslExpiryThreshold: 7, // Alert 7 days before SSL expires
  })
  ```
</CodeGroup>

## Configuration

<Tabs>
  <Tab title="SMS 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") |
  </Tab>

  <Tab title="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              |
  </Tab>
</Tabs>

### SMS Alert Channel Options

<ResponseField name="phoneNumber" type="string" required>
  Phone number to send SMS notifications to. Each SmsAlertChannel supports only one phone number.

  **Usage:**

  ```ts highlight={2} theme={null}
  new SmsAlertChannel("team-sms", {
    phoneNumber: "+1234567890",
  })
  ```

  **Use cases**: Team notifications, individual alerts, role-based alerting.
</ResponseField>

<ResponseField name="name" type="string">
  Friendly name for the SMS alert channel (e.g. "Tim's phone").

  **Usage:**

  ```ts highlight={3} theme={null}
  new SmsAlertChannel("team-sms", {
    name: "Tim's phone",
    phoneNumber: "+1234567890",
  })
  ```

  **Use cases**: Personalization, user-friendly identification, role-based alerting.
</ResponseField>

### General Alert Channel Options

<ResponseField name="sendRecovery" type="boolean">
  Whether to send notifications when checks recover from failure or degraded state.

  **Usage:**

  ```ts highlight={3} theme={null}
  new SmsAlertChannel("recovery-sms", {
    phoneNumber: "+1234567890",
    sendRecovery: true, // Send recovery notifications
  })
  ```

  **Examples:**

  <CodeGroup>
    ```ts Recovery Notifications theme={null}
    const opsSms = new SmsAlertChannel("ops-sms", {
      phoneNumber: "+1234567890",
      sendRecovery: true, // Get notified when issues are resolved
      sendFailure: true,
    })
    ```

    ```ts Failure Only theme={null}
    const alertsSms = new SmsAlertChannel("alerts-only", {
      phoneNumber: "+1234567890",
      sendRecovery: false, // Only failures, no recovery notifications
      sendFailure: true,
    })
    ```
  </CodeGroup>

  **Use cases**: Recovery confirmation, operational awareness, noise reduction.
</ResponseField>

<ResponseField name="sendFailure" type="boolean">
  Whether to send notifications when checks fail.

  **Usage:**

  ```ts highlight={3} theme={null}
  new SmsAlertChannel("failure-sms", {
    phoneNumber: "+1234567890",
    sendFailure: true, // Send failure notifications
  })
  ```

  **Examples:**

  <CodeGroup>
    ```ts Failures Only theme={null}
    const criticalSms = new SmsAlertChannel("critical-sms", {
      phoneNumber: "+1234567890",
      sendFailure: true,
      sendRecovery: false,
      sendDegraded: false,
    })
    ```

    ```ts All Notifications theme={null}
    const comprehensiveSms = new SmsAlertChannel("all-notifications", {
      phoneNumber: "+1234567890",
      sendFailure: true,
      sendRecovery: true,
      sendDegraded: true,
    })
    ```
  </CodeGroup>

  **Use cases**: Incident response, failure monitoring, operational alerting.
</ResponseField>

<ResponseField name="sendDegraded" type="boolean">
  Whether to send notifications when API checks degrade (performance thresholds exceeded but not failed).

  **Usage:**

  ```ts highlight={3} theme={null}
  new SmsAlertChannel("performance-sms", {
    phoneNumber: "+1234567890",
    sendDegraded: true, // Send degraded performance notifications
  })
  ```

  **Use cases**: Performance monitoring, early warning systems, SLA tracking.
</ResponseField>

<ResponseField name="sslExpiry" type="boolean">
  Whether to send notifications for SSL certificate expiry warnings.

  **Usage:**

  ```ts highlight={3} theme={null}
  new SmsAlertChannel("security-sms", {
    phoneNumber: "+1234567890",
    sslExpiry: true,
    sslExpiryThreshold: 30, // Alert 30 days before expiry
  })
  ```

  **Use cases**: Certificate management, security compliance, proactive maintenance.
</ResponseField>

<ResponseField name="sslExpiryThreshold" type="number">
  Number of days before SSL certificate expiry to send notifications. Only relevant when `sslExpiry` is enabled.

  **Usage:**

  ```ts highlight={4} theme={null}
  new SmsAlertChannel("ssl-monitoring", {
    phoneNumber: "+1234567890",
    sslExpiry: true,
    sslExpiryThreshold: 30, // Alert 30 days before expiry
  })
  ```

  **Use cases**: Certificate renewal planning, compliance management, operational scheduling.
</ResponseField>

## SMS Alert Channel Examples

<Tabs>
  <Tab title="On-Call Team">
    ```ts theme={null}
    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",
      },
    })
    ```
  </Tab>

  <Tab title="Multiple Team Members">
    ```ts theme={null}
    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",
      },
    })
    ```
  </Tab>

  <Tab title="Regional On-Call">
    ```ts theme={null}
    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",
      },
    })
    ```
  </Tab>

  <Tab title="Severity-Based Alerting">
    ```ts theme={null}
    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",
      },
    })
    ```
  </Tab>
</Tabs>

## Phone Number Format

The phone numbers used for SMS alerting need to be in [E.164 format format](https://www.twilio.com/docs/glossary/what-e164). 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

<Tabs>
  <Tab title="Correct Format">
    ```ts theme={null}
    // 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
    })
    ```
  </Tab>

  <Tab title="Incorrect Format">
    ```ts theme={null}
    // ❌ 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'
    ```
  </Tab>
</Tabs>

## Combining with Other Alert Channels

SMS works well in combination with other notification methods:

```ts theme={null}
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

<Info>
  **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.
</Info>

<Tabs>
  <Tab title="Critical Alerts Only">
    ```ts theme={null}
    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",
      },
    })
    ```
  </Tab>

  <Tab title="Escalation Pattern">
    ```ts theme={null}
    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",
      },
    })
    ```
  </Tab>
</Tabs>