Reecall
Basic Steps

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
+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
Code
MyCompany {{ brand.name }}

Body

  • Type: String
  • Required: Yes
  • Templatable: Yes
  • Max Length: 1600 characters
  • Description: The SMS message content to send
Code
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:

TypeScriptCode
{ 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

Code
{{ sms_step.messageId }} {{ sms_step.status }} {{ sms_step.segments }}

Examples

Simple notification

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

With alphanumeric sender ID

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

Dynamic recipient and content

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

Order status notification

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

Alert with conditional content

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

Multi-language support

JSONCode
{ "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:

TypeScriptCode
{ 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:

TypeScriptCode
{ 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.

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: 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
Last modified on