SMS Integration

When to Use SMS

SMS works best for:

• Time-sensitive messages: Appointment reminders, flash sales, event notifications
• High-priority updates: Order confirmations, shipping alerts, payment reminders
• Multi-channel sequences: Combine email + SMS for higher engagement
• Immediate response: When you need subscribers to see the message within minutes

SMS should complement email, not replace it. Use it sparingly for maximum impact.

Two SMS Modes

ILLIXIS supports two SMS configurations:

Platform SMS (Default)

• What it is: Use ILLIXIS's Twilio account
• Pros: No Twilio setup required, faster onboarding
• Cons: Shared sending number, less branding control
• Best for: Testing SMS, small volume

Custom SMS (BYOA - Bring Your Own Account)

• What it is: Connect your own Twilio account
• Pros: Dedicated phone number, full control, volume discounts
• Cons: Requires Twilio account setup and toll-free verification
• Best for: High volume, brand control

You can switch between modes at any time in SMS Settings.

Setting Up SMS

Quick Setup (Platform SMS)

1. Go to Integrations > SMS Settings (/integrations/sms/)
2. Verify "Use Platform SMS" is enabled (default)
3. No other configuration needed
4. Start adding SMS steps to sequences

Platform SMS uses ILLIXIS's Twilio account. You'll be billed for SMS usage per your plan's SMS quota.

Custom Twilio Setup

To use your own Twilio account:

1. Get Twilio credentials:

• Sign up at twilio.com
• Buy a toll-free number (required for marketing SMS)
• Find your Account SID and Auth Token in Twilio Console

2. Complete toll-free verification:

• Twilio requires verification before sending marketing SMS
• Go to Console > Verify > Toll-Free Numbers
• Submit business verification form (required)
• See "Toll-Free Verification" section below for requirements

3. Connect to ILLIXIS:

• Go to Integrations > SMS Settings
• Toggle "Use Custom Twilio Account"
• Enter Account SID, Auth Token, and Phone Number
• Click "Save Settings"

4. Test your connection:

• Click "Send Test SMS"
• Enter your phone number
• Confirm message received

Adding SMS Steps to Sequences

In the Visual Sequence Builder

1. Open any email sequence
2. Click "Edit Flow" to enter the canvas builder
3. Click the "SMS" button in the top toolbar
4. Place the SMS node on the canvas
5. Connect it to the previous step

SMS Node Configuration

Click the SMS node to configure in the right sidebar:

Message Content:

• Write your SMS message (160 characters recommended for single segment)
• Use template variables: {{first_name}}, {{last_name}}, {{email}}
• Custom fields: {{custom_fields.company}}, {{custom_fields.appointment_time}}
• Include opt-out language: "Reply STOP to opt out"

Timing:

• Add a Delay node before the SMS if needed
• SMS sends immediately when the step is reached
• Consider time zones to avoid late-night messages

Example SMS Template:
```
Hi {{first_name}}, your appointment is tomorrow at 2pm.
Reply STOP to opt out. - [Your Business Name]
```

SMS + Email Sequences

Combine SMS with email for multi-channel campaigns:

Pattern 1: Email → SMS Reminder

1. Email: Initial message with details
2. Delay: 1 day
3. SMS: Brief reminder with key info

Pattern 2: SMS → Email Follow-up

1. SMS: Time-sensitive alert
2. Delay: 2 hours
3. Email: Detailed follow-up with links

Pattern 3: Alternating Touchpoints

1. Email: Welcome message
2. Delay: 1 day
3. SMS: Quick tip
4. Delay: 2 days
5. Email: Educational content
6. Delay: 1 day
7. SMS: Offer reminder

SMS Consent Requirements

Why Consent Matters

Twilio (and US law) requires explicit opt-in before sending marketing SMS. Subscribers must:

• Check an SMS consent box (unchecked by default)
• See clear language about what they're opting into
• Have easy access to privacy policy and terms

Missing or invalid consent will cause Twilio toll-free verification to fail.

Consent Tracking in ILLIXIS

Every subscriber record has an sms_consent field. SMS steps automatically check this field before sending.

Subscribers receive SMS only if:

• sms_consent = True
• They have a phone number on file
• They haven't replied STOP to previous messages

How Subscribers Opt In

Via Lead Forms:
When creating lead forms in ILLIXIS, include the SMS consent checkbox:

• "Text me updates from [Your Business Name]. (Optional - message and data rates may apply)"
• Checkbox is unchecked by default
• Privacy Policy and Terms links displayed nearby

Via Manual Import:
When importing subscribers, set sms_consent = True only for contacts who explicitly opted in elsewhere.

Via External Forms:
If using your own website forms, ensure the SMS consent checkbox meets Twilio requirements (see Compliance section).

