How SMS Delivery Works

Demeterrr uses Twilio as its SMS service provider. Twilio delivers your messages through:

• Messaging Service: A pool of phone numbers for optimal delivery
• Global carrier connectivity for reliable message delivery
• Delivery status tracking
• Two-way messaging capabilities (for future features)

Your organization's administrator configures Twilio credentials during initial setup. Once configured, SMS sending works seamlessly from the Demeterrr interface.

When you send a survey via SMS, Demeterrr generates a concise, personalized text message.

The standard SMS message format is:

Hi [FirstName]! [Your Company Name] would love your feedback. Please take 30 seconds: [Survey URL]

With first name:

Hi Sarah! Main Street Dental would love your feedback. Please take 30 seconds: https://demeterrr.com/s/abc123

Without first name:

Hi! Main Street Dental would love your feedback. Please take 30 seconds: https://demeterrr.com/s/abc123

Personalization: Uses the contact's first name if available in their record

Company Name: Pulled from your organization settings to identify who's asking for feedback

Call to Action: Sets expectations ("take 30 seconds") to improve response rates

Survey URL: A unique, trackable link to the survey. The URL is shortened automatically by Demeterrr to save SMS character count.

Unlike email, SMS messages:

• Don't include your logo or brand colors
• Don't support rich formatting or HTML
• Must be concise due to character limits
• Don't include an unsubscribe link in the message (contacts can text STOP to opt out via Twilio's system)

For SMS delivery to work, contacts must have valid phone numbers in a supported format.

Demeterrr accepts phone numbers in many formats and automatically converts them to E.164 (international standard):

Common Formats Accepted:

• 555-123-4567 (US formatting)
• (555) 123-4567 (with parentheses)
• 555.123.4567 (dot separators)
• 5551234567 (raw digits)
• +1 555 123 4567 (E.164 with spaces)
• +15551234567 (E.164 standard)

All non-numeric characters (dashes, parentheses, spaces, dots) are automatically stripped during processing.

When you send an SMS, Demeterrr's formatPhoneNumber() function:

1. Removes all non-digit characters
2. Checks if it's already in E.164 format (starts with +)
3. For 10-digit numbers, assumes US/Canada and adds +1
4. For 11-digit numbers starting with 1, adds + prefix
5. Returns the E.164 formatted number for Twilio

Example transformations:

• 555-123-4567 → +15551234567
• (555) 123-4567 → +15551234567
• 15551234567 → +15551234567
• +1 555 123 4567 → +15551234567

For international numbers outside the US and Canada:

• Use full E.164 format: +[country code][number]
• Example (UK): +447911123456
• Example (France): +33612345678

If you're entering numbers in the Contacts interface, include the country code to ensure proper delivery.

Before sending, Demeterrr validates phone numbers using isValidPhoneNumber():

• Must be in E.164 format after formatting
• Must start with +
• Must contain 10-15 digits (international standard)

If a contact's phone number fails validation:

• SMS sending will fail
• The system automatically falls back to email (if Auto channel selected)
• The sending event logs the fallback reason as no_phone

Demeterrr uses a soft cap system to prevent unexpected costs while maintaining flexibility.

Unlike a hard cap that blocks sending entirely, the soft cap:

1. Checks quota before each SMS send
2. Allows sending if under monthly limit
3. Falls back to email if quota is exceeded
4. Never fails outright (Auto channel always delivers somehow)
5. Logs the reason for transparency

This approach ensures your customers always receive their survey invitation, even if SMS isn't available.

Each organization has two SMS quota fields:

smsMonthlyLimit

• The maximum number of SMS messages allowed per calendar month
• Set by your subscription plan or custom configuration
• Examples: 100 SMS/month on Starter, 500 SMS/month on Pro

smsUsedThisMonth

• Counter that increments with each SMS sent
• Resets to 0 at the start of each month
• Tracked automatically by Demeterrr

Before sending via SMS, the system verifies:

✅ Contact has a valid phone number ✅ smsMonthlyLimit is not null and greater than 0 ✅ smsUsedThisMonth is less than smsMonthlyLimit

If all checks pass → SMS is sent If any check fails → Falls back to email (if Auto channel)

When SMS isn't available, the sending event logs one of these reasons:

