V2 Messaging Infrastructure Upgrade - Customer Testing & Migration Guide


Jason Sommerset



Important Upcoming V2 API Changes

V2 API Upgrade Resources

V2 Upgrade Process/Schedule

Overview of 3 Steps to Migrate to new V2 Infrastructure

Recommended Testing Plan


Overview V2 Infrastructure Upgrade

As part of Bandwidth’s on-going investment in our messaging platform, we have completed the migration of our HTTP V2 interfaces to new V2 messaging infrastructure.  This infrastructure upgrade was made to improve the overall integration and reliability of our operational environments, tooling and operational standards. These types of infrastructure upgrade projects are rare, so it also provided us an opportunity for a much needed rebranding of our base URL to align with Bandwidth standards.  


Important Upcoming V2 API Changes

The two changes customer’s need to be aware of are:

1)  New Base URL - our new infrastructure will use a new base URL:

https://messaging.bandwidth.com/api/v2  will replace current base URL of https://api.catapult.inetwork.com/v2

2) New v2 /media resource for Inbound MMS messages - for inbound MMS, we are replacing using v1/media  with a new v2/media resource. This change is expected to be non-breaking for customers.  

Today, for inbound MMS, we send:

"media"         : [ "https://api.catapult.inetwork.com/v1/users/{userId}/media/14762070468292kw2fuqty55yp2b2/0/bw.png"],


After we migrate inbound traffic, we will send:

"media"         : [ "https://messaging.bandwidth.com/api/v2/users/{userId}/media/14762070468292kw2fuqty55yp2b2/0/bw.png"],

Developers should use the full URL provided for inbound MMS just as they do today and will automatically begin using the new v2 media resource, you can read more here. Your token/secret will remain unchanged from today’s v1 media location.


V2 API Upgrade Resources


V2 Upgrade Process/Schedule

Bandwidth will work with customers on a 3-step upgrade.  All changes are seamless to customers, except for Step 3 where customers will need to migrate all outbound traffic to the new base URL. 

April 2019 Upgrade Schedule



 Monday, April 8, 2019  Step 1 - Inbound Traffic Migrated
8:00 PM PT / 11:00 PM ET
 Wednesday, April 10, 2019  Step 2 - Dashboard Portal Migrated
8:00 PM PT / 11:00 PM ET

 Monday, April 15, 2019

 Step 3 - Customers migrate their outbound traffic

 *Customer action required*


Overview of 3 Steps to Migrate to New V2 Infrastructure

There are 3 steps for migrating your account to the new V2 infrastructure, customer action is only required for Step 3.  Bandwidth will perform steps 1 and 2 as part of our upgrade process for your account.


Step 1: Bandwidth Migrates Inbound SMS/MMS 

April 8, 2019 @ 8PM PT / 11 PM ET



Customer Action Required: None.

Bandwidth will perform all these steps, there is no action required by customers for step 1.  

Bandwidth Step:  Bandwidth will migrate customer Location/Callback URL and Token data to New V2 Infrastructure so inbound traffic will be migrated to our new infrastructure.

At that time, the following will happen:

  1. One-Time Replication Applications & Tokens: Bandwidth takes a snapshot of application and tokens and migrates to the new infrastructure - so your applications/callback URLs and tokens will work in both old and new at the same time.
  1. Updates to Your Locations: Bandwidth updates all existing customer V2 locations to send inbound SMS/MMS traffic to customers via the new V2 infrastructure to your already configured applications/callback URLs.  There are no changes to the API and inbound SMS/MMS will have the same fields and format it does today.

Inbound MMS Uses New v2 /media:  As noted in the introduction, upon migration of inbound traffic - all inbound MMS media files will be stored on new V2 /media infrastructure.  IMPORTANT NOTE: Your existing API tokens will work to retrieve this media.

Dashboard Portal Applications & Tokens Special Note: The Dashboard Portal will not be migrated at Step 1, therefore any updates to applications and tokens will result in out of sync issues.  Please contact Bandwidth support if you need to update applications or tokens before you complete step 3 below, migrating your outbound traffic.  



Step 2: Bandwidth Migrates Dashboard Portal

April 10, 2019 @ 8PM PT / 11 PM ET




Customer Action Required: None.

Bandwidth will perform all these steps, there is no action required by customers for step 2.  

Bandwidth Step:  Bandwidth will migrate Bandwidth Dashboard Portal (dashboard.bandwidth.com) to use the New V2 Infrastructure.

At that time, the following will happen:

Migrate Dashboard Portal to new V2 Infrastructure. Bandwidth will migrate Dashboard Portal (dashboard.bandwidth.com) to point at the new V2 infrastructure to manage applications/callback URLs.  Dashboard Portal Applications & Tokens Special Note: From this step forward, changes customers make to applications and tokens managed by Dashboard Portal will only update the new V2 infrastructure.  Any updates to applications and tokens will not work on the old V2 infrastructure, therefore customers must migrate their outbound traffic before making any changes to applications and tokens .


Step 3: Customers Migrate Outbound SMS/MMS

Anytime after April 15




Customer Action Required:  Migrate outbound traffic to new base URL.

Bandwidth Step:  None.

At that time, the following should happen:

  1. Customers Migrate Outbound SMS/MMS to new Base URL.  Customers should change their base URL from https://api.catapult.inetwork.com/v2 to https://messaging.bandwidth.com/api/v2  
  2. At that time, all inbound and outbound traffic will have been successfully migrated to the new V2 infrastructure and all Dashboard Portal management changes you make to Applications and Tokens will be effective to all aspects of your account.

Optional Step:

Outbound MMS Using Bandwidth Media Resource - the vast majority of customer’s host attachments on their own media servers for purposes of sending outbound MMS.  In rare cases, some customers have chosen to upload media to our /media resource for purposes of “sending”. If you are uploading to v1 /media for purposes of sending, you will need to take an additional step to migrate to v2 /media at the same time you migrate outbound SMS/MMS.  If you require more assistance with this, please contact support.


Recommended Testing Plan

After we deploy our new V2 infrastructure on Step 2:

While leaving your production traffic pointed at the old base URL, you should test outbound traffic with a subset of your TNs, sending outbound test traffic to the new base URL and verifying success for your various use cases.

A minimal test plan would be:

  1. Set-up a new test location using an existing testing Application you have already set-up before April 8th. This location was migrated already for you.
  2. Test both with moving an existing test number to your new test location and adding a new number to your test location
  3. Send SMS (and MMS if you use MMS)
  4. Verify callbacks are working as expected
  5. Test inbound SMS (and MMS if applicable)





Article is closed for comments.