Twilio Integration

1. Platform Overview

NOCTURN (nocturnevents.com) is a multi-tenant SaaS platform where independent event promoters manage ticketing, guest lists, artist bookings, contracts, and audience engagement. Each promoter operates within their own organization on the platform.

The Twilio integration enables promoters to send SMS and WhatsApp messages to ticket buyers and contacts for event announcements, reminders, and marketing campaigns — all from within the NOCTURN dashboard.

2. Integration Architecture

NOCTURN uses a Bring Your Own Account (BYOA) model where each promoter organization connects their own Twilio account. This provides:

• Full isolation — each org's messages come from their own Twilio account and phone numbers
• Independent billing — Twilio charges go directly to the promoter's Twilio account
• Own phone numbers — promoters use their registered A2P phone numbers
• Compliance ownership — each promoter maintains their own Twilio compliance (A2P 10DLC, toll-free verification)

┌─────────────────────────────────────────────────┐
│                NOCTURN Platform                  │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │  Org A   │  │  Org B   │  │  Org C   │      │
│  │ (Promoter)│  │ (Venue)  │  │(Festival)│      │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘      │
│       │              │              │             │
│  ┌────▼─────┐  ┌────▼─────┐  ┌────▼─────┐      │
│  │ Twilio   │  │ Twilio   │  │ Twilio   │      │
│  │ Account  │  │ Account  │  │ Account  │      │
│  │ (BYOA)   │  │ (BYOA)   │  │ (BYOA)   │      │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘      │
│       │              │              │             │
└───────┼──────────────┼──────────────┼─────────────┘
        │              │              │
        ▼              ▼              ▼
   ┌─────────────────────────────────────┐
   │         Twilio API (REST)           │
   │   SMS / MMS / WhatsApp / Voice      │
   └─────────────────────────────────────┘

3. Account Linking Flow

Promoters connect their Twilio account through the NOCTURN dashboard settings page. The flow:

1. Promoter navigates to Settings → Messaging → Connect Twilio
2. Enters their Twilio Account SID, Auth Token, and Phone Number
3. NOCTURN validates the credentials by calling GET /2010-04-01/Accounts/{SID}.json
4. On success, credentials are encrypted and stored in the twilio_sub_accounts table
5. All subsequent messages for that organization use their linked Twilio account

POST /api/v1/settings/twilio/connect
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "twilioAccountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "twilioAuthToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "phoneNumber": "+1234567890",
  "messagingServiceSid": "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"  // optional
}

Credentials are stored encrypted at rest. The Auth Token is never exposed in API responses — only the Account SID and phone number are returned for display.

4. Messaging Features

5. Twilio API Usage

NOCTURN uses the Twilio REST API directly via fetch() (not the Twilio SDK) to minimize bundle size for serverless deployment. The following Twilio APIs are used:

Request Format

POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json
Authorization: Basic {base64(AccountSid:AuthToken)}
Content-Type: application/x-www-form-urlencoded

To=+1234567890&From=+0987654321&Body=Your+tickets+for+SOLSTICE+2026+are+confirmed!

6. Data Flow

User Action: Promoter clicks "Send Blast" in NOCTURN dashboard
                    │
                    ▼
Step 1: NOCTURN API receives request (POST /api/v1/sms/blast)
        - Validates JWT auth token
        - Checks promoter role
                    │
                    ▼
Step 2: Credit check
        - Atomic SQL: SELECT balance WHERE balance >= required
        - If insufficient: return 402 Payment Required
        - If sufficient: atomically deduct credits
                    │
                    ▼
Step 3: Load org's Twilio credentials
        - Query twilio_sub_accounts WHERE organization_id = {orgId}
        - Decrypt auth token
                    │
                    ▼
Step 4: Send messages via Twilio REST API
        - Loop through recipients
        - POST to Twilio Messages API per recipient
        - Log each delivery (success/failure) to message_deliveries table
                    │
                    ▼
Step 5: Reconcile credits
        - Refund credits for failed deliveries
        - Update campaign stats (delivered, failed, credits used)
                    │
                    ▼
Step 6: Return summary to promoter
        - { sent: 450, failed: 3, creditsUsed: 450, creditsRefunded: 3 }

7. Compliance & Consent Management

NOCTURN enforces messaging compliance at the platform level:

TCPA Compliance (SMS)

• Separate SMS opt-in checkbox at ticket checkout (not bundled with Terms of Service)
• smsMarketingConsent field stored per buyer with timestamp and source
• All SMS sends filter by smsMarketingConsent = true AND unsubscribedSms = false
• Unsubscribe handling via STOP keyword (Twilio automatic) + platform-level flag

CAN-SPAM Compliance (Email)

• Implied consent on ticket purchase (emailMarketingConsent defaults to true)
• Every marketing email includes unsubscribe link
• Unsubscribe flag honored on all future sends

Consent Database Schema

buyers table:
  email_marketing_consent  BOOLEAN  DEFAULT true   -- CAN-SPAM: implied on purchase
  sms_marketing_consent    BOOLEAN  DEFAULT false  -- TCPA: explicit opt-in required
  whatsapp_consent         BOOLEAN  DEFAULT false  -- Meta policy: explicit opt-in
  consent_timestamp        TIMESTAMP               -- When consent was recorded
  consent_source           VARCHAR                  -- ticket_purchase, manual_optin, import
  unsubscribed_email       BOOLEAN  DEFAULT false
  unsubscribed_sms         BOOLEAN  DEFAULT false

8. Security

9. API Endpoints

10. Pricing Model

NOCTURN uses a prepaid credit model for messaging. Promoters purchase credit bundles and each message type consumes a defined number of credits. Twilio charges flow to the promoter's own Twilio account — NOCTURN's credit system covers the platform's value-add (audience management, consent tracking, campaign tools, analytics).

Credit Bundles

Credit Costs Per Message