Skip to main content

Bandwidth International A2P Messaging

Introduction#

Bandwidth's International A2P Messaging API enables customers to send SMS over HTTP/HTTPS and to receive Delivery Reports (DLRs) over via HTTP callbacks (webhooks).

Table of Contents#

Concepts#

Bandwidth's international A2P messaging API relies heavily on HTTP callbacks/webhooks. Final message state (delivered, rejected, undelivered) is only delivered as a HTTP Callback/webhook.


Messages are submitted over HTTPS from customers to Bandwidth's system. When Bandwidth's system has information of what happened with the delivery of the message it will send (also over HTTPS) an event to the customer provided Callback DLR URL.

There are four cases:

  • Delivered message (DELIVERED)
  • Undelivered message (UNDELIVERED)
  • Rejected message (REJECTED)
  • Buffered (temporary undelivered) message (BUFFERED) followed by final DLR event, delivered (DELIVERED), undelivered (UNDELIVERED) or rejected (REJECTED)

When messages cannot be delivered as fast as possible due to temporary problems a buffered DLR event will be sent to Callback DLR URL if the customer has enabled non-final state notifications via the dlrMask. If the customer has not enabled non-final state notifications, when the message has reached a terminal state, a DLR will be sent to the dlrUrl.

Sending SMS Messages#

Bandwidth's International A2P Messaging API is highly customizable allowing you to format the messages based on your unique use-case.

Users can customize:

  • Message Encoding
  • Alphanumeric Sender

Message Encoding#

Bandwidth's International A2P Messaging API allows customers format messages as either GSM or Unicode. Bandwidth split submitted messages into several segments or reject messages because they are too long. Customers are billed for each segment.

GSM Character Set#

Dec0163248648096112
Hex010203040506070
00@ΔSP0¡Pp
11£_!1AQaq
22$Φ2BRbr
33¥Γ#3CScs
44èΛ¤4DTdt
55éΩ%5EUeu
66ùΠ&6FVfv
77ìΨ7GWgw
88òΣ(8HXhx
99ÇΘ)9IYiy
10ALFΞ*:JZjz
11BØ<ESC>+;KÄkä
12CøÆ,<LÖlö
13DCRæ-=MÑmñ
14EÅ.>NÜnü
15FåÉ/?O§oà

Supported Characters in Alphanumeric Sender#

Standard letters and digits:

  • 0123456789
  • abcdefghijklmnopqrstuvwxyz
  • ABCDEFGHIJKLMNOPQRSTUVWXYZ
