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. 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 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
Code
From
- Type: String
- Required: No, if the provider has a default sender
- Templatable: Yes
- Description: Sender phone number or alphanumeric sender ID
Code
Body
- Type: String
- Required: Yes
- Templatable: Yes
- Max Length: 1600 characters
- Description: The SMS message content to send
Code
Output
The SMS step returns the provider's send result:
Code
Accessing the output
Code
Examples
Simple notification
Code
With alphanumeric sender ID
Code
Dynamic recipient and content
Code
Order status notification
Code
Alert with conditional content
Code
Multi-language support
Code
Error handling
Missing sender information and provider failures throw FLUX_SMS_ERROR.
Missing sender
When neither from nor a provider default sender is available:
Code
Sending failure
When the SMS fails to send:
Code
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.
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.
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.
- 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: 1as 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