SMS OUT

Introduction

DIDWW offers Person-to-Person (P2P) 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. https://www.didww.com/coverage/.

The only exception is U.S. which due to significant growth of texting over local phone numbers, adopted a set of standards and registration processes for 10DLC numbers and A2P (application-to-person) messaging.

10DLC stands for 10-digit long code and it’s a channel the mobile carriers have designated for business-to-consumer (A2P) messaging over local phone numbers.

Note

Disclaimer: These changes are not related to DIDWW. We are providing this information to inform our clients of the changes in the U.S. market.

DIDWW began managing 10DLC registrations on behalf of our customers. For more information, please contact DIDWW Customer Care at customer.care@didww.com

DIDWW does not support P2P messaging in the United States and only A2P (application-to-person) messaging via 10DLC (10-digit long code) phone numbers is currently available. It is required to register your messaging campaigns in the U.S. at https://www.campaignregistry.com/ or contact DIDWW customer care team at customer.care@didww.com for further assistance in setting up your A2P messaging service.

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

SMS

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.

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 a 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 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:

  1. Outbound SMS trunk credentials. Details at Outbound SMS Trunk creation and configuration

  2. Build a string of the form username:password.

  3. BASE64 encode the string.

  4. 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 an SMS

DIDWW Outbound SMS API allows you to 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 Country Code or Area Code cannot be processed because of its absence in your price list, callback with code_id 2 will 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 the list configured in Outbound SMS Trunk are accepted, otherwise callback with code_id 8 will be sent. Details on Callback error 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

A basic example on 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

DIDWW system will return HTTP 201 Created in case SMS is successfully accepted with the following payload:

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

Requests are handled asynchronously, therefore this SMS identifier status can be tracked using Status Callbacks or by using SMS log page on the DIDWW user-panel

Handling exceptions

401 unauthorized

Provided Authorization header is not correct or the request was sent from unauthorized (not allowed) IP address. Refer to Authentication

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

400 Bad Request

Request data has incorrect structure. Refer to JSON API specification.

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

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

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 you can choose either of them ESME or SMSC indicating how 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 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