twilio-debugging-observability

1. Check status callbacks FIRST
   (Did your endpoint receive delivery/call status? What error code?)
   |
2. Check the resource directly via REST API
   (GET /Messages/{sid} or /Calls/{sid} — current state + error_code)
   |
3. Check number reputation / sender registration
   (Is the number spam-flagged? Is A2P 10DLC registered? Toll-free verified?)
   |
4. Check the Console Debugger for webhook/TwiML errors
   (Console > Monitor > Errors — shows HTTP request/response details)
   |
5. Check your webhook endpoint
   (Is it reachable? Responding within 15s? Returning valid TwiML/200?)
   |
6. Query Monitor Alerts API or Event Streams
   (For patterns across many messages/calls, or historical analysis)

import json, os
from flask import Flask, request
from twilio.request_validator import RequestValidator

app = Flask(__name__)
validator = RequestValidator(os.environ["TWILIO_AUTH_TOKEN"])

@app.route("/debugger", methods=["POST"])
def debugger_event():
    sig = request.headers.get("X-Twilio-Signature", "")
    if not validator.validate(request.url, request.form, sig):
        return "Forbidden", 403
    level = request.form.get("Level")
    payload = json.loads(request.form.get("Payload", "{}"))
    error_code = payload.get("error_code")
    resource_sid = payload.get("resource_sid")
    msg = payload.get("more_info", {}).get("msg", "")
    print(f"[{level}] Error {error_code} on {resource_sid}: {msg}")
    return "", 204

const express = require("express");
const twilio = require("twilio");
const app = express();
app.use(express.urlencoded({ extended: false }));

app.post("/debugger", (req, res) => {
    const valid = twilio.validateRequest(
        process.env.TWILIO_AUTH_TOKEN,
        req.headers["x-twilio-signature"],
        `https://${req.headers.host}${req.originalUrl}`,
        req.body
    );
    if (!valid) return res.status(403).send("Forbidden");
    const payload = JSON.parse(req.body.Payload || "{}");
    const { error_code, resource_sid } = payload;
    const msg = payload.more_info?.msg || "";
    console.log(`[${req.body.Level}] Error ${error_code} on ${resource_sid}: ${msg}`);
    res.sendStatus(204);
});

from datetime import datetime, timedelta

# Alerts from the last 24 hours
start = datetime.utcnow() - timedelta(days=1)
alerts = client.monitor.alerts.list(
    start_date=start,
    log_level="error",
    limit=50
)

for alert in alerts:
    print(f"{alert.date_created} [{alert.error_code}]")
    # Fetch full details including HTTP request/response
    detail = client.monitor.alerts(alert.sid).fetch()
    print(f"  Request URL: {detail.request_url}")
    print(f"  Response body: {detail.response_body}")

const startDate = new Date(Date.now() - 24 * 60 * 60 * 1000);
const alerts = await client.monitor.alerts.list({
    startDate,
    logLevel: "error",
    limit: 50,
});

for (const alert of alerts) {
    console.log(`${alert.dateCreated} [${alert.errorCode}]`);
    const detail = await client.monitor.alerts(alert.sid).fetch();
    console.log(`  Request URL: ${detail.requestUrl}`);
    console.log(`  Response body: ${detail.responseBody}`);
}

events = client.monitor.events.list(limit=20)
for event in events:
    print(f"{event.event_date}: {event.event_type}")
    print(f"  Resource: {event.resource_type} ({event.resource_sid})")
    print(f"  Actor: {event.actor_type} ({event.actor_sid}) from {event.source_ip_address}")

import os, requests

account_sid = os.environ["TWILIO_ACCOUNT_SID"]
auth_token = os.environ["TWILIO_AUTH_TOKEN"]

# Step 1: Create a webhook sink
sink = requests.post(
    "https://events.twilio.com/v1/Sinks",
    auth=(account_sid, auth_token),
    data={
        "Description": "Error monitoring sink",
        "SinkType": "webhook",
        "SinkConfiguration": '{"destination": "https://yourapp.com/twilio-errors", "method": "POST"}'
    }
).json()

# Step 2: Subscribe to error log events
subscription = requests.post(
    "https://events.twilio.com/v1/Subscriptions",
    auth=(account_sid, auth_token),
    data={
        "Description": "Error log subscription",
        "SinkSid": sink["sid"],
        "Types": '[{"type": "com.twilio.error-logs.error.logged"}]'
    }
).json()

print(f"Sink: {sink['sid']}, Subscription: {subscription['sid']}")

# Attach when sending
message = client.messages.create(
    to="+15558675310", from_="+15017122661", body="Hello!",
    status_callback="https://yourapp.com/msg-status"
)

call = client.calls.create(
    to="+15558675310", from_="+15017122661",
    url="https://yourapp.com/voice",
    status_callback="https://yourapp.com/call-status",
    status_callback_event=["initiated", "ringing", "answered", "completed"]
)

# In TwiML
response = VoiceResponse()
response.record(
    recording_status_callback="https://yourapp.com/recording-status",
    recording_status_callback_event="completed absent failed"
)

# Simulate an inbound SMS webhook
curl -X POST https://yourapp.com/sms \
  -d "From=+15551234567" \
  -d "To=+15559876543" \
  -d "Body=Test message" \
  -d "MessageSid=SM00000000000000000000000000000000"

# Check message delivery status
message = client.messages("SMxxxxxxxxxx").fetch()
print(f"Status: {message.status}, Error: {message.error_code}")

# Check call status
call = client.calls("CAxxxxxxxxxx").fetch()
print(f"Status: {call.status}, Duration: {call.duration}")

const message = await client.messages("SMxxxxxxxxxx").fetch();
console.log(`Status: ${message.status}, Error: ${message.errorCode}`);

const call = await client.calls("CAxxxxxxxxxx").fetch();
console.log(`Status: ${call.status}, Duration: ${call.duration}`);

# Verbose output for any CLI command
twilio api:core:messages:list --limit 5 -l debug

# Log levels: debug, info, warn, error

import os
from twilio.rest import Client

client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])

alerts = client.monitor.alerts.list(log_level="error", limit=10)
for alert in alerts:
    print(f"{alert.date_created}: [{alert.error_code}] {alert.alert_text}")

const twilio = require("twilio");
const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);

const alerts = await client.monitor.alerts.list({ logLevel: "error", limit: 10 });
alerts.forEach(a => {
    console.log(`${a.dateCreated}: [${a.errorCode}] ${a.alertText}`);
});