How Subscribers Opt Out

Reply STOP:
Subscribers can reply STOP to any SMS. ILLIXIS automatically:

• Sets sms_consent = False
• Adds "sms-opted-out" tag
• Stops all SMS sends to that subscriber

Reply START:
Subscribers who previously opted out can reply START to re-enable SMS.

Rate Limiting

ILLIXIS enforces rate limits to prevent spam and protect your sending reputation.

Per-Subscriber Limit

• Default: 3 SMS per subscriber per day
• Resets: Daily at midnight UTC
• Purpose: Protects recipients from over-messaging

If you attempt to send a 4th SMS to the same subscriber in one day, it will be blocked with error: "This subscriber has received 3 SMS today (max 3). Try again tomorrow."

Per-Tenant Tracking

ILLIXIS tracks your daily SMS volume for analytics but does not enforce a tenant-level limit (you use your own Twilio account in BYOA mode).

Overriding Limits (Admin Only)

Contact ILLIXIS support if you need to adjust per-subscriber limits for specific campaigns.

SMS Delivery Tracking

Delivery Status

ILLIXIS tracks SMS delivery status via Twilio webhooks:

• Sent: Message handed to carrier
• Delivered: Message reached recipient's phone
• Failed: Delivery failed (invalid number, carrier error)
• Undelivered: Carrier couldn't deliver

Viewing Delivery Status

In Sequence Enrollment Details:

1. Go to Email & Automation > Sequences
2. Click a sequence
3. Click "Enrollments" tab
4. Click a subscriber
5. View "SMS Messages" section with delivery status

In Subscriber Profile:

1. Go to Email & Automation > Subscribers
2. Click a subscriber
3. View "SMS Activity" section

Webhook Configuration

Twilio webhooks are automatically configured when you connect your Twilio account. The webhook URL is:
```
https://app.illixis.io/marketing-automation/webhooks/twilio/status/
```

If webhooks stop working, verify this URL is configured in Twilio Console > Phone Numbers > [Your Number] > Messaging Configuration > Status Callback URL.

SMS Pricing & Quotas

Pricing

SMS costs vary by plan tier:

• Starter: 100 SMS/month included
• Professional: 500 SMS/month included
• Scale: 2,000 SMS/month included

Overage charges: $0.10 per SMS beyond plan quota (billed monthly)

Usage Tracking

View your SMS usage in Integrations > SMS Settings:

• Messages sent this month
• Messages remaining in quota
• Overage charges (if any)

Platform SMS vs BYOA Costs

• Platform SMS: Uses your ILLIXIS plan quota + overage charges
• BYOA (Custom Twilio): You pay Twilio directly (~$0.0079/SMS for US numbers)

BYOA is more cost-effective for high-volume sending (500+ SMS/month).

Toll-Free Verification (Custom Twilio)

If using your own Twilio account, you must complete toll-free verification before sending marketing SMS.

Requirements

Twilio requires:

1. Business name clearly visible in consent text
2. SMS consent checkbox unchecked by default and optional (not required to submit form)
3. Privacy Policy page with SMS section (opt-out, frequency, rates)
4. Terms of Service page mentioning SMS opt-in
5. Privacy/Terms links visible near consent checkbox

Verification Process

1. In Twilio Console, go to Verify > Toll-Free Numbers
2. Submit verification form with:

• Business name
• Website URL
• Sample SMS message
• Opt-in workflow description

3. Twilio reviews (typically 1-2 business days)
4. If approved, SMS sending is enabled
5. If rejected, review rejection reason and fix issues

Common Rejection Reasons

Code 30505: Opt-in must be optional

• Fix: Ensure checkbox is unchecked by default
• Fix: Add "(Optional)" to consent label
• Fix: Form submits successfully without SMS consent

Code 30506: Must reflect end business

• Fix: Show your business name (not "ILLIXIS") in consent text
• Fix: Example: "Text me updates from [Your Business Name]"

Need Help?

ILLIXIS provides a compliance checklist in Integrations > SMS Settings to verify your setup meets Twilio requirements. Follow each step before submitting for verification.

Full checklist: TENANT_SMS_ONBOARDING_CHECKLIST.md

Compliance Checklist

Before sending marketing SMS, verify:

Website Requirements:

• SMS consent checkbox is unchecked by default
  
• Consent text includes your business name
  
• "(Optional)" label present
  
• "Message and data rates may apply" disclosure
  
• Privacy Policy page has SMS section
  
• Terms of Service page mentions SMS
  
• Privacy/Terms links visible near consent checkbox
  

ILLIXIS Configuration:

• SMS Settings configured (Platform or Custom)
  
• Test SMS sent and received successfully
  
• Subscribers have sms_consent = True before sending
  
