1. Verify Basic Connectivity

curl -I https://api.twilio.com

nslookup api.twilio.com
nslookup studio.twilio.com
nslookup flex.twilio.com

Note: If basic connectivity works but your application still fails, skip to Step 3. If no IP addresses are returned, you have a DNS issue - proceed to Step 2.

2. Check Your Network Environment

nslookup api.twilio.com
nslookup api.twilio.com 8.8.8.8

Note: If results differ, your local DNS may be filtering Twilio domains.

3. Install MTR (My Traceroute)

brew install mtr

sudo apt-get update
sudo apt-get install mtr

mtr --report --report-cycles 100 api.twilio.com > mtr_api.txt
mtr --report --report-cycles 100 studio.twilio.com > mtr_studio.txt

mtr --report --report-cycles 100 global.vss.twilio.com > mtr_video.txt
mtr --report --report-cycles 100 --udp --port 3478 global.vss.twilio.com > mtr_video_udp.txt

mtr --report --report-cycles 100 flex.twilio.com > mtr_flex.txt
mtr --report --report-cycles 100 flex-api.twilio.com > mtr_flex_api.txt

mtr --report --report-cycles 100 serverless.twilio.com > mtr_serverless.txt
# Replace [your-domain] with your actual domain
mtr --report --report-cycles 100 [your-domain].twil.io > mtr_function.txt

5. Analyze MTR Results

Problem Indicators:

• Packet loss percentage above 5% that continues to the destination
• Latency above 150ms for real-time services (Video, Flex voice)
• Complete timeouts (***) at the final destination
• Sudden latency increases of more than 50ms between hops

Normal Behavior:

• Single hop showing packet loss (often just ICMP limiting)
• Slight latency variations (±10ms)
• Some middle hops showing *** but final destination responding

Understanding MTR Results: Testing Twilio Platform Connectivity

Here are three scenarios that demonstrate how to interpret MTR (My Traceroute) output when diagnosing connectivity to Twilio Platform and Applications.

Example 1: Healthy Connection to Twilio API

Clean Connection

Start: 2024-11-13T09:15:42+0000
HOST: customer-router	Loss%	Snt	Last	Avg	Best	Wrst	StDev
1.|-- 192.168.1.1	0.0%	10	0.4	0.5	0.4	0.6	0.1
2.|-- 10.20.30.1	0.0%	10	1.2	1.3	1.1	1.8	0.2
3.|-- isp-gateway.example.net	0.0%	10	3.5	4.1	3.2	6.8	1.1
4.|-- core-router-1.isp.net	0.0%	10	5.2	5.8	5.0	8.4	1.2
5.|-- peer-transit.net	0.0%	10	8.7	9.2	8.5	11.3	0.9
6.|-- edge-router.twilio.com	0.0%	10	9.1	9.4	9.0	10.2	0.4
7.|-- api.twilio.com	0.0%	10	9.8	10.1	9.6	11.5	0.6

This trace shows the route from a customer's router to api.twilio.com. The results indicate a healthy connection requiring 7 hops, with zero packet loss at every point along the path. This is what you want to see when troubleshooting Twilio API connectivity.

Example 2: False Alarm - Control Plane Rate Limiting

Apparent Loss (Not Actually a Problem)

Start: 2024-11-13T14:22:18+0000
HOST: customer-router	Loss%	Snt	Last	Avg	Best	Wrst	StDev
1.|-- 10.0.0.1	0.0%	10	0.3	0.4	0.3	0.5	0.1
2.|-- 203.0.113.1	0.0%	10	2.1	2.3	2.0	3.1	0.3
3.|-- transit-1.carrier.net	0.0%	10	8.4	8.9	8.2	11.2	0.9
4.|-- transit-2.carrier.net	40.0%	10	15.3	15.7	15.1	16.8	0.6
5.|-- ix-peer-1.backbone.net	60.0%	10	22.1	22.8	21.9	24.3	0.8
6.|-- ix-peer-2.backbone.net	70.0%	10	28.4	29.1	28.2	31.5	1.1
7.|-- core-01.backbone.net	50.0%	10	35.2	35.9	34.8	38.1	1.2
8.|-- core-02.backbone.net	80.0%	10	42.7	43.2	42.3	45.1	0.9
9.|-- border-gateway.twilio.net	60.0%	10	48.9	49.5	48.6	51.2	0.8
10.|-- edge-lb-01.twilio.com	40.0%	10	49.8	50.3	49.5	52.1	0.7
11.|-- chunderhead-gll-us1.twilio.com	0.0%	10	50.2	50.6	50.0	51.8	0.5

This trace to a Twilio media gateway (chunderhead) shows significant packet loss across multiple transit provider hops. However, notice that the final destination (hop 11) shows zero packet loss. This indicates the path is actually working correctly.

What's Really Happening: This is Control Plane Policing in action. MTR sends ICMP Echo packets with increasing TTL values. When TTL expires at a router, that router should return an ICMP Type 11 "Time Exceeded" message. However, major carriers and Twilio's infrastructure deliberately limit how many ICMP packets their control plane will process to prevent resource exhaustion. When these rate limits are hit, intermediate routers stop responding to traceroute packets—but they continue forwarding your actual traffic (like SIP, WebSocket, or API calls). The key indicator is: if your final destination shows no loss, your Twilio connectivity is fine.

