Message Schemas

Detailed schemas for all supported message types with examples and validation rules.

OTP Messages

One-time password messages for authentication and verification flows.

Schema

{
  "to": "+15551234567",
  "type": "otp",
  "body": {
    "code": "123456",           // Required: 4-8 digit code
    "purpose": "signin",        // Required: signin, signup, reset, verify
    "expires_at": "2025-01-15T10:30:00Z", // Required: ISO 8601
    "app_name": "MyApp",        // Optional: Custom app name
    "app_icon": "https://...",  // Optional: App icon URL
    "auto_clear": true          // Optional: Auto-clear after use
  }
}

Sign In OTP

{
  "to": "+15551234567",
  "type": "otp",
  "body": {
    "code": "847291",
    "purpose": "signin",
    "expires_at": "2025-01-15T10:35:00Z",
    "app_name": "MyApp"
  }
}

Password Reset

{
  "to": "+15551234567",
  "type": "otp",
  "body": {
    "code": "592847",
    "purpose": "reset",
    "expires_at": "2025-01-15T10:45:00Z",
    "auto_clear": true
  }
}

Delivery Messages

Order and shipment tracking notifications with rich status updates.

Schema

{
  "to": "+15551234567",
  "type": "delivery",
  "body": {
    "order_id": "A-123",        // Required: Order identifier
    "status": "shipped",        // Required: ordered, confirmed, shipped, delivered
    "tracking_number": "1Z...", // Optional: Carrier tracking number
    "tracking_url": "https://", // Optional: Tracking page URL
    "carrier": "FedEx",         // Optional: Shipping carrier
    "estimated_delivery": "2025-01-16T18:00:00Z", // Optional: ETA
    "items": [                  // Optional: Order items
      {
        "name": "Product Name",
        "quantity": 2,
        "image": "https://..."
      }
    ]
  }
}

Order Shipped

{
  "to": "+15551234567",
  "type": "delivery",
  "body": {
    "order_id": "ORD-2024-001",
    "status": "shipped",
    "tracking_number": "1Z999AA1234567890",
    "tracking_url": "https://fedex.com/track",
    "carrier": "FedEx",
    "estimated_delivery": "2025-01-16T18:00:00Z"
  }
}

Order Delivered

{
  "to": "+15551234567",
  "type": "delivery",
  "body": {
    "order_id": "ORD-2024-001",
    "status": "delivered",
    "delivered_at": "2025-01-16T15:30:00Z",
    "delivered_to": "Front door",
    "signature_required": false
  }
}

Transaction Messages

Financial transaction notifications including payments, refunds, and account updates.

Schema

{
  "to": "+15551234567",
  "type": "transaction",
  "body": {
    "transaction_id": "txn_123", // Required: Transaction ID
    "type": "payment",           // Required: payment, refund, transfer
    "amount": 29.99,             // Required: Transaction amount
    "currency": "USD",           // Required: ISO currency code
    "status": "completed",       // Required: pending, completed, failed
    "merchant": "Acme Store",    // Optional: Merchant name
    "description": "Order #123", // Optional: Transaction description
    "timestamp": "2025-01-15T10:25:00Z", // Required: Transaction time
    "balance": 150.50,           // Optional: Account balance after
    "receipt_url": "https://..." // Optional: Receipt link
  }
}

Payment Completed

{
  "to": "+15551234567",
  "type": "transaction",
  "body": {
    "transaction_id": "pay_1234567890",
    "type": "payment",
    "amount": 49.99,
    "currency": "USD",
    "status": "completed",
    "merchant": "Coffee Shop",
    "description": "Latte + Croissant",
    "timestamp": "2025-01-15T08:30:00Z"
  }
}

Refund Processed

{
  "to": "+15551234567",
  "type": "transaction",
  "body": {
    "transaction_id": "ref_9876543210",
    "type": "refund",
    "amount": 29.99,
    "currency": "USD",
    "status": "completed",
    "original_transaction": "pay_1234567890",
    "reason": "Item returned",
    "timestamp": "2025-01-15T14:20:00Z"
  }
}