• SMS templates include opt-out language
  
• SMS templates include business name
  

Twilio Verification (Custom only):

• Toll-free number purchased
  
• Verification form submitted
  
• Verification approved
  
• Webhook URL configured
  

SMS Best Practices

Message Length

• 160 characters or less: Single SMS segment (~$0.008)
• 161-306 characters: 2 segments (~$0.016)
• 307-459 characters: 3 segments (~$0.024)

Keep messages short to minimize costs and improve deliverability.

Content Guidelines

• Include business name: "This is [Your Business] following up..."
• Include opt-out: "Reply STOP to opt out" or similar
• Be relevant: Only send messages subscribers expect
• Avoid spam triggers: No "FREE!!!" or excessive caps/emojis
• Personalize: Use {{first_name}} when available

Timing

• Respect time zones: Don't send SMS at 3am
• Business hours: Send between 9am-8pm local time
• Urgency: SMS implies urgency - use it for time-sensitive messages only

Frequency

• Less is more: SMS is intrusive - use sparingly
• Weekly max: Most subscribers tolerate 1-2 SMS per week
• Monthly typical: 2-4 SMS per month is safer
• Rate limiting: ILLIXIS enforces 3 per day per subscriber

Multi-Channel Strategy

• Email first: Send detailed content via email
• SMS reminder: Follow up with brief SMS reminder
• Don't duplicate: SMS should complement email, not repeat it

Troubleshooting

"SMS not configured" Error

Cause: SMS Settings not configured or inactive
Fix: Go to Integrations > SMS Settings and enable Platform SMS or connect your Twilio account

"No phone number" Error

Cause: Subscriber record has no phone field
Fix: Update subscriber record with phone number, or segment sequences to subscribers with phones only

"Subscriber has not opted in" Error

Cause: sms_consent = False for this subscriber
Fix: Subscriber must opt in via form or reply START to previous message

"Rate limit reached" Error

Cause: Subscriber received 3+ SMS today
Fix: Wait until tomorrow, or contact support to adjust limits

SMS Delivered but Not Received

Possible causes:

• Carrier blocking (spam filter)
• Invalid phone number format
• Carrier outage

Debugging steps:

1. Check delivery status in ILLIXIS (should show "Delivered")
2. Verify phone number is E.164 format (+1XXXYYYZZZZ)
3. Check Twilio logs in Twilio Console
4. Try sending test SMS to a different number

Toll-Free Verification Rejected

Fix: Review rejection reason code in Twilio Console
Common fixes:

• Code 30505: Make SMS consent checkbox optional and unchecked
• Code 30506: Add your business name to consent text (not "ILLIXIS")

Review full checklist in Integrations > SMS Settings before resubmitting.

Frequently Asked Questions

Q: Can I use a short code instead of toll-free?
A: No. ILLIXIS currently supports toll-free numbers only. Short codes require separate provisioning.

Q: Can I send SMS internationally?
A: Yes, if your Twilio account has international sending enabled. Rates vary by country (typically $0.05-$0.15 per SMS).

Q: What happens if I exceed my SMS quota?
A: Platform SMS: Overage charges apply ($0.10/SMS). Custom Twilio: You're billed directly by Twilio.

Q: Can I send MMS (images)?
A: Not yet. MMS support is planned for a future release.

Q: How do I track SMS ROI?
A: Use Goal nodes in sequences to track conversions. Compare sequences with/without SMS to measure lift.

Q: Can I schedule SMS sends?
A: Yes. Add a Delay node before the SMS step to schedule relative to enrollment time.

Q: What if a subscriber replies to SMS?
A: STOP = auto-unsubscribe. START = re-subscribe. Other replies are not yet supported but planned.

Q: Can I use SMS for transactional messages?
A: Yes. Transactional SMS (order confirmations, password resets) do not require opt-in but still need a compliant opt-out mechanism.

Q: How do I migrate from Platform SMS to Custom Twilio?
A: Toggle "Use Custom Twilio Account" in SMS Settings. All future SMS use your account. Past sends remain under Platform SMS billing.

Related Features

• Visual Sequence Builder: Create email + SMS sequences (Help Guide)
• Lead Capture Forms: Collect SMS consent (Help Guide)
• Subscriber Management: View SMS consent status (Help Guide)
• CRM Integration: Sync phone numbers from HubSpot (Help Guide)

Need Help?

Setup issues: Contact ILLIXIS support with your Twilio Account SID (never share Auth Token)

Compliance questions: Review TENANT_SMS_ONBOARDING_CHECKLIST.md

Twilio verification: Submit verification form with complete business info. Most rejections are due to missing business name in consent text or non-optional checkbox.

Best practices: Start with email-only sequences. Add SMS to high-performing sequences to test lift before scaling.