Migrate SMS from US1 to IE1

Confirm that IE1 supports your use case by reviewing the Messaging features in IE1. The following senders aren't supported in IE1:

• +1 phone numbers
• Short codes

A phone number's region determines which Twilio region it can use for Messaging. This has the following implications:

• Sending outbound SMS: You must use the correct region's API endpoint to send messages from that number. Messages from a number in the wrong region will fail with error 21663.
• Receiving inbound SMS: Inbound messages sent to that number are routed to the webhook configuration in that region.

This means that when you update a phone number's region, your application must be ready to use the new region's API endpoint and process requests from the new region's webhooks.

You must coordinate your application update with the phone number region update to avoid downtime or dropped messages.

The goal of these guides is to help you migrate active SMS implementations while avoiding downtime or dropped messages. Because every use case and implementation is unique, zero downtime can't be guaranteed. To manage the overall risk of your migration, we recommend that you:

• Test IE1 integration manually and in non-production environments.
• Perform test migrations in non-production environments.
• Migrate during periods of low messaging traffic to reduce the impact of any issues.
• Have a rollback plan in case of unexpected issues. This may include reverting your application code to use US1 APIs and updating phone number regions back to US1.

To access APIs in IE1, you need IE1-specific API credentials. For instructions, see Manage Regional API Credentials.

Alphanumeric sender IDs do not require a region update. To migrate, you only need to update your application code to target IE1 APIs and use IE1 API credentials.

If your use case is inbound-initiated and you primarily receive and respond to inbound messages, migrating to IE1 can be less error-prone than outbound-initiated use cases. This is because you can pre-configure your inbound webhooks in IE1 before changing a number's region, ensuring that inbound messages are routed to the correct webhook as soon as the region update is complete.

1. Depending on how your application responds to inbound messages, you may need to set up a new webhook consumer that targets the IE1 API for outbound messages.
2. Configure inbound webhooks in IE1 to target your new webhook consumer. You can do this for all of your phone numbers before changing the numbers' regions. See Phone number inbound webhooks and Messaging service inbound webhooks for details.
3. Keep US1 webhooks active during migration.
4. When ready to migrate: Update phone number regions to IE1.
5. Optional: Decommission US1 webhooks.

If you also have outbound-initiated use cases—for example, sending notifications or marketing messages—pair this inbound migration with one of the outbound migrations in this guide.

You can set a phone number's inbound webhook in IE1 using the Incoming Phone Numbers resource or the Numbers and Senders page in the Console.

You can set a Messaging Service's inbound webhook in IE1 using the Messaging Service resource or the Messaging Services page in the Console. Set UseInboundWebhookOnNumber to false for inbound messages to be routed to the service's webhooks.

Use this workflow when a brief downtime is acceptable. This migration involves updating both your application code and phone number regions as close together as possible. In the time between the region update and the application update, outbound messages can fail with error 21663.

1. Prepare application code targeting IE1. See Use the Programmable Messaging API with Twilio Regions for API and SDK examples.
2. When you're ready to migrate, update phone number regions to IE1 and update the application as close together as possible.
3. Check the Messaging Logs to identify failed messages. Once you've identified failed messages, retry them and confirm that messages are sent from IE1.

Use this workflow when your implementation sends outbound messages directly from phone numbers without the use of Messaging Services. This approach adds fallback logic to the outbound send path so that requests that fail during the migration are automatically retried.

1. Prepare error handling and retry logic in application code. For a full migration in a limited timeframe, we recommend trying IE1 first and falling back to US1. If you prefer to migrate numbers gradually over a longer period, you can try US1 first and fall back to IE1.
2. When you're ready to migrate, update the application code and start updating phone number regions to IE1.
3. After all numbers are in IE1, remove the US1 fallback path from your code.

Trying IE1 first and falling back to US1 is the recommended approach for a full migration in a limited timeframe. This approach sets your application up for the best performance when the migration is complete. This approach introduces initial latency while your numbers are mainly in US1 at the beginning of the migration. Time your application update and the phone number region updates close together to minimize this period of retry latency.

If you prefer to migrate numbers gradually over a longer period, you can try US1 first and fall back to IE1. This approach avoids any retry latency for the bulk of your numbers that are still in US1. It also has the additional benefit of allowing you to update application code and migrate numbers at different times.

If you intend to keep both regions active for a long time, you can also add a step to check the phone number region before attempting to send a message. Note that the V3 Phone Number Regional Configuration API reflects the latest region immediately, but the region update can take up to 5 minutes to take effect. This delay means the check is ineffective for faster migrations, and fallback logic should still be used to handle region-mismatch errors.

Use this workflow if your application uses Messaging Services. Service sender pools can help make the migration smoother and reduce downtime since services in IE1 can be seeded with phone numbers to handle the initial traffic in a migration.

It's important to know these details about Messaging Services in regions before starting the migration:

• Messaging Services are region-isolated and cannot be transferred to a different region. You must create new services in IE1.
• Sticky Sender mappings are not transferable between regions and will be initially lost when migrating to IE1. If you use Sticky Sender, new mappings will be created automatically in IE1 as messages are sent from the service.

