# SMS

Use SMS to send text messages through the configured Twilio or AWS SNS provider.

## Overview

**Type:** `sms`

The provider must be configured before execution. Recipient, sender, and body fields accept [Morpher templates](/docs/morpher). The result contains the provider's immediate send status, not a final delivery receipt.

## Configuration

Put these fields in the step's `config` object. The examples below are configuration fragments; see [Execute workflows](/docs/execute-workflows) for the full request format. Supply their referenced variables in context.

### To

* **Type:** String
* **Required:** Yes
* **Templatable:** Yes
* **Pattern:** `^\+[1-9]\d{1,14}$` (E.164 format)
* **Description:** Recipient phone number in international format

```
+33612345678
{{ user.phoneNumber }}
+1{{ contact.mobile }}
```

### From

* **Type:** String
* **Required:** No, if the provider has a default sender
* **Templatable:** Yes
* **Description:** Sender phone number or alphanumeric sender ID

```
MyCompany
{{ brand.name }}
```

### Body

* **Type:** String
* **Required:** Yes
* **Templatable:** Yes
* **Max Length:** 1600 characters
* **Description:** The SMS message content to send

```
Hello {{ user.name }}, your verification code is {{ code }}.
Your order #{{ order.id }} has been shipped!
```

## Output

The SMS step returns the provider's send result:

```typescript
{
  messageId: string,    // Provider message ID (Twilio SID or AWS SNS MessageId)
  status: string,       // Immediate provider status (not a later delivery receipt)
  to: string,          // Recipient phone number
  from: string,        // Sender phone number or ID
  segments: number     // Defaults to 1 when the provider omits a segment count
}
```

### Accessing the output

```
{{ sms_step.messageId }}
{{ sms_step.status }}
{{ sms_step.segments }}
```

## Examples

### Simple notification

```json
{
  "to": "+33612345678",
  "from": "+15551234567",
  "body": "Your verification code is 123456"
}
```

### With alphanumeric sender ID

```json
{
  "to": "+33612345678",
  "from": "MyCompany",
  "body": "Your verification code is 123456"
}
```

### Dynamic recipient and content

```json
{
  "to": "{{ user.phoneNumber }}",
  "from": "{{ brand.name }}",
  "body": "Hello {{ user.firstName }}, your order #{{ order.id }} has been confirmed!"
}
```

### Order status notification

```json
{
  "to": "{{ customer.mobile }}",
  "from": "{{ company.twilioNumber }}",
  "body": "Your package will arrive on {{ delivery.estimatedDate }}. Track it here: {{ tracking.url }}"
}
```

### Alert with conditional content

```json
{
  "to": "{{ admin.phone }}",
  "from": "AlertSystem",
  "body": "Alert: {{ alert.type | uppercase }} - {{ alert.message }}. Severity: {{ alert.severity }}"
}
```

### Multi-language support

```json
{
  "to": "{{ user.phoneNumber }}",
  "from": "{{ company.smsNumber }}",
  "body": "{{ user.language | lookup({'fr': 'Bonjour'}, 'Hello') }} {{ user.name }}, {{ notification.message }}"
}
```

## Error handling

Missing sender information and provider failures throw `FLUX_SMS_ERROR`.

### Missing sender

When neither `from` nor a provider default sender is available:

```typescript
{
  code: "FLUX_SMS_ERROR",
  message: "SMS sender (from) is required. Please provide the 'from' field or configure a default sender"
}
```

### Sending failure

When the SMS fails to send:

```typescript
{
  code: "FLUX_SMS_ERROR",
  message: "SMS sending failed: [error details]"
}
```

### Invalid phone number

The configuration schema declares an E.164 pattern for `to`. Provider validation also applies. The execution endpoint does not automatically validate rendered phone numbers against that schema, so validate input numbers before execution.

## Best practices

### Phone number format

* Always use international E.164 format: `+[country code][number]`
* Include the leading `+` sign
* Remove spaces, dashes, and parentheses
* Example valid formats: `+33612345678`, `+14155552671`

### Sender configuration

* **Alphanumeric IDs**: Available in some countries (11 characters max for Twilio; the handler accepts letters, numbers, and spaces)
* Use consistent sender identities to build brand recognition
* Alphanumeric sender IDs require supported destinations and any required registration. They cannot consist only of digits and do not support replies. See [Twilio sender ID requirements](https://www.twilio.com/docs/trust-hub/registrations/alphanumeric-sender-id).

### Message content

* Keep messages concise and clear
* Include relevant context (order numbers, codes, names)
* Keep the body within the schema's 1600-character limit. Shorter messages use fewer segments.
* **Message Segments**: For Twilio, a single GSM-7 SMS holds up to 160 characters, and a single UCS-2 SMS holds up to 70. Concatenated messages generally hold 153 GSM-7 or 67 UCS-2 characters per segment. Some characters consume more than one encoding unit. See [Twilio message length documentation](https://www.twilio.com/docs/glossary/what-sms-character-limit).

### Personalization

* Use Morpher templating to personalize messages with user data
* Include the recipient's name and the information they need to act on the message.

### Compliance

* Ensure recipients have opted in to receive SMS notifications
* Include opt-out instructions. For alphanumeric senders, provide an alternative to replying STOP because recipients cannot reply to that sender. See [Twilio alphanumeric sender guidance](https://www.twilio.com/docs/numbers-and-senders/alphanumeric-senders).
* Follow applicable messaging and data-protection laws and the provider policies for each destination.
* Avoid sending messages during night hours in the recipient's timezone
* Maintain consent records for audit purposes

### Cost management

* SMS delivery incurs costs per segment
* Check provider billing records for actual segment counts and costs. Both built-in providers currently omit the normalized segment count, so this step returns `segments: 1` as a fallback.
* Avoid unnecessary characters that trigger Unicode encoding
* Consider alternative channels (email, push notifications) for longer content

## Common use cases

* **Two-factor authentication (2FA):** Send verification codes for secure login
* **Order notifications:** Confirm purchases and provide shipping updates
* **Appointment reminders:** Reduce no-shows with timely reminders
* **Emergency alerts:** Deliver critical system or service notifications
* **Delivery updates:** Keep customers informed about package status
* **Marketing campaigns:** Send promotional messages to opted-in customers
* **Password resets:** Deliver secure password reset codes
* **Account alerts:** Notify users of suspicious activity or important account changes
* **Booking confirmations:** Confirm reservations and appointments
* **Payment reminders:** Send payment due notifications

## Troubleshooting

### Message not delivered

* Verify the phone number is in correct E.164 format
* Check that the recipient's device is powered on and has signal

### Invalid phone number error

* Double-check the phone number format
* Ensure the country code is included
* Remove any formatting characters (spaces, dashes, parentheses)
* Verify the number is a valid mobile number (not landline)

### Invalid sender error

* Check alphanumeric sender ID is supported in destination country
* Ensure alphanumeric ID meets format requirements (11 chars max for Twilio; letters, numbers, and spaces)
* For toll-free or short codes, verify proper registration

### High segment count

* Check for Unicode characters (emojis, special symbols, accented letters)
* Consider using GSM-7 compatible characters only
* Check provider billing records before changing how long messages are sent
* Review message length and remove unnecessary content
