V1 → V2 Messaging API Migration Guide

Follow

Jessica Murray

Updated

 

Tables of Contents

Key Differentiators  

Credentials  

Retrieving Message Data in V2 

Message Request Structure 

Response Code for Creating Messages 

Response Structure for Creating Messages     

Group Messaging  

Rate Limits  

How Callbacks Work  

Callback Structure      

Error Codes 

Rules on Media 

SDKs   

Resources  

 

Key Differentiators

First, let’s review the significant changes between the V1 Messaging API and V2 Messaging API and what this difference will look like in the API.

 

Difference

v1/messages v2/messages

Message Storage

All messages are stored within the API and can be fetched for 3 days

Messages are not stored at all within the API and must be stored per your needs

Outbound Message callbackUrl Messages could be sent with a combination of callbackUrl and receiptRequested in order to get status updates as the message progresses throughout the system ALL messages must include the applicationId and all status events are automatically sent to the callbackUrl specified in the application
Creating message http code The API returns 201 - Created when sending the message, however the message may still fail with an error code The API returns a 202 - Accepted and will send a callback for every event(including delivered and error)
Creating message response The API returns with the {message-id} in the Location Header The API returns a JSON object that contains information about the request
Outbound message to value Can only include a single phone number as a string Will accept both a string and an array. If an array with more than one phone number is sent, the message will be treated as a group message
Any Message Callback Message callbacks are sent as a single JSON object for both sms and mms Message callbacks are sent as an array of objects for every event
HTTP Errors See the errors for possible responses See the V2 errors for possible responses
Segment Count Messages sent or received with the v1/messages API do not contain the number of segments in the callbacks In the v2 API, the message segment is returned in the callbacks.

 

Credentials

V1 and V2 both use Basic Auth.

In V1, the only credentials you need are a token and secret.

In V2, you'll use a token and secret to create and send messages. You can get these credentials from the Applications page in the Dashboard.

In addition, for number management functions in V2, you'll use the username and password for a user on your V2 account as your credentials.

 

Retrieving Message Data in V2

In V2, you cannot do a GET request on an endpoint to retrieve message data. Rather, our new callbacks are more thorough and robust. We'll send each callback repeatedly over the course of 24 hours until either receive a 2XX response from your server confirming receipt of the callbacks, or 24 hours passes. It's up to you to store the data in the callbacks if you need that data later.

 

Message Request Structure

 

V1 Create Message POST Request

POST
https://api.catapult.inetwork.com/v1/users/{userId}/messages
Content-Type: application/json
Authorization: Basic {{token_secret_encoded}}

{
  "from"  : "{fromnumber}",
  "to"  : "{tonumber}",
  "text"  : "Good morning, this is a test message",
  "callbackUrl" : "http://my.callback.com"
}

 

V1 Create Message POST Request

POST
https://messaging.bandwidth.com/api/v2/users/{{accountId}}/messages
Content-Type: application/json
Authorization: Basic {{token_secret_encoded}}

{
  "to"            : ["+12345678902"],
  "from"          : "+12345678901",
  "text"          : "Hey, check this out!",
  "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",
  "tag"           : "test message"
}
 

 

Key Differentiators

Difference Description
Endpoint updated https://messaging.bandwidth.com/api/v2 is the main URI for v2 messaging
Application ID must be included 93de2206-9669-4e07-948d-329f4b722ee2” applicationId is used to direct callbacks for the message status.
“To” value is an array The “to” value in the message creation request can be set to an array of phone numbers to send to a group. 
Maximum number of participants: 10Not supported with Toll-Free Messaging
Message requests handled asynchronously The API responds with HTTP-202 indicating that the message request has been accepted any further successful or error information is delivered via HTTP callbacks

 

Response Code for Creating Messages

In V1, a successful message creation request will return a 201 Created. In V2, the API returns 202 Accepted.

 

Response Structure for Creating Messages

 

V1 HTTP-201 Created -  Successful Response

HTTP/1.1 201 Created
Location: https://api.catapult.inetwork.com/v1/users/{userId}/messages/{message-id}  

 