1. Create Messaging Services in IE1 and apply the same configurations from the US1 service.
2. It is recommended to seed IE1 services with some new or unused phone numbers. A Messaging Service can start to handle traffic as soon as one phone number is in it, so adding new or unused numbers first lets you validate your implementation in IE1 and handle the initial traffic in the migration.
3. When you're ready to migrate, start to migrate traffic to IE1.
4. Migrate existing numbers from the US1 service to IE1 in coordination with migrated traffic.

You need to recreate your Messaging Services in IE1 and apply any configurations. You can create a Messaging Service in IE1 using the Messaging Services page in the Console or use the Messaging Service resource for programmatic bulk operations.

How you migrate traffic to IE1 depends on your implementation and how long you intend to keep your US1 implementation active. This section covers the recommended workflow to migrate traffic fully from US1 to IE1. If you plan to keep both implementations active or split traffic in unique ways, you can pair your traffic migration plan with the guide as you see fit.

When migrating traffic from a US1 service to an IE1 service, the main factor is keeping both sender pools sized for their respective traffic share throughout the migration. When your application switches to IE1, the IE1 pool must be large enough to handle the initial volume and continue to scale. At the same time, the US1 pool must retain enough numbers to handle any trailing traffic.

1. Optionally, migrate a portion of existing numbers from the US1 service to IE1 ahead of time. This builds up the IE1 sender pool so it can handle expected volume from the moment the application switches over. For example, you can plan to migrate during your lowest messaging traffic window and migrate enough numbers that can serve that traffic.
2. Update your application code to target IE1 APIs and use IE1 Service SIDs.
3. Migrate the remaining numbers from the US1 service to IE1.
4. Optionally, keep a small set of numbers in the US1 service until you confirm no traffic is flowing through it. Once the US1 service has zero traffic, migrate the remaining numbers.

For each phone number in the US1 service, repeat these steps:

1. Remove the phone number from the US1 service.
2. Update the phone number's region to IE1.
3. Wait for the region update to propagate, then add the phone number to the IE1 service.

Because region updates can take up to 5 minutes to propagate, adding the number to the IE1 service immediately after the update can fail with error 21669. The following example waits a configurable delay before attempting to add the number, then retries if the error occurs. The example below is sequential. When migrating large number pools, consider adding concurrency or processing batches in parallel to speed up the migration.

1
const twilio = require('twilio');
2
const axios = require('axios');
3

4
const us1Client = twilio(US1_API_KEY_SID, US1_API_KEY_SECRET, {
5
  accountSid: ACCOUNT_SID
6
});
7

8
const ie1Client = twilio(IE1_API_KEY_SID, IE1_API_KEY_SECRET, {
9
  accountSid: ACCOUNT_SID,
10
  edge: 'dublin',
11
  region: 'ie1'
12
});
13

14
const INITIAL_WAIT_MS = 20000;
15
const RETRY_WAIT_MS = 10000;
16
const MAX_RETRIES = 10;
17

18
function sleep(ms) {
19
  return new Promise(resolve => setTimeout(resolve, ms));
20
}
21

22
async function migrateNumber(phoneNumberSid, phoneNumber, us1ServiceSid, ie1ServiceSid) {
23
  // Step 1: Remove from US1 service
24
  await us1Client.messaging.v1
25
    .services(us1ServiceSid)
26
    .phoneNumbers(phoneNumberSid)
27
    .remove();
28

29
  // Step 2: Update region to IE1
30
  await axios.post(
31
    `https://routes.twilio.com/v3/PhoneNumbers/${phoneNumber}`,
32
    new URLSearchParams({ messagingRegion: 'ie1' }),
33
    { auth: { username: US1_API_KEY_SID, password: US1_API_KEY_SECRET } }
34
  );
35

36
  // Step 3: Wait then add to IE1 service with retry
37
  await sleep(INITIAL_WAIT_MS);
38

39
  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
40
    try {
41
      await ie1Client.messaging.v1
42
        .services(ie1ServiceSid)
43
        .phoneNumbers
44
        .create({ phoneNumberSid });
45
      console.log(`Migrated ${phoneNumber} to IE1 service`);
46
      return;
47
    } catch (err) {
48
      if (err.code === 21669 && attempt < MAX_RETRIES) {
49
        console.log(`Attempt ${attempt} failed, retrying in ${RETRY_WAIT_MS / 1000}s`);
50
        await sleep(RETRY_WAIT_MS);
51
      } else {
52
        throw err;
53
      }
54
    }
55
  }
56
}

You can update a phone number's messaging region using the V3 Phone Number Regional Configuration API or the Numbers and Senders page in the Console. Region updates can take up to 5 minutes to take effect. The V3 Phone Number Regional Configuration API requires US1 credentials.

You can monitor your IE1 implementation using these pages in the Console:

• Messaging Logs to confirm messages are being sent in IE1 and to see errors.
• Messaging Insights to view delivery metrics for your IE1 implementation.

Look out for error 21663, which indicates that a message was sent from a phone number in the wrong region.