SMS OUT¶

Introduction¶

DIDWW Outbound SMS trunk allows you to send messages from your DID(s) to mobile phones around the globe using DIDWW Outbound SMS.

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.

Getting started¶

Purchasing SMS Enabled DIDs¶

Service Purchase

Outbound SMS Trunk creation and configuration¶

SMS Via HTTP¶

Outbound SMS Trunk Creation and Configuration

SMS Via SMPP¶

ESME Trunk

SMSC Trunk

SMS via HTTP¶

This document assumes that you are familiar with web programming concepts, web data formats and with JSON specification. Any additional information about JSON is available on their official website.

Endpoints¶

DIDWW SMS routing system is distributed so you can choose nearest servers for your requests:

HTTP
https://sms-out.didww.com/outbound_messages
https://us.sms-out.didww.com/outbound_messages
https://nyc.us.sms-out.didww.com/outbound_messages
https://mia.us.sms-out.didww.com/outbound_messages
https://lac.us.sms-out.didww.com/outbound_messages
https://eu.sms-out.didww.com/outbound_messages
https://sg.sms-out.didww.com/outbound_messages

Headers¶

Clients MUST send all JSON API data in request documents 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 an username and password provided as part of 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 to API based on their IP address. After you whitelist an IP address, you can only access the API if you are connecting from a whitelisted IP address. Any access attempts from other IPs will be blocked. This is a security tool that you can use to help prevent malicious activity on your account.

Simple example¶

Most client software provides a simple mechanism for supplying a username and password that 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 content Basic followed by the encoded string. For example, the string john:doe encodes to am9objpkb2U= 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

Sending SMS message¶

DIDWW Outbound SMS API helps you send SMS messages.

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

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)

Please note that in case if Country Code or Area Code could not be processed because of it’s absence in your price list, callback with code_id 2 would be sent. Details on Callback error codes

source required

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 list configured in Outbound SMS Trunk accepted, otherwise callback with code_id 8 would be sent. Details on Callback error codes

content required

data type: string

this parameter includes full text of the message that you will send. Single message is 160 characters in length. support encoding is UTF8

There is example how to send SMS using cURL:

curl \
   -X POST \
   -u username:password \
   -H "Content-Type: application/vnd.api+json" \
   -d '{
       "data": {
       "type": "outbound_messages",
       "attributes": {
           "destination": "37041654321",
           "source": "37041123456",
           "content": "Hello World!"
           }
       }
   }' \
   https://sms-out.didww.com/outbound_messages

Response format¶

Our system will return HTTP 201 Created in case of successful accepting SMS with such payload:

{
    "data": {
        "type": "outbound_messages",
        "id": "550e8400-e29b-41d4-a716-446655440000"
    }
}

We handle request asynchronously, so using this identifier SMS status can be tracked using Status Callbacks or using SMS log page at our userpanel URL

Handling Exceptions¶

401 Unauthorized¶

Provided not correct Authorization header or request sent from not allowed IP address. Refer to Authentication

{
    "errors": [
        {
            "title": "Unauthorized",
            "detail": "Authorization failed",
            "code": "401",
            "status": "401"
        }
    ]
}

400 Bad Request¶

Request data has not correct structure. Refer to JSON API specification.

{
    "errors": [
        {
            "title": "Bad Request",
            "detail": "Invalid request",
            "code": "400",
            "status": "400"
        }
    ]
}

Status Callbacks¶

You can receive events related your message processing status using Callback mechanism. See Callback URL configuration of your Outbound SMS trunk.

Callback request¶

We are using HTTP POST method to send notification payload:

{
    "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 splitted.

code_id

data type: integer

Error code ID. List of available values at Callback error codes

Callback error codes¶

null: Message was sent successfully
1: No routes found
2: No rate found
3: No routes found
4: Internal error
5: Origination gateway is blocked
6: Internal error
7: Origination account is blocked
8: SMS source address is not allowed
100: No balance available during TTL
101: All termination attempts failed during TTL

SMS via SMPP¶

SMPP protocol is used for communication between SMSC (Short Message Service Centre) and ESME (Extended Short Message Entity). When creating a trunk customer can choose either of them ESME or SMSC indicating in which way both systems will communicate to each other.

Mandatory Bind Parameters¶

Name	Description
system_id	Provided via DIDWW user-panel.
password	Provided via DIDWW user-panel.
system_type	Defined while creating SMPP trunk.
host	us.sms-out.didww.com (46.19.209.14).
port	· ESME trunk types 34846. · SMSC port could be defined via user-panel.

Encoding¶

Default encoding (data_coding) used, also called DCS (Data Coding Scheme) for short messages is GSM-7 (DCS = 0). 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).

Binary SMS¶

Binary-encoded SMS messages can contain a high data content and are therefore used to send more complex data, such as rich-content messages. They can contain a maximum of 140 bytes per SMS.

DIDWW SMPP protocol supports binary-encoded messages, however, it is not enabled by default. To enable it, please contact our Technical Support team at support@didww.com

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