> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cfosilvia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TWILIO EVENT STREAMS SETUP

# Twilio Event Streams Setup Guide

## Overview

Twilio Event Streams provides real-time error and warning notifications for all Twilio services. This replaces the legacy debugger webhook with a more scalable and reliable approach.

## What We're Monitoring

Based on your error analysis (`twilio-error-analysis.txt`), you have:

* **666 failed messages**
* **666 undelivered messages**
* **52.6% delivery rate** (should be 95%+)
* **339 "unknown" errors** with no details

Event Streams will help you:

* ✅ Get details on those "unknown" errors
* ✅ Catch errors in real-time
* ✅ Monitor A2P 10DLC compliance
* ✅ Track rate limits and API issues
* ✅ Improve your delivery rate

## Architecture

```
Twilio detects an error
         ↓
Event Streams publishes event
         ↓
POST https://cfosilvia.com/api/twilio/events
         ↓
Validate signature
         ↓
Log to twilio_error_logs table
         ↓
Alert on critical errors
```

## Files Created

### 1. `/app/api/twilio/events/route.ts`

**Webhook endpoint for Event Streams**

* **POST**: Receives error events from Twilio
  * Validates Twilio signature
  * Parses CloudEvents format
  * Logs to database
  * Alerts on critical errors

* **GET**: View recent error logs
  * Returns last 50 errors
  * Groups by type and level
  * Useful for monitoring

### 2. `/sql-queries/create-twilio-error-logs-table.sql`

**Database schema for error logs**

```sql theme={null}
CREATE TABLE twilio_error_logs (
  id UUID PRIMARY KEY,
  event_id TEXT UNIQUE,
  event_type TEXT,
  event_time TIMESTAMP,
  account_sid TEXT,
  level TEXT, -- "Error" or "Warning"
  payload JSONB,
  raw_event JSONB,
  created_at TIMESTAMP
)
```

### 3. `/scripts/setup-twilio-event-streams.sh`

**Automated setup script**

Creates sink and subscriptions via Twilio CLI.

## Setup Instructions

### Step 1: Install Twilio CLI (if not already installed)

```bash theme={null}
npm install -g twilio-cli
```

### Step 2: Login to Twilio

```bash theme={null}
twilio login
```

Enter your Account SID and Auth Token when prompted.

### Step 3: Create Database Table

Run the SQL in Supabase:

```bash theme={null}
# Copy the SQL file contents
cat sql-queries/create-twilio-error-logs-table.sql

# Then paste and run in Supabase SQL Editor
```

Or use psql:

```bash theme={null}
psql 'postgresql://postgres:[PASSWORD]@db.[PROJECT-ID].supabase.co:5432/postgres' \
  -f sql-queries/create-twilio-error-logs-table.sql
```

### Step 4: Deploy the Endpoint

The endpoint is already created at `/app/api/twilio/events/route.ts`.

**Deploy to production:**

```bash theme={null}
git add .
git commit -m "Add Twilio Event Streams error monitoring"
git push
```

Wait for Vercel to deploy.

### Step 5: Run Setup Script

```bash theme={null}
./scripts/setup-twilio-event-streams.sh
```

This will:

1. Create a webhook sink pointing to your endpoint
2. Subscribe to messaging error events
3. Subscribe to voice error events
4. Display the Sink SID for reference

**Output:**

```
🎉 Twilio Event Streams Setup Complete!

Configuration:
  Webhook URL: https://www.cfosilvia.com/api/twilio/events
  Sink SID: DGxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Subscribed to:
  ✅ Messaging errors (SMS/MMS)
  ✅ Voice errors (calls)
```

### Step 6: Test It

**Trigger a test error:**

Send an SMS to an invalid number or trigger any Twilio error.

**Check if it worked:**

```bash theme={null}
# View in browser
open https://www.cfosilvia.com/api/twilio/events

# Or with curl
curl https://www.cfosilvia.com/api/twilio/events
```

**Check database:**

```sql theme={null}
SELECT * FROM twilio_error_logs 
ORDER BY created_at DESC 
LIMIT 10;
```

## Event Types

### Messaging Errors

**Type:** `com.twilio.messaging.error-log`

**Common errors you'll see:**

* Error 30034: Exceeded max price
* Error 30007: Carrier violation
* Error 21610: User opted out (STOP)
* Error 21617: Queue overflow
* Error 21408: Permission denied
* Error 12300: Invalid number format

### Voice Errors

**Type:** `com.twilio.voice.error-log`

**Common errors:**

* Call failures
* Invalid phone numbers
* TwiML errors
* Connection issues

## CloudEvents Format

Events arrive in CloudEvents format:

```json theme={null}
{
  "specversion": "1.0",
  "type": "com.twilio.messaging.error-log",
  "source": "/v1/Messaging/...",
  "id": "EZ00000000000000000000000000000000",
  "dataschema": "https://events-schemas.twilio.com/...",
  "datacontenttype": "application/json",
  "time": "2025-10-27T12:00:00.000Z",
  "data": "{\"account_sid\":\"AC...\",\"level\":\"Error\",\"payload\":{...}}"
}
```

