Customer SMS Notifications

Environment tip: All examples use v3.onsched.com for production. Replace the host with api-stage.onsched.com when calling the staging environment.

What Are SMS Notifications?

SMS (text message) notifications allow customers to receive appointment alerts on their mobile phones. OnSched supports SMS alongside email notifications, giving customers choice in how they stay informed.

SMS notifications can be sent for:

New appointments – Booking confirmations
Appointment confirmations – When appointment is confirmed
Reminders – Upcoming appointment alerts
Rescheduling – When appointment time changes
Cancellations – When appointment is cancelled

How SMS Notifications Work

Notification Flow

Appointment event occurs (booking, confirmation, reminder, etc.)
System checks customer's notificationType preference
If SMS enabled (SMS or ALL), message is queued
SMS gateway (Twilio) delivers message to customer's phone
Delivery status logged

SMS Provider

OnSched uses Twilio for SMS delivery. Twilio configuration is handled at the platform level (contact support for SMS gateway setup).

Configuring Customer SMS Preferences

Notification Type Options

Customers can have one of four notification preferences:

EMAIL – Email notifications only (default)
SMS – Text message notifications only
ALL – Both email and SMS
NONE – No automated notifications

Setting Preference During Creation

curl -X POST https://v3.onsched.com/v3/customer \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jamie",
    "lastName": "Chen",
    "email": "[email protected]",
    "phone": "+15550123",
    "notificationType": "ALL"
  }'

Customer will receive both email and SMS notifications.

Updating Preference

curl -X PUT https://v3.onsched.com/v3/customer/CUSTOMER_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notificationType": "SMS"
  }'

Customer now receives SMS only (no email).

Phone Number Requirements

Format

Phone numbers must be:

E.164 format – International format with country code
Examples: +15550123 (US), +442071234567 (UK), +61291234567 (AU)

Validation

OnSched validates phone format but doesn't verify the number is active. Ensure:

Country code is included (+1 for US/Canada)
No spaces, dashes, or parentheses
Number is mobile (landlines can't receive SMS)

Missing Phone Numbers

If customer has notificationType: SMS or notificationType: ALL but no phone number:

SMS notifications are skipped
Email notifications still send (if ALL)
No error is thrown

Best practice: Validate phone number exists before setting SMS preferences.

Notification Cascade

Preference Hierarchy

SMS preferences cascade:

Customer preference (if set)
Location customerNotificationType (if no customer preference)
Company notificationType (if no location override)

Example:

Company: notificationType: EMAIL
Location: customerNotificationType: ALL
Customer with no preference: Receives both email and SMS (inherits from location)
Customer with notificationType: EMAIL: Receives email only (customer preference overrides)

Resource Notifications

Resources (staff) can also have notificationType for their own appointment alerts. This is separate from customer notifications:

Customer notifications: Alerts to customers about their appointments
Resource notifications: Alerts to staff about appointments assigned to them

SMS Message Content

Message Format

SMS notifications include:

Appointment details – Date, time, service
Location information – Where to go
Customer name – Confirmation recipient
Business name – Who the appointment is with

Example SMS:

OnSched Reminder: Your Haircut appointment with Style Salon is tomorrow at 2:00 PM. Location: 123 Main St. Questions? Call (555) 0100.

Message Customization

SMS content is generated automatically based on:

Notification type (booking, reminder, cancellation)
Appointment details
Location/company information

For custom messaging:

Use email templates (customizable via dashboard)
SMS templates follow standard format (contact support for custom SMS templates)

Character Limits

SMS messages are limited to 160 characters (standard SMS). Longer messages are split into multiple texts. Keep information concise:

Short business name
Essential details only
Link to confirmation page if more info needed

SMS Costs

Twilio Pricing

SMS delivery incurs per-message costs through Twilio:

US/Canada: ~$0.0075 per message
International: Varies by country (~$0.01-0.50 per message)

Costs are billed through your Twilio account (contact support for billing setup).

Cost Management

To control costs:

Offer email as default, SMS as opt-in
Send SMS only for critical notifications (reminders, day-of confirmations)
Use email for less time-sensitive messages
Monitor SMS volume monthly

Enabling SMS for Locations

Location-Level SMS

SMS must be enabled at the location level:

curl -X PUT https://v3.onsched.com/v3/location/LOCATION_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerNotificationType": "ALL"
  }'

This sets the default for customers booking at this location.

Company-Level SMS

Set company default:

curl -X PUT https://v3.onsched.com/v3/company \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notificationType": "ALL"
  }'