Special Characters
SupportedNot Supported
CharacterASCII CodeCharacterASCII Code
SPACE0x20$0x24
!0x21@0x40
0x22[0x5B
#0x23\0x5C
%0x25]0x5D
&0x26^0x5E
0x27_0x5F
(0x28`0x60
)0x29{0x7B
*0x2A|0x7C
+0x2B}0x7D
,0x2C~0x7E
-0x2D
.0x2E
/0x2F
:0x3A
;0x3B
<0x3C
=0x3D
>0x3E
?0x3F

Create Message API#

Request URL#

POST https://bulksms.ia2p.bandwidth.com:12021/bulk/sendsms

Supported Parameters#

ParameterMandatoryDescription
typeYesThe type of message to send.
For the Bandwidth API, the only valid type is "text"
authYesAuthorization credentials for the Bandwidth International A2P Messaging API.
Please contact support to learn how to find these credentials to get started.
senderYesThe alphanumeric value to appear as the outbound message sender. See the Supported Characters table above to learn more.
- Maximum Length when using Alphanumeric sender is 11 Characters.
- Maximum Length when using Numeric sender is 16 Digits.
receiverYesThe desired destination phone number of the end user
dcsYesSpecifies the encoding to use for the outbound message. See the Message Encoding information to learn more.
Valid values are:
-"GSM" for GSM encoding
-"UCS" for Unicode UTF-8 encoding
textYesThe text content to be sent to the receiver
dlrMaskYesSpecifies which DLR values to send to the dlrUrl.

ℹ️ Bandwidth recommends setting the code to 19 to receive all of DELIVERED, UNDELIVERED, REJECTED events.
See the dlrMask table for more information.
dlrUrlYesThe publicly addressable callback URL to send DLR information about the outbound message

dlrMask values#

Delivery events that Bandwidth's International A2P Messaging API sends are listed below. Statuses marked with 'final status' are final delivery reports - no further delivery reports will be sent for message.

ValueCallbacks ReceivedMessage stateDescription
1DELIVEREDFinalDelivered to phone
2UNDELIVEREDFinalNon-Delivered to Phone
4BUFFEREDTemporaryQueued on SMSC
Queued on SMSC usually means that there was some problem delivering message to the mobile phone, and further DLRs will follow.
Queued on SMSC means that Bandwidth's system sent message to destination network .
8SENT_TO_SMSCTemporaryDelivered to SMSC,
16REJECTEDFinalNon-Delivered to SMSC

ℹ️ DLR Mask set for each sent message can be combination of these values. For example, 1+2+16=19 means that all the final statuses will be reported (DELIVERED, UNDELIVERED, REJECTED).

ValueCallbacks Received
3DELIVERED & UNDELIVERED
19RECOMMENDED DELIVERED, UNDELIVERED, & REJECTED
31All statuses

Example 1 of 4: Text messages in GSM Encoding#

POST https://bulksms.ia2p.bandwidth.com:12021/bulk/sendsms HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"type" : "text",
"auth" : {
"username" : "testuser",
"password" : "testpassword"
},
"sender" : "BulkTest",
"receiver" : "4179123456",
"dcs" : "GSM",
"text" : "This is test message",
"dlrMask" : 19,
"dlrUrl" : "http://my-server.com/dlrjson.php"
}

Responds

Status: 202 Accepted
Content-Type: application/json; charset=utf-8
{
"msgId" : "9325d0a8-2638-11e6-afe7-bffc7cc8fa4f",
"numParts" : 1
}

Example 2 of 4: Text messages in Unicode Encoding#

POST https://bulksms.ia2p.bandwidth.com:12021/bulk/sendsms HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"type" : "text",
"auth" : {
"username" : "testuser",
"password" : "testpassword"
},
"sender" : "BulkTest",
"receiver" : "4179123456",
"dcs" : "UCS",
"text" : "This is test message with some UTF-8 characters üöä€ ",
"dlrMask" : 19,
"dlrUrl" : "http://my-server.com/dlrjson.php"
}

Responds

Status: 202 Accepted
Content-Type: application/json; charset=utf-8
{
"msgId" : "9325d0a8-2638-11e6-afe7-bffc7cc8fa4f",
"numParts" : 2
}

Example 3 of 4: Text messages in GSM Encoding with invalid sender#

POST https://bulksms.ia2p.bandwidth.com:12021/bulk/sendsms HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"type" : "text",
"auth" : {
"username" : "testuser",
"password" : "testpassword"
},
"sender" : "😀",
"receiver" : "4179123456",
"dcs" : "GSM",
"text" : "This is test message",
"dlrMask" : 19,
"dlrUrl" : "http://my-server.com/dlrjson.php"
}

Responds

Status: 420 Method Failure
Content-Type: application/json; charset=utf-8
{
"error": {
"code" : "107",
"message" : "Invalid sender"
}
}

Example 4 of 4: Text messages in GSM Encoding Rate Limited#

POST https://bulksms.ia2p.bandwidth.com:12021/bulk/sendsms HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"type" : "text",
"auth" : {
"username" : "testuser",
"password" : "testpassword"
},
"sender" : "BulkTest",
"receiver" : "4179123456",
"dcs" : "GSM",
"text" : "This is test message",
"dlrMask" : 19,
"dlrUrl" : "http://my-server.com/dlrjson.php"
}

Responds

Status: 420 Method Failure
Content-Type: application/json; charset=utf-8
{
"error": {
"code" : "105",
"message" : "Too many messages submitted withing short period of time. Resend later."
}
}

HTTP Responses (Success & Errors)#

Success Response Parameters#

Bandwidth's International A2P Messaging API will respond with an HTTP 202: Accepted when a message is accepted via the API. Final status will be delivered via HTTP Callback/webhooks.

ParameterDescriptionExample
msgIdThe internal message ID"9325d0a8-2638-11e6-afe7-bffc7cc8fa4f"
numPartsNumber of segments for the message. (Note: Customers are billed for each segment.)2

Error Response Parameters#

Bandwidth's International A2P Messaging API will respond with an HTTP 420: Method Failure when a message is failed via the API.

ParameterDescriptionExample
error.codeThe error code indicating why the message could not be created. See the Error Codes table to learn more."107"
error.messageThe human readable detailed message about the error."Invalid sender"
Rate Limits#

In the case that a submission failed with RC_THROTTLING_ERROR, the customer should wait one second and then retry submission.

Internal server error#

In the case that a submission failed with HTTP status code HTTP 500, INTERNAL_SERVER_ERROR, the customer should wait at least one minute and then retry submission.

HTTP Error Codes#
Error codeValueDescription
RC_APPLICATION_ERROR101Internal application error
RC_ENCODING_ERROR102Encoding not supported or message not encoded with given encoding
RC_NO_ACCOUNT103No account with given username/password
RC_IP_NOT_ALLOWED104Sending from clients IP address not allowed
RC_THROTTLING_ERROR105Too many messages submitted withing short period of time. Resend later.
RC_BLACKLISTED_SENDER106Sender contains words blacklisted on destination
RC_INVALID_SENDER107Sender contains illegal characters
RC_MESSAGE_TOO_LONG108Message (not split automatically by Bandwidth system, but by customer) is too long.
RC_BAD_CONTENT_FORMAT109Format of text/content parameter is wrong.
RC_MISSING_MANDATORY_PARAMETER110Mandatory parameter is missing
RC_UNKNOWN_MESSAGE_TYPE111Unknown message type
RC_BAD_PARAMETER_VALUE112Format of some parameter is wrong.
RC_NO_CREDIT113No credit on account balance
RC_NO_ROUTE114No route for given destination
RC_CONCAT_ERROR115Message cannot be split into concatenated messages (e.g. too many parts will be needed)

DLRs via HTTP Callbacks (webhooks)#

Delivered messages#

When a customer submits SMS to Bandwidth's International A2P Messaging API messages will be delivered to mobile phones as fast as possible. When Bandwidth's system receives confirmation that a message is delivered it will send a DLR Event 1 to the callback DLR URL.

Delivered

Undelivered messages#

This case is similar to “Delivered message”, but describes failure in delivery. Callback DLR URL will be invoked with DLR event 2 and reason. No further attempt of delivery will be made. Messages are undelivered in cases when:

  • Destination number does not represent existing mobile phone
  • There is no route to required destination
  • If Bandwidth's system was not able to deliver messages to phone during validity period (which is by default 24 hours).
  • In case of some other permanent error that makes delivery to mobile phone impossible

Undelivered

Rejected messages#

Messages can be rejected by Bandwidth's system in several cases:

  • When username/password submitted with request do not match the one configured for account
  • When account is disabled
  • When there is no money on account balance
  • When destination is not allowed for customer
  • When sender field contains not allowed characters
  • When parameter format is not correct
  • When contents of some parameters (for example parameter text for text message submission) contains characters not supported with selected DCS.
  • Rejection can happen immediately on submission, in which case an error will be returned to the customer with the HTTP/HTTP response on submission request or it can happen later, in which case callback DLR URL will be invoked with DLR event rejected.

Rejected

Buffered (temporary undelivered) messages#

If Bandwidth's system cannot deliver a message at first attempt, and the DLR mask allows sending of buffered messages to the customer, DLR will be sent to the customer for each attempt with reason of temporary failed delivery.

Reasons for temporary failures can be:

  • Absent subscriber (subscriber is not within reach of destination network or his phone is offline)
  • Mobile phone buffer for SMS is full
  • Any other temporary failures of mobile device or destination mobile network when there is a chance to be resolved within message validity period

Bandwidth's system will stop trying to deliver message in following situations:

  • Message is successfully delivered, in which case DLR event delivered is sent
  • Permanent error happened which makes delivery impossible (e.g. destination number do not exist). DLR event undelivered is sent.
  • Message validity period expired - Bandwidth's system was not able to deliver the message within 24 hours. DLR event undelivered is sent.

Buffered

DLR Format & Parameters#

ParameterDescription
msgIdThe internal message ID
eventThe event of the the callback
One of: "DELIVERED", "UNDELIVERED", "REJECTED", "BUFFERED", "SENT_TO_SMSC"
errorCodeThe error code of the DLR if it exists
errorMessageThe message of the DLR error code if it exists
partNumNumber of the segment delivered Range [0..numParts-1]
numPartsTotal number of message segments
accountNameName of the account from which the message was sent

Example 1 of 4: DELIVERED DLR#

POST /your_url HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"msgId" : "9325d0a8-2638-11e6-afe7-bffc7cc8fa4f",
"event" : "DELIVERED",
"errorCode" : 0,
"errorMessage" : "if exists",
"partNum" : 1,
"numParts" : 2,
"accountName" : "testuser"
}

Example 2 of 4: UNDELIVERED DLR#

POST /your_url HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"msgId" : "9325d0a8-2638-11e6-afe7-bffc7cc8fa4f",
"event" : "UNDELIVERED",
"errorCode" : 995,
"errorMessage" : "Undeliverable",
"partNum" : 1,
"numParts" : 1,
"accountName" : "testuser"
}

Example 3 of 4: REJECTED DLR#

POST /your_url HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"msgId" : "9325d0a8-2638-11e6-afe7-bffc7cc8fa4f",
"event" : "REJECTED",
"errorCode" : 991,
"errorMessage" : "Rejected by message text filter",
"partNum" : 1,
"numParts" : 1,
"accountName" : "testuser"
}

Example 4 of 4: BUFFERED DLR#

POST /your_url HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"msgId" : "9325d0a8-2638-11e6-afe7-bffc7cc8fa4f",
"event" : "BUFFERED",
"partNum" : 1,
"numParts" : 2,
"accountName" : "testuser"
}

DLR Error Codes#

In the case of a REJECTED or UNDELIVERED event, Bandwidth will provide an error code and message information indicating the reason the message was not delivered.

Value (dec)Description
0No error
1Unknown subscriber
9Illegal subscriber
11Teleservice not provisioned
13Call barred
15CUG reject
19No SMS support in MS
20Error in MS
21Facility not supported
22Memory capacity exceeded
29Absent subscriber
30MS busy for MT SMS
36Network/Protocol failure
44Illegal equipment
60No paging response
61GMSC congestion
63HLR timeout
64MSC/SGSN_timeout
70SMRSE/TCP error
72MT congestion
75GPRS suspended
80No paging response via MSC
81IMSI detached
82Roaming restriction
83Deregistered in HLR for GSM
84Purged for GSM
85No paging response via SGSN
86GPRS detached
87Deregistered in HLR for GPRS
88The MS purged for GPRS
89Unidentified subscriber via MSC
90Unidentified subscriber via SGSN
112Originator missing credit on prepaid account
113Destination missing credit on prepaid account
114Error in prepaid system
500Other error
988MNP Error
989Supplier rejected SMS
990HLR failure
991Rejected by message text filter
992Ported numbers not supported on destination
993Blacklisted sender
994No credit
995Undeliverable
996Validity expired
997Blacklisted receiver
998No route
999Repeated submission (possible looping)