Event Messages

Calendar events, reminders, and appointment notifications.

Schema

{
  "to": "+15551234567",
  "type": "event",
  "body": {
    "title": "Doctor Appointment", // Required: Event title
    "start_time": "2025-01-16T14:00:00Z", // Required: Start time
    "end_time": "2025-01-16T15:00:00Z",   // Optional: End time
    "location": "123 Main St",    // Optional: Event location
    "description": "Annual checkup", // Optional: Event description
    "reminder_minutes": 60,       // Optional: Reminder before event
    "calendar_url": "https://...", // Optional: Add to calendar link
    "organizer": "Dr. Smith",     // Optional: Event organizer
    "attendees": ["john@..."],    // Optional: Other attendees
    "status": "confirmed"         // Optional: confirmed, tentative, cancelled
  }
}

Appointment Reminder

{
  "to": "+15551234567",
  "type": "event",
  "body": {
    "title": "Dentist Appointment",
    "start_time": "2025-01-16T10:00:00Z",
    "end_time": "2025-01-16T11:00:00Z",
    "location": "Smile Dental, 456 Oak Ave",
    "reminder_minutes": 60,
    "organizer": "Dr. Johnson",
    "status": "confirmed"
  }
}

Meeting Invitation

{
  "to": "+15551234567",
  "type": "event",
  "body": {
    "title": "Project Kickoff",
    "start_time": "2025-01-17T09:00:00Z",
    "end_time": "2025-01-17T10:30:00Z",
    "location": "Conference Room A",
    "description": "Q1 project planning",
    "calendar_url": "https://cal.com/add/...",
    "organizer": "Sarah Chen"
  }
}

Custom Messages

Flexible message format for custom use cases and rich content.

Schema

{
  "to": "+15551234567",
  "type": "custom",
  "body": {
    "title": "Message Title",    // Required: Message title
    "content": "Message body",   // Required: Main content
    "actions": [                 // Optional: Action buttons
      {
        "label": "View Details",
        "url": "https://...",
        "type": "url"
      },
      {
        "label": "Confirm",
        "action": "confirm",
        "type": "callback"
      }
    ],
    "media": {                   // Optional: Media attachments
      "type": "image",
      "url": "https://...",
      "alt": "Description"
    },
    "priority": "high",          // Optional: low, normal, high
    "category": "notification"   // Optional: Custom category
  }
}

Rich Notification

{
  "to": "+15551234567",
  "type": "custom",
  "body": {
    "title": "New Feature Available",
    "content": "We've added dark mode to the app! Try it out in settings.",
    "actions": [
      {
        "label": "Open Settings",
        "url": "myapp://settings",
        "type": "deeplink"
      },
      {
        "label": "Learn More",
        "url": "https://blog.myapp.com/dark-mode",
        "type": "url"
      }
    ],
    "media": {
      "type": "image",
      "url": "https://cdn.myapp.com/dark-mode-preview.png",
      "alt": "Dark mode interface preview"
    },
    "priority": "normal",
    "category": "feature_announcement"
  }
}

Validation Rules

Phone Numbers

• Must be in E.164 format (e.g., +15551234567)
• Maximum length: 15 digits
• Must include country code
• No spaces, dashes, or parentheses

Message Content

• Maximum message size: 64KB
• UTF-8 encoding required
• HTML tags are not allowed in text fields
• URLs must be HTTPS for security

Timestamps

• Must be in ISO 8601 format with timezone
• Future timestamps allowed for scheduling
• Maximum 30 days in the future
• Timezone-aware (UTC recommended)

Media Attachments

• Supported formats: JPEG, PNG, GIF, WebP
• Maximum file size: 10MB
• Images are automatically optimized
• Alt text required for accessibility