V2 HTTP-202 Accepted -  Successful Response

V2 returns the full message data with the response to a successful response

Status: 202 Accepted
Content-Type: application/json

{
  "id"            : "14762070468292kw2fuqty55yp2b2",
  "time"          : "2016-09-14T18:20:16Z",
  "to"            : [ "+12345678902" ],
  "from"          : "+12345678901",
  "text"          : "Hey, check this out!",
  "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",
  "tag"           : "test message",
  "owner"         : "+12345678901",
  "direction"     : "out",
  "segmentCount"  : 1
}

 

Group Messaging

V2 supports group messaging. To send a group message, include the list of group participants phone numbers as the “to” value.

POST https://messaging.bandwidth.com/api/v2/users/{accountId}/messages HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Basic {{token_secret_encoded}}

{
"to"            : [
      "+12345678902",
      "+12345678903"
    ],
    "from"          : "+12345678901",
    "text"          : "Hey, check out this sample group message!",
    "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",
    "tag"           : "Group Message"
}

Bandwidth will send a callback for EACH participant in the group.

 

Rate Limits

If you exceed your rate limit of creating messages in V1, you'll get a 403 Forbidden error.

 

V1 Rate Limit - HTTP 403

Status: 403 Forbidden
Content-Type: application/json
{
  "category": "limit",
  "code": "message-rate-limit",
  "message": "You can send 1 messages per 1 seconds, calculated as the average over 10 seconds. Your rate is: 1.1",
  "details": [
    {
      "name": "requestMethod",
      "value": "POST"
    },
    {
      "name": "remoteAddress",
      "value": "x.x.x.x"
    },
    {
      "name": "requestPath",
      "value": "users/u-asdf/messages"
    }
  ]
}

 

V2 Rate Limit - HTTP 429

Status: 429 Too Many Requests
Content-Type: application/json; charset=utf-8
{
 "Type"       : "max-message-queue-size-exceeded",
 "description": "The SMS queue for your account is full and cannot accept more messages right now. Your allowed rate is 60 messages per minute. The capacity of this queue is 900 messages (15 minutes). Reduce your message sending rate, or contact support to increase your allowed rate."
}

Your Implementation Specialist can provide more details about your rate limits, because these can vary among different customers depending on your contract.

 

How Callbacks Work

In V1, if you do not request a delivery receipt, you'll receive one callback reflecting that the message was created and sent. If you do request a delivery receipt, you'll receive one initial callback where the delivery status is set to “waiting” that indicates that the message was successfully created and sent, followed by a later callback that contains the final delivery receipt.

In V2, you'll receive one callback that contains a final delivery receipt within 24 hours, though most messages get a confirmed final delivery receipt much sooner than that. The callback will either contain an error indicating the message was not successfully created, or contain an error indicating a failed delivery, or will say the message was successfully created and delivered.

V1 delivery errors can be found here.

V2 delivery errors are different and more detailed. You can find the list here.

 

Callback Structure

 

V1 HTTP Callback

Content-Type: application/json

{
"eventType"     : "sms",
"direction"     : "in",
"messageId"     : "{messageId}",
"messageUri"    : "https://api.catapult.inetwork.com/v1/users/{userId}/messages/{messageId}",
"from"          : "+13233326955",
"to"            : "+13865245000",
"text"          : "Example",
"applicationId" : "{appId}",
"time"          : "2012-11-14T16:13:06.076Z",
"state"         : "received",
"segmentCount"  : 1
}

 

Key Differentiators

Difference Description
Callbacks are always arrays Each v2 Messaging callback is sent as an array. As of 2019-08-12 each array will only contain a single message object
Callbacks are more detailed Each v2 Messaging callback contains more information about the message including applicationId & more detailed error codes

 

V2 HTTP Callback

Content-Type: application/json

