Twilio Integration

​

Overview

• One-time password (OTP) codes for login
• Appointment confirmations and reminders
• Draw and auction outcome notifications
• Queue admission alerts
• Waitlist updates

​

Prerequisites

• A Twilio account with an active phone number
• Twilio Account SID and Auth Token
• A messaging service or phone number for sending

​

Supported Message Types

​

Authentication Messages

​

Appointment Messages

​

Experience Outcome Messages

​

Waitlist Messages

​

Message Delivery

​

How Messages Are Sent

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Fanfare   │────▶│    SNS      │────▶│    SQS      │────▶│   Lambda    │
│   Event     │     │   Topic     │     │   Queue     │     │  Processor  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                                                                    │
                                                                    │
                                                                    ▼
                                                            ┌─────────────┐
                                                            │   Twilio    │
                                                            │    API      │
                                                            └─────────────┘

1. An event triggers an SMS (e.g., consumer wins auction)
2. Message is queued via SNS/SQS
3. Lambda processor sends via Twilio API
4. Delivery status tracked via webhooks

​

Delivery Status

​

Webhook Events

​

Webhook Payload

​

Webhook Security

// Signature computation
const signature = computeTwilioSignature(authToken, fullUrl, params);
const isValid = timingSafeEqual(signature, headerSignature);

1. The full webhook URL (including query parameters)
2. All form parameters in alphabetical order

​

Engagement Tracking

• Consumer’s engagedCount is incremented
• lastEngagedAt timestamp is updated
• Used for engagement scoring and analytics

​

API Reference

​

Queue SMS Message

POST /api/messaging/send-sample
Content-Type: application/json

{
  "channel": "SMS",
  "template": "OTP_LOGIN",
  "toPhone": "+15551234567",
  "templateData": {
    "template": "OTP_LOGIN",
    "otpCode": "123456"
  }
}

{
  "status": "queued",
  "id": "msg_abc123"
}

​

Template Data Schemas

{
  "template": "OTP_LOGIN",
  "otpCode": "123456"
}

{
  "template": "APPOINTMENT_CONFIRMATION",
  "appointmentDate": "2024-06-25T14:00:00Z",
  "timeZone": "America/Los_Angeles",
  "locationName": "Downtown Store",
  "productName": "Limited Edition Sneakers"
}

{
  "template": "AUCTION_WON",
  "productName": "Exclusive Watch",
  "winningBid": "$1,250.00"
}

{
  "template": "QUEUE_ADMITTED",
  "productName": "New Release"
}

​

Rate Limiting

​

API Rate Limits

​

Twilio Rate Limits

• US/Canada: ~1 message/second per phone number
• Use messaging services for higher throughput

​

Phone Number Validation

• Start with + followed by country code
• No spaces, dashes, or parentheses
• Examples: +15551234567, +442071234567

{
  "error": "Invalid phone number format"
}

​

Testing

​

Sending Test Messages

POST /api/messaging/send-sample
Content-Type: application/json

{
  "channel": "SMS",
  "template": "OTP_LOGIN",
  "toPhone": "+15551234567"
}

​

Test Metadata

• isTest: true
• requestedBy: <userId>
• ts: <timestamp>

​

Troubleshooting

​

Common Issues

• Verify phone number is in E.164 format
• Check if the number is valid and can receive SMS
• Review Twilio logs for carrier errors

• Verify webhook URL is publicly accessible
• Check Twilio signature validation
• Review webhook configuration in Twilio console

• Wait for the rate limit window to reset
• Reduce message frequency
• Contact support for higher limits

• Verify all required fields are provided
• Check field types match the schema
• Use the correct template name

​

Checking Message Status

SELECT
  id,
  status,
  provider_message_id,
  created_at,
  sent_at
FROM transactional_messages
WHERE organization_id = 'org_123'
  AND channel_type = 'SMS'
ORDER BY created_at DESC;

​

Delivery Event Logs

SELECT
  event_type,
  event_time,
  raw_webhook_data
FROM message_delivery_events
WHERE transactional_message_id = 'msg_123'
ORDER BY event_time;

​

Security

​

Message Content

• Messages are sent from Fanfare’s verified sender
• No sensitive data beyond the template variables
• OTP codes expire after a short window

​

Phone Number Privacy

• Phone numbers are stored encrypted
• Only displayed in masked format in the UI
• Not included in logs

​

Webhook Authentication

• All callbacks verified via Twilio signature
• Invalid signatures are rejected with 401
• Timing-safe comparison prevents timing attacks

​

Limitations

​

Delivery Considerations

​

Carrier Filtering

• Use clear, non-promotional language
• Include opt-out instructions where required
• Monitor delivery rates for issues

​

Time Zones

• Store appointments in UTC
• Pass timeZone parameter for display formatting
• Messages show localized date/time

​

Related Resources

• Consumer Authentication
• Appointment Management
• Transactional Messaging