Skip to main content

Twilio Integration

Set up Twilio to enable phone number verification and WhatsApp messaging for your Event Schedule deployment.

Overview

Twilio is an optional integration that enables two features in Event Schedule:

Feature Description
Phone Verification Users and schedules can verify their phone numbers via SMS code, adding trust and enabling phone-based contact
WhatsApp Messaging Send event notifications and updates to attendees via WhatsApp, with support for the 24-hour messaging window
Note

Twilio is entirely optional. If not configured, the app will gracefully skip SMS and WhatsApp features without errors.

Create a Twilio Account

  1. Sign up for a Twilio account at twilio.com
  2. From the Twilio Console dashboard, note your Account SID and Auth Token
  3. Navigate to Phone Numbers > Manage > Buy a number
  4. Purchase a phone number with SMS capability (and WhatsApp if you plan to use WhatsApp messaging)
Tip

Twilio provides trial credit for new accounts, which is sufficient for testing. You can upgrade to a paid account when you are ready to go live.

Environment Setup

Add the following variables to your .env file:

TWILIO_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_FROM_NUMBER=+1234567890

TWILIO_SID

Your Twilio Account SID. Find it on the Twilio Console dashboard, displayed prominently at the top of the page.

TWILIO_AUTH_TOKEN

Your Twilio Auth Token. Found on the same Console dashboard page. Click to reveal the token and copy it.

TWILIO_FROM_NUMBER

The Twilio phone number to send SMS from, in E.164 format (e.g., +15551234567). This must be a number you have purchased or verified in your Twilio account.

Phone Number Verification

Once Twilio is configured, phone verification is automatically enabled in two places:

  • User profiles - Users can add and verify a phone number on their account. A 6-digit code is sent via SMS and must be entered to confirm ownership.
  • Schedule contact info - Schedule editors can verify a phone number for their schedule, which is displayed as verified contact information on the public page.

How It Works

  1. The user enters a phone number in E.164 format (e.g., +15551234567)
  2. A 6-digit verification code is sent via SMS
  3. The code is valid for 10 minutes
  4. After successful verification, the phone number is marked as verified
Rate Limiting

To prevent abuse, verification codes are limited to 5 requests per hour per phone number. Failed verification attempts are limited to 5 per 10 minutes.

WhatsApp Setup

To send WhatsApp messages, your Twilio number must be registered as a WhatsApp sender.

Register as a WhatsApp Sender

  1. In the Twilio Console, go to Messaging > Senders > WhatsApp Senders
  2. Click Add WhatsApp Sender and follow the guided setup
  3. Submit your business profile and messaging templates for Meta approval
  4. Once approved, your number can send WhatsApp messages

Configure the Webhook URL

Set the incoming message webhook so Event Schedule can receive WhatsApp replies:

  1. In the Twilio Console, go to your WhatsApp Sender settings
  2. Set the webhook URL to: https://yourdomain.com/api/whatsapp/webhook
  3. Set the HTTP method to POST
24-Hour Messaging Window

WhatsApp enforces a 24-hour reply window. You can send free-form messages only within 24 hours of a user's last message. Outside this window, you must use pre-approved message templates. Plan your messaging strategy accordingly.

Testing

Testing SMS

During development, you can verify SMS is working by checking the Laravel log file:

tail -f storage/logs/laravel.log

If Twilio is not configured, the app will log a warning: Twilio SMS not configured, skipping SMS send. If configured but a send fails, error details including the Twilio response will be logged.

Testing WhatsApp

Twilio provides a WhatsApp sandbox for testing without requiring Meta approval:

  1. In the Twilio Console, go to Messaging > Try it out > Send a WhatsApp message
  2. Follow the instructions to join the sandbox by sending a message from your phone to the Twilio sandbox number
  3. Once connected, you can send and receive test messages through the sandbox
Note

The Twilio sandbox is for development only. For production use, you must complete the WhatsApp sender registration and Meta approval process.