Managing Twilio Deep

Twilio Deep Management Skill

Comprehensive management and analysis of Twilio voice, messaging, and telephony resources.

API Conventions

Authentication

All API calls use HTTP Basic Auth with Account SID and Auth Token, injected automatically.

Base URL

https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID

Core Helper Function

#!/bin/bash

twilio_api() {
    local method="$1"
    local endpoint="$2"
    local data="${3:-}"

    if [ -n "$data" ]; then
        curl -s -X "$method" \
            -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
            "https://api.twilio.com/2010-04-01/Accounts/${TWILIO_ACCOUNT_SID}${endpoint}.json" \
            -d "$data"
    else
        curl -s -X "$method" \
            -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
            "https://api.twilio.com/2010-04-01/Accounts/${TWILIO_ACCOUNT_SID}${endpoint}.json"
    fi
}

Output Rules

• Target ≤50 lines per script output
• Use jq to extract only needed fields
• Never dump full API responses

Phase 1: Discovery

#!/bin/bash
echo "=== Account Info ==="
twilio_api GET "" | jq '{sid: .sid, name: .friendly_name, status: .status, type: .type}'

echo ""
echo "=== Phone Number Inventory ==="
twilio_api GET "/IncomingPhoneNumbers?PageSize=50" \
    | jq -r '.incoming_phone_numbers[] | "\(.phone_number)\t\(.friendly_name)\t\(.capabilities | to_entries | map(select(.value==true) | .key) | join(","))"' \
    | column -t | head -20

echo ""
echo "=== Recent Messages (last 24h) ==="
twilio_api GET "/Messages?PageSize=20&DateSent>=$(date -u -d '1 day ago' +%Y-%m-%d)" \
    | jq -r '.messages[] | "\(.date_sent[0:16])\t\(.direction)\t\(.status)\t\(.from)\t\(.to)"' | head -15

echo ""
echo "=== Recent Calls ==="
twilio_api GET "/Calls?PageSize=20&StartTime>=$(date -u -d '1 day ago' +%Y-%m-%d)" \
    | jq -r '.calls[] | "\(.start_time[0:16])\t\(.direction)\t\(.status)\t\(.duration)s\t\(.from)\t\(.to)"' | head -15

Phase 2: Analysis

Messaging Health

#!/bin/bash
echo "=== Message Delivery Summary (last 7 days) ==="
twilio_api GET "/Messages?PageSize=1000&DateSent>=$(date -u -d '7 days ago' +%Y-%m-%d)" \
    | jq -r '.messages[] | .status' | sort | uniq -c | sort -rn

echo ""
echo "=== Failed Messages ==="
twilio_api GET "/Messages?Status=failed&PageSize=20" \
    | jq -r '.messages[] | "\(.date_sent[0:16])\t\(.error_code)\t\(.error_message[0:60])\t\(.to)"' | head -15

echo ""
echo "=== Error Code Breakdown ==="
twilio_api GET "/Messages?Status=failed&PageSize=200" \
    | jq -r '.messages[] | "\(.error_code) \(.error_message)"' | sort | uniq -c | sort -rn | head -10

Call Quality & Usage

#!/bin/bash
echo "=== Call Summary (last 7 days) ==="
twilio_api GET "/Calls?PageSize=500&StartTime>=$(date -u -d '7 days ago' +%Y-%m-%d)" \
    | jq '{
        total: (.calls | length),
        by_status: (.calls | group_by(.status) | map({(.[0].status): length}) | add),
        avg_duration_sec: (.calls | map(.duration | tonumber) | if length > 0 then add / length | floor else 0 end)
    }'

echo ""
echo "=== Usage Records (current month) ==="
twilio_api GET "/Usage/Records/ThisMonth" \
    | jq -r '.usage_records[] | select(.count != "0") | "\(.category)\t\(.count)\t$\(.price)"' \
    | sort -t$'\t' -k3 -rn | head -15

Output Format

=== Account: <name> (SID: <sid>) ===
Status: <active|suspended>
Phone Numbers: <count>

--- Messaging Health ---
Delivered: <n>  Failed: <n>  Undelivered: <n>
Top Errors: <error_code>: <count>

--- Call Quality ---
Total Calls: <n>  Avg Duration: <n>s
By Status: completed: <n>, busy: <n>, failed: <n>

--- Monthly Usage ---
<category>  <count>  $<price>

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Common Pitfalls

• Date format: Use YYYY-MM-DD for date filters
• Pagination: Default page size is 50, max 1000; check next_page_uri for more
• Rate limits: 100 requests/second concurrency limit
• Error codes: Reference https://www.twilio.com/docs/api/errors for error code meanings