Twilio Integration

Overview

Twilio is an optional integration. One Twilio account serves the whole deployment: you configure it once in .env, and every schedule on the platform uses it. There is nothing for an individual schedule owner to connect. Twilio powers exactly three things:

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
5. If you want WhatsApp event creation, register that same number as a WhatsApp sender as well. Event Schedule sends WhatsApp from the number you put in TWILIO_FROM_NUMBER, so it does not need a second number.

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

All three are required. If any one of them is empty, both SMS and WhatsApp stay switched off: the app writes a warning to the log and carries on rather than failing.

Variable reference

Phone Number Verification

Once Twilio is configured, a verification control appears next to every saved but unverified phone number, in two places:

• Account settings - the Phone Number field on a user's own profile. While the number is unverified the page reads "Your phone number is unverified." with a Click here to verify your phone link underneath.
• Schedule settings, Details → Contact Info - the schedule's Phone Number field. Any editor of the schedule can run the verification, and the result belongs to the schedule rather than to the person who ran it.

Both controls are hosted-only. A single-tenant selfhosted install does not show them even with Twilio configured.

How it works

1. Enter the number and save. The field has a country selector and stores the number in E.164 format (e.g., +15551234567); the verify link only appears once a number has been saved.
2. Click Click here to verify your phone. A 6-digit code is sent by SMS, reading "Your Event Schedule verification code is: ...".
3. Type the code into the box that appears and click Verify. The code is valid for 10 minutes.
4. On success the number is marked verified and the control disappears. Editing the number later clears the verification and the control comes back.

What a verified number unlocks

• A public phone number. A schedule's phone is only shown to visitors when it has been verified and the Show phone number toggle is on. The same rule governs a venue's phone number on an event page.
• Platform discovery. A schedule qualifies for the platform's public listings once either its email address or its phone number is verified.
• WhatsApp. Incoming WhatsApp messages are matched to an account by verified phone number, so nobody can create events by WhatsApp until their account phone is verified.
• Claiming. When a user verifies their account phone, any unclaimed schedule carrying the same number and created within the past year is attached to that account as owner, and becomes their default schedule if they do not already have one.

WhatsApp Setup

WhatsApp on Event Schedule is inbound-first: an organizer messages your Twilio number, the app creates the event, and the confirmation goes back on the same thread. To accept those messages, your Twilio number has to be registered as a WhatsApp sender and pointed at the app's webhook.

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 for Meta approval
4. Once approved, your number can send and receive WhatsApp messages

Configure the webhook URL

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

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

The webhook lives on your main application domain rather than on a tenant subdomain, it needs no authentication, and it accepts at most 60 requests per minute.

Creating events by WhatsApp Enterprise - Requires the Enterprise plan

Once the sender and the webhook are live, an organizer can send event details as text, or a photo of a flyer or poster, and AI parses the content into an event on their default schedule.

An incoming message has to satisfy all of the following, or the sender gets an explanatory reply instead of an event:

• The sending number belongs to a user account whose phone number has been verified.
• That user has a Default schedule set in their account settings, or is an editor of exactly one schedule.
• The message carries text, an image, or both. Only the first attachment is read, and only if it is an image.
• Your deployment has an AI key configured (GEMINI_API_KEY, or OPENAI_API_KEY). It is the same parser used by AI import in the admin portal.

The reply carries the new event's name, link and date. If the parser recognises the event as one that already exists, it replies with a link to it rather than creating a duplicate.

For user-facing instructions on creating events via WhatsApp, see the Creating Events guide.

Testing

Testing SMS

Requesting a phone verification code is the quickest end-to-end test, because the code is sent immediately rather than queued. Watch the Laravel log while you do it:

tail -f storage/logs/laravel.log

If a variable is missing, the app logs Twilio SMS not configured, skipping SMS send (or Twilio not configured, skipping WhatsApp send) and carries on. If Twilio is configured but rejects the send, the failure is logged with the HTTP status and Twilio's response body, which usually names the problem outright.

Invitation messages are dispatched to the queue instead, so a stopped queue worker looks exactly like a broken Twilio account. Check the worker before you check the credentials.

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 the join code from your phone to the Twilio sandbox number
3. Point the sandbox's incoming-message webhook at https://yourdomain.com/api/whatsapp/webhook using POST
4. Set TWILIO_FROM_NUMBER to the sandbox number while you are testing. Replies are always sent from whatever that variable holds, so a mismatch shows up as an event that gets created without any confirmation coming back.

Troubleshooting

• No reply at all. The signature check almost certainly failed, and by design that produces an empty response rather than an error. Compare the URL in Twilio's Console debugger with the URL the app builds, and confirm the auth token matches.
• "Your phone number is not linked to an account." The sending number does not match a user with a verified phone number. Verify it in account settings first.
• "No default schedule set." The user edits more than one schedule and has not chosen a Default schedule in account settings.
• "Could not create event." The AI parser returned nothing usable, or no AI key is configured. The log entry for the request has the detail.