Bandwidth Messaging API
|Messaging API Overview||Learn how to format and send messages|
|Message Events/Callbacks||Learn about the different HTTP Callbacks Bandwidth will send to the URL configured in your application|
|Message Error Codes||Learn about the different error codes associated with a message failure event|
Messaging Media Overview
|Messaging Media API Overview||Learn how to upload, retrieve, delete and list media|
There are a few concepts that are important to understand how Bandwidth's new messaging API functions:
- Message Storage
- Message Callbacks
- Message Creation
- Segment Counts
- MMS and Group Message Delivery Receipts
- Group Message Invalid Number Behavior
Message Storage IE
Bandwidth Messaging does not keep any records to fetch later. If you need to keep track of delivered, error-ed, received messages after you receive the corresponding callback event, you MUST store the events in the data-store of your choice.
Once we have successfully delivered the callback event and receive an
HTTP 2xx response, Bandwidth can no longer provide any detail about that message.
As the messaging API does not offer message storage or detailed messaging records, Bandwidth will attempt to deliver every callback until your server replies with a
HTTP 2xx status code. If the callback request times out, or your server returns a code less than
HTTP 2xx or greater than
HTTP 3xx Bandwidth will try to deliver the callback multiple times over the next 24 hours.
After 24 hours, if your server has not returned a
HTTP 2xx code, Bandwidth will no longer try to send the callback.
Message Creation/Acceptance (
HTTP 201 vs
The messaging 2.0 API works off of an internal queuing system. As such, when you
POST to the
v2/.../messages to create a new message, Bandwidth will reply with an
HTTP 202 - Accepted. This indicates that the message has been placed on the queue
As the message progresses through the internal system you will receive a a Message Delivered callback when the message has been handed off to the downstream carrier.
If at any-point through the process the message fails, you will receive a detailed Message Failed callback with an error code describing the reason for failure.
Message Segment Counts
This indicates the number of segments the original message from the user is broken into before sending over to carrier networks. Segmentation of messages depends on the size and encoding. Bandwidth will segment the message if the character count is over the below limits:
- 160 for GSM-7
- 70 for UCS-2
- For MMS messages the segment count will always be set to 1.
segmentCount is returned in the callback events and the response when creating the message.
MMS and Group Message Delivery Receipts
MMS and Group messages don’t currently support delivery receipts. However, you will still receive a message delivered event when the message is sent. For only MMS and Group Messages this means that your message has been handed off to the Bandwidth core network, but has not been confirmed at the downstream carrier. We are actively working to support true delivery receipts for the v2 Messaging API.
Invalid Phone Numbers and Group Messaging Behavior
You will receive the
message-failed event for the invalid number, but then you get the
message-delivered event for each of the
to numbers including the ones for which you already got
message-failed with the
invalid-to-number] code. So you would get both a failed and a success callback for the invalid ones, and just the success one for the success ones.
You will exactly one callback per
to number. The ones that are invalid are
message-failed with an error code that means
invalid-to-number, and the ones that are valid will receive the