SMS OUT
Introduction
DIDWW offers Person-to-Person (P2P) and Application-to-Person (A2P) type messaging for SMS supported countries. P2P is generally described as the exchange of text messages between end-users, usually characterised as low-volume and two-way communications. Where as A2P allows businesses to send high volume of automated SMS to a group of people.
The DIDWW Outbound SMS API is a fully compliant implementation of the JSON API specification.
The DIDWW Outbound SMPP SMS is a fully compliant implementation of SMPP specifications.
HTTP SMS Specification
This document assumes that you are familiar with web programming concepts, web data formats and with JSON:API specification. Any additional information about JSON:API is available on their official website.
Headers
All JSON API data MUST be sent with the header Content-Type: application/vnd.api+json
without any media type parameters.
Authentication
This section shows you how to allow REST clients to authenticate themselves using basic authentication with a username
and password
provided as part of the Outgoing Trunk credentials.
Basic authentication
Basic authentication is defined in RFC 2617, HTTP Authentication: Basic and Digest Access Authentication.
Whitelisting an IP address
Whitelisting an IP Address is a security feature that allows you to control who can access the API based on their IP address. After whitelisting an IP address, you can only access the API if you are connecting from a whitelisted IP address. Any access attempts from non-authorised IPs will be blocked. This security tool can help you prevent malicious activity on your account.
Simple example
Most client software provides a simple mechanism for supplying a username and password which it then uses to build the required authentication headers automatically. For example, you can specify the -u
argument with cURL as follows:
curl \
-u username:password \
-X POST \
-H "Content-Type: application/vnd.api+json" \
https://sms-out.didww.com/outbound_messages
Supplying basic auth headers
If you need to, you may construct and send basic auth headers yourself. To do this you need to perform the following steps:
Outbound SMS trunk credentials. Details at Outbound SMS Trunk Creation and Configuration
Build a string of the form
username:password
.BASE64 encode the string.
Supply an
Authorization
header with contentBasic
followed by the encoded string. For example, the stringjohn:doe
encodes toam9objpkb2U=
in base64, so you would make the request as follows:
curl \
-X POST \
-H "Authorization: Basic am9objpkb2U=" \
-H "Content-Type: application/vnd.api+json" \
https://sms-out.didww.com/outbound_messages
Handling exceptions
400 Bad Request
Request data has incorrect structure. Refer to JSON API specification.
{
"errors": [
{
"title": "Bad Request",
"detail": "Invalid request",
"code": "400",
"status": "400"
}
]
}
Request Format
Post request payload:
{
"data": {
"type": "outbound_messages",
"attributes": {
"destination": "37041654321",
"source": "37041123456",
"content": "Hello World!"
}
}
}
Outbound message attributes
- destination
required
data type:string
orArray<string>
if used withbulk_outbound_messages
type.Destination number that SMS message is being sent to. Format this number in E.164 format (Country Code + Area Code + Subscriber’s Number, e.g. 123456789). The destinations are limited to a maximum of 1000 numbers in array.Please note that in case Country Code or Area Code cannot be processed because of its absence in your price list, callback withcode_id
2 will be sent. Details on Callback status codes- source
optional
data type:string
Source number that message is being sent from. This is your DID number. Format this number in E.164 format (Country Code + Area Code + Subscriber’s Number e.g. 123456789)Please note that only numbers from the list configured in Outbound SMS Trunk are accepted, otherwise callback withcode_id
8 will be sent. Details on Callback status codes- content
required
data type:string
this parameter includes full text of the message that you will send. A single message is 160 characters in length. support encoding is UTF8- campaign_id
optional
data type:string
this parameters includes the campaign ID of the registered A2P campaign.
Status Callbacks
You can receive events related to your message processing status using the Callback mechanism. See Callback URL configuration of your Outbound SMS trunk.
Callback request
Notification payload is sent by using HTTP POST method:
{
"data": {
"type": "outbound_message_callbacks",
"id": "550e8400-e29b-41d4-a716-446655440000",
"attributes": {
"time_start": "1997-07-16T19:20:30.45Z",
"end_time": "2001-07-16T19:20:30.45Z",
"destination": "37041654321",
"source": "37041123456",
"status": "Success",
"code_id": null,
"fragments_sent": 7
}
}
}
Outbound message callback attributes
- time_start
data type:string
Time message was accepted for routing. Formatted in ISO 8601- time_end
data type:string
Time message was sent or time processing finished. Formatted in ISO 8601- source
data type:string
Source number that message is being sent from.- destination
data type:string
Destination number that message is being sent to.- status
data type:string
Current message processing status. Available values: Success, Routing Error, Failed- fragments_sent
data type:integer
Quantity of fragments your message content was split to.- code_id
data type:integer
Error code ID. List of available values at Callback error codes
Callback error codes
Error code |
Error meaning |
---|---|
null |
Message was sent successfully |
1 |
No routes found |
2 |
No rate found |
3 |
No routes found |
4 |
Internal Error |
5 |
SMS trunk is blocked |
6 |
Internal error |
7 |
Origination account is blocked |
8 |
SMS source address is not allowed |
9 |
SMS destination address is not allowed |
10 |
SMS Campaign not found |
11 |
SMS Campaign blocked |
100 |
No balance available during TTL |
101 |
All termination attempts failed during TTL |
102 |
No encoding available |
103 |
Max balance attempts reached |
104 |
Message defragmentation failed |
105 |
Routing failed |
Single SMS example
Single SMS should be sent to the following endpoints of your choice:
Main endpoint: https://sms-out.didww.com/outbound_messages
Note
When campaign_id attribute is present but source attribute is absent, the sender ID value will be assigned randomly from registered campaign.
When source attribute is present with sender ID value from the registered campaign, campaign_id attribute is not required.
http
POST /outbound_messages HTTP/1.1
Host: sms-out.didww.com
Content-Type: application/vnd.api+json
Authorization: Basic
{
"data": {
"type": "outbound_messages",
"attributes": {
"destination": "37041654321",
"source": "37041123456",
"content": "Hello World!"
}
}
}
curl
curl -i -X POST https://sms-out.didww.com/outbound_messages -H "Content-Type: application/vnd.api+json" -H "Authorization: Basic" --data-raw '{"data": {"attributes": {"content": "Hello World!", "destination": "37041654321", "source": "37041123456"}, "type": "outbound_messages"}}'
response
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"type": "outbound_messages",
"id": "550e8400-e29b-41d4-a716-446655440000"
}
}
http
POST /outbound_messages HTTP/1.1
Host: sms-out.didww.com
Content-Type: application/vnd.api+json
Authorization: Basic
{
"data": {
"type": "outbound_messages",
"attributes": {
"destination": "37041654321",
"content": "Hello World!",
"campaign_id": "1111aaa-1a1a-a1a1-aaaa-11aaaaa1111"
}
}
}
curl
curl -i -X POST https://sms-out.didww.com/outbound_messages -H "Content-Type: application/vnd.api+json" -H "Authorization: Basic" --data-raw '{"data": {"attributes": {"campaign_id": "1111aaa-1a1a-a1a1-aaaa-11aaaaa1111", "content": "Hello World!", "destination": "37041654321"}, "type": "outbound_messages"}}'
response
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"type": "outbound_messages",
"id": "550e8400-e29b-41d4-a716-446655440000"
}
}
Single SMS Callback example
If the user has setup callbacks on his desired endpoint, the following attributes will be visible.