no_phone: Contact doesn't have a phone number in their record sms_not_enabled: Organization's SMS monthly limit is set to 0 sms_quota_exceeded: Monthly SMS limit has been reached

You can view fallback reasons in the Sendings table by inspecting the sending event details (available to administrators).

SMS sending incurs per-message costs through Twilio, which Demeterrr manages via subscription tiers and add-on packs.

Each Demeterrr subscription tier includes a base SMS allotment:

• Starter Plan: 100 SMS/month included
• Pro Plan: 500 SMS/month included
• Business Plan: 1,000 SMS/month included

These limits are set in your organization's smsMonthlyLimit field.

If you need more SMS capacity:

$10 per pack

• Each pack includes 500 additional SMS credits
• Purchase directly from Settings > Billing
• Credits are added to your monthly limit
• Purchase as many packs as needed

Example: Pro plan (500 SMS) + 2 add-on packs (1,000 SMS) = 1,500 SMS/month total

To check your current SMS usage:

1. Navigate to Settings > Billing
2. View your current plan's SMS allowance
3. See how many SMS you've used this month
4. Purchase add-on packs if needed

Your administrator can also monitor usage via the organization settings or by querying the smsUsedThisMonth counter.

To optimize SMS costs:

✅ Use Auto channel to automatically prefer email (free) when available ✅ Send email-only campaigns for non-urgent feedback requests ✅ Reserve SMS for time-sensitive scenarios (post-visit, appointment reminders) ✅ Monitor usage regularly to avoid hitting your limit mid-month ✅ Upgrade your plan if you consistently need more SMS capacity

After sending an SMS, Twilio provides delivery status tracking.

Sent

• Message was accepted by Twilio and sent to the carrier
• Most common successful status

Delivered

• Carrier confirmed the message reached the recipient's device
• Strongest confirmation of delivery

Failed

• Message could not be delivered
• Common reasons: invalid number, carrier rejection, number no longer in service

Undelivered

• Carrier attempted delivery but failed
• May retry automatically

Currently, Demeterrr marks sendings as "sent" once Twilio accepts the message. Future versions will integrate delivery webhooks to update status based on carrier confirmations.

Demeterrr uses Twilio's Messaging Service feature rather than individual phone numbers.

A Messaging Service is a pool of:

• Multiple phone numbers
• Managed by Twilio
• Used intelligently for optimal delivery
• Handles sender phone number compliance automatically

Benefits:

• Better deliverability (uses best number for each carrier)
• Automatic handling of opt-outs and compliance
• Scalability without managing individual numbers
• Simplified configuration

Your administrator configures the Messaging Service SID in the TWILIO_MESSAGING_SERVICE_SID environment variable.

Contacts can opt out of SMS messages at any time.

Twilio automatically handles standard SMS opt-out keywords:

• STOP: Unsubscribes from future messages
• UNSTOP or START: Re-subscribes
• HELP: Provides help information

When a contact texts STOP:

• Twilio adds them to an internal opt-out list
• Future messages to that number are blocked
• This happens at the Twilio level, not in Demeterrr's database

Currently, Demeterrr doesn't automatically sync Twilio's opt-out list with the contact database. This means:

• A contact who texts STOP won't receive SMS
• But their contact record won't show unsubscribed: true
• They could still receive emails

Future versions will add webhook integration to sync opt-outs bidirectionally.

For now, if a contact reports they opted out but are still receiving messages, manually update their contact record to mark them as unsubscribed.

SMS quota exceeded mid-month

• Purchase SMS add-on packs from Settings > Billing
• Consider upgrading to a higher plan
• Use email for non-urgent sends

Messages not being delivered

• Verify the contact's phone number is correct and in a valid format
• Check Twilio's delivery logs in the Twilio dashboard
• Confirm the number isn't on Twilio's opt-out list
• Ensure your Twilio account is in good standing

International numbers not working

• Verify the number includes the full country code
• Check Twilio's supported countries list
• Some countries require pre-registration for SMS sending

Contact shows "no valid phone or email"

• Edit the contact to add a properly formatted phone number
• Use E.164 format for international numbers
• Add an email address as a fallback option

Now that you understand SMS delivery, explore:

• How to send surveys to individual contacts
• Understanding email delivery
• Sending to multiple contacts at once
• Tracking delivery and response status
• Managing contact information