All locations without override will use this setting.

Testing SMS

Test Messages

Before going live:

Create test customer with your phone number
Set notificationType: SMS
Book test appointment
Verify SMS arrives
Test all notification types (booking, reminder, cancellation)

Troubleshooting Test Messages

If SMS doesn't arrive:

Check phone number format (E.164)
Verify Twilio account is active (contact support)
Check Twilio logs for delivery status
Ensure customer has valid notificationType

Common Issues

SMS Not Sending

Check:

Customer has phone number in E.164 format
Customer's notificationType includes SMS (SMS or ALL)
Location has notifications enabled
Twilio account is configured and funded
Appointment creation didn't specify skip_notifications: true

SMS Sent to Wrong Number

Check:

Customer record has correct phone number
No typos in phone field
Country code is correct

SMS Delayed

SMS delivery typically takes seconds but can be delayed:

Carrier congestion
International routing
Twilio processing time

Delays beyond 5 minutes warrant investigation (check Twilio logs).

SMS Content Wrong

SMS templates are auto-generated. For customization:

Contact support for custom SMS templates
Or skip SMS and send via your own SMS gateway using webhook triggers

Best Practices

Ask for SMS Permission

Don't assume customers want SMS:

Add checkbox during booking: "Send SMS reminders?"
Respect opt-out requests
Comply with SMS regulations (TCPA in US, GDPR in EU)

Validate Phone Numbers

Before setting notificationType: SMS:

Verify phone number is provided
Check format is E.164
Consider phone validation service for extra reliability

Offer Both Options

Let customers choose:

Email only
SMS only
Both
Neither

Flexibility improves customer satisfaction.

Monitor SMS Volume

Track SMS usage monthly:

How many customers opted in?
Average SMS sent per appointment?
Total monthly cost?

Adjust strategy if costs are high.

Use SMS for Time-Sensitive Alerts

SMS is best for:

Same-day reminders – Day-of appointment alerts
Last-minute changes – Reschedules, cancellations
Urgent updates – Staff sickness, location closures

Email is better for:

Confirmations (not urgent)
Receipts
Marketing campaigns

Compliance

TCPA (US)

Telephone Consumer Protection Act requires:

Opt-in consent – Customers must agree to receive SMS
Opt-out mechanism – Provide way to stop messages (e.g., "Reply STOP to unsubscribe")
Business hours – Don't send messages late at night

GDPR (EU)

General Data Protection Regulation requires:

Consent – Explicit permission to send SMS
Purpose limitation – Only send appointment-related messages
Right to withdraw – Easy opt-out process

CAN-SPAM / CASL

Similar requirements in other jurisdictions. Always:

Get consent before sending
Provide opt-out
Honor unsubscribe requests immediately

Opt-Out Handling

Customer Requests Opt-Out

If customer replies "STOP" to SMS:

Twilio automatically blocks future messages to that number
Update customer record: notificationType: EMAIL or NONE
Respect preference across all future appointments

Unsubscribe Process

Customer texts "STOP" to SMS number
Twilio blocks number
Update customer in OnSched:

curl -X PUT https://v3.onsched.com/v3/customer/CUSTOMER_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notificationType": "EMAIL"
  }'

Confirm with customer (via email)

Alternative SMS Solutions

Using Your Own SMS Gateway

If you prefer to handle SMS yourself:

Set customer notificationType: NONE
Configure webhooks for appointment events
Your system receives webhook
Send SMS via your gateway (Twilio, Plivo, AWS SNS, etc.)

This gives full control over:

SMS content
Timing
Cost management
Compliance tracking

Common Questions

Can customers reply to SMS?

Not directly to OnSched SMS. Messages are one-way notifications. To enable replies:

Use your own SMS gateway
Configure two-way SMS in Twilio (custom setup)

What if customer changes phone number?

Update customer record:

curl -X PUT https://v3.onsched.com/v3/customer/CUSTOMER_ID \
  -d '{"phone": "+15550NEW"}'

Future SMS will use new number.

Can I send custom SMS outside of appointments?

OnSched SMS is triggered by appointment events only. For marketing SMS:

Use your own SMS gateway
Export customer list and send via Twilio directly
Use marketing automation tools (Mailchimp, HubSpot)

How do I know if SMS was delivered?

Check Twilio logs:

Login to Twilio dashboard
View message logs
Check delivery status (sent, delivered, failed, undelivered)

Can I preview SMS before they send?

SMS templates are fixed per notification type. To preview:

Send test appointment to yourself
Review actual SMS received
Contact support for template customization