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

• International A2P Concepts
• Sending SMS messages
  • Create Message API
  • HTTP Responses (Success & Errors)
• Delivery Receipts (DLR) via HTTP Callbacks (webhooks)
  • DLR Format & Parameters
  • DLR Error Codes

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

Dec		0	16	32	48	64	80	96	112
	Hex	0	10	20	30	40	50	60	70
0	0	@	Δ	SP	0	¡	P		p
1	1	£	_	!	1	A	Q	a	q
2	2	$	Φ	“	2	B	R	b	r
3	3	¥	Γ	#	3	C	S	c	s
4	4	è	Λ	¤	4	D	T	d	t
5	5	é	Ω	%	5	E	U	e	u
6	6	ù	Π	&	6	F	V	f	v
7	7	ì	Ψ	‘	7	G	W	g	w
8	8	ò	Σ	(	8	H	X	h	x
9	9	Ç	Θ	)	9	I	Y	i	y
10	A	LF	Ξ	*	:	J	Z	j	z
11	B	Ø	<ESC>	+	;	K	Ä	k	ä
12	C	ø	Æ	,	<	L	Ö	l	ö
13	D	CR	æ	-	=	M	Ñ	m	ñ
14	E	Å		.	>	N	Ü	n	ü
15	F	å	É	/	?	O	§	o	à

Supported Characters in Alphanumeric Sender

Standard letters and digits:

• 0123456789
• abcdefghijklmnopqrstuvwxyz
• ABCDEFGHIJKLMNOPQRSTUVWXYZ

Special Characters
Supported		Not Supported
Character	ASCII Code	Character	ASCII Code
SPACE	0x20	$	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

POSThttps://bulksms.ia2p.bandwidth.com:12021/bulk/sendsms

Supported Parameters

Parameter	Mandatory	Description
type	Yes	The type of message to send. For the Bandwidth API, the only valid type is "text"
auth	Yes	Authorization credentials for the Bandwidth International A2P Messaging API. Please contact support to learn how to find these credentials to get started.
sender	Yes	The 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.
receiver	Yes	The desired destination phone number of the end user
dcs	Yes	Specifies 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
text	Yes	The text content to be sent to the receiver
dlrMask	Yes	Specifies 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.
dlrUrl	Yes	The 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.

Value	Callbacks Received	Message state	Description
1	DELIVERED	Final	Delivered to phone
2	UNDELIVERED	Final	Non-Delivered to Phone
4	BUFFERED	Temporary	Queued 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 .
8	SENT_TO_SMSC	Temporary	Delivered to SMSC,
16	REJECTED	Final	Non-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).

Value	Callbacks Received
3	DELIVERED & UNDELIVERED
19	RECOMMENDED DELIVERED, UNDELIVERED, & REJECTED
31	All 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.

Parameter	Description	Example
msgId	The internal message ID	"9325d0a8-2638-11e6-afe7-bffc7cc8fa4f"
numParts	Number 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.

Parameter	Description	Example
error.code	The error code indicating why the message could not be created. See the Error Codes table to learn more.	"107"
error.message	The 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 code	Value	Description
RC_APPLICATION_ERROR	101	Internal application error
RC_ENCODING_ERROR	102	Encoding not supported or message not encoded with given encoding
RC_NO_ACCOUNT	103	No account with given username/password
RC_IP_NOT_ALLOWED	104	Sending from clients IP address not allowed
RC_THROTTLING_ERROR	105	Too many messages submitted withing short period of time. Resend later.
RC_BLACKLISTED_SENDER	106	Sender contains words blacklisted on destination
RC_INVALID_SENDER	107	Sender contains illegal characters
RC_MESSAGE_TOO_LONG	108	Message (not split automatically by Bandwidth system, but by customer) is too long.
RC_BAD_CONTENT_FORMAT	109	Format of text/content parameter is wrong.
RC_MISSING_MANDATORY_PARAMETER	110	Mandatory parameter is missing
RC_UNKNOWN_MESSAGE_TYPE	111	Unknown message type
RC_BAD_PARAMETER_VALUE	112	Format of some parameter is wrong.
RC_NO_CREDIT	113	No credit on account balance
RC_NO_ROUTE	114	No route for given destination
RC_CONCAT_ERROR	115	Message 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.

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

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.

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.

DLR Format & Parameters

Parameter	Description
msgId	The internal message ID
event	The event of the the callback One of: "DELIVERED", "UNDELIVERED", "REJECTED", "BUFFERED", "SENT_TO_SMSC"
errorCode	The error code of the DLR if it exists
errorMessage	The message of the DLR error code if it exists
partNum	Number of the segment delivered Range [0..numParts-1]
numParts	Total number of message segments
accountName	Name 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
0	No error
1	Unknown subscriber
9	Illegal subscriber
11	Teleservice not provisioned
13	Call barred
15	CUG reject
19	No SMS support in MS
20	Error in MS
21	Facility not supported
22	Memory capacity exceeded
29	Absent subscriber
30	MS busy for MT SMS
36	Network/Protocol failure
44	Illegal equipment
60	No paging response
61	GMSC congestion
63	HLR timeout
64	MSC/SGSN_timeout
70	SMRSE/TCP error
72	MT congestion
75	GPRS suspended
80	No paging response via MSC
81	IMSI detached
82	Roaming restriction
83	Deregistered in HLR for GSM
84	Purged for GSM
85	No paging response via SGSN
86	GPRS detached
87	Deregistered in HLR for GPRS
88	The MS purged for GPRS
89	Unidentified subscriber via MSC
90	Unidentified subscriber via SGSN
112	Originator missing credit on prepaid account
113	Destination missing credit on prepaid account
114	Error in prepaid system
500	Other error
988	MNP Error
989	Supplier rejected SMS
990	HLR failure
991	Rejected by message text filter
992	Ported numbers not supported on destination
993	Blacklisted sender
994	No credit
995	Undeliverable
996	Validity expired
997	Blacklisted receiver
998	No route
999	Repeated submission (possible looping)