Issue

A released Twilio phone number may still appear in your Proxy pool and be eligible for assignment to new Proxy sessions, even after you have released it from your account. This can cause confusion or errors, especially in high-traffic applications where sessions may remain open or be quickly recreated.

Symptoms

• The released phone number is still visible in the Proxy pool.
• Attempts to remove the number from the Proxy pool via Console or API fail with errors indicating active sessions.
• The number cannot be reassigned or repurchased, but it remains associated with open Proxy sessions.

Product

Twilio proxy

Environment

Twilio Console

Cause

Twilio Proxy does not automatically remove a phone number from the Proxy pool if there are active sessions associated with it. Even after releasing the number from your account, any open Proxy sessions using that number must be closed before the number can be fully removed from the Proxy pool.

Resolution

To fully remove a released phone number from your Proxy pool, you must:

1. Identify and Close All Active Proxy Sessions Using the Number
   • Fetch all sessions in your Proxy service.
   • For each session, check if the released phone number is assigned as a participant (proxy_identifier_sid).
   • Close any sessions where the number is present.
2. Remove the Phone Number from the Proxy Pool
   • Once all sessions using the number are closed, remove the number from the Proxy pool via the Console or API.

Step-by-Step Instructions

1. Fetch and Close Sessions

• Use the Proxy Sessions API to list all sessions.
• For each session, use the Participants API to check if the released number is present.
• If found, update the session status to closed using the Update Session API.

2. Remove the Number

• In the Twilio Console:
  Go to Proxy → Services → [Your Service] → Numbers and click Remove next to the number.
• Or, use the Proxy Phone Number Remove API.

3. Grace Period

• After releasing a number, Twilio enforces a 10-day grace period before the number is fully removed from all associations.
• If sessions remain open after 10 days, they may still reference the released number. Sessions without an explicit date-expiry or ttl property can remain open indefinitely.

Additional Information

• If you attempt to remove a number and receive errors about active sessions, ensure all sessions using the number are closed.
• After the 10-day grace period, the number cannot be repurchased, but manual cleanup of sessions may still be required.
• For high-traffic applications, consider automating session closure and number removal as part of your release workflow.

Below you will find references to useful documents:

• Twilio Proxy API Documentation