## Monitoring & Alerting

### View Recent Errors

**Via API:**

```bash theme={null}
curl https://www.cfosilvia.com/api/twilio/events
```

**Via Database:**

```sql theme={null}
-- All errors today
SELECT * FROM twilio_error_logs 
WHERE event_time >= CURRENT_DATE 
ORDER BY event_time DESC;

-- Group by error type
SELECT 
  event_type,
  level,
  COUNT(*) as count
FROM twilio_error_logs
WHERE event_time >= CURRENT_DATE
GROUP BY event_type, level
ORDER BY count DESC;

-- Critical errors only
SELECT * FROM twilio_error_logs 
WHERE level = 'Error'
ORDER BY event_time DESC
LIMIT 20;
```

### Add Alerting (Optional)

Edit `/app/api/twilio/events/route.ts` and add alerting:

```typescript theme={null}
// Alert on critical errors
if (level === 'Error') {
  // Send email
  await sendEmail({
    to: 'admin@cfosilvia.com',
    subject: 'Twilio Error Alert',
    body: JSON.stringify(eventData, null, 2)
  })
  
  // Or send to Slack
  await sendSlackMessage({
    channel: '#alerts',
    text: `🚨 Twilio Error: ${eventType}`,
    payload: eventData
  })
}
```

## Managing Event Streams

### List All Sinks

```bash theme={null}
twilio api:events:v1:sinks:list
```

### List All Subscriptions

```bash theme={null}
twilio api:events:v1:subscriptions:list
```

### Delete a Sink

```bash theme={null}
twilio api:events:v1:sinks:remove --sid DGxxxxx
```

### Delete a Subscription

```bash theme={null}
twilio api:events:v1:subscriptions:remove --sid DFxxxxx
```

### Update Sink URL

If you need to change the webhook URL:

```bash theme={null}
twilio api:events:v1:sinks:update \
  --sid DGxxxxx \
  --sink-configuration '{"destination":"https://new-url.com/api/twilio/events","method":"POST"}'
```

## Testing with ngrok

For local testing:

1. **Start ngrok:**
   ```bash theme={null}
   ngrok http 3000
   ```

2. **Update the script:**
   Edit `scripts/setup-twilio-event-streams.sh`:
   ```bash theme={null}
   WEBHOOK_URL="https://your-ngrok-url.ngrok-free.app/api/twilio/events"
   ```

3. **Run setup:**
   ```bash theme={null}
   ./scripts/setup-twilio-event-streams.sh
   ```

4. **Trigger an error and watch logs:**
   ```bash theme={null}
   # In your dev server terminal
   npm run dev
   ```

## Troubleshooting

### Events not arriving

1. **Check sink status:**
   ```bash theme={null}
   twilio api:events:v1:sinks:fetch --sid DGxxxxx
   ```

2. **Check subscriptions:**
   ```bash theme={null}
   twilio api:events:v1:subscriptions:list
   ```

3. **Test the endpoint:**
   ```bash theme={null}
   curl -X POST https://www.cfosilvia.com/api/twilio/events \
     -H "Content-Type: application/json" \
     -d '[{"type":"test","id":"test123","data":"{}"}]'
   ```

4. **Check Vercel logs:**
   Go to Vercel Dashboard → Logs → Filter by `/api/twilio/events`

### Signature validation failing

* Ensure `TWILIO_AUTH_TOKEN` is set in environment variables
* Check that the URL in Twilio matches exactly (including https\://)
* Verify no proxy or CDN is modifying the request

### Database errors

* Ensure `twilio_error_logs` table exists
* Check Supabase service role key is set
* Verify database connection

## Benefits

### Before Event Streams:

* ❌ No visibility into account-level errors
* ❌ Manual checking of Twilio Console
* ❌ 339 "unknown" errors with no details
* ❌ Reactive debugging after users complain

### After Event Streams:

* ✅ Real-time error notifications
* ✅ Automatic logging to database
* ✅ Detailed error information
* ✅ Proactive monitoring and alerting
* ✅ Historical error tracking
* ✅ Ability to analyze trends

## Cost

Event Streams is **free** for error logs! No additional charges beyond your normal Twilio usage.

## Next Steps

1. ✅ Create database table
2. ✅ Deploy endpoint to production
3. ✅ Run setup script
4. ✅ Test with a triggered error
5. ⏭️ Add alerting (optional)
6. ⏭️ Create dashboard for error visualization (optional)
7. ⏭️ Set up automated reports (optional)

## Resources

* [Twilio Event Streams Docs](https://www.twilio.com/docs/events)
* [Webhook Quickstart](https://www.twilio.com/docs/events/webhook-quickstart)
* [Error Log Event Types](https://www.twilio.com/docs/events/event-types#errors)
* [CloudEvents Spec](https://cloudevents.io/)

***

**Status**: Ready to deploy and configure


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.