[
  {
    "type"        : "message-received",
    "time"        : "2016-09-14T18:20:16Z",
    "description" : "Incoming message received",
    "to"          : "+12345678902",
    "message"     : {
      "id"            : "14762070468292kw2fuqty55yp2b2",
      "time"          : "2016-09-14T18:20:16Z",
      "to"            : ["+12345678902"],
      "from"          : "+12345678901",
      "text"          : "Hey, check this out!",
      "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",
      "media"         : [ "https://messaging.bandwidth.com/api/v2/users/{accountId}/media/14762070468292kw2fuqty55yp2b2/0/bw.png"
        ],
      "owner"         : "+12345678902",
      "direction"     : "in",
      "segmentCount"  : 1
    }
  }
]


Incoming group message 

Content-Type: application/json

[
  {
    "type"          : "message-received",
    "time"          : "2016-09-14T18:20:16Z",
    "description"   : "Incoming message received",
    "to"            : "+12345678902",
    "message"       : {
      "id"            : "14762070468292kw2fuqty55yp2b2",
      "time"          : "2016-09-14T18:20:16Z",
      "to"            : [
          "+12345678902",
          "+12345678903"
        ],
      "from"          : "+12345678901",
      "text"          : "Hey, check this out!",
      "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",
      "media"         : [
"https://messaging.bandwidth.com/api/v2/users/{accountId}/media/14762070468292kw2fuqty55yp2b2/0/bw.png"
        ],
      "owner"         : "+12345678902",
      "direction"     : "in",
      "segmentCount"  : 1
    }
  }
]

 

Message successfully delivered

Content-Type: application/json

[
  {
    "type"          : "message-delivered",
    "time"          : "2016-09-14T18:20:16Z",
    "description"   : "Message delivered to carrier",
    "message"       : {
      "id"            : "14762070468292kw2fuqty55yp2b2",
      "time"          : "2016-09-14T18:20:16Z",
      "to"            : [
          "+12345678902",
          "+12345678903"
        ],
      "from"          : "+12345678901",
      "text"          : "Hey, check this out!",
      "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",
      "owner"         : "+12345678902",
      "direction"     : "in",
      "segmentCount"  : 1
    }
  }
]

 

Message failed 

Content-Type: application/json

[
  {
    "type"          : "message-failed",
    "time"          : "2016-09-14T18:20:16Z",
    "description"   : "forbidden to country",
    "to"            : "+52345678903",
    "errorCode"     : 4432,
    "message"       : {
      "id"            : "14762070468292kw2fuqty55yp2b2",
      "time"          : "2016-09-14T18:20:16Z",
      "to"            : [
          "+12345678902",
          "+52345678903"
        ],
      "from"          : "+12345678901",
      "text"          : "Hey, check this out!",
      "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",
      "media"         : [
          "https://s3.amazonaws.com/bw-v2-api/demo.jpg"
        ],
      "owner"         : "+12345678901",
      "direction"     : "out",
      "segmentCount"  : 1
    }
  }
]
 

 

Error Codes

V2 has different message delivery error codes than V1. Please review here.

 

Rules on Media

In V1, the media endpoint is https://api.catapult.inetwork.com/v1/users/{userId}/media and you can upload unlimited files up to 65MB each. Incoming media via MMS is stored for 30 days.

In V2, the media endpoint is https://messaging.bandwidth.com/api/v2/users/{accountId}/media/{mediaName} and you can upload unlimited files up to 3.75MB per file. All media, whether uploaded or from incoming MMS, are stored for 48 hours unless you delete them sooner.

 

SDKs

For V1, there are SDKs in NodeJS, C#, Ruby, Python, Java, and PHP.

V2 currently has SDKs in Ruby and Python. SDKs are coming soon in C# (Beta), Java, Node, and PHP. In addition, some of the V1 SDKs have V2 functionality in them, and the phone number management side of V2 has its own set of SDKs.

For sending messages, the V1 SDKs in NodeJS, C#, and Ruby have V2 functionality.

For phone number management, there are SDKs in NodeJS, C#, Ruby, Python, Java, and PHP.

 

Resources

Click here to view documentation or open a support ticket with our team if you have any additional questions. We're happy to help!

Article is closed for comments.