> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodostatus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS Subscriptions

> Allow users to subscribe to status updates via SMS

SMS subscriptions let your users receive critical status updates as text messages. This is especially valuable for users who need to know about outages immediately, even when they're away from email.

## How It Works

1. User enters phone number on your status page
2. They receive a verification code via SMS
3. After verifying, they receive SMS for incidents matching their preferences
4. Users can unsubscribe anytime by replying STOP

## Enabling SMS Subscriptions

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Dashboard → Settings → Subscribers**
    2. Enable **SMS Subscriptions**
    3. Configure Twilio credentials (see below)
    4. Customize the verification message
    5. Save settings
  </Tab>

  <Tab title="Configuration">
    ```json theme={null}
    {
      "subscribers": {
        "sms": {
          "enabled": true,
          "verification_message": "Your Kodo verification code is: {{code}}",
          "incident_message": "{{service}}: {{status}} - {{message}}",
          "require_verification": true
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Twilio Setup

Kodo uses Twilio for SMS delivery. You'll need:

1. **Twilio Account SID**: Found in your Twilio Console
2. **Twilio Auth Token**: Your API authentication token
3. **Phone Number**: A Twilio phone number to send from

```bash theme={null}
# Set via CLI
kodo config set twilio.account_sid "ACXXXXXXXXXX"
kodo config set twilio.auth_token "your_auth_token"
kodo config set twilio.phone_number "+15551234567"
```

<Warning>
  SMS costs apply based on your Twilio pricing. Each verification and notification counts as a message.
</Warning>

## Subscriber Management

### View SMS Subscribers

```bash theme={null}
kodo subscribers list --type sms

# Output:
# Phone           | Verified | Subscribed
# +1555123xxxx    | Yes      | 2024-01-15
# +1555456xxxx    | Yes      | 2024-01-10
# +1555789xxxx    | No       | (pending verification)
```

### Subscriber Preferences

SMS subscribers can choose what to receive:

| Preference        | Default | Description                   |
| ----------------- | ------- | ----------------------------- |
| All incidents     | Yes     | All new incidents             |
| Critical only     | No      | Only critical severity        |
| Specific services | No      | Only selected services        |
| Resolutions       | Yes     | When incidents resolve        |
| Maintenance       | No      | Scheduled maintenance notices |

### Manually Add Subscriber

For internal teams or VIP customers:

```bash theme={null}
curl -X POST "https://kodostatus.com/api/sms/subscribers" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sms",
    "phone": "+15551234567",
    "verified": true,
    "preferences": {
      "severity_filter": ["critical", "major"],
      "services": ["svc_api", "svc_payments"]
    }
  }'
```

## SMS Message Templates

Customize the messages your subscribers receive:

### Incident Created

```
Default: [Kodo] {{severity}} incident: {{title}}

Custom example:
[YourApp] {{severity}}: {{title}}. Updates at status.yourapp.com
```

### Incident Updated

```
Default: [Kodo] Update: {{title}} - {{status}}

Custom example:
[YourApp] {{title}} is now {{status}}
```

### Incident Resolved

```
Default: [Kodo] Resolved: {{title}}

Custom example:
[YourApp] All clear: {{title}} resolved
```

### Available Variables

| Variable       | Description                                     |
| -------------- | ----------------------------------------------- |
| `{{title}}`    | Incident title                                  |
| `{{severity}}` | critical, major, minor                          |
| `{{status}}`   | investigating, identified, monitoring, resolved |
| `{{message}}`  | Latest update message                           |
| `{{service}}`  | Affected service name                           |
| `{{url}}`      | Link to status page                             |

## International SMS

Kodo supports international phone numbers:

* Numbers are validated before sending
* Country codes are required (+1 for US, +44 for UK, etc.)
* Delivery rates vary by country
* Some countries have regulatory requirements

<Note>
  For compliance in certain regions (EU, India, etc.), you may need to register your Twilio number as a verified sender.
</Note>

## Unsubscribing

Users can unsubscribe by:

1. **Replying STOP**: Standard SMS opt-out
2. **Status page**: Click "Manage Subscription" link
3. **API**: You can remove subscribers programmatically

```bash theme={null}
curl -X DELETE "https://kodostatus.com/api/sms/subscribers?id=sub_abc123" \
  -H "X-API-Key: your_api_key"
```

## Rate Limits & Best Practices

<AccordionGroup>
  <Accordion title="Message length">
    Keep messages under 160 characters to avoid splitting into multiple SMS (which costs more).
  </Accordion>

  <Accordion title="Frequency">
    Don't spam subscribers. Combine rapid updates into fewer messages where possible.
  </Accordion>

  <Accordion title="Timing">
    Consider time zones—avoid sending non-critical updates at 3 AM.
  </Accordion>

  <Accordion title="Verification expiry">
    Verification codes expire after 10 minutes. Unverified subscribers are removed after 24 hours.
  </Accordion>

  <Accordion title="Compliance">
    Ensure you have consent before adding subscribers. Keep records of opt-ins for TCPA compliance.
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Messages not delivering?

1. Check Twilio dashboard for delivery errors
2. Verify phone number format includes country code
3. Ensure Twilio account has sufficient balance
4. Check if number is on a carrier blocklist

### Verification codes not received?

1. Confirm phone number is correct
2. Check for carrier filtering (common with short codes)
3. Try resending after a few minutes
4. Contact support if issues persist