fig. 1. Single SMS callback
Bulk SMS example
Bulk SMS should be sent to the following endpoints of your choice:
Main endpoint: https://sms-out.didww.com/bulk_outbound_messages
http
POST /bulk_outbound_messages HTTP/1.1
Host: sms-out.didww.com
Content-Type: application/vnd.api+json
Authorization: Basic
{
"data": {
"type": "bulk_outbound_messages",
"attributes": {
"destination": ["37041654321", "37041654322"],
"source": "37041123456",
"content": "Hello World!"
}
}
}
curl
curl -i -X POST https://sms-out.didww.com/bulk_outbound_messages -H "Content-Type: application/vnd.api+json" -H "Authorization: Basic" --data-raw '{"data": {"attributes": {"content": "Hello World!", "destination": ["37041654321", "37041654322"], "source": "37041123456"}, "type": "bulk_outbound_messages"}}'
response
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data":{
"type":"bulk_outbound_messages",
"id":"2C4807D1-74E4-4639-BBC4-057402F052FF",
"relationships":{
"outbound_messages":{
"data":[
{
"type":"outbound_messages",
"id":"E34C1810-434B-4E64-AFD9-EC0568F324A9"
},
{
"type":"outbound_messages",
"id":"B6A48E34-3219-407D-99E6-770CF524F611"
}
]
}
}
}
}
Note
When sending bulk SMS, the “destination” attribute must be an Array.
Bulk SMS Callback example
When sending bulk SMS, you will receive callbacks for every single destination number with a unique ID.

fig. 2. Bulk SMS callback
SMS OUT via SMPP
SMPP protocol is used for communication between SMSC (Short Message Service Centre) and ESME (Extended Short Message Entity). When creating a trunk you can choose either ESME or SMSC indicating how both systems will communicate with each other.
Note
For A2P messaging, the sender ID value must be from a registered campaign.
Mandatory bind parameters
Name |
Description |
---|---|
system_id |
Provided via DIDWW user-panel |
password |
Provided via DIDWW user-panel |
system_type |
Defined when creating SMPP trunk |
host |
us.sms-out.didww.com (46.19.209.214) |
port |
ESME trunk types 2775 SMSC port can be defined via user-panel |
Encoding
The default used encoding (data_coding) for short messages is GSM-7 (DCS = 0), also known as DCS (Data Coding Scheme) . All DIDWW SMPP server supported DCS options include:
DCS value |
Encoding |
Max characters per SMS |
---|---|---|
0 |
Default value. With the SMPP Server this is GSM-7. |
160 |
1 |
US-ASCII. |
160 |
3 |
Latin1 (ISO-8859-1). |
160 |
8 |
Unicode / UCS-2 (ISO/IEC-10646). |
70 |
SMS length depends on the type of data_coding
used. If you use standard GSM-7 or ASCII characters, an SMS has a limit of 160 characters. Unicode (UCS-2) 16-bit encoding supports a great range of characters and languages, but the message length is reduced to 70 characters.
Concatenated messages
Every additional character after the first 160 characters (or 70 unicode characters) is referred to as a concatenated message part.
The maximum number of concatenated message parts supported by DIDWW in a single text message is 255 parts.
The maximum length per concatenated message part is slightly reduced due to the inclusion of concatenation headers:
153 characters for 7-bit encoding (e.g. Latin-1/9 and GSM-7).
67 characters for 16-bit encoding (Unicode).
Endpoints
SMPP |
---|
sms-out.didww.com |
us.sms-out.didww.com |
nyc.us.sms-out.didww.com |
mia.us.sms-out.didww.com |
lac.us.sms-out.didww.com |
eu.sms-out.didww.com |
sg.sms-out.didww.com |