Example 3: Genuine Connectivity Issues

Real Packet Loss to Twilio Flex

Start: 2024-11-13T16:45:30+0000
HOST: customer-router	Loss%	Snt	Last	Avg	Best	Wrst	StDev
1.|-- 172.16.0.1	0.0%	10	0.5	0.6	0.5	0.8	0.1
2.|-- 198.51.100.1	0.0%	10	1.8	2.1	1.7	3.2	0.4
3.|-- isp-core-1.example.net	0.0%	10	6.3	6.8	6.1	8.9	0.8
4.|-- isp-core-2.example.net	0.0%	10	12.5	13.1	12.2	15.4	1.0
5.|-- congested-link.isp.net	20.0%	10	45.7	48.3	44.2	58.9	5.2
6.|-- flex.twilio.com	35.0%	10	52.8	54.1	51.6	62.3	3.8

This trace to flex.twilio.com shows packet loss beginning at hop 5 and persisting through the final destination (hop 6), indicating a genuine connectivity problem. This would likely cause issues with Twilio Flex agents experiencing dropped WebSocket connections, delayed updates, or call quality problems.

Diagnosis: The packet loss starting at the ISP's congested link and continuing to Twilio's Flex endpoint suggests a legitimate network issue that needs to be escalated to the customer's ISP for resolution.

# Check if tcpdump is installed
which tcpdump
# If not installed on Linux:
sudo apt-get install tcpdump

7. Capture Network Traffic

# For general Twilio connectivity issues
sudo tcpdump -i any -w twilio_capture.pcap -c 10000 \
  'host api.twilio.com or host studio.twilio.com or host flex.twilio.com'

# For Twilio Video specifically
sudo tcpdump -i any -w twilio_video_capture.pcap -c 10000 \
  'host global.vss.twilio.com or portrange 10000-20000'

Note: While capturing is running, reproduce your issue 3-5 times. Stop the capture after reproducing the issue.

8. Test Service-Specific Requirements

# Test STUN server connectivity
nc -zvu global.vss.twilio.com 3478

# Test sample UDP media ports
nc -zvu global.vss.twilio.com 10000
nc -zvu global.vss.twilio.com 15000
nc -zvu global.vss.twilio.com 20000

# Test WebSocket connectivity
curl -I -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
  https://flex-api.twilio.com

# Test TaskRouter
curl -I https://taskrouter.twilio.com

# Test runtime endpoints
curl -I https://studio.twilio.com
curl -I https://serverless.twilio.com

# Check TLS version support
openssl s_client -connect studio.twilio.com:443 -tls1_2

9. Create Diagnostic Package

mkdir twilio_diagnostics
cd twilio_diagnostics

# System details
echo "=== System Information ===" > system_info.txt
uname -a >> system_info.txt
date >> system_info.txt

# Network configuration
echo "=== Network Configuration ===" > network_info.txt
# For Linux/Mac:
ifconfig >> network_info.txt 2>/dev/null || ip addr >> network_info.txt
netstat -rn >> network_info.txt
# For Windows (in Command Prompt):
# ipconfig /all > network_info.txt
# route print >> network_info.txt

cp ../mtr_*.txt .
cp ../twilio_capture.pcap .

cat > issue_summary.txt << EOF
Twilio Service Affected: [Video/Flex/Studio/Functions]
Account SID: [Your Account SID from Twilio Console]
Issue Started: [Date and Time]
Issue Frequency: [Constant/Intermittent]
Error Message: [Copy exact error message]

Network Environment:
- Location: [City, Country]
- ISP: [Your Internet Provider]
- Using VPN: [Yes/No]
- Behind Firewall: [Yes/No]

Files Included:
- mtr_*.txt: Network path analysis
- *.pcap: Packet captures
- system_info.txt: System configuration
- network_info.txt: Network configuration
EOF

# For Linux/Mac:
tar -czf twilio_diagnostics.tar.gz *
# For Windows (using 7-Zip):
# 7z a twilio_diagnostics.zip *

10. Determine if You Need Twilio Support

Contact Twilio Support if you see:

Self-resolution possible if you see:

1. How to contact Twilio Support: https://help.twilio.com/articles/360048500694-Contacting-Twilio-Support
2. Provide the following information:

Subject: Network Connectivity Issue - [Service Name]

Account SID: [Your Account SID]
Affected Service: [Video/Flex/Studio/Functions]
Issue Duration: [Start time - Present/Resolved]
Number of Affected Users: [Count or percentage]

Issue Description:
[Describe what specific operation is failing]

Diagnostic Data Findings:
- MTR shows [describe packet loss or latency issues]
- PCAP shows [describe connection failures or errors]
- Error occurs at [specific timestamp]

What I've Tried:
- [List your troubleshooting steps]
- [What worked or didn't work]

3. Attach your compressed diagnostic file (twilio_diagnostics.tar.gz or .zip)
4. Submit the ticket

12. While Waiting for Support Response

# Create a simple monitoring script
while true; do
  date
  curl -w "\nResponse time: %{time_total}s\n" -o /dev/null -s https://api.twilio.com
  sleep 60
done > connectivity_monitor.log &

Network Requirements by Service